claude
8688a60ded
The single-file ledger had grown to 2968 lines / ~42k tokens, mixing current design law with accreted history: 59 cycle-stamped realization blocks, 18 [HISTORY] passages, 22 supersession markers, and the C10 / C22 / C24 reframe sagas layered several supersessions deep. A code-grounding audit (31 agents, adversarially verified) confirmed 11 defects stated as current truth: stale crate homes from the C28 #288 roster split (cost nodes, PositionManagement, PositionEvent, Session), the renamed InputSpec->PortSpec, the pre-#241 project model in C16 and the open-threads section, a stale HarnessKind retirement deferral in C24, and three C28-internal inconsistencies. New shape, per the ailang precedent: - INDEX.md stays the sole addressable entry point: foundation, external components, a C-id-keyed contract map (one line per contract), and only the genuinely open architectural threads. - contracts/cNN-<slug>.md carries each contract's current truth only: Guarantee / Forbids / Why with ratified refinements integrated, plus a code-anchored Current state. All confirmed defects are fixed here; crate anchors were re-verified against the tree. - contracts/cNN-<slug>.history.md (18 sidecars) and INDEX.history.md preserve every superseded block verbatim, stamps and issue refs intact, under a frozen-record banner. Nothing was deleted: superseded design intent remains an addressable working-tree artifact, off the per-cycle audit walk. - Ledger discipline is now stated in INDEX.md: live files are edited in place at cycle close, superseded text moves verbatim to the sidecar, and a supersession marker in a live file is itself an audit finding. Every contract file was verified against its old text by an independent zero-loss pass (statement-by-statement) plus a code-accuracy spot check; C-ids and contract titles are unchanged, so existing C-id citations in code, tests, and issues resolve as before.
90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# C14 — Headless core, two faces
|
|
|
|
**Guarantee.** The engine is a UI-agnostic library. Two faces sit on it: a
|
|
**programmatic/CLI** face (the primary surface for the LLM and automation —
|
|
author a node, run a sim/sweep, emit structured metrics) and a **visual** face
|
|
for human exploration. Visualization is only a downstream consumer node
|
|
([C8](c08-node-contract.md)) on the streams.
|
|
|
|
**Forbids.** Any UI/pixel knowledge inside the engine.
|
|
|
|
**Why.** The LLM drives programmatically, the human visually; a headless core
|
|
serves both. The visual face is the **playground** ([C22](c22-playground-traces.md)) —
|
|
a **web frontend served from disk-persisted traces** (#101, ratified 2026-06):
|
|
the engine writes recorded traces to disk and a browser charts them. It is
|
|
staged after the runnable substrate but is core to aura's identity, not
|
|
optional. Reading a serialized trace file is a stricter form of "no UI knowledge
|
|
in the engine" than an in-process native UI reaching zero-copy into the live SoA
|
|
columns — the pivot to the disk-trace frontend keeps this contract's core intact
|
|
and arguably tightens it.
|
|
|
|
## Current state
|
|
|
|
**The CLI conventions.** The programmatic/CLI face is a `clap` derive parser
|
|
(`aura-cli`, `crates/aura-cli/src/main.rs`) that meets GNU / clig.dev
|
|
conventions: one declarative source yields scoped `aura <sub> --help`,
|
|
`--version`/`-V`, per-flag Options sections, and GNU `--flag=value` / `--` /
|
|
long-option abbreviation. `clap` is admitted under the
|
|
[C16](c16-engine-project-split.md) per-case dependency policy — a
|
|
research-side, dev-loop/compile tax confined to `aura-cli`, a leaf binary the
|
|
frozen deploy artifact ([invariant 8](c13-hot-reload-frozen-deploy.md)) cannot
|
|
pick up. Usage lines follow the clap house style (`Usage: aura <verb> …`);
|
|
refusal diagnostics stay unprefixed, since a diagnostic is not a usage line.
|
|
|
|
**The exit-code partition** is a durable part of the automation contract: a
|
|
caller branches on the failure class without parsing stderr.
|
|
|
|
- **0 — success.**
|
|
- **2 — usage error:** a command-line fault (clap parse errors + aura's
|
|
post-parse argument-structure validations, *including* the content of an
|
|
argv-named blueprint file, which is itself an argument).
|
|
- **1 — runtime failure:** a well-formed command whose needed environment /
|
|
recorded state is missing, or bad piped stdin data.
|
|
- **3 — campaign completed with failed cells:** a well-formed campaign that ran
|
|
to completion but with at least one failed cell (#272; `exit_on_campaign_result`
|
|
in `crates/aura-cli/src/main.rs`, threaded from the run registry —
|
|
[C18](c18-registry.md)).
|
|
|
|
**Dual grammar.** The four dual-grammar subcommands (run/sweep/walkforward/mc)
|
|
keep both grammars under one token via an optional `[blueprint]` positional plus
|
|
a post-parse `is_file()` dispatch; the execution layer is unchanged (arg-plumbing
|
|
via thin `*_from` adapters). The machine-first help surface (JSON/manifest help,
|
|
stdin op-scripts) is deferred to the #157 / [C21](c21-world.md) track, distinct
|
|
from this human/GNU-convention compliance.
|
|
|
|
**Two artifact classes, two redundancy budgets** (#249, ratified 2026-07-13).
|
|
The data layer the programmatic face emits is a public interface read raw (by
|
|
humans and LLMs), and its records split into two classes with opposite
|
|
redundancy budgets. **Generated outcome records** (manifests, metrics, family
|
|
reports) have a single writer at run time — redundancy there cannot drift and is
|
|
deliberately spent on direct readability. **Authored intent artifacts**
|
|
(blueprints, op-scripts, campaign documents) are author-maintained — every
|
|
redundancy is a drift site and stays out. Consequence in the run manifest
|
|
(`RunManifest`, `crates/aura-engine/src/report.rs`): the untouched bound
|
|
`defaults` are stamped one-directionally beside `params` (which keeps its "what
|
|
varied" reproduce semantics, disjoint by construction from `defaults`, "what was
|
|
held"), so a raw reader of a fully-bound run no longer sees a misleading
|
|
`"params": []`; the blueprint itself carries no such duplication.
|
|
|
|
**The programmatic face is an executor** (#295, ratified 2026-07-20). The
|
|
member-run recipe — the definition of what a standard aura backtest is — is
|
|
library content (`aura-runner` / `aura-backtest` / `aura-measurement`,
|
|
[C28](c28-stratification.md) assembly position), not CLI content: the binary is
|
|
argv → document → executor → presentation, and a downstream World program
|
|
reaches the same recipe with no binary involved. See
|
|
[C25](c25-role-model.md)'s control-surface amendment for the projection rule.
|
|
|
|
## See also
|
|
|
|
- [C8](c08-node-contract.md) — visualization is a downstream sink/consumer node
|
|
- [C16](c16-engine-project-split.md) — the per-case dependency policy under
|
|
which `clap` is admitted
|
|
- [C18](c18-registry.md) — the run registry that yields the exit-3
|
|
completed-with-failures class
|
|
- [C21](c21-world.md) — the #157 machine-first help track (deferred)
|
|
- [C22](c22-playground-traces.md) — the visual face / playground
|
|
- [C25](c25-role-model.md) — the control-surface amendment (executor projection)
|
|
- [C28](c28-stratification.md) — the assembly position of the member-run recipe
|
|
|
|
> History: [c14-headless-two-faces.history.md](c14-headless-two-faces.history.md)
|