Files

T

claude 8688a60ded docs(ledger): split the design ledger into an INDEX map, per-contract live files, and history sidecars

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.

2026-07-21 16:40:36 +02:00

2.2 KiB

Raw Blame History

C4 — Cycle granularity

Guarantee. The clock is data-driven: one input record = one cycle, advanced in global timestamp order, with a monotonic cycle_id. Ties (same timestamp, multiple sources) break by source declaration order.

Forbids. A fixed time-grid clock; nondeterministic tie ordering.

Why. The market is an irregular event sequence; a grid is arbitrary and either wastes empty cycles or clumps ticks. Backtest and live differ only in the origin of records, not the cycle semantics. Tie determinism preserves C1.

Current state

Harness::run (crates/aura-engine/src/harness.rs) increments cycle_id once per popped record and each cycle picks the smallest (timestamp, source index); the source-index tie-break is the source declaration order.

Ingestion sources are supplied to the production run path by role name, not list position (#275). SourceSpec carries role: Option<String> — the bound Role's name, load-bearing for source binding only, with every other flat-graph name staying a non-load-bearing debug symbol (C23). Harness::run_bound resolves a keyed supply against those roles via bind_sources, emitting sources in SourceSpec declaration order, so the tie-break is independent of how the caller orders the supply. A mis-bound feed is a named SourceBindError (MissingFeed / ExtraFeed / DuplicateFeed / UnnamedSource) at start time, not a silently wrong run. The raw-index run(Vec) primitive (positional, C23) is unchanged: SourceSpec::raw carries role: None and every hand-built graph keeps role: None; a raw-index arity mismatch stays an engine-wiring panic, while a keyed role mismatch is a user data-binding Result.

2.2 KiB Raw Blame History

C4 — Cycle granularity

Current state

See also

2.2 KiB

Raw Blame History