alpha — the command-line reference#

The end-user executable is alpha (cabal run alpha -- <command> or the built binary from cabal list-bin -O2 exe:alpha). It is one command shell over one semantic engine: every command resolves the workspace manifest alpha.project, a root, an edition, a profile and a target explicitly, never prompts, and reports through stable exit statuses and typed JSONL events. Start with alpha doctor: it checks the workspace and lists every canonical command with its availability. alpha COMMAND --help is authoritative for each command.

Common tasks#

Workspace#

alpha.project (format alpha-project-v2): name, edition, source-root, default-root, optional stdlib, profile … lines, target, closure, cache. The parser is bounded with exact line diagnostics; unknown keys and duplicates are errors. alpha doctor --init writes the default manifest. Without a manifest, defaults apply (alpha-src, root Main, edition alpha-2026, cache .alpha-cache).

alpha.package v2 binds each declared root's name, source path, namespaces, test roots/suites, and test classification. Duplicate module providers are rejected before resolution. alpha.lock (format alpha-lock-v1) binds every full package source root and its package manifest (alpha package lock / verify / list). Only local/workspace/path/vendored packages exist; no package may execute a build script. Packages and the lockfileBuild · explanationWorkspace and packagesThe alpha.project manifest, alpha.package files, module resolution, and the content-pinned lockfile. describes the manifest, packages and lockfile in full.

Commands#

build OUTPUT --artifact-value NAME requires a valid embedded ELF by default. Use --artifact-format host-elf for a standalone host executable. The compiler verifies the ELF, marks it executable and records its source closure and host region. This format requires no device manifest and makes no device-execution claim. The default elf format still requires the complete embedded-device envelope. alpha verify elf and the build receipt apply to host executables; alpha inspect artifact currently requires a system/device pairing root.

Use --artifact-format bytes for an exact checked Bytes value such as a versioned binary descriptor. This format writes non-executable data, preserves the evaluated bytes, and records artifactFormat: "bytes", source closure, size and SHA-256 in the build receipt. Release verification re-reads the exact written bytes; it does not claim ELF admission. Unknown formats, missing format values, and a format option without --artifact-value are usage errors.

Every command accepts --help, --json, --quiet, --verbose, --workspace DIR, --root MODULE|FILE, --edition E, --profile P, --target T, --receipt PATH, --cache DIR, --no-cache, --observe DIR (record the command as an AOS-JSON/1 stream; also ALPHA_OBSERVE=DIR) and --jobs N (parse up to N modules at once; checking stays sequential).

alpha conformance --edition E checks this workspace against an edition: that the workspace is AT it, that every binding in the edition's manifest still matches the digest of the source it was taken from, that nothing is left unbound (a consumer must reject an edition whose items it depends on are unbound), and that the closure checks. alpha bench compiler [--gate] measures compiler latency against docs/baseline/compiler-budgets.txt, which is the same file the qualification harness judges against, and --gate exits 1 on a budget miss.

alpha check --all-errors keeps going past a failing module and reports every module that fails ON ITS OWN. A module whose import failed is SKIPPED and named as such, because what it would report is a cascade off an interface that does not exist. Without the flag the engine stops at the first failure, which is what a build wants.

Profiles#

check — no code generation, full soundness, maximum incrementality. dev — native ELF for the target. release — dev + independent artifact re-read/digest verification and a release receipt (whole-program specialization and validated optimization are not claimed).

tune — the MEASURED profile. It builds both emission lanes, runs each one nine times on this target, and chooses; the record it writes under .alpha-cache/tune/ names the target, the compiler, the edition, every candidate with its size, digest, fastest run and spread, and any lane that refused, with the refusal. Time decides only when the difference exceeds the measured spread of the runs themselves — on a small program the whole measurement is process startup, so the difference is usually inside the noise and the SMALLER artifact wins, which is deterministic. The record is keyed by the closure digest, the target, the compiler and the edition, so a repeat build reuses the measurement and nothing is reused across targets.

--target selects x86_64-linux (the default) or aarch64-linux, which emits through the direct lane only (--direct). A target this compiler knows but cannot emit is refused with exit 4 and what it is missing, rather than recorded on an artifact built for another target; an unknown target name is refused as unknown.

Exit statuses (stable)#

JSON events (--json)#

run-start, per-module progress lines (progress, status hit|checked|failed, ms, definitions, interface), per-declaration lines on a miss, heartbeat every 2 s while a phase runs (unless --quiet), diagnostic records (alpha-diagnostic-v1; each carries the phase that owns it -- parse, resolve, elaborate or check -- and --all-errors reports every failing declaration of a module, later ones that use a failed name as severity: note cascades), artifact-written, artifact-verified, run-complete, not-available. run-complete (and every check/build receipt) also carries the run's work counters: cache-hits/cache-misses (closure modules adopted from the cache / re-checked), unique-nodes (the exact number of distinct core nodes the checked closure holds, sharing observed by stable names), allocated-bytes (what the compiler thread allocated during the command, the counter the allocation budget is measured against), peak-rss-kb (the process high-water mark the host reports) and evaluator-steps (null on check/build, which never run the evaluator; test-complete reports the steps the measure-steps cases counted).

Receipts (alpha-receipt-v1)#

Written by check/build to --receipt PATH or <cache>/receipts/<run>.json: command, outcome, edition, profile, target, compiler identity, root, the closure with per-module source/interface digests and cache status, hit/miss counts, timings, the artifact (path, bytes, digest) and its verification. A failed run writes an outcome: failed receipt (non-promotable).

Compatibility entry points#

alpha doctor lists the older entry points and their replacements:

alpha-compile's positional pattern matching (a two-argument call is a compile) is exactly the ambiguity the alpha parser retires.

Compiler resource budgets#

check, build, and test accept --budget wall-ms=N,alloc-bytes=N. Either dimension may be omitted. Values are positive decimal integers; unknown or duplicate dimensions reject with exit 2. A budget failure exits 1 and emits resource-limit followed by run-complete with status resource-limit. ALPHA-RESOURCE-WALL and ALPHA-RESOURCE-ALLOCATION are resource outcomes, not typing diagnostics or successful negative-test results. The failure receipt uses alpha-resource-receipt-v1, including limits and the last engine/test marker.

Allocation measures bytes allocated by the guarded bootstrap compiler worker, with GHC allocation-block granularity (approximately 4096 bytes). Exhaustion reports allocatedBytesAtLeast; normal completion reports allocatedBytes. These are not evaluator steps, unique nodes, copied bytes, RSS or child-process allocation. Parallel parsing (--jobs >1) requires a wall-only budget. Wall cancellation joins parser workers, subject to GHC safe points and cleanup. Initial workspace discovery and final publication are outside the worker guard. Budgeted tuning and golden mutation are currently rejected, as they require additional child-work and publication contracts.

Artifacts and receipts are privately staged while the budget runs. A resource failure discards those stages and preserves existing artifact destinations. Only completed work publishes artifacts and final reports. Completed receipts include an additive resource object (alpha-resource-usage-v1), with the same measurements as the resource-usage event. Like finish time, this telemetry is outside the test receipt's semantic identity. Broader work counters (beyond wall time and allocation) are not yet budgeted.