runglet 0.3.0

Intent-oriented industrial control language and Relay IR toolchain

Runglet

Runglet is a block-based, intent-oriented language for industrial control. It lowers into a typed, canonical Relay IR that can be interpreted, tested, and compiled for PLC targets.

The initial backend targets FATEK FBs controllers through WinProLadder 3.32. The initial physical verification target is an isolated FBs-20MCR2-AC test panel; no pressure vessel, oxygen-enriched environment, final chamber actuators, or human occupancy is in scope.

Runglet is alpha software. Its offline compiler and authoring workflow are usable, but target-specific delivery remains evidence-gated and is not production-ready.

Language 0.3 adds declarative writable MEMORY: an optional snapshot-atomic UPDATE block calculates one typed next value from the current scan snapshot and commits it at the scan boundary. Guarded integer and fixed-point updates fail closed when range or resolution safety cannot be proven.

Install

Runglet requires Python 3.12 or later. For the isolated command-line application:

pipx install runglet

To install it into an existing Python environment:

python -m pip install runglet

The distribution is currently proprietary; see LICENSE before use.

For Windows authoring without a Python installation, CI also produces a portable runglet-authoring-*-windows-*.zip. It contains native launchers for both runglet.exe and runglet-lsp.exe, their shared private runtime, and the matching VS Code extension. Extract the complete archive, add its bin directory to the user PATH, and install vscode\runglet-vscode.vsix. The executables launch directly and do not use PowerShell. See packaging/windows/README.md.

Tagged builds are available from GitHub Releases. Each vVERSION release provides the Python wheel and source archive, the standalone Windows authoring ZIP, the matching versioned VSIX, and SHA256SUMS.

Installed package quick start

Create a checked, offline, single-file authoring workspace without a repository checkout:

runglet init my-controller --name my_controller
cd my-controller
runglet authoring-context --profile core --format markdown
runglet format src/main.rung --check
runglet check src/main.rung
runglet suite src/main.rung --scan-period-ms 10

Common interactive aliases are new for init, fmt for format, ctx for authoring-context, and test for suite. Run runglet help --all for the complete tool catalog or runglet help COMMAND for focused usage.

Specialist tools use one namespace level: runglet hil COMMAND, runglet winpro COMMAND, and runglet fatek COMMAND. Run each namespace with --help to list its actions. The earlier flat hil-*, winpro-*, and fatek-* spellings remain accepted as compatibility aliases but are omitted from help.

The scaffold includes AGENTS.md and CLAUDE.md entrypoints, portable Codex and Claude skills, a machine-readable installed-version capability declaration, a canonical starter with passing scenarios, and a hash-bound scaffold manifest. Initialization refuses to merge or overwrite existing files. It never contacts WinProLadder, a PLC, or the network.

Development

Prerequisites:

• Python 3.12
• uv

Install the locked development environment:

uv sync --extra dev --locked

Run all local checks:

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest --cov

Run the CLI:

uv run runglet --version

Start a productive offline authoring loop with the minimal example:

uv run runglet check examples/starter/starter.rung
uv run runglet format examples/starter/starter.rung --check
uv run runglet build examples/starter/starter.rung --output build/starter
uv run runglet suite examples/starter/starter.rung --scan-period-ms 10

check runs the same syntax, resolution, type, ownership, and command validation as the language server without invoking a backend. format --write applies canonical source layout. build adds Relay IR lowering and creates canonical source, Relay IR, and a deterministic hash-bound manifest in a new directory. See the diagnostics guide for codes and exit behavior. The compact authoring card and checked examples/patterns are the preferred starting context for both human and LLM-authored Runglet.

The checked writable-state pattern is examples/patterns/core/writable-memory.rung. Bare MEMORY remains a self-holding declaration for v0.2 compatibility; add an UPDATE block only under SNAPSHOT_ATOMIC.

Machine-facing authoring interfaces are deterministic and offline:

uv run runglet inspect examples/starter/starter.rung --json
uv run runglet authoring-context --profile core --format markdown

The Python environment also installs runglet-lsp. The internal contributor VSIX under editors/vscode prefers that workspace .venv, but also carries a version-locked Python runtime for ordinary non-repository folders. It never uses PowerShell or installs global packages. The server supplies diagnostics, safe fixes, formatting, symbols, hover, completion, and same-file navigation. Its bounded command palette directly exposes saved-source check, backend-neutral build, embedded scenario suite, and one-scenario trace tasks. Checked declaration snippets, server status, semantic occurrence highlights, and matching-block navigation complete the small single-file authoring loop. The extension does not expose target, WinPro, FATEK runtime, or PLC commands.

The repository workspace explicitly associates *.rung with the runglet language. After installing the VSIX, reload VS Code once. To verify the entire editor surface, run Tasks: Run Test Task → Runglet: Verify Editor Integration, or use:

cd editors/vscode
npm ci
npm run verify

Build and smoke the same standalone Windows preview locally with:

uv sync --extra dev --locked
cd editors/vscode
npm ci
cd ../..
uv run python scripts/windows/build-authoring-preview.py

