diff --git a/crates/aura-engine/src/lib.rs b/crates/aura-engine/src/lib.rs index a6da1c0..d254819 100644 --- a/crates/aura-engine/src/lib.rs +++ b/crates/aura-engine/src/lib.rs @@ -3,7 +3,9 @@ //! Home of (to be specified): the ingestion boundary (k-way merge of timestamped //! sources into one chronological cycle stream), the deterministic synchronous //! single-threaded sim loop (one unique state per input tick), freshness-gated -//! recompute, the broker/portfolio node mechanics, and the atomic sim unit +//! recompute, the strategy's broker-independent position-event output and the +//! downstream broker plugins that project it into equity (sim-optimal pip / +//! realistic currency), and the atomic sim unit //! `(topology + params + data-window + seed) -> metrics` that the sweep / //! optimize / walk-forward / Monte-Carlo axes orchestrate. //! diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md index f62be01..9565332 100644 --- a/docs/design/INDEX.md +++ b/docs/design/INDEX.md @@ -8,8 +8,8 @@ its new rationale), never a silent refactor. Provenance: contracts C1–C18 were settled in the initial rough-sketch design interview (2026-06-03), walking the design tree root-to-leaf (C16–C18 and the C10 refinement to a broker-independent position table came in follow-up turns). -The `CLAUDE.md` -**Domain invariants** section is the compressed, always-loaded summary of the +The `CLAUDE.md` **Domain invariants** section is the compressed, always-loaded +summary of the subset that agents must never violate; this file is the fuller form with rationale. @@ -61,8 +61,10 @@ leaks the future is worse than none. Making the future *physically absent* from what a node receives beats merely discouraging it. ### C3 — One merge, at ingestion only -**Guarantee.** Heterogeneous timestamped sources are k-way-merged by `time_ms` -into one chronological cycle stream at the ingestion boundary. +**Guarantee.** Heterogeneous timestamped sources are k-way-merged by timestamp +into one chronological cycle stream at the ingestion boundary; source-native +time units (e.g. data-server's Unix-`time_ms`) are normalized there to the +canonical epoch-ns `timestamp` of C7. **Forbids.** Any merge / as-of join *inside* the graph. **Why.** A single ordered timeline is the mechanism that makes heterogeneous-rate sources (news daily-bias + M5 + ticks) causally combinable without leaking the @@ -117,9 +119,12 @@ required lookback depth, and firing group) + `eval(ctx) -> Option`. The engine provides read-only, zero-copy windows into each input's SoA ring buffer (`ctx.f64_in(x)[k]`, sized at wiring); a node may *additionally* keep its own mutable series for derived/intermediate state. `None`/Void return = filter / -not-yet-warmed-up. A node has exactly one output (one series per node). -**Forbids.** A node sizing/growing its input lookback at runtime; multiple named -outputs per node (model as multiple nodes); copy-on-read of input history. +not-yet-warmed-up. A node is a **producer, a consumer, or both**: a +producer/transformer exposes **at most one** output (one series per node); a +**pure consumer (sink)** — chart, equity, logger — has **no** output. Sources +are pure producers; sinks are pure consumers. +**Forbids.** A node sizing/growing its input lookback at runtime; more than one +output per node (model as multiple nodes); copy-on-read of input history. **Why.** Engine-provided windows mean LLM-authored code cannot mis-manage lookback bookkeeping, and history passes through zero-copy. Fixed, pre-sized buffers suit deterministic, pre-dimensioned sims (no realloc in the hot loop).