Brummel/Aura
1
0
Fork 0
Code Issues 32 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(cli): finish the #159 tidy — sweep dead-symbol comments in main.rs

Browse Source 
Behaviour-free comment/rustdoc sweep of the last file the #159
demo-retirement audit flagged: repoint run_sweep/run_mc/mc_family/
walkforward_family/r_sma_sweep_over/run_oos_r/sample_blueprint_with_sinks
references to their live blueprint_* analogs or mark them retired.
De-links the r_sma_sweep_family intra-doc link at blueprint_sweep_family —
cargo doc --workspace --no-deps is now warning-clean. Verified: suite
1029/0, clippy clean, diff comment-only.

closes #222, refs #159
This commit is contained in:
Brummel
2026-07-09 09:53:28 +02:00
parent 07a73fb66e
commit 3198747b48
1 changed files with 30 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/aura-cli/src/main.rs
+30 -25
View File
@@ -602,7 +602,7 @@ impl DataSource {
/// The full walk-forward span. Synthetic draws the 60-bar `walkforward_prices`
/// span — NOT `showcase_prices` (which `full_window` uses): walk-forward is a
/// *windowed* consumer whose roller `(24,12,12)` needs 36 bars, so it uses the
/// longer built-in stream (byte-unchanged from the pre-`DataSource`
/// longer built-in stream (byte-unchanged from the retired pre-`DataSource`
/// `walkforward_family`, which derived its span the same way). Real: the same
/// probed `--from..--to` window as `full_window`.
fn wf_full_span(&self, env: &project::Env) -> (Timestamp, Timestamp) {
@@ -736,7 +736,7 @@ fn family_member_line(id: &str, report: &RunReport) -> String {
}
/// Monte-Carlo variant of [`family_member_line`]: the per-draw line also carries the
/// realization `seed` (between `family_id` and `report`), matching `run_mc`'s shape.
/// realization `seed` (between `family_id` and `report`) — the shape `run_blueprint_mc` prints.
fn mc_member_line(id: &str, seed: u64, report: &RunReport) -> String {
format!(
r#"{{"family_id":{},"seed":{},"report":{}}}"#,
@@ -901,9 +901,9 @@ fn walkforward_prices() -> Vec<(Timestamp, Scalar)> {
out
}
/// The in-memory windowed source the built-in demo uses (the firewall mapping to
/// `DataServer::stream_m1_windowed` is the real-data path; the demo stays in-memory,
/// mirroring `run_sweep`'s `showcase_prices`). Inclusive `[from, to]`.
/// The in-memory windowed source the synthetic path uses (the firewall mapping to
/// `DataServer::stream_m1_windowed` is the real-data path; synthetic stays in-memory,
/// mirroring `run_blueprint_sweep`'s `showcase_prices`). Inclusive `[from, to]`.
fn walkforward_window_source(from: Timestamp, to: Timestamp) -> VecSource {
VecSource::new(
walkforward_prices()
@@ -1263,7 +1263,7 @@ fn wrap_r(
let mut g = GraphBuilder::new("r_sma");
// SMA-cross signal → Bias, nested as a serializable `price`→`bias` leg.
let sig = g.add(BlueprintNode::Composite(signal));
// pip branch (verbatim from sample_blueprint_with_sinks).
// pip branch (verbatim from the retired `sample_blueprint_with_sinks`, #159).
let broker = g.add(SimBroker::builder(SYNTHETIC_PIP_SIZE));
// R branch: bias + price → RiskExecutor(vol_stop) → dense R-record. The stop is a
// fixed `StopRule` — the pinned default constants, or an arbitrary per-regime rule
@@ -1542,8 +1542,9 @@ fn list_blueprint_axes(doc: &str, env: &project::Env) {
}
}
/// Sweep a serialized signal `doc` over user-named param-space axes — the structural
/// twin of [`r_sma_sweep_family`], with three deviations. (1) The signal source is
/// Sweep a serialized signal `doc` over user-named param-space axes. Structurally it
/// keeps the shape of the retired `r_sma_sweep_family` demo builder (#159), with three
/// deviations. (1) The signal source is
/// `wrap_r(blueprint_from_json(doc))` — a loaded blueprint, not the Rust-built
/// r-sma graph. (2) The signal is RE-loaded from `doc` per member (a `Composite` is
/// `!Clone`, so the throwaway param-space probe and each grid point each reload). (3)
@@ -1555,8 +1556,8 @@ fn list_blueprint_axes(doc: &str, env: &project::Env) {
/// (the symmetric inverse of [`blueprint_mc_family`]'s closed-blueprint requirement),
/// pre-empting the misleading `UnknownKnob(<axis>)` the per-axis resolve would emit for a
/// knob that is not unknown but bound out. Every member manifest carries the shared
/// `topology_hash` of the loaded signal; reduce-mode fold, identical to the mirror's
/// default (no-trace) arm.
/// `topology_hash` of the loaded signal; reduce-mode fold, identical to the retired
/// mirror's default (no-trace) arm.
fn blueprint_sweep_family(
doc: &str,
axes: &[(String, Vec<Scalar>)],
@@ -1611,7 +1612,7 @@ fn blueprint_sweep_family(
}
/// Sweep the LOADED blueprint over the user `--axis` grid on an in-sample window
/// `[from,to]` — the windowed, lattice-carrying twin of `r_sma_sweep_over` and
/// `[from,to]` — the windowed, lattice-carrying twin of
/// `blueprint_sweep_family`. `sweep_with_lattice` gives the grid lattice `--select
/// plateau` needs. An unknown/kind-mismatched axis surfaces as `BindError` at the
/// sweep terminal (no panic, no hidden exit) for the caller to render.
@@ -1641,7 +1642,7 @@ fn blueprint_sweep_over(
}
/// Run the winner params over an out-of-sample window `[from,to]` on the loaded
/// blueprint — the loaded-member analog of `run_oos_r`. The reduce-mode member
/// blueprint. The reduce-mode member
/// (`run_blueprint_member`) retains R-metrics, not a raw pip curve, so the stitching
/// segment is empty (an empty segment leaves the stitched curve unbroken).
#[allow(clippy::too_many_arguments)]
@@ -1709,7 +1710,7 @@ fn blueprint_walkforward_family(
})
}
/// A fresh seeded synthetic price walk for one Monte-Carlo draw — the `mc_family`
/// A fresh seeded synthetic price walk for one Monte-Carlo draw — `blueprint_mc_family`'s
/// pattern (a distinct realization per seed). A FIXED `SyntheticSpec` shared by the
/// `aura mc <blueprint.json>` persist path AND the reproduce MonteCarlo branch, so the
/// seed->walk reconstruction is bit-exact (C1). Length 60 comfortably warms the loaded
@@ -1753,7 +1754,7 @@ fn blueprint_mc_family(
// Closed blueprint -> an empty base point (as `aura run <blueprint.json>`); the MC
// draws vary the SEED, not a tuning param (C12 axis 4). Delegate the disjoint C1 draws
// to the shared `monte_carlo` helper — it runs them in parallel across sims (invariant 1),
// deterministic in seed-input order — exactly as the sibling `mc_family` does. Each draw
// deterministic in seed-input order. Each draw
// re-runs the shared reduce-mode member path over its own seeded synthetic walk.
let seeds: Vec<u64> = (1..=n_seeds).collect();
let base_point: Vec<Scalar> = Vec::new();
@@ -1792,9 +1793,9 @@ fn blueprint_mc_family(
/// error (stderr + exit 2, never a panic), ALWAYS records it as a `FamilyKind::Sweep`
/// family (C18/C21 lineage, exactly as the other family verbs), and prints each member
/// carrying the assigned `family_id` via [`family_member_line`] — so a printed member is
/// linkable back to its stored family, like `run_sweep` / `run_walkforward`.
/// linkable back to its stored family, like `run_blueprint_walkforward` / `run_blueprint_mc`.
///
/// Divergence from `run_sweep` (the one place it does less): the blueprint sweep is
/// Divergence from the retired `run_sweep` (the one place this does less): the blueprint sweep is
/// reduce-only this cycle — [`blueprint_sweep_family`] writes no per-member traces — so
/// `persist`/`--trace` neither writes trace files nor reserves a trace-store name (that
/// reservation would guard a write that never happens, and could spuriously reject a
@@ -1833,7 +1834,8 @@ fn run_blueprint_sweep(
eprintln!("aura: {e}");
std::process::exit(1);
});
// Record the family unconditionally (C18/C21 lineage), exactly like `run_sweep`.
// Record the family unconditionally (C18/C21 lineage), exactly like
// `run_blueprint_walkforward` / `run_blueprint_mc`.
let id = match reg.append_family(name, FamilyKind::Sweep, &sweep_member_reports(&family)) {
Ok(id) => id,
Err(e) => {
@@ -1883,7 +1885,7 @@ fn run_blueprint_walkforward(
/// blueprint (the World/C21 verb), store the canonical blueprint ONCE keyed by the shared
/// `topology_hash` (the 0094 hook, so `aura reproduce` re-derives it), record it as a
/// `FamilyKind::MonteCarlo` family (C18/C21 lineage), and print each draw's member line
/// (carrying the seed) plus the aggregate — mirroring `run_mc` / `run_blueprint_sweep`.
/// (carrying the seed) plus the aggregate — mirroring `run_blueprint_sweep`.
fn run_blueprint_mc(doc: &str, n_seeds: u64, name: &str, data: DataSource, env: &project::Env) {
let family = blueprint_mc_family(doc, n_seeds, &data, env).unwrap_or_else(|e| {
eprintln!("aura: {e}");
@@ -2061,12 +2063,15 @@ fn parse_scalar_csv(csv: &str) -> Option<Vec<Scalar>> {
// The declarative argument grammar. clap owns argv tokenizing, scoped `--help`,
// `--version`, `--flag=value`, `--`, and long-option abbreviation; the `dispatch_*`
// handlers below convert each `*Cmd` into the argument shapes the existing execution
// fns accept, reusing the value helpers (`Strategy`, `RGrid`, `Selection`,
// fns accept, reusing the value helpers (`RGrid`, `Selection`,
// `DataSource::from_choice`, `parse_scalar_csv`, `parse_csv_list`, `parse_select`,
// `parse_param_cells`). The four dual-grammar subcommands carry an optional
// `[blueprint]` positional; a first-positional that names an existing `.json` file
// (`is_blueprint_file`) selects the loaded-blueprint branch, otherwise the built-in
// grammar. Usage errors (clap parse + argv-applicability guards) exit 2; runtime failures exit 1.
// `parse_param_cells`). The four subcommands with an optional `[blueprint]` positional
// dispatch on `is_blueprint_file`: a first-positional naming an existing `.json` file
// selects the loaded-blueprint branch. There is no second built-in grammar anymore
// (#159 demo retirement): without a blueprint the dispatcher prints a usage error and
// exits 2 — except the real-archive r-sma sugar arms of walkforward/mc, which route to
// the campaign path. Usage errors (clap parse + argv-applicability guards) exit 2;
// runtime failures exit 1.
/// The `aura` root parser. `#[command(version)]` reads `CARGO_PKG_VERSION`
/// (the workspace `0.1.0`), so `aura --version` prints `aura 0.1.0`.
@@ -3017,7 +3022,7 @@ fn dispatch_walkforward(a: WalkforwardCmd, env: &project::Env) {
std::process::exit(1);
});
// Unlike `dispatch_generalize` (a single run per instrument, insensitive
// to a day's edge shift), the inline `walkforward_family` sources its span
// to a day's edge shift), `blueprint_walkforward_family` sources its span
// from `DataSource::wf_full_span`, which — for Real — ALWAYS clips
// `--from`/`--to` to the archive's actual first/last bar in range (never the
// literal ms request): a holiday/weekend edge shifts every IS/OOS window's
@@ -3115,7 +3120,7 @@ fn dispatch_mc(a: McCmd, env: &project::Env) {
eprintln!("aura: {e}");
std::process::exit(1);
});
// The inline `walkforward_family` sources its span from
// `blueprint_walkforward_family` sources its span from
// `DataSource::wf_full_span`, which for Real ALWAYS clips `--from`/`--to`
// to the archive's actual first/last bar in range: a holiday/weekend edge
// shifts every IS/OOS window's calendar placement, so the roller must clip