Observability#

Every alpha command can record what it did as an AOS-JSON/1 stream: the invocation, each module of the closure as it was checked (a module reused from the cache is recorded as reused, with the basis on which reuse was valid, never as checked), each declaration as its check completed, the diagnostics, the artifacts written by SHA-256, the resources used, and how the command ended. Gates, benchmarks, device runs and training runs record into the same format, so one set of commands reads all of them.

AOS is the one recorder. A claim about speed, loss, a hang or a device cites the stream or receipt of the run it describes.

Record a command#

alpha check --root Hello.alpha --observe out/aos     # one command
export ALPHA_OBSERVE=$PWD/out/aos                     # or every command in this shell
export ALPHA_OBSERVE_RUN=$(alpha observe new-run)     # many commands, one logical run
ALPHA_OBSERVE_CONTEXT="gate=my-gate;mutant=none" alpha build out.elf --root Hello.alpha

Observing never changes the result: an observed build is byte-identical to an unobserved one, and a host that cannot record fails by name rather than silently dropping the record.

Read what was recorded#

What a stream is#

A stream is UTF-8, one JSON object per line, with integers written as canonical decimal strings, floats as bit patterns, and bytes and identities as lowercase hex. It runs from a header through descriptors (the attempt, its clocks, its capture policy and one schema per event type), the events themselves, the artifacts written and a coverage count of accepted, dropped and excluded records, to a footer.

A check or build also writes, when it seals:

• a build manifest: the compiler identity, the configuration, the SHA-256 of alpha.project and alpha.lock, every module of the closure with the SHA-256 of the bytes checked, and the artifacts written. An uncommitted edit is therefore identified by content, not by a commit label.
• a validation receipt: the claim that the kernel accepted every declaration of the closure, its method, the validator, its assumptions and its boundary (it says nothing about an artifact's behaviour on a device), and the verdict.
• the recorder's own health: what it accepted, excluded and dropped, and the first write failure if there was one.

What the recorder promises#

• Gaps are visible. Every selected record gets a sequence number, whether it is written or dropped. A stream has at most 2,000,000 events and 256 MiB; past that, new events are dropped and counted exactly.
• Clocks stay apart. Event times are CLOCK_MONOTONIC nanoseconds, with a clock epoch derived from the kernel's boot identity, so streams from one boot share a time axis and streams from different boots never do. Civil time is recorded once, separately, and never used for an interval. Imported device records keep their own epoch; they are correlated by a bounded offset, never by subtraction.
• Incomplete is not success. A process killed mid-run leaves a stream with no footer, which reads as incomplete: never as a success, and never as invalid evidence.
• Durability is explicit. Only at the seal is the stream synced and a .seal file written with its length and SHA-256. validate reports sealed, unsealed (crashed, or still being written) or seal-mismatch (changed after sealing).
• Absent is not zero. A value that was not observed is recorded as absent, with its reason, and never defaulted.

Receipts and verdicts#

A receipt's verdict follows from how the validation ran, what it found, and whether its inputs were complete:

alpha observe gate NAME -- COMMAND runs a gate and turns every line it prints beginning ok or FAIL into a receipt the moment it is printed; a claim beginning mutant is recorded as a mutation test. Every alpha command the gate runs records its own stream as a child of the gate's run. A FAIL line fails the gate; a non-zero exit with no FAIL line is inconclusive. alpha observe claim records a single receipt from a script, with its method stated rather than inferred from the wording.

A device result is a physical-observation receipt only when it was observed on the device it names. The same check run offline, on supplied bytes, is recorded as an executable test, never as a physical one.

Bring in device and training records#

alpha observe import FORMAT FILE --out DIR admits records made outside the compiler: the native hosts' telemetry (alphatel), device run records (device-runs), training chains (train-chain), GPU energy samples (gpu-energy, gpu-energy-samples), launch profiles (launch-profile) and system-specific loss and objective records. Each importer has a schema and a gate; a new recorded quantity arrives with a fixture from a real run, a check, and a mutant the check refuses.

To collect streams from several machines, alpha observe ingest SRC... --into STORE admits streams with de-duplication, resumption and quarantine; pull copies them over SSH first; serve and push run an HTTP service with token scopes. prune applies retention and respects pins (pin, unpin).

The standard and the design record#

• The AOS 1.0 standardReference · normativeObservability standard (AOS 1.0)The proposed Alpha Observability Standard, draft 1: identity, time, coverage, evidence and conformance for every observation. (draft 1) defines the semantics, required behaviour and acceptance criteria.
• The repository's design record, docs/observability/README.md, lists what is implemented, where, what each part promises, what is not supported, and the measured device paths.

Read next#

• Tests, gates and CIBuild · explanationTests, gates and CIThe declared suite, proof roots checked to the bit, the negative corpus, gates with executed mutants, and CI.: the gates whose claims become receipts.
• Evidence and statusEvaluate · analysisEvidence and statusHow to read checked, run and measured claims, and what each one does not establish.: what checked, run and measured each establish.