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

4.0 KiB

Raw Blame History

C7 — Four scalar base types, streamed as SoA

Guarantee. Only i64, f64, bool, timestamp (newtype over i64, epoch-ns UTC) are streamed, as columnar Structure-of-Arrays. Composite streams (OHLCV) are bundles of base columns — this is the node-output model too: a node emits a record of 1..K base columns (C8), each forwarded field-wise to a consumer slot; the bundle is structural, never a fifth scalar type. Edges are type-erased to these four kinds; the type check is paid once at wiring/sim-start, then the topology is frozen per sim → direct dispatch, no per-event allocation.

Forbids. Streaming non-scalars (String, Records, tables, calendars) — those live as metadata beside the hot path; dyn Any payloads; per-event heap allocation; topology mutation mid-sim.

Why. Maximal streaming performance (SIMD/cache) needs a tiny closed scalar set and SoA. The open set is composites (schemas of columns), not scalar types. Type-erasure at the edge is also forced by the cdylib boundary (C13).

Current state

The streamed value is split into a tag-free 64-bit word and its kind. Cell (crates/aura-core/src/cell.rs) is the type-erased u64 hot-path carrier: constructed per base type (from_i64/from_f64/from_bool/from_ts) and read only by naming the type at the call site (i64()/f64()/bool()/ts() — branch-free bit-casts, no tag to check). The kind lives once, at the column/edge/port, never in the value — C7's principle made explicit on the single-value carrier (one 8-byte word, not a 16-byte tagged enum). Cell deliberately has no tagged constructors, so a value can never re-acquire a per-value tag once it crosses onto the hot path.

Node::eval returns Option<&[Cell]> (crates/aura-core/src/node.rs) and every node out-buffer is [Cell; N], so the inter-node forward carries tag-free 8-byte words. The harness forwards each field via AnyColumn::push_cell (crates/aura-core/src/any.rs) — branch-free and infallible, because the edge's from_field→slot kind match is verified once at bootstrap, not per value. There is deliberately no per-value runtime kind check on node output: node-output-kind correctness is the node's declared FieldSpec contract (C8), caught by each node's own test — the same authoring-bug class C8 already leaves to a debug_assert for output width.

Scalar (crates/aura-core/src/scalar.rs) is the self-describing, kind-tagged carrier for the dynamic boundaries, where a value travels detached from any co-present schema and so must remember its own type: the param plane (builder binding via bind, sweep points, RunManifest), AnyColumn::get (the type-erased read for sinks/serde), and source ingestion (Source::next → Option<(Timestamp, Scalar)>, the heterogeneous C3 merge). Scalar and Cell are disjoint, bridged by Scalar::from_cell(kind, cell) (decode, the kind supplied by the co-present schema — e.g. a validated param point carries bare cells, its kind living once in the co-indexed ParamSpec) and Scalar::cell() (encode, kind dropped once checked against the slot). Reading a Scalar is caller-asserted: as_i64/as_f64/as_bool/as_ts panic on a kind mismatch (a caller bug). Scalar's value equality preserves IEEE-754 semantics (NaN != NaN, +0.0 == -0.0) and never equates across kinds (i64(0) != f64(0.0)), pinned by the scalar_eq_is_value_not_bitwise fixture; Cell's own Eq/Hash are bit-exact (the semantics of a raw word, not of a number).

4.0 KiB Raw Blame History

C7 — Four scalar base types, streamed as SoA

Current state

See also

4.0 KiB

Raw Blame History