Brummel
57310b83c7
Architect drift review over 9ff90b5..5228542 (node-output-record): drift_found,
all low-severity, NO contract violation. The load-bearing invariants hold:
- C7 forbids intact — the reused `scratch` buffer (cleared+extended, warm after
cycle 1) and node-owned `[Scalar; K]` output buffers give zero per-cycle heap
alloc on the inter-node forward path; no fifth scalar type, no dyn-Any, no
heterogeneous buffer (the TwoField mixed-kind producer is rejected at bootstrap,
never streamed). Purity grep clean. The sharpened C7 guarantee text matches the
shipped per-field kind check + the Edge::from_field scatter.
- C8 revised text faithful — one output port (out_len), record of 1..K columns
(Vec<FieldSpec>), field-wise binding only (N edges, no whole-record bind), scalar
= degenerate K=1. No internal contradiction with C7/C9/C10.
- C6 untouched, verified against the run loop — one eval per node per cycle, every
out-edge stamps SlotState { fresh_at: cycle_id, last_ts: ts } with the same ts,
so the K fields of one record are co-fresh by construction. fires() unchanged.
- C3/C4/C5/C9 unperturbed (diff touches only node/edge plumbing); C2 lookback
enforcement unperturbed (column.rs/ctx.rs/any.rs not in the diff).
- C10 coherence confirmed — a position event is a 5-field record
(event_ts/action/position_id/instrument_id/volume), exactly the K-field
base-column record C8/C7 now sanction; the decision/sizing node is an ordinary
K=5 producer, the broker an N-edge field-wise consumer. No contract gap blocks
the next consumer; C10 correctly out of scope this cycle.
Resolved [low] (the one confirmed drift) — glossary record-reality. The ledger
C7/C8 moved this cycle but the glossary lagged. Fixed three entries to the
post-0005 reality (this is audit's autonomous glossary write authority,
record-reality only): `node` ("at most one output" -> "at most one output port; a
producer's output is a record of 1..K base-scalar columns, scalar = degenerate
K=1"), `composite` (now connects the multi-column stream to the node-output model
— the record a producer's eval returns, bound field-wise), `edge` (forwards "one
field (from_field) of a producer's eval output record", per-field kind check).
The architect named `node` + `composite`; `edge` is an orchestrator-observed
addition in the same record-reality pass (post-from_field it read "forwards one
node's eval output", now imprecise for K>1).
Regression gate: profile regression list empty — architect is the sole gate, now
clean (36 tests: aura-core 19 + aura-std 3 + aura-engine 14; clippy -D warnings
clean; purity grep clean). Cycle 0005 is drift-clean.
Carry-on forward note (next-cycle owner, not a fix now):
- [low] cycle 0004's depth>1 join-lookback guard test remains merely OWED, not a
fresh hole — the substrate enforces it via Window bounds (column.rs/ctx.rs
untouched this cycle) and 0005 added no depth>1 join. Co-fresh borrowed-row
routing does not interact with per-input lookback. A confirmation test is still
owed when a depth>1 join lands.
NOT a milestone close: the walking-skeleton milestone still needs its end-to-end
fieldtest (ingest -> signal -> backtest -> position table -> broker -> pip-equity).
This cycle delivers the record-output substrate that the trading half (C10) now
builds on.
refs walking-skeleton
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
189 lines
12 KiB
Markdown
189 lines
12 KiB
Markdown
# aura glossary
|
||
|
||
Canonical nomenclature for aura's domain. This file is the source of truth for
|
||
naming: where another document names a concept differently, the canonical entry
|
||
and its **Avoid** list win. Rules (format, reading obligation, write discipline)
|
||
live in the skills glossary convention; this file is an instance of it.
|
||
|
||
Each block has three fields: a canonical-term heading, an `**Avoid:**` line
|
||
(synonyms that must not be used; `—` when none), and a ≤2-sentence definition.
|
||
Entries are alphabetical.
|
||
|
||
---
|
||
|
||
### atomic sim unit
|
||
**Avoid:** atomic unit, sim unit
|
||
The primitive `(frozen topology + param-set + data-window + RNG-seed) → deterministic run → metrics` over which the four orchestration axes operate. One frozen-topology unit equals one harness instance.
|
||
|
||
### Aura.toml
|
||
**Avoid:** —
|
||
The per-project declarative config holding only static context (data paths, instrument/pip metadata, default broker & window, runs dir), never logic. Its presence marks the project root, the way `Cargo.toml` marks a cargo crate.
|
||
|
||
### backtest
|
||
**Avoid:** —
|
||
A single deterministic, synchronous run of one harness over historical input — the historical-replay framing of an execution. The commodity substrate the World builds families of; distinct from `sim` (the executable unit) and `run` (its registry record).
|
||
|
||
### blueprint
|
||
**Avoid:** —
|
||
The param-generic, input-role-generic graph-as-data produced by running a Rust builder; it carries free numeric params and free input roles before bootstrap. Bootstrapped into a frozen instance by binding params + data + seed.
|
||
|
||
### bootstrap
|
||
**Avoid:** —
|
||
The distinct, recursive construction phase that binds `(blueprint + param-set + data bindings + seed)` into a frozen instance — buffers sized, topology fixed. The explicit name for the "wiring / graph build" that C7/C12 reference.
|
||
|
||
### bot
|
||
**Avoid:** —
|
||
A frozen artifact that is a deployed strategy + broker: the live trading program (audit trail: this bot = this commit). Every bot is a frozen artifact, but not every frozen artifact is a bot.
|
||
|
||
### broker
|
||
**Avoid:** —
|
||
A downstream consumer node that consumes the position table (plus the relevant price streams) and emits an equity stream; several can attach to one position table at once for directly comparable curves. Two classes: the sim-optimal broker and realistic brokers.
|
||
|
||
### cdylib
|
||
**Avoid:** —
|
||
The dynamically-loadable Rust library form of a project and its nodes, hot-reloaded during authoring; the hot-reload unit is always the project-side cdylib. Frozen to a static artifact for deploy.
|
||
|
||
### 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).
|
||
|
||
### cycle
|
||
**Avoid:** —
|
||
One data-driven clock step: one input record = one cycle, advanced in global timestamp order with a monotonic `cycle_id`. (In the pipeline-process sense "cycle" also names one milestone round; the engine sense is this clock step.)
|
||
|
||
### edge
|
||
**Avoid:** —
|
||
A directed wiring link in a harness that forwards **one field** (`from_field`) of a producer node's `eval` output record into a consumer node's input slot (the engine's `Edge`); the source-side variant binding the source value into an input slot is a **source target** (`Target`). Edges define the DAG the bootstrap topologically orders; a per-field scalar-kind mismatch across an edge is rejected at bootstrap.
|
||
|
||
### equity stream
|
||
**Avoid:** —
|
||
A broker node's output: the marked value of open positions over time — synthetic pips for the sim-optimal broker, currency for realistic brokers. An equity *curve* is explicitly not a strategy's output (the position table is).
|
||
|
||
### experiment
|
||
**Avoid:** —
|
||
A Rust (builder-API) definition of anything beyond a single backtest — sweep, Monte-Carlo, walk-forward, or a structural matrix; it lives in a project's `experiments/`. Authored in native Rust, never a config DSL.
|
||
|
||
### experiment matrix
|
||
**Avoid:** structural matrix
|
||
The set of harness instances produced by varying the structural axes (strategy × instrument × broker × window), expressed as plain Rust loops. The outer orchestration over the structural dimension; the tuning sweep is the inner loop.
|
||
|
||
### firing policy
|
||
**Avoid:** —
|
||
A per-input-group declaration of one of two firing modes: A = fire-on-any-fresh + hold (as-of join), B = all-fresh barrier (synchronizing join). A single node may mix an A input and a B group.
|
||
|
||
### freshness-gated recompute
|
||
**Avoid:** freshness-gating
|
||
A node re-evaluates only when ≥1 of its own inputs is fresh this cycle; otherwise it holds its last output (sample-and-hold). Stale inputs contribute their last held value, not a missing one.
|
||
|
||
### frozen artifact
|
||
**Avoid:** deploy artifact, standalone binary
|
||
A statically-linked, versioned, frozen build, never hot-swapped (audit trail: this artifact = this commit). The general category; a `bot` is the specific case of a deployed strategy + broker.
|
||
|
||
### harness
|
||
**Avoid:** root sim graph, root graph, root scope
|
||
The closed root sim graph that actually runs — sources bound to a strategy's roles + the strategy + broker node(s) + sinks under a clock; C1's disjoint unit. It is not a node (no free inputs, no output); "root scope" is RustAst's name for it.
|
||
|
||
### hot-reload
|
||
**Avoid:** —
|
||
The authoring-loop mechanism in which the project-side cdylib is rebuilt and reloaded live during research; authoring-only, never applied to a live bot. A sweep pays no hot-reload tax — params are runtime data, so the cdylib loads once.
|
||
|
||
### ingestion boundary
|
||
**Avoid:** —
|
||
The single point where heterogeneous timestamped sources are k-way-merged into one chronological cycle stream and source-native time is normalized to canonical epoch-ns. The only place a merge happens — there is no merge or as-of join inside the graph.
|
||
|
||
### instance
|
||
**Avoid:** —
|
||
A concrete, frozen graph produced by binding a blueprint to params + data + seed — buffers sized, topology fixed. A sweep builds many disjoint instances from one blueprint.
|
||
|
||
### manifest
|
||
**Avoid:** —
|
||
The reproducible metadata record of a run (node-commit + params + data-window + seed + broker profile), paired with metrics in the run registry. Determinism lets the full result be re-derived from this tiny record on demand.
|
||
|
||
### Monte-Carlo
|
||
**Avoid:** MC
|
||
An orchestration axis running N seeded realizations that perturb the input; each realization is itself deterministic given its seed (Monte-Carlo = sweep over seeds).
|
||
|
||
### node
|
||
**Avoid:** block
|
||
The universal composable dataflow unit, implementing `schema()` + `eval(ctx)` — a producer, a pure consumer (sink), or both — with at most one output port; a producer's output is a **record of 1..K base-scalar columns** (a scalar is the degenerate K=1 case). Everything that plugs into the engine is fractally a node.
|
||
|
||
### playground
|
||
**Avoid:** —
|
||
The egui-native visual face (`aura play`) that plays any harness — program structure before a run, live sink streams during, recorded traces and meta-views after. A trace explorer / execution viewer, never a scene editor.
|
||
|
||
### position table
|
||
**Avoid:** —
|
||
A strategy's broker-independent, time-ordered table of position events (scalar columns: `event_ts, action, position_id, instrument_id, volume`). The set of open positions at time t is the strategy's state; brokers are the downstream consumers of this table.
|
||
|
||
### realistic broker
|
||
**Avoid:** —
|
||
A broker node that applies real spread / commission / slippage / lot / margin (and may reject or modify positions), emitting a currency equity stream for viability and deploy. Contrasted with the sim-optimal broker.
|
||
|
||
### resampler
|
||
**Avoid:** —
|
||
A node that converts a finer stream to a coarser bar stream, emitting a completed bar only at the boundary so no partial bar ever leaks (enforcing no look-ahead). Clock-sensitive.
|
||
|
||
### run
|
||
**Avoid:** —
|
||
One execution recorded in the run registry as a manifest + metrics — the registry-record framing of an execution. Distinct from `sim` (the executable unit) and `backtest` (the replay framing).
|
||
|
||
### run registry
|
||
**Avoid:** registry, runs dir
|
||
The aura-native, per-project store of one record per run — a manifest + metrics, queryable, with lineage (composite ← signals; run ← inputs). It lives under `runs/` and is the World's memory.
|
||
|
||
### run-count
|
||
**Avoid:** total_count
|
||
The per-series push counter on every `Column` — bumped on each push, never moved by a read; the node-visible freshness primitive. The engine's per-cycle firing gate (C5/C6) reads a per-wiring-slot cycle epoch (`fresh_at == cycle_id`, the freshness epoch C4's cycle_id materializes as) rather than this counter, which remains the column-level count a node may read for its own logic. ("total_count" is RustAst's name for the same counter.)
|
||
|
||
### scalar base types
|
||
**Avoid:** —
|
||
The four streamed scalar kinds — `i64`, `f64`, `bool`, `timestamp` (a newtype over i64, epoch-ns UTC) — the only payloads on the hot path. Non-scalars (String, records, tables, calendars) live as metadata beside it, never in it.
|
||
|
||
### session node
|
||
**Avoid:** —
|
||
A node that exposes session context as scalar streams (`bars_since_open`, `in_session`, `session_open_ts`) so session logic stays inside the stream model. Calendars and instrument specs remain metadata beside the hot path.
|
||
|
||
### signal
|
||
**Avoid:** —
|
||
A node whose output is a score, feeding the `signals (scores) → decision/sizing node → position events` chain. A specific node role — distinct from a general node and from a strategy.
|
||
|
||
### sim
|
||
**Avoid:** —
|
||
The disjoint, executable unit of one deterministic harness run; the unit of parallelism (parallelism is *across* sims, never within one). Distinct from `backtest` (the replay framing) and `run` (the registry record).
|
||
|
||
### sim-optimal broker
|
||
**Avoid:** —
|
||
The deterministic, frictionless, perfect-fill broker that emits synthetic equity in pips — the neutral, currency-free yardstick for comparing and optimizing strategy logic. Distinct from the Aura.toml "default broker" (a config role) and from realistic brokers.
|
||
|
||
### sink
|
||
**Avoid:** —
|
||
A pure consumer node with no output that persists a stream (equity, position events, a node's output) into the run registry. The sole recording and observability mechanism: displayable = exactly what a sink recorded.
|
||
|
||
### SoA
|
||
**Avoid:** Structure-of-Arrays
|
||
The columnar Structure-of-Arrays layout in which the four scalar base types are streamed on the hot path. Composite streams are bundles of base columns; the layout is what makes streaming cache- and SIMD-friendly.
|
||
|
||
### source
|
||
**Avoid:** —
|
||
Anything that produces timestamped scalar streams — market data and non-financial feeds (e.g. a news-bias node) are treated identically; a pure producer node. `data-server` is aura's first source.
|
||
|
||
### strategy
|
||
**Avoid:** —
|
||
A reusable composite-node blueprint — broker-, data-, and viz-independent, inputs declared as named roles — whose output is the position table (not an equity curve). Frozen with a broker into a bot for deploy.
|
||
|
||
### structural axes
|
||
**Avoid:** —
|
||
The harness's structural parameterization — which strategy, instrument(s), broker(s), window — whose variation selects *different* instances; together they form the experiment matrix. Contrasted with tuning params (numeric params swept within a fixed structure).
|
||
|
||
### sweep
|
||
**Avoid:** param-sweep, parameter sweep
|
||
An orchestration axis varying tuning params (grid or random) within a fixed structure. The inner, param-tuning loop, distinct from the structural experiment matrix.
|
||
|
||
### walk-forward
|
||
**Avoid:** —
|
||
An orchestration axis: rolling in-sample optimize + out-of-sample test across moving windows, stitched into one out-of-sample verdict plus parameter stability.
|
||
|
||
### World
|
||
**Avoid:** —
|
||
The project's meta-level program that dynamically constructs and orchestrates *families* of harnesses (walk-forward / sweep / optimize / Monte-Carlo / comparison). aura's differentiator and product, as opposed to the single-backtest substrate.
|