audit(families-view): cycle close 0061 — drift-clean, ledger records the comparison view

Architect drift review over 99fd32b..HEAD (the housekeeping commits #99/#98 plus
the 0061 cycle): code drift-clean. Engine untouched (aura-engine + aura-core diff
empty — C9/C14); C21 realized faithfully (the comparison view consumes a set of
runs, a family is the first producer, no orchestration-axis rebuild); C18/C10
refuse-don't-guess honoured (every new error path exits 2, never panics; all six
tracing entry points guarded before persist, so name resolution is total). The only
finding was a ledger-realization gap, lifted in this commit.

Ledger (docs/design/INDEX.md): added a C22 amendment recording the
families-comparison view as realized (#107) — aura chart <family> overlays one tap
across a family's members on a shared y-scale, union-ts spine giving one mechanism /
three correct readings, the write-guard totalising name resolution; reconciled the
two stale "families-comparison ... remain open" lines (the #104 note and the
open-threads list) and named the deferred follow-ons (#102 run-context header, #47
multi-column tap selection, the orchestration-composability rebuild).

Regression: cargo test --workspace green (no failures), clippy --workspace
--all-targets -D warnings exit 0, cargo build --workspace clean — verified by the
orchestrator before close. No baseline to update (aura's regression gate is the
gated determinism suite, which is part of the workspace tests).

Retire the cycle's ephemeral spec + plan (0061). refs #107
This commit is contained in:
2026-06-21 18:58:32 +02:00
parent 4c64feb9ed
commit 53eeba5e16
3 changed files with 36 additions and 919 deletions
+36 -4
View File
@@ -1040,7 +1040,8 @@ targets disjoint member dirs, so it is lock-free. Opt-in: without `--trace`,
stdout/registry are byte-unchanged. Because `TraceStore` resolves `<name>/<member_key>`
as a subpath, `aura chart <name>/<member_key>` charts any single member with no
view-side change — the write-side precondition for the family-comparison **view**
(overlay / small-multiples across members), which itself remains open.
(overlay / small-multiples across members) — now realized (#107; see the
families-comparison amendment below).
**Amendment (real-data family source, #106, 8e5d14b).** The family runs gain an
**opt-in real-data source axis**: `aura sweep|walkforward --real <SYMBOL> [--from
@@ -1067,6 +1068,34 @@ sizes — is a *demo-strategy calibration* patch; the real answer is project-aut
strategies (C9: a project crate owns its own grid), deferred to the project-env
work.
**Amendment (families-comparison view, #107, 4c64feb).** The family-comparison
**view** the #104 amendment left open is now realized. `aura chart <name>`
classifies the name on disk (`TraceStore::name_kind`: a top-level `index.json` is a
single run; else member subdirs with `index.json` are a family; else not-found) and,
for a family, overlays **one tap** (default `equity`, `--tap` to pick) of **every
member** in one self-contained uPlot page: `build_comparison_chart_data` emits one
labelled series per member, all on a **single shared y-scale** — members measure one
identical quantity, so a shared scale is what makes them comparable, unlike the
single-run overlay of *different* taps (per-series scales). The series align on the
same union-ts spine via `join_on_ts`, so **one mechanism yields three correct
readings**: sweep/MC members share the data window (a true overlay), walk-forward
members are disjoint OOS windows (null-complementary → the stitched curve). The view
consumes a **set of runs** (`&[FamilyMember]` from `TraceStore::read_family`, sorted
by key for determinism, C1); a family is its *first producer* — the deliberate first
step toward the programmable analysis meta-level (C21) **without** rebuilding the
orchestration axes (that is its own later cycle). Name resolution is made a **total
function** by the write-guard `TraceStore::ensure_name_free`, called once per tracing
command (`run`/`run --macd`/`run --real` → Run; `sweep`/`mc`/`walkforward` → Family)
to refuse cross-kind name reuse — so the one ambiguous on-disk state (a name used by
both a run and a family) is unreachable. Every error path exits 2, never panics
(C18/C10 refuse-don't-guess). Engine untouched (C9/C14): the whole change is
`aura-registry` (the resolver + classifier + guard) + `aura-cli` (the builder +
`emit_chart` name-kind branch + `--tap`); the single-run page is byte-unchanged when
no `--tap` is given. **Still deferred:** the run-context header on the served page
(#102); multi-column tap selection (`build_comparison_chart_data` projects column 0 —
the comparison taps in scope are single-column f64; #47); and the
orchestration-composability rebuild (sweep/MC/WFO as composable meta-level tools).
### C23 — Graph compilation and behaviour-preserving optimisation
**Guarantee.** The bootstrap (C19) is a **compilation**: it lowers a param-generic,
named **blueprint** (the authoring source — nodes, composites, strategy, harness;
@@ -1133,9 +1162,12 @@ load-bearing in the flat graph.
#101; not egui). Settled for the first cut: raw per-tap trace persistence to
disk (columnar/SoA form, C7) + serve-time `join_on_ts` alignment + a static
self-contained HTML chart page (uPlot, vendored like the `render_html`
Graphviz-WASM blob), feeds overlaid or timestamp-aligned in panels. Still open:
families-comparison meta-views (walk-forward, sweep surfaces, multi-strategy /
instrument comparison), a local server, and the run/replay clock controls.
Graphviz-WASM blob), feeds overlaid or timestamp-aligned in panels. The
families-comparison **view**`aura chart <family>` overlaying one tap across a
family's members on a shared y-scale — shipped (#107, see the C22 amendment).
Still open: richer comparison meta-views (sweep-surface heatmaps, cross-family /
multi-strategy comparison, the run-context header #102, multi-column tap selection
#47), a local server, and the run/replay clock controls.
- **Parameter-space search strategies** (Bayesian/genetic) — pluggable policies
atop the atomic sim unit (C12), not yet designed.
- **`aura new` scaffolder, the experiment-builder API, and `Aura.toml`'s