audit: cycle 0045 — registry lineage (C18 ledger note; flat-store follow-up #73)

Architect drift review (eeba218..HEAD) + regression gate (the project's
cargo test --workspace is the gate; no separate regression script).

What holds (architect): C9 layering intact — aura-engine gains no registry
dependency, lineage lives entirely in aura-registry. #71 firewall held —
RunManifest/aura-core byte-untouched, no blob/path/payload field on
FamilyRunRecord, the member window is producer-supplied via
Source::bounds()/window_of, never a Vec scan. C2 clean — bounds() is
cursor-independent (no look-ahead). Family store is a disjoint sibling of the
flat store (pinned by a disjointness test). Regression gate green: 228 tests,
clippy --workspace --all-targets -D warnings clean.

Drift resolved:
- [fix, this commit] C18 ledger gap: docs/design/INDEX.md C18 carried no
  realization note for the run registry. Added the cycle-0029 (flat registry)
  and cycle-0045 (lineage as related records / family store) realization
  notes, in the ledger's established per-cycle style.
- [forward-queue] Flat-store CLI dead-end: after this cycle no CLI command
  writes the flat runs.jsonl (sweep/walkforward moved to the family store,
  aura run never persisted), so aura runs list / rank read an unfed store.
  This is a spec-accepted state (0045 kept runs list "for standalone runs
  only") and a genuine design fork (give aura run a persisting path vs. retire
  the flat-store CLI surface) with no clear default — filed as #73 rather than
  decided here. Recorded as a deferred follow-up in the C18 ledger note.
- [carry-on] Low/cosmetic: family-wrapped CLI stdout alphabetizes nested
  manifest keys (serde_json::json!) vs. declaration order (to_json()); both
  valid JSON, the stored families.jsonl uses declaration order, round-trip
  unaffected. Noted as a sub-item on #73.

refs #70
This commit is contained in:
2026-06-15 18:35:21 +02:00
parent bcd1072ca8
commit a168f07cbb
+30
View File
@@ -654,6 +654,36 @@ has no home in git/Gitea; determinism makes a structured registry cheap.
Sequencing: the walking skeleton emits a manifest + metrics per run from day
one; the registry/index is a later milestone over manifests that already exist.
**Realization (cycle 0029 — the flat run registry).** The experiments-&-results
plane shipped as `aura-registry`: an append-only JSONL store (`runs/runs.jsonl`),
one serde_json `RunReport` (`RunManifest{commit, params, window, seed, broker}` +
`RunMetrics`) per line, with a typed read-path (`load`) and best-first ranking
(`rank_by`/`optimize`). C9 holds — the registry depends on `aura-engine`, never
the reverse.
**Realization (cycle 0045 — lineage as related records, #70).** The *lineage*
depth is now realized as a **family store**: a sweep / Monte-Carlo / walk-forward
run (the C12 axes) is persisted as a *set of related records* — each a
`FamilyRunRecord` (a `RunReport` stamped with a shared `family_id` + `kind` +
`ordinal`) — in a sibling JSONL (`families.jsonl`), leaving the flat `runs.jsonl`
path and its `append`/`load`/`rank_by`/`optimize` API byte-for-byte unchanged.
`family_id = "{name}-{counter}"` (an author-supplied name plus a per-name
generate-and-check run index — not a content hash; re-running the same family
mints a fresh id). `group_families` is the round-trip that re-derives a family
from the stored links (re-listable / rankable as a unit — C21). The manifest *is*
the re-derivation recipe (#71): no input-stream blob / path / payload enters a
record, and a member's window is **producer-supplied** via
`Source::bounds()`/`window_of` (eager or streamed → byte-identical lineage),
never a materialized-`Vec` scan at the call site. CLI surface: `aura mc`,
`aura runs families`, `aura runs family <id> [rank <metric>]`; `aura sweep` /
`walkforward` / `mc` persist via `append_family` with an optional `--name`.
Deferred (Non-goals): content-addressed identity + replay-dedup; the "run-diff"
depth and ranking families against each other (cross-family, vs. within-family);
and a live producer for the flat `runs.jsonl` standalone-run path — after this
cycle no CLI command writes it (sweep/walkforward moved to the family store, and
`aura run` does not persist), so `aura runs list` / `rank` await either a
persisting `aura run` or retirement (forward-queue follow-up).
### C19 — Bootstrap: blueprint → instance (recursive)
**Guarantee.** Construction is a distinct phase, recursive at every level. Each
node type has a **factory** `params → sized concrete node` (e.g. `SMA(length)`