diff --git a/crates/aura-engine/src/construction.rs b/crates/aura-engine/src/construction.rs index 44a07db..f601e9a 100644 --- a/crates/aura-engine/src/construction.rs +++ b/crates/aura-engine/src/construction.rs @@ -392,6 +392,9 @@ impl<'v> GraphSession<'v> { .into_iter() .map(|(name, source, targets)| Role { name, targets, source }) .collect(); + // No doc is attached here: the op-script vocabulary deliberately has no + // doc-carrying surface yet (#125 scope cut) — an op-built composite + // carries no authored rationale until that vocabulary grows a slot. let c = Composite::new(self.name, self.nodes, self.edges, roles, self.out) .with_gangs(self.gangs) .map_err(OpError::Incomplete)?; diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md index 78e66c9..d8adcd0 100644 --- a/docs/design/INDEX.md +++ b/docs/design/INDEX.md @@ -378,6 +378,21 @@ and params and across both graph levels. This does **not** close #21 (a swapped same-kind wiring is still only kind-checked) — it makes those slots self-documenting; a name-consuming validation is its own future cycle. +**Realization (2026-07-11 — composite `doc`, #125).** `Composite` carries an +optional authored rationale `doc: Option` — the prose twin of its `name` +and the same C23 category: a non-load-bearing debug symbol. Authored via +`Composite::with_doc` / `GraphBuilder::doc`; persisted as a Tier-1 +additive-optional `CompositeData` field (no format-version bump; absent-field +documents keep their exact bytes, so existing content ids are untouched); +**blanked in the identity projection** (`strip_debug_symbols`) while staying +canonical-byte-bearing; dissolved at inline like the name (never reaches +`FlatGraph`). Surfaced read-only (C22): the graph model emits an optional +trailing `"doc"` fragment per scope (`json_str` hardened for multi-line free +text — `\n`/`\t`/`\r` named, other control chars as `\u00XX`), the viewer shows +it in both composite view states (collapsed tooltip, expanded cluster frame) and +the root's as a muted header line. The construction op-script vocabulary +deliberately has no doc-carrying surface yet (scope cut recorded on #125). + **Realization (cycle 0040 — wiring totality: every input slot connected exactly once, #65).** The node contract's "the engine provides a window into each input" presupposes each input is actually fed; until now an unwired interior input slot was @@ -1888,7 +1903,13 @@ pip (resolved from the recorded geometry sidecar (`instrument_geometry`) — C10 refuse-don't-guess; a symbol with no recorded geometry exits 2 before any data access), window, and — for walk-forward — its `WindowRoller` sizes (synthetic: bar-index 24/12/12; real: fixed calendar-time 90d/30d/30d in ns; CLI -flags for these are deferred). The engine, ingest, and registry are untouched (C9 — +flags for these are deferred). **[Amended 2026-07-11 (#239): on the dissolved +`walkforward --real`/`mc --real` sugar path the fixed 90/30/30 sizes are a +*ceiling*, not a constant — `fit_wf_ms_sizes` (aura-cli) passes them through +byte-identically whenever they fit the resolved campaign window, and scales them +down preserving the 3:1 IS:OOS ratio (step = OOS, one roll at the minimum) when +the window is shorter; authored process documents still validate their declared +sizes as-is.]** The engine, ingest, and registry are untouched (C9 — the whole change is in `aura-cli`); the synthetic path is byte-unchanged. **MC is excluded** (#106 Fork A): its seed varies a *synthetic* price-walk realization (C12 axis 4), which is undefined over real data's single realization — diff --git a/docs/glossary.md b/docs/glossary.md index b4fe71c..4f2820b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -61,7 +61,7 @@ The type-erased 64-bit word holding one scalar-base-type value with its kind str ### composite **Avoid:** — -A node that wires a sub-graph and exposes one output (a combined signal, or a strategy) — composition is fractal and acyclic. Also names the multi-column stream a node emits: the **record** a producer's `eval` returns, bundling 1..K base scalar columns (e.g. OHLCV), each bound field-wise by a consumer (C7/C8). +A node that wires a sub-graph and exposes one output (a combined signal, or a strategy) — composition is fractal and acyclic. May carry an optional authored rationale (`doc`, #125) — a non-load-bearing debug symbol shown in the graph tooltip, identity-blind like the name. Also names the multi-column stream a node emits: the **record** a producer's `eval` returns, bundling 1..K base scalar columns (e.g. OHLCV), each bound field-wise by a consumer (C7/C8). ### content id **Avoid:** — @@ -143,7 +143,7 @@ The authoring-loop mechanism in which the project-side cdylib is rebuilt and rel ### identity id **Avoid:** identity hash, topology-identity hash -The SHA-256 of a blueprint's identity-canonical form (`blueprint_identity_json`: the canonical document with every non-load-bearing debug symbol blanked — composite, instance, bound-param, role, and output names), surfaced as `aura graph introspect --identity-id`. Same topology → same id across authoring paths (op-script vs Rust builder, renamed twins) while openness, bound values, wiring, and order stay identity-bearing; an introspection-only comparison id — the byte-exact `content id` keeps the store/reproduce roles. +The SHA-256 of a blueprint's identity-canonical form (`blueprint_identity_json`: the canonical document with every non-load-bearing debug symbol blanked — composite, instance, bound-param, role, and output names, and the composite `doc`), surfaced as `aura graph introspect --identity-id`. Same topology → same id across authoring paths (op-script vs Rust builder, renamed twins) while openness, bound values, wiring, and order stay identity-bearing; an introspection-only comparison id — the byte-exact `content id` keeps the store/reproduce roles. ### ingestion boundary **Avoid:** —