Aura/docs/specs/fieldtest-0049-random-sweep.md

# Fieldtest — cycle-0049 (random param-sweep) — 2026-06-17

**Status:** Draft — awaiting orchestrator triage
**Author:** fieldtester (dispatched by fieldtest skill)

## Scope

Cycle 0049 shipped the **random** half of the C12.1 param-sweep axis in
`aura_engine`. New public surface: `RandomSpace` (draws `N` seeded uniform
points over per-slot continuous ranges, validated against a blueprint's
param-space before any run), a typed `ParamRange` (`{lo, hi}` with
`ParamRange::i64` / `ParamRange::f64` constructors and `kind()`), a `Space`
trait (`points()` / `param_specs()`) that both `GridSpace` and `RandomSpace`
implement so `sweep` / `sweep_with_threads` are generic over `impl Space`, and
three new `SweepError` variants (`NonNumericRange`, `RangeKindMismatch`,
`EmptyRange`). The per-point run closure is unchanged (`Fn(&[Cell]) ->
RunReport`). This field test exercised the surface from a standalone downstream
consumer crate (path-deps only; public interface = ledger + glossary + spec
0049 + `cargo doc` rustdoc; no `crates/*/src` read). Binary exercised: each bin
rebuilt from HEAD via `cargo run --manifest-path …` after a clean
`cargo build --workspace`.

## Examples

### fieldtests/cycle-0049-random-sweep/c0049_1_continuous_tune.rs — headline continuous tuning
- Builds a 3-param SMA-cross harness (`sma_cross.fast.length: I64`,
  `sma_cross.slow.length: I64`, `exposure.scale: F64`), declares one
  `ParamRange` per slot, draws 200 seeded points via `RandomSpace::new`, runs
  `sweep`, and picks the best point by `total_pips`.
- Fits the cycle scope: this is the named "audience reaches for it" task — a
  grid over continuous ranges explodes; random draw is the standard tool.
- Outcome: built (first try after a self-inflicted port-name slip), ran,
  matched expected. 200 in-range points, 92 distinct metrics, best #121 =
  6.3216 pips at fast=8/slow=12/scale=1.3182.

### fieldtests/cycle-0049-random-sweep/c0049_2_validation_gate.rs — typed validation gate
- Declares invalid ranges and records the typed `SweepError` from
  `RandomSpace::new` before any run: `Arity`, `RangeKindMismatch` (F64 range on
  I64 slot), `EmptyRange` (I64 `lo>hi`), `EmptyRange` (F64 `lo>=hi`), the valid
  I64 `lo==hi` single point (accepted), and `NonNumericRange` (range on a Bool
  slot). The Bool slot required authoring a tiny custom node (`GateNode`),
  because no shipped `aura-std` node declares a Bool/Timestamp param.
- Fits the cycle scope: directly probes axis-hint 2 (the typed gate).
- Outcome: built, ran, matched expected. Every fault caught pre-run with exact
  slot + kind; `NonNumericRange` wins over `RangeKindMismatch` on the Bool slot.

### fieldtests/cycle-0049-random-sweep/c0049_3_reproducibility.rs — reproducibility + seed-sensitivity + wide-range edge
- Compares whole `SweepFamily`s (`derive(PartialEq)`): same `(ranges, count,
  seed)` reproduces an identical family; a different seed changes it. Then
  probes the full `ParamRange::i64(i64::MIN, i64::MAX)` range through
  `Space::points()` to check the commit-body hardening claim (the literal
  sampler would `% 0`).
- Fits the cycle scope: axis-hint 3 (the C1 promise) plus the documented
  sampler deviation.
- Outcome: built, ran, matched expected. Same-seed family identical;
  different-seed family differs; the full i64-domain range was accepted and
  `points()` produced 8 values spanning the signed domain with no panic.

