From 197936b27d92f6f8c2680c29f453a672b418dda7 Mon Sep 17 00:00:00 2001 From: Brummel Date: Sat, 4 Jul 2026 01:56:48 +0200 Subject: [PATCH] docs: annotator-stage discoverability tightens (fieldtest 0108 F7/F9/F10) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The std::monte_carlo block doc now names the position-dependent semantics (pooled OOS after wf / per-survivor otherwise) and the > 0 execution guard the generic u32 slot hint could not carry; the std::generalize block doc names campaign scope, the >= 2-instrument need, and the R-expectancy metric family. Glossary: new 'stage bootstrap' entry defines the realization payload incl. prob_le_zero; the campaign-run entry gains the generalizations schema and the stdout-wrapper-vs-bare-store-line note. Introspection text and glossary only — no document content id moves. Gates: workspace green, clippy clean. refs #200 --- crates/aura-research/src/lib.rs | 9 +++++++-- docs/glossary.md | 6 +++++- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/crates/aura-research/src/lib.rs b/crates/aura-research/src/lib.rs index 1c6788c..ef0a075 100644 --- a/crates/aura-research/src/lib.rs +++ b/crates/aura-research/src/lib.rs @@ -188,7 +188,10 @@ pub const PROCESS_BLOCKS: &[BlockSchema] = &[ }, BlockSchema { id: "std::monte_carlo", - doc: "R-bootstrap over realised R (terminal annotator)", + doc: "R-bootstrap over realised R (terminal annotator): after a \ + walk_forward, ONE bootstrap over its pooled OOS trade series; \ + otherwise one per surviving member; both slots must be > 0 to \ + execute", slots: &[ SlotInfo { name: "resamples", kind: SlotKind::U32, required: true }, SlotInfo { name: "block_len", kind: SlotKind::U32, required: true }, @@ -196,7 +199,9 @@ pub const PROCESS_BLOCKS: &[BlockSchema] = &[ }, BlockSchema { id: "std::generalize", - doc: "cross-instrument worst-case floor (terminal annotator)", + doc: "cross-instrument worst-case floor (terminal annotator): runs at \ + campaign scope, per (strategy, window) over the cells' nominees; \ + needs >= 2 instruments and an R-expectancy metric to execute", slots: &[SlotInfo { name: "metric", kind: SlotKind::MetricName, required: true }], }, ]; diff --git a/docs/glossary.md b/docs/glossary.md index 04f8fcb..5943aa0 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -49,7 +49,7 @@ The role-6b research artifact (#188/#189): persisted experiment intent as closed ### campaign run **Avoid:** campaign execution record, realized campaign -One execution of a `campaign document` (`aura campaign run `; a file is register-then-run sugar — the content id is the canonical address). Realized once per (strategy, instrument, window) cell in doc order and recorded as a thin `CampaignRunRecord` line in the registry's `campaign_runs.jsonl` — linking the per-stage family ids and gate survivor ordinals over untouched family records, run-counted per campaign id. A cell whose gate leaves no survivors records its realized prefix and the run exits 0: a null result is a valid research result. Deterministic from doc + stores + data (C1): deflation nulls seed from the doc's `seed`. +One execution of a `campaign document` (`aura campaign run `; a file is register-then-run sugar — the content id is the canonical address). Realized once per (strategy, instrument, window) cell in doc order and recorded as a thin `CampaignRunRecord` line in the registry's `campaign_runs.jsonl` — linking the per-stage family ids, gate survivor ordinals, `stage bootstrap` annotations, and (campaign-scope, per strategy × window) `generalizations` entries (`generalization` with `worst_case`/`sign_agreement`/`per_instrument`, plus `winners` params and `missing` instruments on shortfall) over untouched family records, run-counted per campaign id. A cell whose gate leaves no survivors records its realized prefix and the run exits 0: a null result is a valid research result. Deterministic from doc + stores + data (C1): deflation and bootstrap nulls seed from the doc's `seed`. NB the stdout emit wraps each record as `{"campaign_run": …}`; the stored `campaign_runs.jsonl` line is the bare record. ### cdylib **Avoid:** — @@ -251,6 +251,10 @@ The disjoint, executable unit of one deterministic harness run; the unit of para **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. +### stage bootstrap +**Avoid:** mc annotation, bootstrap record +The `std::monte_carlo` stage's realization payload (0108/#200): a moving-block `r_bootstrap` of the stage's incoming R-evidence, recorded on the stage's `StageRealization` in one of two shapes — `pooled_oos` (ONE bootstrap over the preceding walk-forward's per-window OOS trade-R series, pooled in roll order) or `per_survivor` (`[ordinal, bootstrap]` per surviving member over its full in-sample series; ordinals index the population family). Each bootstrap carries `e_r` (quantiles of the resampled E[R] distribution), `prob_le_zero` = P[bootstrap E[R] ≤ 0], `n_trades`, `block_len`, `n_resamples`; seeded from the campaign doc's `seed` (C1). A zero-trade input records the defined all-zero degenerate — a null result is a valid research result. + ### Sizer **Avoid:** risk-manager 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).