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

feat(cli): sweep axes override bound params on the blueprint verb paths

Browse Source 
Task 3-4 of the bound-override cycle. The family boundary derives the
override set from the invocation's axes (override_paths: an axis in the
open space passes through, one naming a bound param re-opens it in
strategy coordinates, one matching neither is refused with a message
pointing at --list-axes) and threads it through the axis probe and every
per-member reload (blueprint_axis_probe_reopened / reopen_all), so probe
and members stay slot-identical. The 'fully bound; nothing to sweep'
refusal retires; identity stays the authored document (the topology_hash
probe reload is never re-opened).

--list-axes now prints the bound surface after the open knobs — one
'<bp>.<node>.<param>:<KIND> default=<value>' line per bound param,
unconditionally (a bound param is an equally re-openable axis regardless
of how many knobs are open beside it).

Walk-forward (blueprint_sweep_over, blueprint_walkforward_family,
run_oos_blueprint) and reproduce (reproduce_family_in plus the
campaign-side trace re-run) derive the same set silently from recorded
manifest param names (bound_overrides_of), so a family that swept an
overridden bound param re-derives bit-identically.

refs #246
This commit is contained in:
Claude
2026-07-13 02:03:14 +02:00
parent 9ffd1952d2
commit 3f4c9478bf
4 changed files with 401 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/aura-cli/src/campaign_run.rs
+20 -3
View File
@@ -839,11 +839,25 @@ pub(crate) fn persist_campaign_traces(
cell_rec.strategy
)
})?;
// The #246 override set (silent variant, `reproduce_family_in`'s
// recipe): re-derived from the cell's own recorded manifest param
// names, against a raw probe space + raw strategy load — the members
// of one cell share the same knob NAMES (only values differ), so this
// is safe to compute once, cell-invariant, from the first member.
let raw_space = crate::blueprint_axis_probe(blueprint_json, env).param_space();
let raw_signal = blueprint_from_json(blueprint_json, &|t| env.resolve(t))
.expect("stored blueprint passed the referential gate; reload is infallible");
let recorded: Vec<String> = members
.first()
.map(|(_, r)| r.manifest.params.iter().map(|(n, _)| n.clone()).collect())
.unwrap_or_default();
let overrides = crate::bound_overrides_of(&recorded, &raw_space, &raw_signal);
// Cell-invariant across every member of this cell (the wrapped param
// space depends only on the cell's blueprint; the resolved geometry
// only on the cell's instrument) — computed once here rather than
// redundantly inside the member loop below.
let space = crate::blueprint_axis_probe(blueprint_json, env).param_space();
let space =
crate::blueprint_axis_probe_reopened(blueprint_json, env, &overrides).param_space();
// Same resolved pip the member ran at (`CliMemberRunner::run_member`'s
// `geo.pip_size`), else the C1 drift-alarm equality below would trip
// spuriously on a re-run computed at a different (default) pip.
@@ -872,8 +886,11 @@ pub(crate) fn persist_campaign_traces(
cell_rec.instrument, from.0, to.0
)
};
let signal = blueprint_from_json(blueprint_json, &|t| env.resolve(t))
.expect("stored blueprint passed the referential gate; reload is infallible");
let signal = crate::reopen_all(
blueprint_from_json(blueprint_json, &|t| env.resolve(t))
.expect("stored blueprint passed the referential gate; reload is infallible"),
&overrides,
);
// Campaign data.bindings overrides win over name defaults — the
// SAME resolution the member ran under, so the C1 drift alarm
// compares like with like.
crates/aura-cli/src/main.rs
+207 -70
View File
@@ -1222,14 +1222,32 @@ fn reproduce_family_in(
eprintln!("aura: blueprint {hash} missing from store");
std::process::exit(1);
});
// The #246 override set (silent variant): re-derived from the RECORDED
// manifest param names, against a raw probe space + raw strategy load — a
// name matching neither space is simply not an override (falls through to
// `point_from_params`'s existing missing-knob refusal below), unlike the
// sweep boundary's `override_paths`, which errors on it.
let recorded: Vec<String> =
stored.manifest.params.iter().map(|(n, _)| n.clone()).collect();
let raw_space = blueprint_axis_probe(&doc, env).param_space();
let raw_signal = blueprint_from_json(&doc, &|t| env.resolve(t)).unwrap_or_else(|e| {
eprintln!("aura: stored blueprint {hash} does not parse: {e:?}");
std::process::exit(1);
});
let overrides = bound_overrides_of(&recorded, &raw_space, &raw_signal);
// Reload the stored blueprint per use: a Composite is !Clone, and both the
// param-space probe (below) and the re-run each consume one. The doc was
// canonical-serialized at store time, so every reload is infallible.
// canonical-serialized at store time, so every reload is infallible. Every
// reload re-opens the same override set derived above, so the recorded
// param names resolve against the space they were minted under (#246).
let reload = || {
blueprint_from_json(&doc, &|t| env.resolve(t)).unwrap_or_else(|e| {
eprintln!("aura: stored blueprint {hash} does not parse: {e:?}");
std::process::exit(1);
})
reopen_all(
blueprint_from_json(&doc, &|t| env.resolve(t)).unwrap_or_else(|e| {
eprintln!("aura: stored blueprint {hash} does not parse: {e:?}");
std::process::exit(1);
}),
&overrides,
)
};
// The param_space of the WRAPPED signal — its knobs carry the `r_sma`
// wrapper's `sma_signal.` node-path prefix, exactly the names the manifest
@@ -1792,8 +1810,17 @@ fn run_blueprint_member(
/// boundary before this runs, so a malformed doc has already exited 2 and
/// never reaches the `.expect`.
fn blueprint_axis_probe(doc: &str, env: &project::Env) -> Composite {
blueprint_axis_probe_reopened(doc, env, &[])
}
/// The axis probe with a #246 override set re-opened on the strategy BEFORE
/// wrapping — probe and per-member reloads must re-open identically so points
/// resolve against one space. The empty-set form is byte-equal to the old
/// probe (mc/run closed-checks and the open `--list-axes` lines read that).
fn blueprint_axis_probe_reopened(doc: &str, env: &project::Env, overrides: &[String]) -> Composite {
let signal = blueprint_from_json(doc, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible");
let signal = reopen_all(signal, overrides);
// The PROBE binding is lenient (unresolvable roles fall back to close),
// like the probe's synthetic pip: the wrap is built for its param_space
// only, never run over data — strict resolution lives on the run paths.
@@ -1805,13 +1832,94 @@ fn blueprint_axis_probe(doc: &str, env: &project::Env) -> Composite {
wrap_r(signal, tx_eq, tx_ex, tx_r, tx_req, StopRule::Vol { length: R_SMA_STOP_LENGTH, k: R_SMA_STOP_K }, true, SYNTHETIC_PIP_SIZE, &probe, None)
}
/// The override subset of `names` (#246): every name missing the un-reopened
/// wrapped OPEN space but naming a BOUND param of the strategy — returned in
/// STRATEGY coordinates (the wrap prefix `<signal.name()>.` stripped) for
/// `Composite::reopen`. Names matching neither space are skipped here; the
/// caller decides whether that is an error (sweep boundary) or falls through
/// to its existing resolution errors. The silent variant `reproduce_family_in`
/// uses over the RECORDED manifest param names (the sweep boundary uses the
/// stricter `override_paths`, which errors on an unmatched name instead).
fn bound_overrides_of(
names: &[String],
open_space: &[ParamSpec],
signal: &Composite,
) -> Vec<String> {
let open: HashSet<&str> = open_space.iter().map(|p| p.name.as_str()).collect();
let prefix = format!("{}.", signal.name());
let bound: HashSet<String> = signal
.bound_param_space()
.into_iter()
.map(|b| format!("{prefix}{}", b.name))
.collect();
names
.iter()
.filter(|n| !open.contains(n.as_str()) && bound.contains(*n))
.map(|n| n[prefix.len()..].to_string())
.collect()
}
/// The sweep-boundary variant (#246): like `bound_overrides_of`, but an axis
/// matching NEITHER the open nor the bound space is the error — the honest
/// replacement of the retired "fully bound; nothing to sweep" refusal.
fn override_paths(
axes: &[(String, Vec<Scalar>)],
open_space: &[ParamSpec],
signal: &Composite,
) -> Result<Vec<String>, String> {
let open: HashSet<&str> = open_space.iter().map(|p| p.name.as_str()).collect();
let prefix = format!("{}.", signal.name());
let bound: HashSet<String> = signal
.bound_param_space()
.into_iter()
.map(|b| format!("{prefix}{}", b.name))
.collect();
let mut overrides = Vec::new();
for (name, _) in axes {
if open.contains(name.as_str()) {
continue;
}
if bound.contains(name) {
overrides.push(name[prefix.len()..].to_string());
} else {
return Err(format!(
"axis {name}: names no param of this blueprint (open or bound) — \
see `aura sweep <bp> --list-axes`"
));
}
}
Ok(overrides)
}
/// Apply a validated override set to a freshly loaded strategy (#246).
/// Infallible by contract: the set was derived against this same document at
/// the family boundary.
fn reopen_all(signal: Composite, overrides: &[String]) -> Composite {
overrides.iter().fold(signal, |s, p| {
s.reopen(p).expect("override set validated at the family boundary")
})
}
/// `aura sweep <blueprint.json> --list-axes`: one `<name>:<kind>` line per open
/// sweepable knob, in `param_space()` order; a closed blueprint prints nothing.
/// Names are exactly what `--axis` binds (same probe as the sweep terminal).
/// sweepable knob, in `param_space()` order (byte-identical to before #246),
/// followed by one `<name>:<kind> default=<value>` line per BOUND param —
/// every bound param IS a sweepable default, re-openable by naming it as an
/// `--axis` (#246), on EVERY blueprint shape (fully open, partially open, or
/// fully closed) — not only the fully-closed case: `--axis`/`override_paths`
/// accepts a bound name regardless of how many knobs happen to be open
/// alongside it, so the discovery surface must list it regardless too. Names
/// are exactly what `--axis` binds.
fn list_blueprint_axes(doc: &str, env: &project::Env) {
for p in blueprint_axis_probe(doc, env).param_space() {
let space = blueprint_axis_probe(doc, env).param_space();
for p in &space {
println!("{}:{:?}", p.name, p.kind); // ScalarKind Debug -> I64/F64/Bool/Timestamp
}
let signal = blueprint_from_json(doc, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary");
let bp = signal.name().to_string();
for b in signal.bound_param_space() {
println!("{bp}.{}:{:?} default={}", b.name, b.kind, render_value(&b.value));
}
}
/// Sweep a serialized signal `doc` over user-named param-space axes. Structurally it
@@ -1823,11 +1931,9 @@ fn list_blueprint_axes(doc: &str, env: &project::Env) {
/// The axes are taken verbatim BY NAME (not the four suffix-resolved r-sma knobs):
/// each `(name, vals)` is fed straight to the `SweepBinder`, so an unknown name or a
/// kind mismatch surfaces as the sweep terminal's [`BindError`], rendered to a message
/// string — a named error, never a panic. A FULLY BOUND (closed) blueprint has an empty
/// `param_space` — nothing to sweep — and is refused up front with a clear message
/// (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
/// string — a named error, never a panic. An axis naming a bound param re-opens it
/// (#246: bound value = default); an axis matching neither space is refused by
/// `override_paths` before any run. Every member manifest carries the shared
/// `topology_hash` of the loaded signal; reduce-mode fold, identical to the retired
/// mirror's default (no-trace) arm.
fn blueprint_sweep_family(
@@ -1836,14 +1942,11 @@ fn blueprint_sweep_family(
data: &DataSource,
env: &project::Env,
) -> Result<SweepFamily, String> {
// The doc is parse-validated at the dispatch boundary (with file-path context),
// so every reload here is infallible: the builder has a single error contract —
// the `BindError` returned by the sweep terminal — and no hidden process exit.
let reload = |d: &str| {
blueprint_from_json(d, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible")
};
let probe_signal = reload(doc);
// Identity + binding read the AUTHORED doc, raw (no override re-open):
// topology and the resolved role plan are properties of the document, not
// of any one sweep's axis choices.
let probe_signal = blueprint_from_json(doc, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible");
let topo = topology_hash(&probe_signal);
// Strict binding resolution (name defaults — the verb path carries no
// campaign overrides): the family's open plan and wrap plan in one value.
@@ -1853,23 +1956,26 @@ fn blueprint_sweep_family(
}
let pip = data.pip_size();
let window = data.full_window(env);
// a single throwaway floated build, only to resolve param_space (borrow) then seed
// the named axes (move) — its taps are never drained. The wrapped probe is the one
// `blueprint_axis_probe` single-sources (identical `false, true, None` wrap).
let probe = blueprint_axis_probe(doc, env);
// The un-reopened wrapped OPEN space (#246): derives the override set (which
// named axes re-open a bound param) before the real, reopened probe is built —
// probe and per-member reloads must re-open identically so points resolve
// against one space. A name matching neither space is the error here.
let raw_space = blueprint_axis_probe(doc, env).param_space();
let overrides = override_paths(axes, &raw_space, &probe_signal)?;
let probe = blueprint_axis_probe_reopened(doc, env, &overrides);
let space = probe.param_space();
// A fully bound blueprint has no open knob — there is nothing to sweep. Refuse it up
// front (mirroring blueprint_mc_family's closed-blueprint guard, inverted) BEFORE the
// per-axis resolve, which would otherwise return `UnknownKnob(<axis>)` — misleading, as
// the named knob is not unknown but bound out. Exit-free: the message is returned for
// the IO wrapper to render + exit 2, so the precondition is unit-testable.
if space.is_empty() {
return Err(
"this blueprint is fully bound; nothing to sweep (use `aura sweep <bp> --list-axes` \
to confirm there are no open knobs)"
.to_string(),
);
}
// The doc is parse-validated at the dispatch boundary (with file-path context),
// so every reload here is infallible: the builder has a single error contract —
// the `BindError` returned by the sweep terminal — and no hidden process exit.
// Member reloads re-open the SAME override set derived above, so every member
// resolves its axes against the identical (reopened) param space the probe used.
let reload = |d: &str| {
reopen_all(
blueprint_from_json(d, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible"),
&overrides,
)
};
// seed the named axes verbatim: the first via Composite::axis (consumes the probe),
// the rest via SweepBinder::axis. resolve_axes name- and kind-checks them at the
// sweep terminal, so an UnknownKnob / KindMismatch is returned, not panicked.
@@ -1894,7 +2000,12 @@ fn blueprint_sweep_family(
/// `[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.
/// sweep terminal (no panic, no hidden exit) for the caller to render. An axis
/// naming a bound param re-opens it (#246: bound value = default, same
/// `override_paths`/`reopen_all` recipe as `blueprint_sweep_family` — this is
/// its walk-forward in-sample twin); an axis matching neither space is refused
/// (wrapped as `BindError::UnknownKnob`, the honest replacement for the retired
/// "fully bound; nothing to sweep" refusal) before any member runs.
fn blueprint_sweep_over(
doc: &str, axes: &[(String, Vec<Scalar>)], from: Timestamp, to: Timestamp, data: &DataSource,
env: &project::Env, binding: &binding::ResolvedBinding,
@@ -1904,8 +2015,16 @@ fn blueprint_sweep_over(
.expect("doc parse-validated at the dispatch boundary; reload is infallible")
};
let pip = data.pip_size();
let topo = topology_hash(&reload(doc));
let probe = blueprint_axis_probe(doc, env);
let probe_signal = reload(doc);
let topo = topology_hash(&probe_signal);
// The un-reopened wrapped OPEN space (#246), against a raw probe + raw strategy
// load: derives the override set (which named axes re-open a bound param) before
// the reopened probe is built — probe and per-member reloads must re-open
// identically so points resolve against one space, exactly like
// `blueprint_sweep_family`.
let raw_space = blueprint_axis_probe(doc, env).param_space();
let overrides = override_paths(axes, &raw_space, &probe_signal).map_err(BindError::UnknownKnob)?;
let probe = blueprint_axis_probe_reopened(doc, env, &overrides);
let space = probe.param_space();
let mut iter = axes.iter();
let (first_name, first_vals) = iter.next().expect("a blueprint walk-forward declares >= 1 axis");
@@ -1916,21 +2035,29 @@ fn blueprint_sweep_over(
binder.sweep_with_lattice(|point| {
let sources = data.windowed_sources(from, to, env, &binding.columns());
let window = window_of(&sources).expect("non-empty in-sample window");
run_blueprint_member(reload(doc), point, &space, sources, window, 0, pip, &topo, env, StopRule::Vol { length: R_SMA_STOP_LENGTH, k: R_SMA_STOP_K }, binding, &[])
run_blueprint_member(reopen_all(reload(doc), &overrides), point, &space, sources, window, 0, pip, &topo, env, StopRule::Vol { length: R_SMA_STOP_LENGTH, k: R_SMA_STOP_K }, binding, &[])
})
}
/// Run the winner params over an out-of-sample window `[from,to]` on the loaded
/// 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).
/// segment is empty (an empty segment leaves the stitched curve unbroken). `overrides`
/// (#246) is the SAME family-wide set `blueprint_walkforward_family` derived once and
/// resolved `space`/`params` against — the OOS reload must re-open it too, or a
/// bound-param axis's winner point (kind-checked against the REOPENED space) fails
/// `bootstrap_with_cells`'s arity check against this still-closed reload.
#[allow(clippy::too_many_arguments)]
fn run_oos_blueprint(
doc: &str, params: &[Cell], space: &[ParamSpec], from: Timestamp, to: Timestamp,
topo: &str, data: &DataSource, env: &project::Env, binding: &binding::ResolvedBinding,
overrides: &[String],
) -> (Vec<(Timestamp, f64)>, RunReport) {
let reload = blueprint_from_json(doc, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible");
let reload = reopen_all(
blueprint_from_json(doc, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible"),
overrides,
);
let pip = data.pip_size();
let sources = data.windowed_sources(from, to, env, &binding.columns());
let window = window_of(&sources).expect("non-empty out-of-sample window");
@@ -1956,10 +2083,22 @@ fn blueprint_walkforward_family(
std::process::exit(2);
}
};
let space = blueprint_axis_probe(doc, env).param_space();
let probe_signal = blueprint_from_json(doc, &|t| env.resolve(t))
.expect("doc parse-validated at the dispatch boundary; reload is infallible");
let topo = topology_hash(&probe_signal);
// The un-reopened wrapped OPEN space (#246), against a raw probe + raw strategy
// load: derives the override set ONCE for the whole family — every per-window
// sweep AND the OOS reload re-open the SAME set, mirroring
// `blueprint_sweep_family`/`blueprint_sweep_over`. The SILENT variant
// (`bound_overrides_of`, not the validating `override_paths`): an axis matching
// neither space is simply not an override here — the strict check + its
// established error message stay single-sourced in `blueprint_sweep_over`'s own
// pre-flight call below, so this derivation cannot double-validate with a
// differently-worded rejection.
let axis_names: Vec<String> = axes.iter().map(|(n, _)| n.clone()).collect();
let raw_space = blueprint_axis_probe(doc, env).param_space();
let overrides = bound_overrides_of(&axis_names, &raw_space, &probe_signal);
let space = blueprint_axis_probe_reopened(doc, env, &overrides).param_space();
// Strict binding resolution, once per family; refusal is the established
// `aura: ` + exit-1 register (the roller's usage refusals stay exit 2).
let binding = binding::resolve_binding(probe_signal.name(), probe_signal.input_roles(), &BTreeMap::new())
@@ -1995,7 +2134,7 @@ fn blueprint_walkforward_family(
Err(msg) => { eprintln!("aura: {msg}"); std::process::exit(2); }
};
let (oos_equity, mut oos_report) =
run_oos_blueprint(doc, &best.params, &space, w.oos.0, w.oos.1, &topo, data, env, &binding);
run_oos_blueprint(doc, &best.params, &space, w.oos.0, w.oos.1, &topo, data, env, &binding, &overrides);
oos_report.manifest.selection = Some(selection);
WindowRun { chosen_params: best.params, oos_equity, oos_report }
})
@@ -5311,36 +5450,34 @@ mod tests {
let _ = std::fs::remove_dir_all(&dir);
}
/// Property: sweeping a FULLY BOUND (closed) blueprint is refused up front with a
/// clear "fully bound / nothing to sweep" message — NOT the terse `UnknownKnob(<axis>)`
/// the per-axis resolve would otherwise emit (misleading: the named knob is not unknown,
/// it is bound out, so there is simply nothing to sweep). Symmetric inverse of
/// `blueprint_mc_family_rejects_an_open_blueprint` (mc requires a closed blueprint; a
/// sweep requires >= 1 open knob). Type-agnostic on the error (renders it via Debug), so
/// the RED phase compiles whether the builder returns a `BindError` or a `String`.
/// #246: a fully-bound (closed) blueprint IS sweepable — an axis naming a
/// bound param re-opens it (the bound value is the default), so the retired
/// "fully bound; nothing to sweep" refusal must not resurface. Inverse
/// guard: an axis naming NEITHER an open nor a bound param gets the one
/// clear boundary message (not a terse `UnknownKnob` debug leak).
#[test]
fn blueprint_sweep_family_rejects_a_fully_bound_blueprint() {
fn blueprint_sweep_family_overrides_a_bound_param_and_names_unknown_axes() {
let env = project::Env::std();
// both SMA knobs bound -> empty param_space
// same fixture the retired test swept: both SMA knobs bound.
let closed = load_closed_r_sma();
let doc = blueprint_to_json(&closed).expect("serializes");
// an axis naming a bound-out knob: the pre-fix path returns UnknownKnob for it.
// (a) override axis: two members, no refusal
let axes = vec![(
"sma_signal.slow.length".to_string(),
vec![Scalar::i64(4), Scalar::i64(6)],
"sma_signal.fast.length".to_string(),
vec![Scalar::i64(2), Scalar::i64(4)],
)];
let err = match blueprint_sweep_family(&doc, &axes, &DataSource::Synthetic, &env) {
Ok(_) => panic!("a fully-bound blueprint has nothing to sweep"),
Err(e) => format!("{e:?}"),
};
assert!(
err.contains("fully bound") || err.contains("nothing to sweep"),
"names the fully-bound / nothing-to-sweep condition: {err}"
);
assert!(
!err.contains("UnknownKnob"),
"must not leak the misleading UnknownKnob: {err}"
);
let fam = blueprint_sweep_family(&doc, &axes, &DataSource::Synthetic, &env)
.expect("a bound param is a default — the axis overrides it");
assert_eq!(fam.points.len(), 2);
// (b) unknown axis: the boundary message, no UnknownKnob leak
let bad = vec![("sma_signal.nope".to_string(), vec![Scalar::i64(1)])];
let err = blueprint_sweep_family(&doc, &bad, &DataSource::Synthetic, &env)
.expect_err("an axis matching neither space is refused");
assert!(err.contains("names no param"), "boundary message, got: {err}");
assert!(err.contains("--list-axes"), "must point at --list-axes: {err}");
assert!(!err.contains("UnknownKnob"), "must not leak the debug render: {err}");
}
/// Property: an MC family's `aura reproduce` lines carry the member's own `seed=<N>`