### fieldtests/cycle-0049-random-sweep/c0049_4_space_interchange.rs — Space-trait interchangeability
- One downstream `tune_and_rank<S: Space>(space: &S)` consumer, written once and
  called with both a `GridSpace` and a `RandomSpace` over the same param-space,
  same `run_one` closure, asserting both produce comparable, non-degenerate
  families carrying the same schema.
- Fits the cycle scope: axis-hint 4 (the abstraction's payoff).
- Outcome: built, ran, matched expected. Both 12-point families ranked through
  the identical generic consumer; shared `family.space`; named view identical.

## Findings

### [working] Headline continuous-range tuning is the code a researcher would write
- Example: c0049_1.
- The whole flow — `param_space()` → one `ParamRange` per slot →
  `RandomSpace::new(&space, ranges, count, seed)?` → `sweep(&rand_space,
  run_one)` → rank by metric → `family.named_params(best)` for a readable
  coordinate — read naturally and compiled/ran on the first real attempt. All
  200 draws landed inside their declared ranges (I64 inclusive, F64 half-open),
  and `bootstrap_with_cells(point)` paired cleanly with the `Fn(&[Cell]) ->
  RunReport` closure (no `Scalar`/`Cell` conversion dance in the hot loop). The
  family spread (92 distinct metrics over 200 points) and a single argmax pass
  picked the best. This is the cycle's primary acceptance criterion met
  empirically.
- Recommended downstream action: carry-on.

### [working] The typed validation gate is precise and fires before any run
- Example: c0049_2.
- Every reachable fault surfaced from `RandomSpace::new` with an exact,
  self-describing variant: `Arity { expected: 3, got: 2 }`, `RangeKindMismatch
  { slot: 0, expected: I64, got: F64 }`, `EmptyRange { slot: 0 }` (I64 lo>hi)
  and `{ slot: 2 }` (F64 lo>=hi), and `NonNumericRange { slot: 0, kind: Bool }`.
  The valid I64 `lo==hi` single point was accepted (7 points). The ordering is
  sensible: a non-numeric slot is reported as `NonNumericRange` even when the
  supplied range's kind also mismatches, so the author sees the structural cause
  (wrong slot kind) rather than a downstream symptom.
- Recommended downstream action: carry-on.

### [working] Reproducibility, seed-sensitivity, and the wide-range i64 hardening all hold
- Example: c0049_3.
- `SweepFamily`'s `derive(PartialEq)` made the C1 promise checkable in one line:
  `family(seed) == family(seed)` held end to end (manifest + metrics included),
  and `family(seed_a) != family(seed_b)`. The full `[i64::MIN, i64::MAX]` range
  — the case the commit body (e17d78f) flags as a spec deviation hardened
  against `% 0` / signed-overflow — was accepted by `new` and produced 8 finite
  values across the signed domain through the public `Space::points()`, no
  panic. The documented deviation is observably upheld at the public surface.
- Recommended downstream action: carry-on.

### [working] The Space trait delivers its payoff: one consumer, both enumerations
- Example: c0049_4.
- A single generic `tune_and_rank<S: Space>` drove a `GridSpace` and a
  `RandomSpace` with zero per-enumeration branching, the same `run_one`, and a
  shared `family.space` schema for the named view. The grid path stayed
  behaviour-preserving (the existing `GridSpace::new` / `points()` /
  `param_specs()` inherent methods are still there alongside the trait impl).
- Recommended downstream action: carry-on.

### [spec_gap] `NonNumericRange` / Bool-slot ranges are unreachable with the shipped node roster
- Example: c0049_2 (the GateNode workaround).
- Every shipped `aura-std` node declares only `I64` (`length`) or `F64`
  (`scale`) params; none has a `Bool` or `Timestamp` knob. So a downstream
  consumer using only the standard roster can never hit the `NonNumericRange`
  gate (nor a Bool `RangeKindMismatch`) — I had to author a custom
  `PrimitiveBuilder`-based node with a Bool param purely to construct a Bool
  slot. The variant is correct and the C16 "author your own node" path makes it
  reachable, but the cycle ships a validation arm that no shipped surface can
  trigger. The ledger/spec do not say whether a Bool knob is an expected
  near-term authoring case or a purely defensive guard. Plausible alternate
  reading: `NonNumericRange` is dead-until-a-Bool-knob-node-exists and could
  have been deferred with the rest of the random axis. I picked the reading "it
  is a defensive structural guard for future Bool/Timestamp knobs" and the
  example demonstrates it works under that reading.
- Recommended downstream action: ratify (record in the ledger that the
  Bool/Timestamp param-slot is a forward-looking authoring case the gate guards,
  so the otherwise-untriggerable variant is intentional, not drift).

### [friction] `RandomSpace` has no named-axis builder; positional `ranges` must line up with `param_space()` by hand
- Examples: c0049_1, c0049_3, c0049_4.
- `GridSpace` has a fluent, by-name sibling: `Composite::axis("sma_cross.fast",
  …).sweep(run)` (the `SweepBinder`), which resolves axes against
  `param_space()` by name so a mis-ordered or mis-counted axis is impossible.
  `RandomSpace` has no counterpart: the author must build `Vec<ParamRange>` in
  exactly `param_space()` slot order and pass it positionally to
  `RandomSpace::new(&space, ranges, …)`. The `Arity` / `RangeKindMismatch`
  checks catch a wrong count or a kind-swapped slot, but a same-kind transposition
  (e.g. swapping the two I64 ranges for `fast.length` and `slow.length`) passes
  validation silently and tunes the wrong knob over the wrong interval — the
  exact failure class the named `SweepBinder` was built to remove for the grid
  axis (cf. node memory: the mw_1 ParamAlias pain, fixed by naming). The task
  completes, but the author re-takes on the positional-alignment burden that the
  grid path already retired.
- Recommended downstream action: plan (a `RandomSpace` named-axis builder — a
  `RandomBinder` sibling to `SweepBinder` mapping `name -> ParamRange` against
  `param_space()`, so the by-name resolution that protects the grid sweep also
  protects the random sweep).

### [spec_gap] `SweepError`'s rustdoc summary names only GridSpace though it now gates both spaces
- Examples: c0049_2 (the error type the consumer reads).
- The `SweepError` enum's top-level rustdoc (the public doc a consumer reads to
  understand the type) still reads: "A structural fault constructing a
  **`GridSpace`** — the typed gate before any run." The enum now also carries
  the three RandomSpace-only variants (`NonNumericRange`, `RangeKindMismatch`,
  `EmptyRange`), each documented individually as RandomSpace faults, but the
  type-level summary is stale: a consumer scanning the type doc would not learn
  that this same error type gates `RandomSpace::new`. The audit commit (3fca781)
  noted refreshing the *module* doc to name `RandomSpace` + the `Space` trait,
  but the `SweepError` type doc itself was not updated. Another equally-plausible
  reading is that `SweepError` is deliberately the single shared sweep-error type
  and the summary should say so; I cannot tell which from the public surface.
- Recommended downstream action: tighten the design ledger / docs (one-line
  doc-debt fix: broaden the `SweepError` summary to "constructing a `GridSpace`
  *or* `RandomSpace`" — doc-only, behaviour-preserving, the same low-grade
  doc-debt class the audit already fixed inline for the module doc).

## Recommendation summary

| Finding | Class | Action |
|---|---|---|
| Headline continuous tuning works | working | carry-on |
| Typed validation gate is precise | working | carry-on |
| Reproducibility + seed-sensitivity + wide-i64 hold | working | carry-on |
| Space-trait interchangeability payoff | working | carry-on |
| NonNumericRange unreachable with shipped roster | spec_gap | ratify |
| No named-axis builder for RandomSpace | friction | plan |
| SweepError doc summary names only GridSpace | spec_gap | tighten the design ledger / docs |