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.
65 lines
4.0 KiB
Markdown
65 lines
4.0 KiB
Markdown
# 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).
|
|
|
|
## See also
|
|
- [C1](c01-determinism.md) — behaviour-preservation / bit-identity across the carrier split
|
|
- [C3](c03-single-merge.md) — heterogeneous ingestion, where `Scalar` is the ingest carrier
|
|
- [C8](c08-node-contract.md) — the node-output record and `eval`'s Cell buffer; `FieldSpec` output-kind contract
|
|
- [C13](c13-hot-reload-frozen-deploy.md) — the cdylib boundary that also forces edge type-erasure
|
|
- [C23](c23-graph-compilation.md) — bootstrap compilation; the once-at-wiring edge kind check; names non-load-bearing
|
|
|
|
> History: [c07-scalar-soa.history.md](c07-scalar-soa.history.md)
|