The result is written below dist/windows/. The smoke test invokes the frozen CLI and stdio language server themselves, including project initialization, checking, inspection, scenarios, build output, UTF-16 LSP initialization, and clean shutdown.

That check covers the language association and assets, direct server/compiler discovery, the offline compiler task, diagnostics, formatting, completion, hover, definition, references and highlights, matching-block navigation, status reporting, missing-server recovery, and post-start server crash recovery without contacting WinPro or a PLC.

Generate the reviewable paired-FUN30 initial-delivery plan (no PLC download or run). ADR-0007 selects this explicit native integer contract first; the generated binary32 implementation remains a portable follow-on and comparison oracle:

uv run runglet check fixtures/control/split-range-fun30-v0.2/controller.rung
uv run runglet format fixtures/control/split-range-fun30-v0.2/controller.rung --check
uv run runglet winpro fun30-plan \
  fixtures/control/split-range-fun30-v0.2/controller.rung \
  --profile profiles/fatek/fbs-20mcr2-ac.json \
  --allocation-policy profiles/fatek/fbs-20mcr2-ac-allocation.json \
  --config fixtures/control/split-range-fun30-v0.2/fun30-plan.json \
  --output build/fun30-plan

After filling a copy of vendor-trace-template.json from a WinPro simulator capture, verify its plan identity, field contract, scan ordering, and first arithmetic divergence:

uv run runglet winpro fun30-verify-trace \
  fixtures/control/split-range-fun30-v0.2/controller.rung \
  build/fun30-vendor-capture.json \
  --profile profiles/fatek/fbs-20mcr2-ac.json \
  --allocation-policy profiles/fatek/fbs-20mcr2-ac-allocation.json \
  --config fixtures/control/split-range-fun30-v0.2/fun30-plan.json

The native fixture is a complete, canonical single-file program. check applies resolution, integer type, ownership, and command-completeness validation; the plan command repeats those checks before invoking the explicit target-native lowering path. Generic build remains the backend-neutral Relay IR path and does not lower native FUN30 declarations.

The emitted parameters.json records the mandatory native language contract, requested and realized tuning for both directions, exact quantization errors, documented native parameter ranges, and the ordered FUN30 PR table layout. wrapper-relay-ir.json is the integer-only, executable Relay IR for compiler-owned direction, dwell, override, and routing behavior; the vendor FUN30 outputs and error flags remain explicit boundaries. wrapper-differential.json records stable-ID alignment across the independent oracle, source Relay IR, and FATEK Network IR without claiming vendor timer execution. direction-project.ldr is the evidence-bounded 64-record PID direction, parameter-table, and paired-core artifact; its provenance explicitly excludes the remaining control and routing wrapper. vendor-trace-template.json binds both native cores and their parameter tables to ten required simulator cases per direction, with raw observations for all seven private working registers; it remains not_captured until checked WinPro evidence is supplied. wrapper-emission-coverage.json accounts for all 32 planned ladder network IDs: the accepted artifact covers 17 of 29 source networks plus signed-error materialization, while 12 source networks and two derived core-enable snapshots remain as 26 staged control/routing steps. evidence-manifest.json binds all four source inputs and twelve generated artifacts by SHA-256. It records the four completed offline gates and leaves WinPro lifecycle, vendor arithmetic/timer, simulator, review, and bench gates explicitly not_verified; therefore the emitted candidate is not promotion-ready. Exact native tuning and target configuration are currently supplied by the checked fun30-plan.json contract, with tuning realization recorded in parameters.json; unifying those values with general source parameter sets remains later language work.

Run the complete bench-only demonstration suite with human-readable semantic coverage:

uv run runglet suite fixtures/demo-chamber-v0.1/demo.rung --scan-period-ms 10

Use --json for a canonical machine-readable scenario and coverage report. Run the checked mutation campaign with:

uv run runglet mutate fixtures/demo-chamber-v0.1/demo.rung \
  --manifest fixtures/demo-chamber-v0.1/mutations.json \
  --scan-period-ms 10

The demonstration is an exact-scan reference-runtime proof over normalized Boolean test points and dummy commands. It is not a production chamber program, safety function, physical deployment authorization, or compliance argument.

For the isolated-bench workflow, validate the design and generate the unexecuted manual checkout first:

uv run runglet hil bench-check hil/bench-panel-v0.1.json
uv run runglet hil checkout-plan hil/bench-panel-v0.1.json \
  --output build/hil/manual-io-checkout.json

After qualified assembly/review and local authorization, runglet hil observe can append read-only status and X0-X6/Y0-Y3 samples under manual stimulus control. It exposes no physical write option and does not authorize energization. See docs/hil/read-only-recorder-v0.1.md.

Project architecture and milestones are documented in IMPLEMENTATION_PLAN.md, DESIGN_DECISIONS.md, and TASK_BREAKDOWN.md. The current usable workflow and ordered delivery gaps are summarized in docs/language/readiness.md. For a clean Codex and WinProLadder move to another Windows machine, follow the bare-metal Windows handoff.