diff --git a/README.md b/README.md index 77dd533..2c9c077 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,9 @@ Invoke it as `aura …` (examples below use the plain name). ## Running & orchestrating a loaded blueprint These verbs all take the **blueprint file as their first positional argument** -and drive a family of runs over it. (Each verb also has a legacy built-in form -selected by `--strategy`/`--harness` instead of a `.json` path, for the -engine's own bundled example strategies — see `--help`.) +and drive a family of runs over it. (`walkforward`, `mc`, and `generalize` also +accept a legacy built-in form selected by `--strategy` instead of a `.json` +path, for the engine's own bundled example strategies — see `--help`.) | Command | Purpose | |---|---| diff --git a/crates/aura-cli/src/verb_sugar.rs b/crates/aura-cli/src/verb_sugar.rs index 0a7db0b..ecbf1f5 100644 --- a/crates/aura-cli/src/verb_sugar.rs +++ b/crates/aura-cli/src/verb_sugar.rs @@ -512,7 +512,7 @@ pub(crate) struct GeneratedMc { /// Translate one `aura mc --strategy r-sma --real` invocation into its two generated /// documents: a `[std::sweep(argmax), std::walk_forward, std::monte_carlo]` process /// (the sweep enumerates the IS-refit survivor grid for the wf stage; the terminal -/// monte_carlo stage pools the per-window OOS trade-R series and r-bootstraps E[R]) +/// monte_carlo stage pools the per-window OOS trade-R series and r-bootstraps `E[R]`) /// and a campaign running the fast/slow grid over one instrument under a single risk /// regime that carries the stop. Unlike `translate_walkforward` (which hardcodes /// `seed: 0`), `translate_mc` sets `campaign.seed = seed` (the mc `--seed`): the wf diff --git a/crates/aura-cli/tests/cli_run.rs b/crates/aura-cli/tests/cli_run.rs index 3259796..b15ec5b 100644 --- a/crates/aura-cli/tests/cli_run.rs +++ b/crates/aura-cli/tests/cli_run.rs @@ -1198,13 +1198,14 @@ fn run_unknown_harness_exits_two() { /// Property (#159 cut 2): `--strategy r-breakout` is a fully retired CLI token, on /// BOTH `sweep` and `walkforward` — indistinguishable from an unrecognized token -/// (`bogus`), i.e. it falls through `strategy_from`'s catch-all into the plain -/// usage error, not into a "valid-but-unsupported" branch (contrast -/// `walkforward_unsupported_strategy_exits_2_naming_the_token`, which pins that -/// shape for `momentum`). A regression that left `Strategy::RBreakout` parseable -/// while only deleting its family builder would make this test's stderr start -/// naming "r-breakout" specially instead of reading the generic `Usage: aura -/// …` line — this is the negative that catches a half-finished retirement. +/// (`bogus`). `--strategy` is now a plain `Option` with no per-token +/// dispatch, so a retired value carries nothing special: it flows into clap's +/// generic usage path and out as exit 2 with the generic `aura: Usage: aura +/// …` line, never a "valid-but-unsupported" message. A regression that +/// re-taught the CLI to recognize "r-breakout" specially (rather than leaving it +/// deleted) would make this test's stderr start naming "r-breakout" instead of +/// reading the generic usage line — this is the negative that catches a +/// half-finished retirement. #[test] fn sweep_and_walkforward_reject_retired_r_breakout_token_as_unrecognized() { for (args, verb) in [ @@ -1345,7 +1346,7 @@ fn generalize_grades_a_candidate_across_two_instruments() { /// Characterization pin (byte-identity anchor for the generalize dissolution, /// #210). The current `aura generalize` binds its protective stop as a grid axis -/// (`r_sma_sweep_family` with `stop_open=true`); the dissolution rebinds the same +/// (`blueprint_sweep_family` with `stop_open=true`); the dissolution rebinds the same /// stop through the risk-regime seam (`RiskRegime::Vol -> StopRule::Vol`). The /// sibling `generalize_grades_a_candidate_across_two_instruments` asserts shape /// only — `worst_case` and the per-instrument R floats are never checked — so a diff --git a/crates/aura-engine/src/blueprint.rs b/crates/aura-engine/src/blueprint.rs index 4414767..c110298 100644 --- a/crates/aura-engine/src/blueprint.rs +++ b/crates/aura-engine/src/blueprint.rs @@ -1955,8 +1955,8 @@ mod tests { } } - /// Today's flat, hand-wired SMA-cross signal-quality harness (the - /// `sample_harness` wiring from `aura-cli`), with two recording sinks. + /// A flat, hand-wired SMA-cross signal-quality harness, with two + /// recording sinks. #[allow(clippy::type_complexity)] fn hand_wired_sma_cross_harness() -> ( Harness, @@ -2398,9 +2398,9 @@ mod tests { } /// A macd-like composite: one f64 input role `price`, three f64 outputs - /// (macd/signal/histogram), three params (fast/slow/signal lengths). Mirrors the - /// CLI `macd` composite's typed multi-output boundary, used to exercise - /// `derive_signature` on a composite. + /// (macd/signal/histogram), three params (fast/slow/signal lengths). A typed + /// multi-output boundary, used to exercise `derive_signature` on a + /// composite. fn macd_fixture() -> Composite { Composite::new( "macd", diff --git a/crates/aura-engine/src/graph_model.rs b/crates/aura-engine/src/graph_model.rs index 1127356..2fc6547 100644 --- a/crates/aura-engine/src/graph_model.rs +++ b/crates/aura-engine/src/graph_model.rs @@ -333,8 +333,7 @@ mod tests { /// source role (`price`, → a synthetic source node), a composite reference /// (`sma_cross`, → a `composites` entry), a plain node (`Bias`), and a /// sink (`Recorder`, `output: vec![]`). A deliberately minimal serializer - /// fixture, independent of the CLI's built-in sample (`build_sample` in - /// aura-cli — a richer nested `signals` graph since cycle 0036), kept small so + /// fixture, kept small so /// this golden stays stable; the Recorder receiver is dropped because the /// model serializer never runs the graph. fn sample_root() -> Composite { diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md index 4686341..a16f6dc 100644 --- a/docs/design/INDEX.md +++ b/docs/design/INDEX.md @@ -850,6 +850,10 @@ against an R-evaluator harness (the gross-R → net-R chain). On a non-R harness (exit 2)**, not a silent no-op — refuse-don't-guess. Negative cost rates are likewise rejected (exit 2) with a named diagnostic that identifies the offending flag. CLI ergonomics only; the cost-model graph and the R math are untouched. +[HISTORY — the built-in `--harness` selector (its `sma`/`macd` non-R examples) +was retired with the demos → blueprint-data (#159, cuts 1b-4); the cost-flag +scoping rule survives on the `aura ` r-sma run path over +examples/r_*.json.] **Reframe (2026-06-23, #117 — exposure → bias, R as the signal-quality unit).** [HISTORY — its R spine survives into the 2026-06-28 contract; its Stage-2 currency / @@ -937,6 +941,9 @@ harness fanning one bias into both `SimBroker` (legacy pip) and the RiskExecutor dedicated `aura-composites` crate, so `aura-engine`'s runtime dependency stays `aura-core`-only and `aura-std` is an `aura-engine` `[dev-dependencies]` (the graph stays acyclic). +[HISTORY — the built-in `--harness` selector was retired with the demos → +blueprint-data (#159, cuts 1b-4); `run` is now blueprint-driven — `aura run +` over examples/r_*.json.] **Realization (2026-07-06 — the risk regime as a structural campaign axis, #210).** The `StopRule{Fixed,Vol}` structural axis is realized at the campaign-document @@ -970,6 +977,9 @@ lengths), holding the stop and sizing fixed: `risk_budget` is R-invariant and 1R**, so varying it would change what R *means* per member and break cross-member SQN comparability. Each swept member's manifest records the fixed R-defining params beside the floated knobs (reproducible from its own manifest, C18). +[HISTORY — the built-in `--strategy` sweep surface was retired with the demos → +blueprint-data (#159, cuts 1b-4); the rankable R sweep now runs as `aura sweep + --axis …` over examples/r_sma_open.json.] **Realization (cycle 0067, #130 + #135).** **#130 (SQN100):** `RMetrics` gains `sqn_normalized = (mean_R/stdev_R)·√(min(n, 100))` — the n-normalized "SQN score" @@ -980,6 +990,9 @@ stay byte-unchanged, and the field carries `#[serde(default)]` (C18). Below the `r_sma_sweep_family` persists each member's equity / exposure / r_equity under `runs/traces///` via the same `persist_traces_r` the single run uses; per-member `--trace` is symmetric across all three sweep strategies. +[HISTORY — the built-in `--strategy` sweep triple (sma / momentum / r-sma) was +retired with the demos → blueprint-data (#159, cuts 1b-4); the per-member +`--trace` symmetry now lives on the `aura sweep ` path.] **Realization (cycle 0068, #115 — position-event derive).** [The derivation survives as the **deploy / reconciliation** layer per the 2026-06-28 reframe — its @@ -1858,7 +1871,7 @@ by key for determinism, C1); a family is its *first producer* — the deliberate step toward the programmable analysis meta-level (C21) **without** rebuilding the orchestration axes (that is its own later cycle). Name resolution is made a **total function** by the write-guard `TraceStore::ensure_name_free`, called once per tracing -command (`run`/`run --harness macd`/`run --real` → Run; `sweep`/`mc`/`walkforward` → Family) +command (`run`/`run `/`run --real` → Run; `sweep`/`mc`/`walkforward` → Family) to refuse cross-kind name reuse — so the one ambiguous on-disk state (a name used by both a run and a family) is unreachable. Every error path exits 2, never panics (C18/C10 refuse-don't-guess). Engine untouched (C9/C14): the whole change is @@ -2362,7 +2375,11 @@ the project layout and docs-by-role are open (#192 context). path (its member lines carry no instrument/topology_hash/selection stamp and register no campaign document) — the built-in `--strategy` demo surface is #159's hard-wired-harness retirement target, not the dissolution's; for generalize/walkforward/mc the dissolved form - is `--strategy r-sma --real`. Milestone closed 2026-07-07 on a green end-to-end fieldtest + is `--strategy r-sma --real`. [HISTORY — #159 (cuts 1b-4) has since landed + (post-2026-07-07): the retirement target has been hit — the built-in + `--strategy` sweep/demo surface is retired and the inline `--strategy r-sma + --real` path no longer exists; the surviving form is `aura + --axis …` over examples/r_*.json.] Milestone closed 2026-07-07 on a green end-to-end fieldtest (0 bugs; behaviour preservation, campaign-substrate reach-through, and the risk-regime axis all confirmed); residual findings are discoverability/ergonomics follow-ups (#216 risk-axis discoverability, #217 verb knob asymmetry, #218 no-project store litter). diff --git a/docs/glossary.md b/docs/glossary.md index bfbd079..2c216a6 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -285,7 +285,7 @@ The harness's structural parameterization — which strategy, instrument(s), bro ### 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. On a loaded blueprint every open knob (`--list-axes`) is **required** — a subset is refused with the missing knob named; pin an unwanted knob with a single-value axis (`--axis name=`), there is no default. `aura sweep --axis` takes the `--list-axes`-printed, root-composite-wrapped name (e.g. `graph.fast.length`) — not the raw `param_space` name (`fast.length`) that `graph introspect --params` and a campaign document's axes use; the CLI strips exactly one leading wrapper segment (#210). The `aura sweep` CLI verb is now thin sugar over the `campaign document` path — its blueprint form (` --real`) translates to a generated, content-addressed campaign run through the one executor (#210); `aura sweep --strategy …` stays the inline built-in-demo path (#159's hard-wired-harness retirement target). +An orchestration axis varying tuning params (grid or random) within a fixed structure. The inner, param-tuning loop, distinct from the structural experiment matrix. On a loaded blueprint every open knob (`--list-axes`) is **required** — a subset is refused with the missing knob named; pin an unwanted knob with a single-value axis (`--axis name=`), there is no default. `aura sweep --axis` takes the `--list-axes`-printed, root-composite-wrapped name (e.g. `graph.fast.length`) — not the raw `param_space` name (`fast.length`) that `graph introspect --params` and a campaign document's axes use; the CLI strips exactly one leading wrapper segment (#210). The `aura sweep` CLI verb is now thin sugar over the `campaign document` path — its blueprint form (` --real`) translates to a generated, content-addressed campaign run through the one executor (#210); the built-in `--strategy` sweep surface was retired by #159 (its hard-wired harnesses removed) — sweep now runs from a blueprint + `--axis`, and a retired `--strategy` token falls to the generic usage error. ### tap **Avoid:** —