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

feat(cli): dissolve aura mc --strategy r-sma --real (#210)

Browse Source 
The FOURTH and LAST verb dissolution. `aura mc --strategy r-sma --real`
now runs as thin sugar over the one campaign executor: a generated,
content-addressed [std::sweep(argmax), std::walk_forward, std::monte_carlo]
campaign document whose terminal monte_carlo stage produces the same
StageBootstrap::PooledOos(RBootstrap). The sugar reads it from
run.outcome.record.cells[].stages[].bootstrap and reprints the existing
mc_r_bootstrap_json — one line, byte-identical to the inline path.

Pure sugar, NO executor change (aura-campaign/aura-engine/aura-research
diff-free). Mirrors the shipped walkforward dissolution:
- verb_sugar.rs: GeneratedMc, translate_mc, register_generated_mc,
  run_mc_sugar (record-read + one grade line, no member lines).
- main.rs: mc_args_from + the dispatch_mc built-in-arm split gated on
  `--strategy r-sma && --real`.

The one new load-bearing decision is the seed mapping: translate_mc sets
campaign.seed = the mc --seed. The wf winners are argmax hence
deflation-seed-independent (proven by the shipped walkforward anchor), so
the pooled OOS series is unchanged while the terminal r_bootstrap at that
seed reproduces the inline bootstrap. A new e2e
(mc_dissolved_seed_changes_the_bootstrap_draw_not_the_pooled_series)
pins exactly this: two --seed values yield identical n_trades but a moved
E[R] mean.

Fork C retention (as walkforward): the arm splits, run_mc_r_bootstrap /
run_mc stay inline for the fenced synthetic/non-real paths (until #159).
The three synthetic-r-sma tests use no --real, so they never enter the
sugar branch and run the inline path unchanged. --name/--trace are
rejected on the sugar path, matching the inline mc r-path.

Verification: the committed byte-identity anchor
mc_r_bootstrap_real_e2e_pins_the_exact_current_grade runs the real GER40
archive and passes byte-for-byte through the new path; full workspace
suite green; clippy --all-targets -D warnings clean.

refs #210
This commit is contained in:
Brummel
2026-07-07 00:23:33 +02:00
parent 764dc2adbf
commit 7f5f576f41
3 changed files with 625 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/aura-cli/src/main.rs
+160
View File
@@ -4264,6 +4264,44 @@ fn walkforward_args_from(
Ok((name, symbol, fast, slow, stop_length[0], stop_k[0], a.from, a.to))
}
/// Convert `McCmd` into the resolved argument shape the mc sugar consumes (the
/// dissolved `--strategy r-sma --real` branch). Single instrument, multi-value
/// fast/slow (the IS-refit grid), single-value stop (Fork A: the stop is a risk
/// regime, not a swept axis); all four grid knobs required. `--block-len`/
/// `--resamples`/`--seed` default to `1`/`1000`/`1` — byte-identical to the inline
/// `McArgs::RealR` defaults (`main.rs:5064-5066`), so an omitted flag produces the
/// same document either way. The usize->u32 conversion for `block_len`/`resamples`
/// lands HERE, at the argv boundary where the CLI's `usize` meets the document's
/// `u32` vocabulary (`StageBlock::MonteCarlo`), keeping every downstream signature
/// in the document's native type. `--name`/`--trace` are rejected: the inline mc
/// R-path rejects them too (`main.rs:5047`), so the sugar preserves that (the
/// R-bootstrap records without a family name — the campaign name is a constant
/// "mc").
#[allow(clippy::type_complexity)]
fn mc_args_from(
a: &McCmd,
) -> Result<(String, String, Vec<i64>, Vec<i64>, i64, f64, u32, u32, u64, Option<i64>, Option<i64>), String> {
let symbol = match a.real.as_deref() {
None | Some("") => return Err("mc --strategy r-sma dissolves only over --real <SYMBOL>".to_string()),
Some(s) => s.to_string(),
};
if a.name.is_some() || a.trace.is_some() {
return Err("mc --strategy r-sma: --name/--trace are not accepted (the R-bootstrap records without a family name)".to_string());
}
let knobs = || "mc requires --fast --slow --stop-length --stop-k (fast/slow may be CSV grids; the stop is single-value)".to_string();
let fast: Vec<i64> = parse_csv_list(a.fast.as_deref().ok_or_else(knobs)?).map_err(|()| knobs())?;
let slow: Vec<i64> = parse_csv_list(a.slow.as_deref().ok_or_else(knobs)?).map_err(|()| knobs())?;
let stop_length: Vec<i64> = parse_csv_list(a.stop_length.as_deref().ok_or_else(knobs)?).map_err(|()| knobs())?;
let stop_k: Vec<f64> = parse_csv_list(a.stop_k.as_deref().ok_or_else(knobs)?).map_err(|()| knobs())?;
if stop_length.len() != 1 || stop_k.len() != 1 {
return Err("mc: the stop is a single risk regime; --stop-length and --stop-k take one value each".to_string());
}
let block_len = a.block_len.map(|v| v as u32).unwrap_or(1);
let resamples = a.resamples.map(|v| v as u32).unwrap_or(1000);
let seed = a.seed.unwrap_or(1);
Ok(("mc".to_string(), symbol, fast, slow, stop_length[0], stop_k[0], block_len, resamples, seed, a.from, a.to))
}
/// Convert `GeneralizeCmd` into the resolved argument shape the generalize sugar
/// consumes. The candidate is a single cell (clap already types `--fast`/etc. as
/// one `i64`/`f64`), all four knobs required, `--real` a `>=2`-distinct comma
@@ -4947,6 +4985,51 @@ fn dispatch_mc(a: McCmd, env: &project::Env) {
eprintln!("aura: {}", usage());
std::process::exit(2);
}
// Dissolution split (#210, Reading A): only the real-archive r-sma
// R-bootstrap execution routes through the campaign path. Everything else —
// synthetic-r-sma (no --real), the synthetic seed-resweep, the blueprint
// path — stays on the inline handler below, fenced until #159.
if a.strategy.as_deref() == Some("r-sma") && a.real.is_some() {
let (name, symbol, fast, slow, stop_length, stop_k, block_len, resamples, seed, from, to) =
mc_args_from(&a).unwrap_or_else(|m| {
eprintln!("aura: {m}");
std::process::exit(2);
});
let signal = sma_signal(None, None);
let canonical = blueprint_to_json(&signal).expect("a bare sma_signal serializes");
let reg = env.registry();
let topo = topology_hash(&signal);
reg.put_blueprint(&topo, &canonical).unwrap_or_else(|e| {
eprintln!("aura: {e}");
std::process::exit(1);
});
// The inline `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
// identically here too, even when both flags are given, or the per-window
// winners and pooled OOS series diverge from the committed exact-grade anchor.
let source = DataSource::from_choice(
DataChoice::Real { symbol: symbol.clone(), from_ms: from, to_ms: to },
env,
);
let (from_ts, to_ts) = source.full_window(env);
let (from_ms, to_ms) = (
aura_ingest::epoch_ns_to_unix_ms(from_ts),
aura_ingest::epoch_ns_to_unix_ms(to_ts),
);
let (is_ms, oos_ms, step_ms) = wf_ms_sizes();
verb_sugar::run_mc_sugar(
&fast, &slow, stop_length, stop_k, WINNER_SELECTION_METRIC,
is_ms, oos_ms, step_ms, resamples, block_len, seed, &name, &symbol, from_ms, to_ms,
&canonical, env,
)
.unwrap_or_else(|m| {
eprintln!("aura: {m}");
std::process::exit(1);
});
return;
}
// The R-bootstrap path is selected by any r-sma knob; otherwise the
// synthetic seed-resweep family. Name flags are invalid on the R path.
let r_path = a.strategy.is_some()
@@ -6498,4 +6581,81 @@ mod tests {
mc_r_bootstrap_report(&DataSource::Synthetic, &RGrid::default(), 1, 256, 1, &env),
);
}
/// A bare `McCmd` with every optional field defaulted to `None`/empty, so each
/// `mc_args_from` refusal test below only sets the fields its scenario needs.
fn bare_mc_cmd() -> McCmd {
McCmd {
blueprint: None,
strategy: None,
real: None,
from: None,
to: None,
name: None,
trace: None,
fast: None,
slow: None,
stop_length: None,
stop_k: None,
block_len: None,
resamples: None,
seed: None,
seeds: None,
}
}
#[test]
fn mc_args_from_refuses_without_a_real_symbol() {
let a = bare_mc_cmd();
let err = mc_args_from(&a).unwrap_err();
assert!(err.contains("dissolves only over --real"), "refuse message: {err}");
}
#[test]
fn mc_args_from_refuses_an_empty_real_symbol() {
let a = McCmd { real: Some(String::new()), ..bare_mc_cmd() };
let err = mc_args_from(&a).unwrap_err();
assert!(err.contains("dissolves only over --real"), "refuse message: {err}");
}
#[test]
fn mc_args_from_refuses_name_and_trace() {
let a = McCmd {
real: Some("GER40".to_string()),
name: Some("a".to_string()),
trace: Some("b".to_string()),
..bare_mc_cmd()
};
let err = mc_args_from(&a).unwrap_err();
assert!(err.contains("--name/--trace are not accepted"), "refuse message: {err}");
}
#[test]
fn mc_args_from_refuses_missing_knobs() {
let a = McCmd {
real: Some("GER40".to_string()),
fast: Some("3".to_string()),
slow: Some("12".to_string()),
..bare_mc_cmd()
};
let err = mc_args_from(&a).unwrap_err();
assert!(
err.contains("requires --fast --slow --stop-length --stop-k"),
"missing-knob refusal: {err}"
);
}
#[test]
fn mc_args_from_refuses_a_multi_value_stop() {
let a = McCmd {
real: Some("GER40".to_string()),
fast: Some("3".to_string()),
slow: Some("12".to_string()),
stop_length: Some("14,20".to_string()),
stop_k: Some("2.0".to_string()),
..bare_mc_cmd()
};
let err = mc_args_from(&a).unwrap_err();
assert!(err.contains("single risk regime"), "stop-regime refusal: {err}");
}
}
crates/aura-cli/src/verb_sugar.rs
+283
View File
@@ -502,6 +502,170 @@ pub(crate) fn run_walkforward_sugar(
Ok(())
}
/// The two generated documents of one dissolved `mc` invocation.
#[derive(Debug)]
pub(crate) struct GeneratedMc {
pub process: ProcessDoc,
pub campaign: CampaignDoc,
}
/// 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])
/// 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
/// winners are argmax hence deflation-seed-independent (the shipped walkforward
/// anchor proved this), so remapping the campaign seed leaves the pooled series
/// unchanged while making the terminal `r_bootstrap` at that seed reproduce the
/// inline bootstrap. The roller sizes (`in_sample_ms`/`out_of_sample_ms`/`step_ms`)
/// and `blueprint_canonical` come from the caller, exactly as for walkforward.
#[allow(clippy::too_many_arguments)]
pub(crate) fn translate_mc(
fast: &[i64],
slow: &[i64],
stop_length: i64,
stop_k: f64,
metric: &str,
in_sample_ms: u64,
out_of_sample_ms: u64,
step_ms: u64,
resamples: u32,
block_len: u32,
seed: u64,
name: &str,
symbol: &str,
from_ms: i64,
to_ms: i64,
blueprint_canonical: &str,
) -> Result<GeneratedMc, String> {
let process = ProcessDoc {
format_version: FORMAT_VERSION,
kind: DocKind::Process,
name: "mc".to_string(),
description: None,
pipeline: vec![
StageBlock::Sweep {
selection: Some(SweepSelection {
metric: metric.to_string(),
select: SelectRule::Argmax,
deflate: false,
}),
},
StageBlock::WalkForward {
in_sample_ms,
out_of_sample_ms,
step_ms,
mode: WfMode::Rolling,
metric: metric.to_string(),
select: SelectRule::Argmax,
},
StageBlock::MonteCarlo { resamples, block_len },
],
};
let mut doc_axes: BTreeMap<String, Axis> = BTreeMap::new();
doc_axes.insert(
"fast.length".to_string(),
axis_from_values("fast.length", &fast.iter().map(|&v| Scalar::i64(v)).collect::<Vec<_>>())?,
);
doc_axes.insert(
"slow.length".to_string(),
axis_from_values("slow.length", &slow.iter().map(|&v| Scalar::i64(v)).collect::<Vec<_>>())?,
);
let campaign = CampaignDoc {
format_version: FORMAT_VERSION,
kind: DocKind::Campaign,
name: name.to_string(),
description: None,
data: DataSection {
instruments: vec![symbol.to_string()],
windows: vec![Window { from_ms, to_ms }],
},
strategies: vec![StrategyEntry {
r#ref: DocRef::ContentId(content_id_of(blueprint_canonical)),
axes: doc_axes,
}],
process: ProcessRef { r#ref: DocRef::ContentId(content_id_of(&process_to_json(&process))) },
risk: vec![RiskRegime::Vol { length: stop_length, k: stop_k }],
seed,
presentation: Presentation {
persist_taps: vec![],
emit: vec!["family_table".to_string()],
},
};
Ok(GeneratedMc { process, campaign })
}
/// Auto-register both generated mc documents (content-addressed, idempotent).
/// Returns `(process_id, campaign_id)`.
pub(crate) fn register_generated_mc(
reg: &aura_registry::Registry,
generated: &GeneratedMc,
) -> Result<(String, String), String> {
let process_id =
reg.put_process(&process_to_json(&generated.process)).map_err(|e| e.to_string())?;
let campaign_id =
reg.put_campaign(&campaign_to_json(&generated.campaign)).map_err(|e| e.to_string())?;
Ok((process_id, campaign_id))
}
/// Run one dissolved `mc` invocation end-to-end: register the generated documents,
/// run through the one campaign path, then reprint the single `mc_r_bootstrap` grade
/// line from the recorded terminal `PooledOos` bootstrap. The stdout line is
/// byte-identical to the inline path (the committed exact-grade anchor is the gate).
/// mc prints ONLY the one summary line — no per-window member lines (unlike
/// walkforward): the monte_carlo stage is a terminal annotator, not a family.
#[allow(clippy::too_many_arguments)]
pub(crate) fn run_mc_sugar(
fast: &[i64],
slow: &[i64],
stop_length: i64,
stop_k: f64,
metric: &str,
in_sample_ms: u64,
out_of_sample_ms: u64,
step_ms: u64,
resamples: u32,
block_len: u32,
seed: u64,
name: &str,
symbol: &str,
from_ms: i64,
to_ms: i64,
blueprint_canonical: &str,
env: &crate::project::Env,
) -> Result<(), String> {
let generated = translate_mc(
fast, slow, stop_length, stop_k, metric, in_sample_ms, out_of_sample_ms, step_ms,
resamples, block_len, seed, name, symbol, from_ms, to_ms, blueprint_canonical,
)?;
let probe_params: Vec<(String, Scalar)> = vec![
("fast.length".to_string(), Scalar::i64(fast[0])),
("slow.length".to_string(), Scalar::i64(slow[0])),
];
validate_before_register(&generated.process, &generated.campaign, blueprint_canonical, &probe_params, env)?;
let reg = env.registry();
let (_process_id, campaign_id) = register_generated_mc(&reg, &generated)?;
let run = crate::campaign_run::run_campaign_returning(&campaign_id, env)?;
// The single cell's terminal monte_carlo StageRealization carries the pooled-OOS
// bootstrap (record path: outcome.record.cells[].stages[].bootstrap).
let boot = run
.outcome
.record
.cells
.iter()
.flat_map(|c| c.stages.iter())
.find_map(|s| match &s.bootstrap {
Some(aura_registry::StageBootstrap::PooledOos(b)) => Some(b),
_ => None,
})
.ok_or("mc produced no pooled-OOS bootstrap")?;
println!("{}", crate::mc_r_bootstrap_json(boot));
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
@@ -792,4 +956,123 @@ mod tests {
assert_eq!(stored_process, process_to_json(&generated.process));
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn translate_mc_is_deterministic_and_carries_the_regime_and_seed() {
let a = translate_mc(
&[3, 5], &[12, 20], 14, 2.0, "sqn_normalized",
7_776_000_000, 2_592_000_000, 2_592_000_000,
1000, 5, 42,
"mc", "GER40", 100, 200, "{\"bp\":1}",
)
.unwrap();
let b = translate_mc(
&[3, 5], &[12, 20], 14, 2.0, "sqn_normalized",
7_776_000_000, 2_592_000_000, 2_592_000_000,
1000, 5, 42,
"mc", "GER40", 100, 200, "{\"bp\":1}",
)
.unwrap();
assert_eq!(
content_id_of(&campaign_to_json(&a.campaign)),
content_id_of(&campaign_to_json(&b.campaign)),
"identical invocations must generate identical campaign ids"
);
// pipeline: sweep(argmax) then walk_forward(argmax, rolling) then monte_carlo
assert_eq!(
a.process.pipeline,
vec![
StageBlock::Sweep {
selection: Some(SweepSelection {
metric: "sqn_normalized".to_string(),
select: SelectRule::Argmax,
deflate: false,
})
},
StageBlock::WalkForward {
in_sample_ms: 7_776_000_000,
out_of_sample_ms: 2_592_000_000,
step_ms: 2_592_000_000,
mode: WfMode::Rolling,
metric: "sqn_normalized".to_string(),
select: SelectRule::Argmax,
},
StageBlock::MonteCarlo { resamples: 1000, block_len: 5 },
]
);
assert_eq!(a.campaign.seed, 42, "the campaign seed carries the mc --seed");
assert_eq!(a.campaign.risk, vec![RiskRegime::Vol { length: 14, k: 2.0 }]);
assert_eq!(a.campaign.data.instruments, vec!["GER40".to_string()]);
assert_eq!(a.campaign.strategies.len(), 1);
assert_eq!(
a.campaign.strategies[0].axes["fast.length"].values,
vec![Scalar::i64(3), Scalar::i64(5)]
);
assert_eq!(
a.campaign.strategies[0].axes["slow.length"].values,
vec![Scalar::i64(12), Scalar::i64(20)]
);
assert_eq!(a.process.name, "mc");
assert!(aura_research::validate_campaign(&a.campaign).is_empty());
assert!(aura_research::validate_process(&a.process).is_empty());
assert!(aura_campaign::preflight(&a.process, &a.campaign).is_ok());
}
#[test]
fn translate_mc_diverging_seeds_and_stops_do_not_collide_content_ids() {
let base = translate_mc(
&[3, 5], &[12, 20], 14, 2.0, "sqn_normalized",
7_776_000_000, 2_592_000_000, 2_592_000_000,
1000, 5, 42,
"mc", "GER40", 100, 200, "{\"bp\":1}",
)
.unwrap();
let different_seed = translate_mc(
&[3, 5], &[12, 20], 14, 2.0, "sqn_normalized",
7_776_000_000, 2_592_000_000, 2_592_000_000,
1000, 5, 7,
"mc", "GER40", 100, 200, "{\"bp\":1}",
)
.unwrap();
let different_k = translate_mc(
&[3, 5], &[12, 20], 14, 3.0, "sqn_normalized",
7_776_000_000, 2_592_000_000, 2_592_000_000,
1000, 5, 42,
"mc", "GER40", 100, 200, "{\"bp\":1}",
)
.unwrap();
let base_id = content_id_of(&campaign_to_json(&base.campaign));
let seed_id = content_id_of(&campaign_to_json(&different_seed.campaign));
let k_id = content_id_of(&campaign_to_json(&different_k.campaign));
assert_ne!(base_id, seed_id, "a different mc seed must not collide onto the same campaign id");
assert_ne!(base_id, k_id, "a different stop_k must not collide onto the same campaign id");
assert_ne!(seed_id, k_id, "the two diverging documents must not collide with each other");
}
#[test]
fn register_generated_mc_stores_documents_the_campaign_can_actually_resolve() {
let dir = std::env::temp_dir().join(format!(
"aura-verb-sugar-mc-registry-test-{}",
std::process::id()
));
std::fs::create_dir_all(&dir).unwrap();
let reg = aura_registry::Registry::open(dir.join("runs.jsonl"));
let generated = translate_mc(
&[3, 5], &[12, 20], 14, 2.0, "sqn_normalized",
7_776_000_000, 2_592_000_000, 2_592_000_000,
1000, 5, 42,
"mc", "GER40", 100, 200, "{\"bp\":1}",
)
.unwrap();
let (process_id, campaign_id) = register_generated_mc(&reg, &generated).unwrap();
let stored_campaign = reg.get_campaign(&campaign_id).unwrap().expect("campaign stored");
assert_eq!(stored_campaign, campaign_to_json(&generated.campaign));
let DocRef::ContentId(ref_id) = &generated.campaign.process.r#ref else {
panic!("mc's process ref is a content id");
};
assert_eq!(ref_id, &process_id, "the stored process id must be the campaign's own ref");
let stored_process = reg.get_process(ref_id).unwrap().expect("process stored");
assert_eq!(stored_process, process_to_json(&generated.process));
let _ = std::fs::remove_dir_all(&dir);
}
}