From a78a0557f435d9afd1901ad3172b77d7c8aabf0c Mon Sep 17 00:00:00 2001 From: Brummel Date: Wed, 1 Jul 2026 14:17:14 +0200 Subject: [PATCH] spec: 0096 discover a loaded blueprint's sweepable axes (boss-signed) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add `aura sweep --list-axes`: a read-only query sub-mode that lists a loaded blueprint's open sweepable knobs (one `:` per line, param_space() order), then exits. Closes the discovery gap #169 surfaced — today the only way to learn the axis names is to guess one and read a MissingKnob/UnknownKnob error, and that error names only the rejected knob, never the valid set. Prerequisite for #173 (IS-refit walk-forward must know which axes to re-fit per in-sample window). Derived surface decision (recorded on #169): the query lands on the SWEEP verb, not `graph introspect`. The axis names `--axis` accepts are produced by the sweep's own harness-wrapping — the loaded signal (name "stage1_signal") is nested via wrap_stage1r as a BlueprintNode::Composite, so collect_params prefixes the names (stage1_signal.fast.length), NOT the raw param_space (fast.length; empirically: the bare name → UnknownKnob). Only the sweep verb, which owns the wrapping, can print the names the user will actually pass; a shared blueprint_axis_probe single-sources the probe for both the sweep terminal and --list-axes, so listed == swept by construction (and stays correct across #159's harness retirement). Boss-signed on grounding-check PASS (independent, fresh-context; one BLOCK raised + fixed: the malformed-sweep .expect panic-path is now pinned by a this-cycle E2E over unknown_node.json, not an untested current-behaviour claim). Engine/registry untouched (invariants 1/8/9). refs #169 --- ...over-a-loaded-blueprints-sweepable-axes.md | 234 ++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 docs/specs/0096-discover-a-loaded-blueprints-sweepable-axes.md diff --git a/docs/specs/0096-discover-a-loaded-blueprints-sweepable-axes.md b/docs/specs/0096-discover-a-loaded-blueprints-sweepable-axes.md new file mode 100644 index 0000000..0fb21a9 --- /dev/null +++ b/docs/specs/0096-discover-a-loaded-blueprints-sweepable-axes.md @@ -0,0 +1,234 @@ +# Discover a loaded blueprint's sweepable axis names — Design Spec + +**Date:** 2026-07-01 +**Status:** Draft — awaiting user spec review +**Authors:** orchestrator + Claude + +## Goal + +Give a data-level blueprint author a way to **list a loaded blueprint's +sweepable axis names before sweeping it** — `aura sweep +--list-axes` prints one `:` line per open knob, exactly as the +`--axis` flag names them, then exits. Today the only way to learn those names +is to guess an axis and read a `MissingKnob`/`UnknownKnob` error — and that +error names only the *rejected* knob, never the valid set, so there is no +discovery path at all (#169, surfaced by the cycle-0093 architect drift +review). This is the prerequisite for #173 (IS-refit walk-forward), which +must know which axes to re-fit per in-sample window. + +## Architecture + +The load-bearing fact (grounded against the current tree, recorded as a +derived decision on #169): the axis names `--axis` accepts are **produced by +the sweep's own harness-wrapping, not by the raw blueprint**. A +loaded-blueprint sweep resolves axes against +`wrap_stage1r(reload(doc)).param_space()` (`crates/aura-cli/src/main.rs`, +`blueprint_sweep_family`): the loaded signal composite (`name == +"stage1_signal"`) is nested as a `BlueprintNode::Composite`, and +`collect_params` (`crates/aura-engine/src/blueprint.rs`) prefixes a nested +composite's params with that composite's own `name`. So the swept names are +**prefixed** — `stage1_signal.fast.length`, not the raw `fast.length` the +blueprint's own `param_space()` yields. + +Consequence for the surface: **only the sweep verb can honestly list the +names**, because only it owns the wrapping. So `--list-axes` is a query +sub-mode on `aura sweep`, computing the *same* probe the sweep resolves +against, via a single shared helper `blueprint_axis_probe`. `graph +introspect --axes` over the raw blueprint would print `fast.length` (names +the sweep rejects); teaching `graph introspect` to apply `wrap_stage1r` +would couple the general read-only-query surface to one research harness. +Correctness beats query-surface cohesion. Single-sourcing the probe also +keeps `--list-axes` correct by construction when the hard-wired stage1-r +wrapping is retired (#159): the listed names track whatever the sweep +actually resolves, with no second source of truth. + +Scope: `crates/aura-cli` only. No `aura-engine` / `aura-registry` change — +pure read-only CLI introspection. Domain invariants 1 (determinism), 8 +(frozen engine), 9 (registry domain-free) untouched. + +## Concrete code shapes + +### Worked user program (the acceptance evidence) + +An author holds a blueprint file and wants to sweep it, but does not know the +axis names: + +```console +$ aura sweep crates/aura-cli/tests/fixtures/stage1_signal_open.json --list-axes +stage1_signal.fast.length:I64 +stage1_signal.slow.length:I64 + +$ # now they can sweep, using exactly those names: +$ aura sweep crates/aura-cli/tests/fixtures/stage1_signal_open.json \ + --axis stage1_signal.fast.length=2,3 --axis stage1_signal.slow.length=4,6 +# ... runs a 2x2 sweep family ... +``` + +A **closed** blueprint (every knob bound) has no open axes — the listing is +empty and exit is 0, a valid "nothing to sweep here" answer, not an error: + +```console +$ aura sweep crates/aura-cli/tests/fixtures/stage1_signal.json --list-axes +$ echo $? +0 +``` + +`--list-axes` is a query, mutually exclusive with an actual sweep: + +```console +$ aura sweep …open.json --list-axes --axis stage1_signal.fast.length=2,3 +aura: --list-axes lists axes and takes no other flags +$ echo $? +2 +``` + +The two printed names are byte-for-byte what `--axis` binds — empirically, on +the current tree, `--axis stage1_signal.fast.length=2,3` passes name +resolution while `--axis fast.length=2,3` returns `UnknownKnob("fast.length")`. + +### Implementation shape (secondary) + +**New shared probe helper** — single source for the wrapped axis namespace, +used by BOTH the sweep terminal and `--list-axes`: + +```rust +/// The exact wrapped probe the loaded-blueprint sweep resolves its axes +/// against: the loaded signal wrapped in the stage1-r scaffolding (stop +/// bound, reduce, no cost), taps discarded. `param_space()` on it is the +/// axis namespace `--axis` binds; `.axis()` consumes it to seed a sweep. +/// The reload is infallible under the SAME dispatch-boundary contract +/// `blueprint_sweep_family` already relies on (main.rs ~3175-3178): the doc +/// is `blueprint_from_json`-validated at the `["sweep", ..]` boundary +/// (main.rs 4108-4110) before this runs, so a malformed doc has already +/// exited 2 and never reaches the `.expect`. This cycle's malformed-sweep +/// E2E pins that guard on the `--list-axes` path (see Testing strategy). +fn blueprint_axis_probe(doc: &str) -> Composite { + let signal = blueprint_from_json(doc, &|t| std_vocabulary(t)) + .expect("doc parse-validated at the dispatch boundary; reload is infallible"); + let (tx_eq, _) = mpsc::channel(); + let (tx_ex, _) = mpsc::channel(); + let (tx_r, _) = mpsc::channel(); + let (tx_req, _) = mpsc::channel(); + wrap_stage1r(signal, tx_eq, tx_ex, tx_r, tx_req, false, true, None) +} +``` + +`blueprint_sweep_family` (main.rs ~3186-3191) replaces its inline channel + +`wrap_stage1r` probe construction with `let probe = blueprint_axis_probe(doc);` +(it still consumes `probe` via `.axis()`, so the helper returns the `Composite`, +not just the space). The listing path takes only the space: + +```rust +/// `aura sweep --list-axes`: one `:` 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). +fn list_blueprint_axes(doc: &str) { + for p in blueprint_axis_probe(doc).param_space() { + println!("{}:{:?}", p.name, p.kind); // ScalarKind Debug -> I64/F64/Bool/Timestamp + } +} +``` + +**Arg grammar** — `SweepBlueprintArgs` gains a `list_axes: bool`; +`parse_sweep_blueprint_args` recognizes `--list-axes` and enforces that it +appears **alone** (no `--axis`/`--name`/`--trace`/`--real`): + +```rust +struct SweepBlueprintArgs { axes: Vec<(String, Vec)>, name: String, + persist: bool, data: DataChoice, list_axes: bool } +// parse: on "--list-axes" set list_axes = true; if list_axes && any other +// flag was seen -> Err("--list-axes lists axes and takes no other flags"). +``` + +**Dispatch** — the existing `["sweep", rest @ ..]` blueprint branch +(main.rs ~4112-4118), after the boundary read + `blueprint_from_json` +validation that already reject a malformed file: + +```rust +let SweepBlueprintArgs { axes, name, persist, data, list_axes } = + parse_sweep_blueprint_args(&rest[1..]).unwrap_or_else(|msg| { eprintln!("aura: {msg}"); exit(2) }); +if list_axes { + list_blueprint_axes(&doc); + return; +} +run_blueprint_sweep(&doc, &axes, &name, persist, DataSource::from_choice(data)); +``` + +## Components + +- `blueprint_axis_probe(doc) -> Composite` (new, main.rs) — the single-sourced + wrapped probe; `blueprint_sweep_family` refactored to call it. +- `list_blueprint_axes(doc)` (new, main.rs) — prints `name:kind` per open knob. +- `SweepBlueprintArgs.list_axes` + `parse_sweep_blueprint_args` (modified) — + parse `--list-axes`, enforce standalone. +- `["sweep", ..]` blueprint dispatch (modified) — short-circuit to the listing. + +## Data flow + +`aura sweep --list-axes` → boundary read + `blueprint_from_json` +validate (existing) → `parse_sweep_blueprint_args` sets `list_axes` → +`list_blueprint_axes(doc)` → `blueprint_axis_probe(doc)` wraps the reloaded +signal in stage1-r scaffolding (stop bound, reduce, no cost) → +`.param_space()` → print each `name:kind` in order → exit 0. + +## Error handling + +- **Malformed / unreadable blueprint** → the `["sweep", ..]` dispatch reads the + `.json` path and runs `blueprint_from_json` validation *before* arg parsing + (main.rs 4098-4111), so a malformed doc exits 2 with a named `aura: : + ` (empirically today: `unknown_node.json` → `aura: …: UnknownNodeType("Nope")`, + exit 2, no panic) *before* `list_blueprint_axes` — hence `blueprint_axis_probe`'s + `.expect` is unreachable on this path. That guard is currently pinned only on the + `run` verb (`aura_run_rejects_an_unknown_node_blueprint`), **not** the `sweep` + verb; **this cycle delivers the E2E that pins it on the `sweep --list-axes` path** + (reusing `unknown_node.json`), closing the gap the new `.expect` would otherwise + leave untested. No new error path is added — the fix is the missing *test*. +- **`--list-axes` combined with any other flag** → `parse_sweep_blueprint_args` + returns `Err("--list-axes lists axes and takes no other flags")`, rendered + `aura: ` + exit 2. +- **Closed blueprint (0 open knobs)** → empty stdout, exit 0. Not an error. +- No panics on any user-reachable input; the probe reload is infallible only + because the doc was validated at the boundary (same contract as the sweep). + +## Testing strategy + +- **Unit — probe names** (`cargo test -p aura-cli --bin aura + blueprint_axis_probe`): load `stage1_signal_open.json`, assert + `blueprint_axis_probe(doc).param_space()` names == `["stage1_signal.fast.length", + "stage1_signal.slow.length"]` with kinds `[I64, I64]`; load `stage1_signal.json`, + assert the space is empty. This pins the prefixed-name fact (grounded by the + existing `param_space_is_flat_path_qualified_and_slot_disambiguated` / + `param_space_reflects_only_open_knobs` / + `param_space_empty_for_paramless_and_empty_blueprints` in + `crates/aura-engine/src/blueprint.rs`). +- **Unit — arg grammar** (`cargo test -p aura-cli --bin aura + parse_sweep_blueprint_args`): `["--list-axes"]` → `list_axes: true`; + `["--list-axes","--axis","stage1_signal.fast.length=2,3"]` → `Err`. +- **E2E** (`cargo test -p aura-cli --test cli_run `, where the existing + blueprint-sweep E2Es live): `aura sweep --list-axes` → stdout + exactly the two lines, exit 0; `aura sweep --list-axes` → + empty stdout, exit 0; `aura sweep --list-axes --axis + stage1_signal.fast.length=2,3` → exit 2 + `--list-axes lists axes` on stderr. +- **E2E — malformed-blueprint safety** (same `--test cli_run`): `aura sweep + crates/aura-cli/tests/fixtures/unknown_node.json --list-axes` → exit 2 + a named + `aura: …: UnknownNodeType(…)` on stderr + **no panic** (`stderr` free of + `panicked`). This pins the dispatch-boundary guard on the `sweep --list-axes` + path, so `blueprint_axis_probe`'s `.expect` is provably unreachable — the gap + the grounding-check flagged (the guard is otherwise pinned only on the `run` + verb). + +## Acceptance criteria + +1. `aura sweep --list-axes` prints one `:` line per + open sweepable knob, in `param_space()` order, exit 0 — and each printed name + is byte-for-byte accepted by `--axis` on the same verb (`stage1_signal.fast.length`, + not `fast.length`). +2. A closed blueprint prints nothing and exits 0. +3. `--list-axes` combined with any other flag is a usage error (exit 2). +4. A malformed/unreadable blueprint on the `--list-axes` path is rejected with a + named `aura:` error and exit 2, never a panic — pinned by a new `sweep + --list-axes` E2E over `unknown_node.json` (closing the gap that the guard was + pinned only on the `run` verb). +5. No `aura-engine` / `aura-registry` change; invariants 1, 8, 9 preserved. +6. `cargo build --workspace`, `cargo test --workspace`, and `cargo clippy + --workspace --all-targets -- -D warnings` are green.