docs: sync ledger cross-ref + glossary to the C10 rework (refs #116)
Follows the C10 rework (29cdc8c). C15: the deploy-grade geometry fields now defer
to the cost model's currency→R normalization / the live deploy edge, not the
retired Stage-2 realistic broker. Glossary: "realistic broker" and "Stage 1 /
Stage 2" marked superseded (kept as history); bias/broker/equity-stream/position-
table/R/R-metrics/R-evaluator/RiskExecutor/Sizer/sim-optimal-broker/veto reworked
to the cost-model-in-R model; added cost model, gross R, net R, net-R equity
curve, conviction-based risk allocation.
This commit is contained in:
@@ -957,8 +957,8 @@ removed that floor**: with the sidecar geometry supplying the real-path pip, the
|
||||
authored table was redundant, so `InstrumentSpec` / `instrument_spec` / the vetted
|
||||
list were deleted. The speculative deploy-grade fields and the override/floor tiers
|
||||
of the #124 hierarchy (tier 1 authored override, tier 3 authored floor) are
|
||||
**deferred** until a consumer — the Stage-2 realistic broker — needs them, read from
|
||||
the sidecar geometry then. The `quote_currency` runtime-type transition is likewise
|
||||
**deferred** until a consumer — the cost model's currency→R normalization (C10), or
|
||||
the live deploy edge (real broker) — needs them, read from the sidecar geometry then. The `quote_currency` runtime-type transition is likewise
|
||||
deferred to that consumer; #124 collapses to **recorded sidecar geometry → refuse**
|
||||
in the meantime.
|
||||
|
||||
|
||||
+35
-15
@@ -25,7 +25,7 @@ A single deterministic, synchronous run of one harness over historical input —
|
||||
|
||||
### 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*).
|
||||
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** — the protective stop lives downstream in the `RiskExecutor` (stop-rule → position-management, in R), never in the strategy, and sizing/fill are deploy concerns outside the research loop; it reframes the pre-reframe `exposure stream` (a signed fractional *position*).
|
||||
|
||||
### blueprint
|
||||
**Avoid:** —
|
||||
@@ -41,7 +41,7 @@ A frozen artifact that is a deployed strategy + broker: the live trading program
|
||||
|
||||
### 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.
|
||||
A downstream consumer node, never part of the strategy: the signal-quality side is the **R-evaluator** (per-trade R-outcomes from the in-R `RiskExecutor` → R-expectancy), read as **gross R** (signal) and **net R** (after the `cost model`). The historical in-graph **realistic broker** is retired (real friction is not historically knowable) — cost is approximated by the `cost model` (a C9 cost-graph, in R), and the only real broker is the **live deploy-edge I/O adapter** against an actual venue (e.g. cTrader Open API), the sole reliable ground truth (measured never modelled, C11/C13); account money lives only at that deploy edge.
|
||||
|
||||
### cdylib
|
||||
**Avoid:** —
|
||||
@@ -55,6 +55,14 @@ The type-erased 64-bit word holding one scalar-base-type value with its kind str
|
||||
**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).
|
||||
|
||||
### conviction-based risk allocation
|
||||
**Avoid:** —
|
||||
A feed-forward, order-independent research axis for scaling risk by bias strength — **flat** (sum of `realized_r`, sign only) vs **conviction-weighted** (sum of `|bias| · realized_r`) R-aggregation. Distinct from the deploy-only money-`Sizer`: because per-trade R is size-invariant, conviction is an **R-aggregation weight**, never a position-size scale (tested via `conviction_at_entry` / `conviction_terciles_r`).
|
||||
|
||||
### cost model
|
||||
**Avoid:** realistic broker
|
||||
A composable downstream **C9 graph of cost nodes**, in **R**, that **approximates** (never claims) a broker's cost: each cost node reads the state it depends on (price, realized-volatility, a C11-recorded rate source, the executor's per-trade R-records) and emits a **cost-in-R** stream subtracted from gross R to yield **net R** (per-trade factors deduct at close, per-cycle-held factors accrue over the hold). It generalizes / subsumes the scalar `round_trip_cost` (its degenerate constant-per-trade case), lives in `aura-std` / `aura-composites`, is optional (zero-cost baseline), and demands every factor be a labelled stress-parameter **or** data-grounded (over-modelling is the anti-pattern).
|
||||
|
||||
### 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.
|
||||
@@ -73,7 +81,7 @@ A directed wiring link in a harness that forwards **one field** (`from_field`) o
|
||||
|
||||
### 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).
|
||||
A downstream node's output over time — the headline form is the **net-R equity curve** (gross R minus the `cost model`'s cost-in-R, via the `net_r_equity` tap); currency equity is not a research artifact (it lives only at the live deploy edge). An equity *curve* is explicitly not a strategy's output (the `bias` stream is).
|
||||
|
||||
### experiment
|
||||
**Avoid:** —
|
||||
@@ -99,6 +107,10 @@ A node re-evaluates only when ≥1 of its own inputs is fresh this cycle; otherw
|
||||
**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.
|
||||
|
||||
### gross R
|
||||
**Avoid:** —
|
||||
The R-multiple outcome of the **signal alone** — per-trade R integrated by the R-evaluator with **no `cost model`** attached (the zero-cost baseline). `net R = gross R − cost-in-R` once a cost model is composed on.
|
||||
|
||||
### 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.
|
||||
@@ -127,6 +139,14 @@ An orchestration axis running N seeded realizations that perturb the input; each
|
||||
**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.
|
||||
|
||||
### net R
|
||||
**Avoid:** —
|
||||
**Gross R** after the `cost model`: `net R = gross R − cost-in-R`. The honest, cost-charged reading of signal quality, folded into `net_expectancy_r` (one home for cost, no double-count).
|
||||
|
||||
### net-R equity curve
|
||||
**Avoid:** —
|
||||
The headline research artifact: the R-equity curve with the `cost model`'s cost-drag drawn onto it (gross R minus cost-in-R), recorded through the named **`net_r_equity`** tap/sink (sibling of `r_equity`). A research / ranking **hypothesis**, never a claim of realism — the forward / live run against a real broker is the ground truth.
|
||||
|
||||
### 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.
|
||||
@@ -145,27 +165,27 @@ The egui-native visual face (`aura play`) that plays any harness — program str
|
||||
|
||||
### 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).
|
||||
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 **deploy / reconciliation** artifact (real volume), not a research artifact and not "fed to a broker" in research; computed, not emitted per `eval` (one decision instant may yield >1 event), and **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).
|
||||
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 research yardstick replacing pips, defined by the stop (Van Tharp R-multiples), read as **gross R** (signal only) and **net R** (after the `cost model`).
|
||||
|
||||
### 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.
|
||||
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 the `cost model`'s cost-in-R per trade — churn-honest; the scalar `round_trip_cost` is its degenerate constant-per-trade case, and it equals `expectancy_r` when no cost model is attached). 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.
|
||||
The signal-quality node: integrates the per-trade R-outcomes of the in-R `RiskExecutor` into an R-expectancy / R-curve — the deterministic, account-/instrument-agnostic yardstick — read as **gross R** (signal only) and **net R** once the `cost model` is composed on. 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).
|
||||
The per-symbol composite turning a bias into a managed position, **in R**: `stop-rule → position-management`, with the **Veto** an optional documented pre-trade-gate seam (a pass-through DCE'd away when absent). The research loop is **pure feed-forward** — **no Sizer**, no equity → size edge, no `z⁻¹` register (sizing/fill and any compounding feedback live at the live deploy edge, not here).
|
||||
|
||||
### 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).
|
||||
**Avoid:** — (retired)
|
||||
**Retired (2026-06-28 C10 reframe), replaced by the `cost model`.** The pre-reframe plan: an in-graph broker node applying authored historical friction (spread / commission / slippage / lot / margin) to emit a currency equity stream. Rejected as "horseshoe-throwing" — real friction is not historically knowable; cost is now approximated by the `cost model` (a C9 cost-graph, in R), and the only real broker is the **live deploy-edge I/O adapter** (measured, never modelled).
|
||||
|
||||
### resampler
|
||||
**Avoid:** —
|
||||
@@ -205,7 +225,7 @@ The disjoint, executable unit of one deterministic harness run; the unit of para
|
||||
|
||||
### 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.
|
||||
**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); post-2026-06-28 reframe `SimBroker` is retained only as a legacy / optional pip yardstick (redundant for quality, not to be expanded).
|
||||
|
||||
### sink
|
||||
**Avoid:** —
|
||||
@@ -213,7 +233,7 @@ A node in its **recording role**: in `eval` it reads its inputs (and `ctx.now()`
|
||||
|
||||
### 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.
|
||||
A **deploy** concept — sizing a trade in currency / lots from account equity — **not a research node**: per-trade R is **size-invariant** (size carries no information in R), so the Sizer and currency `size` / `volume` are removed from the research loop (the research executor is stop-rule → position-management in R). It owns size, not 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
|
||||
@@ -228,8 +248,8 @@ Anything that produces timestamped scalar streams — market data and non-financ
|
||||
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.
|
||||
**Avoid:** — (superseded)
|
||||
**Superseded (2026-06-28 C10 reframe): there is no Stage-2 currency/compounding gate.** Research is one pure feed-forward R loop — gross R → net R via the `cost model` — with money, compounding, and a real broker living only at a separate later **live / deploy edge** (compounding is a post-hoc money-management transform of the net-R sequence, not an in-loop axis). The pre-reframe cleave gated a Stage-2 currency / fixed-fractional / realistic-broker layer behind `E[R] > 0`; **"Stage-1"** now survives only as a historical cycle / identifier name for the shipped feed-forward R chain, not one half of a two-stage gate.
|
||||
|
||||
### strategy
|
||||
**Avoid:** —
|
||||
@@ -245,7 +265,7 @@ An orchestration axis varying tuning params (grid or random) within a fixed stru
|
||||
|
||||
### 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.
|
||||
The **optional** documented pre-trade-gate seam in the execution chain (`stop-rule → [Veto] → position-management`): position / exposure / notional caps that may reject or scale a trade. A pass-through identity DCE'd away when absent (C19/C23); kept as a named seam — it is what LEAN calls "Risk Management" and nautilus the RiskEngine.
|
||||
|
||||
### walk-forward
|
||||
**Avoid:** —
|
||||
|
||||
Reference in New Issue
Block a user