diff --git a/README.md b/README.md index 2bca8e9..d611177 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,8 @@ Invoke it as `aura …` (examples below use the plain name). a Monte-Carlo seed set, a walk-forward window sequence). Families are persisted in a content-addressed store and can be listed, ranked, and reproduced. - **Axis** — one named, sweepable knob of a blueprint (e.g. `graph.fast.length`), - bound with a comma-separated value list. + bound with a comma-separated value list. A **gang** fuses several sibling + knobs into one axis (one value drives all members). ## Running & orchestrating a loaded blueprint @@ -115,7 +116,8 @@ aura graph build < crossover.ops.json > crossover.bp.json aura sweep crossover.bp.json --list-axes ``` -The op kinds are `source`, `input`, `add`, `feed`, `connect`, and `expose`. See +The op kinds are `source`, `input`, `add`, `feed`, `connect`, `expose`, and +`gang`. See `aura graph introspect --node ` for a type's exact ports and the op-script grammar in the design ledger for the full semantics. diff --git a/crates/aura-cli/examples/r_breakout_open.json b/crates/aura-cli/examples/r_breakout_open.json index b760645..6bb36e4 100644 --- a/crates/aura-cli/examples/r_breakout_open.json +++ b/crates/aura-cli/examples/r_breakout_open.json @@ -1 +1 @@ -{"format_version":1,"blueprint":{"name":"r_breakout_signal","nodes":[{"primitive":{"type":"Delay","bound":[{"pos":0,"name":"lag","kind":"I64","value":{"I64":1}}]}},{"primitive":{"type":"RollingMax","name":"channel_hi"}},{"primitive":{"type":"RollingMin","name":"channel_lo"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Sub"}}],"edges":[{"from":0,"to":1,"slot":0,"from_field":0},{"from":0,"to":2,"slot":0,"from_field":0},{"from":1,"to":3,"slot":1,"from_field":0},{"from":2,"to":4,"slot":0,"from_field":0},{"from":3,"to":5,"slot":0,"from_field":0},{"from":4,"to":5,"slot":1,"from_field":0},{"from":4,"to":6,"slot":0,"from_field":0},{"from":3,"to":6,"slot":1,"from_field":0},{"from":5,"to":7,"slot":0,"from_field":0},{"from":6,"to":7,"slot":1,"from_field":0}],"input_roles":[{"name":"price","targets":[{"node":0,"slot":0},{"node":3,"slot":0},{"node":4,"slot":1}],"source":"F64"}],"output":[{"node":7,"field":0,"name":"bias"}]}} \ No newline at end of file +{"format_version":1,"blueprint":{"name":"r_breakout_signal","nodes":[{"primitive":{"type":"Delay","bound":[{"pos":0,"name":"lag","kind":"I64","value":{"I64":1}}]}},{"primitive":{"type":"RollingMax","name":"channel_hi"}},{"primitive":{"type":"RollingMin","name":"channel_lo"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Sub"}}],"edges":[{"from":0,"to":1,"slot":0,"from_field":0},{"from":0,"to":2,"slot":0,"from_field":0},{"from":1,"to":3,"slot":1,"from_field":0},{"from":2,"to":4,"slot":0,"from_field":0},{"from":3,"to":5,"slot":0,"from_field":0},{"from":4,"to":5,"slot":1,"from_field":0},{"from":4,"to":6,"slot":0,"from_field":0},{"from":3,"to":6,"slot":1,"from_field":0},{"from":5,"to":7,"slot":0,"from_field":0},{"from":6,"to":7,"slot":1,"from_field":0}],"input_roles":[{"name":"price","targets":[{"node":0,"slot":0},{"node":3,"slot":0},{"node":4,"slot":1}],"source":"F64"}],"output":[{"node":7,"field":0,"name":"bias"}],"gangs":[{"name":"channel_length","kind":"I64","members":[{"node":1,"pos":0,"name":"length"},{"node":2,"pos":0,"name":"length"}]}]}} \ No newline at end of file diff --git a/crates/aura-cli/examples/r_meanrev_open.json b/crates/aura-cli/examples/r_meanrev_open.json index 7631b15..05bf383 100644 --- a/crates/aura-cli/examples/r_meanrev_open.json +++ b/crates/aura-cli/examples/r_meanrev_open.json @@ -1 +1 @@ -{"format_version":1,"blueprint":{"name":"r_meanrev_signal","nodes":[{"primitive":{"type":"EMA","name":"mean_window"}},{"primitive":{"type":"Sub"}},{"primitive":{"type":"Mul"}},{"primitive":{"type":"EMA","name":"var_window"}},{"primitive":{"type":"Sqrt"}},{"primitive":{"type":"Scale","name":"band"}},{"primitive":{"type":"Add"}},{"primitive":{"type":"Sub"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Sub"}}],"edges":[{"from":0,"to":1,"slot":1,"from_field":0},{"from":1,"to":2,"slot":0,"from_field":0},{"from":1,"to":2,"slot":1,"from_field":0},{"from":2,"to":3,"slot":0,"from_field":0},{"from":3,"to":4,"slot":0,"from_field":0},{"from":4,"to":5,"slot":0,"from_field":0},{"from":0,"to":6,"slot":0,"from_field":0},{"from":5,"to":6,"slot":1,"from_field":0},{"from":0,"to":7,"slot":0,"from_field":0},{"from":5,"to":7,"slot":1,"from_field":0},{"from":6,"to":8,"slot":1,"from_field":0},{"from":7,"to":9,"slot":0,"from_field":0},{"from":8,"to":10,"slot":0,"from_field":0},{"from":9,"to":10,"slot":1,"from_field":0},{"from":9,"to":11,"slot":0,"from_field":0},{"from":8,"to":11,"slot":1,"from_field":0},{"from":11,"to":12,"slot":0,"from_field":0},{"from":10,"to":12,"slot":1,"from_field":0}],"input_roles":[{"name":"price","targets":[{"node":0,"slot":0},{"node":1,"slot":0},{"node":8,"slot":0},{"node":9,"slot":1}],"source":"F64"}],"output":[{"node":12,"field":0,"name":"bias"}]}} \ No newline at end of file +{"format_version":1,"blueprint":{"name":"r_meanrev_signal","nodes":[{"primitive":{"type":"EMA","name":"mean_window"}},{"primitive":{"type":"Sub"}},{"primitive":{"type":"Mul"}},{"primitive":{"type":"EMA","name":"var_window"}},{"primitive":{"type":"Sqrt"}},{"primitive":{"type":"Scale","name":"band"}},{"primitive":{"type":"Add"}},{"primitive":{"type":"Sub"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Gt"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Latch"}},{"primitive":{"type":"Sub"}}],"edges":[{"from":0,"to":1,"slot":1,"from_field":0},{"from":1,"to":2,"slot":0,"from_field":0},{"from":1,"to":2,"slot":1,"from_field":0},{"from":2,"to":3,"slot":0,"from_field":0},{"from":3,"to":4,"slot":0,"from_field":0},{"from":4,"to":5,"slot":0,"from_field":0},{"from":0,"to":6,"slot":0,"from_field":0},{"from":5,"to":6,"slot":1,"from_field":0},{"from":0,"to":7,"slot":0,"from_field":0},{"from":5,"to":7,"slot":1,"from_field":0},{"from":6,"to":8,"slot":1,"from_field":0},{"from":7,"to":9,"slot":0,"from_field":0},{"from":8,"to":10,"slot":0,"from_field":0},{"from":9,"to":10,"slot":1,"from_field":0},{"from":9,"to":11,"slot":0,"from_field":0},{"from":8,"to":11,"slot":1,"from_field":0},{"from":11,"to":12,"slot":0,"from_field":0},{"from":10,"to":12,"slot":1,"from_field":0}],"input_roles":[{"name":"price","targets":[{"node":0,"slot":0},{"node":1,"slot":0},{"node":8,"slot":0},{"node":9,"slot":1}],"source":"F64"}],"output":[{"node":12,"field":0,"name":"bias"}],"gangs":[{"name":"window","kind":"I64","members":[{"node":0,"pos":0,"name":"length"},{"node":3,"pos":0,"name":"length"}]}]}} \ No newline at end of file diff --git a/crates/aura-cli/src/main.rs b/crates/aura-cli/src/main.rs index 0a205e6..aa581f7 100644 --- a/crates/aura-cli/src/main.rs +++ b/crates/aura-cli/src/main.rs @@ -1831,8 +1831,8 @@ const R_BREAKOUT_CHANNEL: i64 = 3; /// as blueprint data (#159 cut 2). The signal computation matches the retired fused /// builder's leg (same nodes, same wiring); the pip/R harness is the generic /// `wrap_r` wrapper, not part of the signal. `channel = Some(n)` binds both rolling -/// nodes (closed); `None` leaves them open (two sweep axes — per-node exposure; -/// ganging one knob into both is the separate #61). This carve has no production +/// nodes (closed); `None` leaves them open, ganged into the single `channel_length` +/// knob (#61) — the channel is structurally ONE parameter. This carve has no production /// (non-test) caller — it is exercised only by the regeneration + proof tests below; /// production code loads the shipped JSON, not this builder — hence `#[cfg(test)]`. #[cfg(test)] @@ -1847,6 +1847,9 @@ fn r_breakout_signal(channel: Option) -> Composite { } let mx = g.add(mx_b); let mn = g.add(mn_b); + if channel.is_none() { + g.gang("channel_length", [mx.param("length"), mn.param("length")]); + } let gt_up = g.add(Gt::builder()); let gt_down = g.add(Gt::builder()); let up_latch = g.add(Latch::builder()); @@ -1869,8 +1872,9 @@ fn r_breakout_signal(channel: Option) -> Composite { } /// The EWMA window for the canonical closed r_meanrev example (ganged mean/var Ema -/// length). Single source for the emitter and the proof tests that must all agree -/// with the baked `examples/r_meanrev.json`. +/// length; the open form gangs them structurally via the single `window` knob, #61). +/// Single source for the emitter and the proof tests that must all agree with the +/// baked `examples/r_meanrev.json`. #[cfg(test)] const R_MEANREV_WINDOW: i64 = 3; @@ -1898,6 +1902,9 @@ fn r_meanrev_signal(window: Option, band_k: Option) -> Composite { let dev = g.add(Sub::builder()); // price - mean let sq = g.add(Mul::builder()); // dev * dev let var = g.add(var_b); // EWMA variance + if window.is_none() { + g.gang("window", [mean.param("length"), var.param("length")]); + } let sigma = g.add(Sqrt::builder()); let mut band_b = Scale::builder().named("band"); if let Some(k) = band_k { diff --git a/crates/aura-cli/tests/cli_run.rs b/crates/aura-cli/tests/cli_run.rs index a56864f..0d9582a 100644 --- a/crates/aura-cli/tests/cli_run.rs +++ b/crates/aura-cli/tests/cli_run.rs @@ -1739,7 +1739,7 @@ fn generalize_real_e2e_pins_the_exact_current_grade() { /// `r_sma_open.json`, so a regression that silently special-cased r-sma paths /// back in (e.g. resolving axes against a hardcoded `sma_signal.*` namespace) /// would ship green there while breaking every other blueprint. This runs the -/// unrelated r-breakout candidate (`channel_hi`/`channel_lo` axes, no +/// unrelated r-breakout candidate (the ganged `channel_length` axis, no /// `sma_signal` node in sight) end-to-end and asserts a well-formed two- /// instrument grade. Gated on the shared GER40/USDJPY Sept-2024 archive; skips /// cleanly on a data refusal. @@ -1752,8 +1752,7 @@ fn generalize_grades_a_non_r_sma_blueprint() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura")) .args([ "generalize", &fixture, "--real", "GER40,USDJPY", - "--axis", "r_breakout_signal.channel_hi.length=20", - "--axis", "r_breakout_signal.channel_lo.length=20", + "--axis", "r_breakout_signal.channel_length=20", "--stop-length", "14", "--stop-k", "2.0", "--from", FROM_MS, "--to", TO_MS, ]) @@ -1848,9 +1847,9 @@ fn walkforward_real_e2e_pins_the_exact_current_grade() { /// namespace (e.g. in `walkforward_summary_json_from_reports`'s per-axis /// `raw_matches_wrapped` search) would ship green there while breaking every /// other blueprint. This runs the unrelated r-breakout candidate -/// (`channel_hi`/`channel_lo` axes, no `sma_signal` node in sight) end-to-end +/// (the ganged `channel_length` axis, no `sma_signal` node in sight) end-to-end /// and asserts a well-formed multi-window summary whose `param_stability` has -/// exactly one entry per bound axis (2 blueprint axes + the 2 stop columns). +/// exactly one entry per bound axis (1 ganged blueprint axis + the 2 stop columns). /// The window count (9) is roller/data-derived, not strategy-derived, so it is /// pinned exactly against the same GER40 2025 span the r-sma anchor uses. /// Gated on the shared GER40 archive; skips cleanly on a data refusal. @@ -1863,8 +1862,7 @@ fn walkforward_dissolves_a_non_r_sma_blueprint() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura")) .args([ "walkforward", &fixture, "--real", "GER40", - "--axis", "r_breakout_signal.channel_hi.length=10,20", - "--axis", "r_breakout_signal.channel_lo.length=10,20", + "--axis", "r_breakout_signal.channel_length=10,20", "--stop-length", "14", "--stop-k", "2.0", "--from", FROM_MS, "--to", TO_MS, ]) @@ -1891,7 +1889,7 @@ fn walkforward_dissolves_a_non_r_sma_blueprint() { assert_eq!(wf["windows"].as_u64(), Some(9), "window count (data/roller-derived): {grade_line}"); assert!(wf["oos_r"]["n_trades"].as_u64().is_some(), "pooled OOS trade count present: {grade_line}"); let ps = wf["param_stability"].as_array().expect("param_stability is an array"); - assert_eq!(ps.len(), 4, "one entry per bound axis (channel_hi, channel_lo, stop_length, stop_k): {grade_line}"); + assert_eq!(ps.len(), 3, "one entry per bound axis (channel_length, stop_length, stop_k): {grade_line}"); } /// Fork A: the dissolved walkforward binds the stop as a single risk regime, so a @@ -3882,7 +3880,7 @@ fn mc_r_bootstrap_real_e2e_pins_the_exact_current_grade() { /// exercises `r_sma_open.json`; a regression that silently special-cased the /// pipeline's axis lookup back to a hardcoded `sma_signal.*` namespace would /// ship green there while breaking every other blueprint. This runs the -/// unrelated r-breakout candidate (`channel_hi`/`channel_lo` axes, no +/// unrelated r-breakout candidate (the ganged `channel_length` axis, no /// `sma_signal` node in sight) end-to-end and asserts a well-formed /// `mc_r_bootstrap` grade: the argv-echoed knobs (`block_len`/`n_resamples`) /// pin exactly, `n_trades`/`e_r.mean`/`prob_le_zero` are asserted present and @@ -3898,8 +3896,7 @@ fn mc_dissolves_a_non_r_sma_blueprint() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura")) .args([ "mc", &fixture, "--real", "GER40", - "--axis", "r_breakout_signal.channel_hi.length=10,20", - "--axis", "r_breakout_signal.channel_lo.length=10,20", + "--axis", "r_breakout_signal.channel_length=10,20", "--stop-length", "14", "--stop-k", "2.0", "--block-len", "5", "--resamples", "1000", "--seed", "42", "--from", FROM_MS, "--to", TO_MS, @@ -4175,8 +4172,7 @@ fn walkforward_campaign_runs_an_arbitrary_blueprint() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura")) .args([ "walkforward", &fixture, "--real", "GER40", - "--axis", "r_breakout_signal.channel_hi.length=20,40", - "--axis", "r_breakout_signal.channel_lo.length=10,20", + "--axis", "r_breakout_signal.channel_length=10,20", "--stop-length", "3", "--stop-k", "2.0", "--from", FROM_MS, "--to", TO_MS, ]) @@ -4207,9 +4203,9 @@ fn walkforward_campaign_runs_an_arbitrary_blueprint() { let v: serde_json::Value = serde_json::from_str(grade_line).expect("summary line parses as JSON"); let wf = &v["walkforward"]; assert!(wf["windows"].as_u64().is_some_and(|w| w >= 1), "at least one window: {grade_line}"); - // param_stability rows: channel_hi, channel_lo, stop_length, stop_k. + // param_stability rows: channel_length, stop_length, stop_k. let ps = wf["param_stability"].as_array().expect("param_stability is an array"); - assert_eq!(ps.len(), 4, "two channel axes + the stop pair: {grade_line}"); + assert_eq!(ps.len(), 3, "one ganged channel axis + the stop pair: {grade_line}"); } /// #220 weld-gone proof for mc: the R-bootstrap pipeline runs the same @@ -4227,8 +4223,7 @@ fn mc_campaign_runs_an_arbitrary_blueprint() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura")) .args([ "mc", &fixture, "--real", "GER40", - "--axis", "r_breakout_signal.channel_hi.length=20,40", - "--axis", "r_breakout_signal.channel_lo.length=10,20", + "--axis", "r_breakout_signal.channel_length=10,20", "--stop-length", "3", "--stop-k", "2.0", "--block-len", "5", "--resamples", "100", "--seed", "7", "--from", FROM_MS, "--to", TO_MS, @@ -4263,8 +4258,9 @@ fn mc_campaign_runs_an_arbitrary_blueprint() { } /// #220 weld-gone proof for generalize: one mean-reversion candidate graded -/// across two instruments — three axes with names the CLI has never heard of, -/// including an F64 axis. Gated on the GER40/USDJPY Sept-2024 archive. +/// across two instruments — two axes with names the CLI has never heard of — +/// one ganged I64 window and an independent F64 band. Gated on the GER40/USDJPY +/// Sept-2024 archive. #[test] fn generalize_campaign_runs_an_arbitrary_blueprint() { if !local_data_present() { @@ -4276,8 +4272,7 @@ fn generalize_campaign_runs_an_arbitrary_blueprint() { let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura")) .args([ "generalize", &fixture, "--real", "GER40,USDJPY", - "--axis", "r_meanrev_signal.mean_window.length=20", - "--axis", "r_meanrev_signal.var_window.length=20", + "--axis", "r_meanrev_signal.window=20", "--axis", "r_meanrev_signal.band.factor=2.0", "--stop-length", "3", "--stop-k", "2.0", "--from", GER40_SEPT2024_FROM_MS, "--to", GER40_SEPT2024_TO_MS, diff --git a/crates/aura-cli/tests/graph_construct.rs b/crates/aura-cli/tests/graph_construct.rs index 7930847..7f112ad 100644 --- a/crates/aura-cli/tests/graph_construct.rs +++ b/crates/aura-cli/tests/graph_construct.rs @@ -744,7 +744,8 @@ fn shipped_r_breakout_example_is_genuinely_closed() { } /// Property (#159 cut 2): the shipped open example (`examples/r_breakout_open.json`) -/// lists its two channel axes, in lowering order (per-node exposure; ganging is #61). +/// lists its ONE ganged channel axis (#61: the two rolling windows are structurally +/// one knob). #[test] fn shipped_r_breakout_open_example_lists_its_axis_namespace() { let dir = temp_cwd("r-breakout-example-open-params"); @@ -752,8 +753,47 @@ fn shipped_r_breakout_open_example_lists_its_axis_namespace() { run_in(&dir, &["graph", "introspect", "--params", &example("r_breakout_open.json")]); assert_eq!(code, Some(0), "stdout: {stdout} stderr: {stderr}"); assert_eq!( - stdout, "channel_hi.length:I64\nchannel_lo.length:I64\n", - "the raw open params, in order, from the public gallery copy" + stdout, "channel_length:I64\n", + "the ganged channel knob — one public axis for the two rolling windows (#61)" + ); +} + +/// Property (#61 + #159 cut 2): binding the shipped open example's ganged +/// `channel_length` axis through the REAL `aura sweep` CLI pipeline (argv -> +/// `parse_axes` -> `compile_with_cells`'s gang expansion) reproduces the exact +/// metrics of running the shipped CLOSED example, whose `channel_hi`/ +/// `channel_lo` are separately hardwired to the same value. The equivalence +/// between a gang and its member-bound twin is already pinned at the builder/ +/// engine level (aura-engine's `gang_e2e.rs`, and this crate's +/// `r_breakout_example_loaded_runs_identically_to_the_carved_signal`, which +/// calls `run_signal_r` directly); this instead drives the actual public +/// binary end-to-end on the actual shipped files, so a regression in the +/// CLI's own axis-name resolution or grid-point binding (e.g. silently +/// treating the gang as an unbound param, or fanning the value to only one +/// member) would be caught here even if the internal builder-level +/// equivalence still holds. +#[test] +fn shipped_r_breakout_open_gang_axis_matches_the_closed_example() { + let closed_dir = temp_cwd("r-breakout-gang-axis-closed"); + let (closed_stdout, closed_stderr, closed_code) = run_in(&closed_dir, &["run", &example("r_breakout.json")]); + assert_eq!(closed_code, Some(0), "closed run stderr: {closed_stderr}"); + let closed: serde_json::Value = + serde_json::from_str(closed_stdout.trim()).expect("closed run report parses as JSON"); + + let sweep_dir = temp_cwd("r-breakout-gang-axis-sweep"); + let (sweep_stdout, sweep_stderr, sweep_code) = run_in( + &sweep_dir, + &["sweep", &example("r_breakout_open.json"), "--axis", "r_breakout_signal.channel_length=3"], + ); + assert_eq!(sweep_code, Some(0), "sweep stderr: {sweep_stderr}"); + let lines: Vec<&str> = sweep_stdout.lines().collect(); + assert_eq!(lines.len(), 1, "one grid point for a single-value axis: {sweep_stdout}"); + let member: serde_json::Value = serde_json::from_str(lines[0]).expect("member line parses as JSON"); + + assert_eq!( + member["report"]["metrics"], closed["metrics"], + "channel_length=3, bound via the real sweep CLI, must fan out to both channel_hi \ + and channel_lo identically to the closed example's hardwired channel=3" ); } @@ -777,8 +817,45 @@ fn shipped_r_meanrev_open_example_lists_its_axis_namespace() { run_in(&dir, &["graph", "introspect", "--params", &example("r_meanrev_open.json")]); assert_eq!(code, Some(0), "stdout: {stdout} stderr: {stderr}"); assert_eq!( - stdout, "mean_window.length:I64\nvar_window.length:I64\nband.factor:F64\n", - "the raw open params, in lowering order" + stdout, "window:I64\nband.factor:F64\n", + "the ganged EWMA window + the independent band knob, in lowering order" + ); +} + +/// Property (#61 + #159 cut 3): a sweep over TWO axes at once — the ganged +/// `window` knob (fusing `mean_window.length`/`var_window.length`) alongside +/// the independent, un-ganged `band.factor` knob — binds both correctly +/// through the real CLI grid, matching the shipped closed example's hardwired +/// window=3/band=2.0. This is a distinct risk from the r_breakout gang test +/// (a lone gang axis): a mis-scoped gang-expansion map that shifts sibling +/// param positions could silently mis-bind the co-present un-ganged axis +/// instead (or vice-versa) even though each axis alone still resolves. +#[test] +fn shipped_r_meanrev_open_gang_plus_plain_axis_matches_the_closed_example() { + let closed_dir = temp_cwd("r-meanrev-gang-axis-closed"); + let (closed_stdout, closed_stderr, closed_code) = run_in(&closed_dir, &["run", &example("r_meanrev.json")]); + assert_eq!(closed_code, Some(0), "closed run stderr: {closed_stderr}"); + let closed: serde_json::Value = + serde_json::from_str(closed_stdout.trim()).expect("closed run report parses as JSON"); + + let sweep_dir = temp_cwd("r-meanrev-gang-axis-sweep"); + let (sweep_stdout, sweep_stderr, sweep_code) = run_in( + &sweep_dir, + &[ + "sweep", &example("r_meanrev_open.json"), + "--axis", "r_meanrev_signal.window=3", + "--axis", "r_meanrev_signal.band.factor=2.0", + ], + ); + assert_eq!(sweep_code, Some(0), "sweep stderr: {sweep_stderr}"); + let lines: Vec<&str> = sweep_stdout.lines().collect(); + assert_eq!(lines.len(), 1, "one grid point for two single-value axes: {sweep_stdout}"); + let member: serde_json::Value = serde_json::from_str(lines[0]).expect("member line parses as JSON"); + + assert_eq!( + member["report"]["metrics"], closed["metrics"], + "window=3 (ganged) + band.factor=2.0 (plain), bound via the real sweep CLI, must \ + match the closed example's hardwired window=3/band=2.0" ); } diff --git a/docs/authoring-guide.md b/docs/authoring-guide.md index 9c2605c..6e984a1 100644 --- a/docs/authoring-guide.md +++ b/docs/authoring-guide.md @@ -31,7 +31,7 @@ $ aura graph build < smacross.json > blueprint.json Nodes are referenced by an **identifier** (given by `add`, see below); ports are dotted `.` on both sides of a wire. -### The six ops +### The seven ops | op | JSON shape | does | |---|---|---| @@ -41,6 +41,7 @@ are dotted `.` on both sides of a wire. | `feed` | `{"op":"feed","role":,"into":[, …]}` | fan a previously-declared role into one or more interior input slots, all-or-nothing (a failing target leaves none of the batch wired). | | `connect` | `{"op":"connect","from":,"to":}` | wire one interior output field to one interior input slot. A `connect` that would close a dataflow cycle is rejected immediately — the only legal feedback path is an explicit delay/state node (domain invariant 5). | | `expose` | `{"op":"expose","from":,"as":}` | promote an interior output field to a boundary output under the alias `as` — the only op whose name key is a real *alias* (contrast `add`'s `name`, which is an identifier, not a rename). | +| `gang` | `{"op":"gang","as":"channel_length","into":["channel_hi.length","channel_lo.length"]}` | Fuse two or more sibling params into ONE public knob: the member addresses leave the sweepable param space and `as` replaces them; the bound or swept value fans out to every member at bootstrap. Members must share one scalar kind and stay open (un-bound). | Value forms are the typed-tag representations used everywhere in this family of artifacts: @@ -78,6 +79,12 @@ up in `--params`/`--list-axes`, and no campaign axis and no `aura sweep --axis` can reopen it. `bind` is for a constant the strategy never varies; leave a param unbound, as all three are here, to keep it open for sweeping. +A param therefore has three states: **open** (a sweepable axis), **bound** +(closed by a `bind` — gone from the axis namespace), and **ganged** (open, but +fused with its siblings under ONE public knob declared by a `gang` op; the +member addresses are unbindable and only the gang's own single-segment name — +wrapped like any knob, e.g. `graph.channel_length` — appears in `--list-axes`). + ### Commands ``` @@ -125,6 +132,10 @@ raw (--params, campaign axes): fast.length wrapped (--list-axes, --axis): graph.fast.length ``` +A ganged knob's raw address has one path segment less than a member address +would — it sits at the composite's own level, like a role name (e.g. +`channel_length`, not `channel_hi.length`) — and wraps identically (`graph.channel_length`). + `--content-id`, `--identity-id`, `--params`, and `graph register` all accept **either** shape: the raw op-script array or an already-built `#155` blueprint envelope (object) — shape-discriminated automatically, so you diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md index bf439a6..5956609 100644 --- a/docs/design/INDEX.md +++ b/docs/design/INDEX.md @@ -2093,6 +2093,11 @@ node type, edge semantics, or structural-axis kind) bumps `format_version` so an old reader refuses cleanly (`LoadError::UnsupportedVersion` / `UnknownNodeType`, already green). The per-section required-flag scheme is deferred (no current Tier-2 section to validate it; recorded on #156). +Pre-ship dormancy (#61, 2026-07-10): until the first external ship there are +no out-of-repo readers — reader and writer change atomically in one commit — +so the Tier-2 bump discipline is dormant and structurally-semantic additions +(the `gangs` section) land as additive-optional fields of v1; the first ship +consciously freezes v1, gangs included, and activates the bump discipline. **Milestone delivered — 2026-06-30, cycle 0090 — the serializable format + loader + construction service.** A green end-to-end milestone fieldtest (`fieldtests/milestone-topology-as-data/`) proves the full author → serialize → load → construct → introspect → reproduce story from the public surface alone, 0 behavioural bugs; the round-trippable format (#155), the construction service (#157), and the forward-compat two-tier discipline (#156) all shipped. Polish filed forward: op-script grammar docs + a stale example (#163), the canonical trailing-newline / `Composite` value ergonomics (#164), CLI discoverability of `build`/`introspect` (#159). **Realization (2026-06-30, cycle 0092 — runs are built FROM blueprint-data, #165).** `aura run ` now loads a serialized **signal** blueprint @@ -2195,7 +2200,7 @@ fixture from the scaffolder. **Op-script grammar (`aura graph build`, the #157 wire surface).** The construction op-script is a JSON **array of ops**, each object internally tagged by `"op"`, replayed in order; nodes are referenced **by identifier**, ports as dotted -`.`. The six verbs: +`.`. The seven verbs: - `source` — `{"op":"source","role":,"kind":}` — declare a root source role producing a base column of `kind`. - `input` — `{"op":"input","role":}` — declare a root input role (kind inferred @@ -2212,6 +2217,11 @@ replayed in order; nodes are referenced **by identifier**, ports as dotted - `expose` — `{"op":"expose","from":,"as":}` — promote an interior output field to a boundary output, aliased by `as` — **the only verb that keeps `as`** (a real alias, not a naming; contrast `add`'s `name`). +- `gang` — `{"op":"gang","as":"channel_length","into":["channel_hi.length","channel_lo.length"]}` + — fuse two or more sibling params into ONE public knob: the member addresses + leave the sweepable param space and `as` replaces them; the bound or swept + value fans out to every member at bootstrap. Members must share one scalar + kind and stay open (un-bound). Value forms are the #155 representations: a `Scalar` bind value is the typed tag form `{"I64":2}` / `{"F64":0.5}` / `{"Bool":true}` / `{"Timestamp":}`, and `kind` is diff --git a/docs/glossary.md b/docs/glossary.md index 5271244..0e1b363 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -119,6 +119,16 @@ A node re-evaluates only when ≥1 of its own inputs is fresh this cycle; otherw **Avoid:** deploy artifact, standalone binary A statically-linked, versioned, frozen build, never hot-swapped (audit trail: this artifact = this commit). The general category; a `bot` is the specific case of a deployed strategy + broker. +### gang +**Avoid:** — +A blueprint-level declaration that two or more sibling nodes' open params are +semantically one knob. The member addresses leave the blueprint's parameter +space; one gang address (a single path segment at the composite's level) +replaces them, and its value fans out to every member at bootstrap. Binding is +structural, not advisory — no consumer can bind a member independently. The +gang's name is a debug/axis symbol (identity-blind); its member coordinates +are identity-bearing. Declared by the `gang` op / `GraphBuilder::gang`. + ### gross R **Avoid:** — The R-multiple outcome of the **signal alone** — per-trade R integrated by the R-evaluator with **no `cost model`** attached (the zero-cost baseline). `net R = gross R − cost-in-R` once a cost model is composed on. @@ -293,7 +303,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); 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. +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. A ganged pair contributes ONE axis. ### tap **Avoid:** —