Brummel
3e8fd73f68
Resolves the four non-bug findings from the inferential-validation milestone
fieldtest (the bug — the broken-pipe panic — is fixed in 1088320):
- [friction] generalize refusals now carry a reason instead of a bare usage dump:
<2 instruments, a multi-value candidate flag, a missing knob, a duplicate
symbol, and a non-stage1-r strategy each get a one-line why (mirroring the
R-only metric refusal). Two parser tests strengthened to pin the message.
- [friction] --select <argmax|plateau:mean|plateau:worst> added to the
walkforward branch of the global USAGE (aura --help) — the plateau objective
was undiscoverable from the only help the CLI prints (the per-subcommand usage
already carried it).
- [spec_gap] C1 gains a scope note: bit-identity is per-run; a derived metric
recomputed by two different command paths may differ by floating-point
reassociation (<=1 ULP), which is not a C1 violation — ratifies the
fieldtester's reading of the sweep-vs-generalize sqn difference.
- [spec_gap] the milestone vocabulary is added to docs/glossary.md:
cross-instrument generalization, deflated score, overfit probability,
neighbourhood score, plateau selection, sign-agreement, worst-case floor.
The fieldtest triage spec (docs/specs/fieldtest-*) is removed now its findings
are resolved; the tracked fieldtests/ scenario corpus stays.
Verified: cargo test --workspace green (0 failed), clippy --workspace
--all-targets -D warnings clean; `aura --help` shows --select; the refusals
print their reason.
refs #146
261 lines
20 KiB
Markdown
261 lines
20 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).
|
||
|
||
### bias
|
||
**Avoid:** exposure, exposure stream, intent stream
|
||
A strategy's primary, backtestable DAG output: one signed, bounded `f64 ∈ [-1,+1]` per cycle whose **sign is direction and magnitude is conviction** (conviction optional). Bias is **unsized** — sizing and the protective stop live downstream in the risk-based execution layer (`Sizer`/`RiskExecutor`), never in the strategy; it reframes the pre-reframe `exposure stream` (a signed fractional *position*).
|
||
|
||
### 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 emits an equity stream, never part of the strategy. The signal-quality side is the **R-evaluator** (Stage 1: per-trade R-outcomes from a flat-1R `RiskExecutor` → R-expectancy); **realistic brokers** (Stage 2) consume the derived **position-event table** (real frictions → currency equity), and a **Broker/Account** composite aggregates per-symbol P&L into account equity. Several can attach at once for directly comparable curves.
|
||
|
||
### 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.
|
||
|
||
### cell
|
||
**Avoid:** —
|
||
The type-erased 64-bit word holding one scalar-base-type value with its kind stripped off (`crates/aura-core/src/cell.rs`): the type lives at the schema/column/port, so a cell is read only by naming it via a branch-free accessor (`i64()`/`f64()`/`bool()`/`ts()`). A bare cell is what the SoA hot path reads without a per-value branch, whereas a `Scalar` — the self-describing tagged union of the four base types, used at the dynamic boundaries — is its disjoint counterpart, bridged by `Scalar::cell` (encode) / `Scalar::from_cell` (decode).
|
||
|
||
### 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).
|
||
|
||
### cross-instrument generalization
|
||
**Avoid:** cross-symbol pooling, pooled generalization
|
||
The validation read that grades how consistently one *brought* candidate holds across a set of instruments, scored on its weakest one — the across-instrument axis of the anti-false-discovery discipline. Realised by `aura generalize`; an aggregator (a recomputable family score), never a selector that picks a winner.
|
||
|
||
### 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.)
|
||
|
||
### deflated score
|
||
**Avoid:** trials-adjusted score
|
||
A sweep winner's metric penalised for the number of configurations tried (trials-deflation), recorded additively on the winning member's `selection` without changing which member won. Paired with an **overfit probability**; the across-trials defence against a winner that is luck at sweep scale.
|
||
|
||
### 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 downstream node's output over time — an **R-curve** for the R-evaluator (Stage 1, its per-trade R integral), **currency** for realistic brokers (Stage 2). An equity *curve* is explicitly not a strategy's output (the `bias` stream 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.
|
||
|
||
### exposure stream
|
||
**Avoid:** — (superseded)
|
||
**Superseded by `bias` (2026-06 R-reframe).** The pre-reframe primary output: a signed, bounded `f64 ∈ [-1,+1]` per cycle read as the desired fractional *position* (conflating direction + conviction + size). Reframed to `bias` (unsized direction + conviction), sizing moved downstream to the `Sizer`/`RiskExecutor`; the term and the `Exposure` node persist in pre-reframe code until the Stage-1 rename.
|
||
|
||
### 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).
|
||
|
||
### neighbourhood score
|
||
**Avoid:** smoothed score
|
||
The metric of a sweep cell averaged (or worst-cased) over its closed grid neighbourhood — the surface a **plateau selection** argmaxes instead of the bare peak. Recorded on a plateau winner's `selection` alongside its neighbour count.
|
||
|
||
### node
|
||
**Avoid:** block
|
||
The universal composable dataflow unit, implementing `lookbacks()` + `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.
|
||
|
||
### overfit probability
|
||
**Avoid:** P(overfit), luck probability
|
||
The recorded chance that a deflated sweep winner is noise rather than edge — a rank of the winner's metric against a centred no-edge null over the family. Paired with the **deflated score** on the winner's `selection`.
|
||
|
||
### plateau selection
|
||
**Avoid:** plateau-over-peak (as a noun)
|
||
A selection objective that argmaxes the neighbourhood-smoothed metric surface (mean or worst-case) rather than the bare in-sample peak, preferring a robust parameter plateau to a lucky spike. Opt-in via `--select plateau:mean|plateau:worst`; the default selection stays a bare argmax.
|
||
|
||
### 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 broker-independent, time-ordered table of position events (scalar columns: `event_ts, action, position_id, instrument_id, volume`) — the **derived** first difference of the executed **book** (book-tracking `deal = target − book − in_flight`; a close sizes the actual book), a **decoupled** Stage-2 position-management layer feeding realistic brokers / deploy. Computed, not emitted per `eval` (one decision instant may yield >1 event); **not** the strategy's direct DAG output (that is the `bias` stream).
|
||
|
||
### R
|
||
**Avoid:** —
|
||
The native unit of strategy performance: 1R = the loss if the protective stop is hit, so a trade's outcome is a multiple of R (−1R stopped out, +2R, …) and the primary question is *"how much R out per 1R risked?"*. Risk-normalized and account-/instrument-agnostic — the Stage-1 yardstick replacing pips, defined by the stop (Van Tharp R-multiples).
|
||
|
||
### R metrics
|
||
**Avoid:** —
|
||
The R-multiple summary metrics `summarize_r` folds into `RunMetrics.r`, which double as the higher-is-better rank vocabulary for `aura runs family <id> rank <metric>` (cycle 0066): **`sqn`** (the System Quality Number — see SQN), **`sqn_normalized`** (the n-normalized SQN100 — see SQN; cycle 0067), **`expectancy_r`** (mean realized R per trade, the headline E[R]), and **`net_expectancy_r`** (expectancy net of one round-trip cost per trade — churn-honest; equals `expectancy_r` while Stage 1 is frictionless). A family member with no `r` block ranks last under any of them, so a pip-only family ranked by an R metric falls back to ordinal order.
|
||
|
||
### R-evaluator
|
||
**Avoid:** —
|
||
The Stage-1 signal-quality node: integrates the per-trade R-outcomes of a flat-1R `RiskExecutor` into an R-expectancy / R-curve — the deterministic, account-/instrument-agnostic yardstick. The R-reframe successor of the `sim-optimal broker` (pip integral); unlike it the R-evaluator requires a stop, so it consumes a RiskExecutor, not raw bias.
|
||
|
||
### RiskExecutor
|
||
**Avoid:** risk-manager
|
||
The per-symbol composite turning a bias into a managed position — `stop-rule → Sizer → Veto → position-management` — with the only feedback (equity → Sizer, Stage 2) cut by a `z⁻¹` register on the fill edge and encapsulated inside. RiskExecutors nest in a Broker/Account composite that aggregates per-symbol P&L into account equity; the account mode (netting/hedging) constrains how many exist per (strategy, symbol).
|
||
|
||
### realistic broker
|
||
**Avoid:** —
|
||
A Stage-2 broker node that consumes the derived position-event table and 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 R-evaluator (Stage 1, which consumes a flat-1R RiskExecutor and measures signal quality in R).
|
||
|
||
### 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.
|
||
|
||
### sign-agreement
|
||
**Avoid:** sign consistency
|
||
In a cross-instrument generalization, the count of instruments on which the candidate's R-metric is net positive. Reported beside the **worst-case floor** to express consistency of direction across instruments.
|
||
|
||
### signal
|
||
**Avoid:** —
|
||
A node whose output is a score, feeding the `signals (scores) → decision node → bias stream` 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:** —
|
||
**Pre-reframe term, succeeded by the `R-evaluator`.** The deterministic, frictionless, perfect-fill broker (`SimBroker`) that consumes the **exposure stream** + prices and integrates `exposure·return` into synthetic pip equity to measure signal quality. The R-reframe replaces pips with R (the R-evaluator integrates per-trade R-outcomes from a flat-1R RiskExecutor); `SimBroker` persists in pre-reframe code until the Stage-1 rename.
|
||
|
||
### sink
|
||
**Avoid:** —
|
||
A node in its **recording role**: in `eval` it reads its inputs (and `ctx.now()`) and pushes the record to an out-of-graph destination it holds as a field (a channel, a chart handle, the run registry) — a role, not a type, so a node may be a pure consumer (no output) or record *and* forward an output in the same `eval` (the C8 "both" case). The sole recording and observability mechanism: displayable = exactly what a sink recorded.
|
||
|
||
### Sizer
|
||
**Avoid:** risk-manager
|
||
The node that sizes a trade from bias + the stop — in R (flat-1R, Stage 1) or in lots from account equity (fixed-fractional, Stage 2) — owning the size, not the direction (bias) or the gate (Veto). "risk-manager" is avoided: in LEAN/nautilus that names the Veto layer, not the sizer.
|
||
|
||
### 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.
|
||
|
||
### SQN
|
||
**Avoid:** system-quality-number (spell out once, then SQN)
|
||
System Quality Number — `√n · mean_R / stdev_R`: the dispersion- and trade-count-aware single-number objective for ranking a sweep family by R signal quality (cycle 0066; van Tharp). Higher is better; `n < 2` or zero-variance → 0. One of the R metrics. Its n-normalized variant **`sqn_normalized`** (SQN100 = `(mean_R / stdev_R) · √(min(n, 100))`, van Tharp's trade-count cap at 100) is turnover-robust across members with different trade counts and equals `sqn` below the cap (cycle 0067, #130).
|
||
|
||
### Stage 1 / Stage 2
|
||
**Avoid:** —
|
||
The two-stage cleave of evaluation: **Stage 1** (R / signal quality) is flat-1R, feed-forward (no equity feedback), measured by the R-evaluator in R-expectancy — the primary research loop; **Stage 2** (currency / deploy viability) is fixed-fractional sizing that reads equity and compounds, with realistic brokers and real frictions, entered only once `E[R] > 0`. The cleave quarantines the only feedback into Stage 2 (flat-1R vs compounding is a structural axis, C11); aura's own synthesis, closest precedent vectorbt's signal vs money-management split.
|
||
|
||
### strategy
|
||
**Avoid:** —
|
||
A reusable composite-node blueprint — broker-, data-, and viz-independent, inputs declared as named roles — whose output is the **bias** stream (unsized direction + conviction; not an equity curve, not a size; sizing and the position table are derived downstream layers). 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.
|
||
|
||
### veto
|
||
**Avoid:** risk-manager
|
||
The distinct pre-trade gate in the execution chain (`… → Sizer → Veto → position-management`): position / exposure / notional caps that may reject or scale a sized intent before it reaches the broker. Kept separate from the Sizer — it is what LEAN calls "Risk Management" and nautilus the RiskEngine.
|
||
|
||
### 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.
|
||
|
||
### worst-case floor
|
||
**Avoid:** min-over-instruments
|
||
The headline cross-instrument generalization score: the minimum of a candidate's R-metric across the instruments, so a single strong market cannot flatter it (non-dominable by construction). The cross-instrument sibling of a worst-case **plateau selection**.
|