feat(aura-cli): --tap TAP=FOLD fold-subscription selector on aura run

Decide #310's data-authorability fork as (b), split by run-mode
authority: selecting a Named fold subscription is data-reachable on the
one-shot run path; adding a fold stays a Rust entry (role 2, C25).
`aura run` gains a repeatable --tap TAP=FOLD selector feeding the
existing TapPlan seam: no flag keeps the record-all default; any flag
replaces the plan entirely (unlisted taps stay unbound — C27 inert,
non-error). Validation stays in bind_tap_plan (roster-enumerating label
refusal, typed UndeclaredTap, both before store I/O); parse-level
refusals (malformed pair, duplicate tap) exit 2 via the verb's usage
convention.

Rejected alternatives (minuted on #310 with the skeptic-pass
rationale): an op-script/blueprint carrier (C27 forbids recording
policy in the serialized fragment); ratifying Rust-only (softens a
designed-in promise with effort as the only rationale). The
campaign/document carrier and the persist_taps/declared-tap namespace
reconciliation are deferred to the Measurement-reachable milestone
(#312/#327, minuted on #312).

Ledger: C27 Current state records the boundary; the superseded sentence
moved verbatim to the new c27-declared-taps.history.md sidecar; the
glossary tap-plan paragraph updated, fixing the pre-existing inaccuracy
that named `aura measure` a record-all-passing verb (it is the post-hoc
IC analysis and constructs no tap plan).

Verification: 5 new unit tests (parse branches), 5 new binary-level
selector tests incl. a byte-identity pin of an explicit all-record plan
vs the record-all default (C1), 1 measurement-arm test; full workspace
suite green; clippy -D warnings clean. Independent opus diff review:
approved, no Important/Minor findings (nits: inert-arm generic refusal,
a=b=c falling to the roster refusal — accepted as-is).

closes #310
This commit is contained in:
2026-07-24 15:03:39 +02:00
parent 9124275bf3
commit 1baee774bb
6 changed files with 280 additions and 5 deletions
+79 -3
View File
@@ -46,7 +46,7 @@ use aura_measurement::information_coefficient;
// (a sibling module reaching it via `crate::blueprint_axis_probe_reopened`,
// the crate-root re-export this `use` gives it), not from this module itself.
use aura_runner::member::{blueprint_axis_probe, blueprint_axis_probe_reopened, run_signal_r, wrapped_bound_names, RunData};
use aura_runner::TapPlan;
use aura_runner::{TapPlan, TapSubscription};
#[cfg(test)]
use aura_runner::member::{run_blueprint_member, wrap_r, SYNTHETIC_PIP_SIZE};
// The family builders (blueprint sweep / walk-forward / MC), the shared
@@ -105,6 +105,7 @@ use aura_std::Sma;
#[cfg(test)]
use std::sync::mpsc;
use std::collections::HashSet;
use std::collections::BTreeSet;
#[cfg(test)]
use std::collections::BTreeMap;
use clap::{Args, Parser, Subcommand};
@@ -1343,6 +1344,12 @@ struct RunCmd {
/// Not accepted — CLI-side trace persistence is retired (see #224).
#[arg(long)]
trace: Option<String>,
/// Subscribe a declared tap to a fold for this run (repeatable,
/// TAP=FOLD; e.g. --tap signal=mean). Replaces the record-all
/// default: only listed taps are bound, unlisted taps stay unbound.
/// Fold roster: `aura graph introspect --folds`.
#[arg(long = "tap", value_name = "TAP=FOLD")]
tap: Vec<String>,
}
#[derive(Args)]
@@ -1761,6 +1768,32 @@ fn campaign_window_ms(choice: DataChoice, env: &aura_runner::project::Env) -> (i
)
}
/// Build the run's tap plan from repeated `--tap TAP=FOLD` selections
/// (#310). No selections → the record-all default (today's behaviour).
/// Any selection → an explicit plan that REPLACES the default entirely:
/// only listed taps are bound; unlisted declared taps stay unbound,
/// which C27 defines as inert, not an error. Tap/label existence is
/// bind_tap_plan's to validate (roster refusal / UndeclaredTap), before
/// any store I/O.
fn tap_plan_from_args(args: &[String]) -> Result<TapPlan, String> {
if args.is_empty() {
return Ok(TapPlan::record_all());
}
let mut plan = TapPlan::empty();
let mut seen = BTreeSet::new();
for raw in args {
let (tap, label) = match raw.split_once('=') {
Some((t, l)) if !t.is_empty() && !l.is_empty() => (t, l),
_ => return Err(format!("--tap expects TAP=FOLD, got \"{raw}\"")),
};
if !seen.insert(tap.to_string()) {
return Err(format!("--tap names tap \"{tap}\" twice"));
}
plan.subscribe(tap, TapSubscription::named(label));
}
Ok(plan)
}
/// `aura run`: the loaded-blueprint branch (an existing `.json` first-positional) or
/// the built-in harness-kind dispatch.
fn dispatch_run(a: RunCmd, env: &aura_runner::project::Env) {
@@ -1797,6 +1830,13 @@ fn dispatch_run(a: RunCmd, env: &aura_runner::project::Env) {
// probing a no-`bias` signal would panic on UnknownOutPort).
let has_bias = signal.output().iter().any(|o| o.name == "bias");
let has_tap = !signal.taps().is_empty();
let tap_plan = match tap_plan_from_args(&a.tap) {
Ok(p) => p,
Err(m) => {
eprintln!("aura: {m}");
std::process::exit(2);
}
};
if has_bias {
// Refuse an open (free-knob) blueprint at the dispatch boundary,
// mirroring `blueprint_mc_family`'s closed-guard: `run` bootstraps
@@ -1819,7 +1859,7 @@ fn dispatch_run(a: RunCmd, env: &aura_runner::project::Env) {
None => Vec::new(),
};
let data = run_data_from(a.real.as_deref(), a.from, a.to);
let report = run_signal_r(signal, &params, data, a.seed.unwrap_or(0), env, TapPlan::record_all());
let report = run_signal_r(signal, &params, data, a.seed.unwrap_or(0), env, tap_plan);
println!("{}", report.to_json());
} else if has_tap {
// Measurement path: wrap_r-free closed guard via the signal's own
@@ -1840,7 +1880,7 @@ fn dispatch_run(a: RunCmd, env: &aura_runner::project::Env) {
None => Vec::new(),
};
let data = run_data_from(a.real.as_deref(), a.from, a.to);
let report = run_measurement(signal, &params, data, a.seed.unwrap_or(0), env, TapPlan::record_all());
let report = run_measurement(signal, &params, data, a.seed.unwrap_or(0), env, tap_plan);
println!("{}", report.to_json());
} else {
eprintln!(
@@ -3859,5 +3899,41 @@ mod tests {
assert_eq!(stop_length, R_SMA_STOP_LENGTH, "omitted --stop-length defaults to the regime");
assert_eq!(stop_k, R_SMA_STOP_K, "omitted --stop-k defaults to the regime");
}
#[test]
fn tap_plan_from_args_empty_is_record_all_ok() {
assert!(tap_plan_from_args(&[]).is_ok());
}
#[test]
fn tap_plan_from_args_refuses_a_pair_without_equals() {
let err = match tap_plan_from_args(&["fast_tapmean".to_string()]) {
Err(e) => e,
Ok(_) => panic!("expected an error"),
};
assert_eq!(err, "--tap expects TAP=FOLD, got \"fast_tapmean\"");
}
#[test]
fn tap_plan_from_args_refuses_empty_tap_or_label() {
assert!(tap_plan_from_args(&["=mean".to_string()]).is_err());
assert!(tap_plan_from_args(&["fast_tap=".to_string()]).is_err());
}
#[test]
fn tap_plan_from_args_refuses_the_same_tap_twice() {
let args = vec!["a=mean".to_string(), "a=last".to_string()];
let err = match tap_plan_from_args(&args) {
Err(e) => e,
Ok(_) => panic!("expected an error"),
};
assert_eq!(err, "--tap names tap \"a\" twice");
}
#[test]
fn tap_plan_from_args_accepts_distinct_selections() {
let args = vec!["a=mean".to_string(), "b=record".to_string()];
assert!(tap_plan_from_args(&args).is_ok());
}
}