Aura/docs/specs/risk-regime-axis.md

# Risk regime as a structural campaign axis — Design Spec

**Date:** 2026-07-06
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude

## Goal

The campaign document cannot vary the protective stop. The R-path stop is
baked to fixed constants (vol-stop length 3, k 2.0) inside the non-serialized
`wrap_r` scaffolding, invisible to every stored artifact; stored strategy
blueprints are the signal leg only (price → bias). Only the legacy verbs vary
stops, and they do it by gridding stop params jointly with the signal params
and argmaxing across the whole grid — comparing R-multiples measured in
*different* R units (C10: the stop defines 1R). This blocks the
behaviour-preserving dissolution of `generalize`, `walkforward`, and `mc`'s
R-path equally, and leaves the executed stop regime unreconstructable from any
recorded artifact (the C18 audit gap named in the fork triage).

This cycle makes the risk regime a first-class **structural axis** of the
campaign matrix — a peer of instruments and windows — so that:

1. a campaign document enumerates a finite list of risk regimes and runs every
   `(strategy, instrument, window, regime)` cell;
2. each member's resolved stop is stamped into its manifest, closing the C18
   gap (the stop becomes addressable, auditable data);
3. regimes are **compared** at presentation, never argmax-**selected** across —
   the cross-R-unit comparison the structural framing deliberately forecloses
   (the parity break ratified in the direction decision, Gitea #210).

The user decision (regime = structural axis, not an ordinary param axis) and
the derived sub-forks are recorded on Gitea #210 (comments 2846 / 2847). This
is the design pass that unblocks the remaining verb dissolutions; the
"how do I find the best regime" methodology is a consequence of the compared-
not-selected semantics and is deliberately **not** written down (it follows
from the architecture).

## Architecture

Three tiers, matching the existing campaign stack:

- **Document vocabulary (`aura-research`)** — a new serializable `RiskRegime`
  closed vocabulary and an optional top-level `CampaignDoc.risk: Vec<RiskRegime>`
  field. This crate stays dependency-pure (aura-core + serde + sha2); it knows
  nothing of the runtime `StopRule`.
- **Matrix expansion (`aura-campaign`)** — the realization matrix gains a
  fourth structural coordinate. The regime is a **kept-separate** axis (a peer
  of `window`), not an **aggregated-over** axis (a peer of `instrument`):
  generalize aggregates across instruments (a candidate must survive *all*
  instruments — worst-case R floor), but regimes are alternatives compared to
  find the most robust one, never a set the candidate must all survive. So each
  `(strategy, window, regime)` triple is an independent generalize-across-
  instruments unit, and the regime enters the nominee key.
- **Runtime binding (`aura-cli`)** — the CLI member runner maps
  `RiskRegime → StopRule` at the runtime boundary (exactly as it maps campaign
  axes → runtime param-spaces), threads the resolved stop into the `wrap_r`
  bound-stop arm in place of the baked constants, and stamps the resolved stop
  into the member manifest.

The **default regime** (absent or empty `risk`) is a single implicit regime
equal to today's baked constants. The default's *value* lives in `aura-cli`
(`R_SMA_STOP_LENGTH` / `R_SMA_STOP_K`), so `aura-campaign` carries the regime as
`Option<RiskRegime>` where `None` means "member runner supplies its default" —
the doc is never mutated to inject a default (its content id must hash with
`risk` absent).

## Concrete code shapes

### The campaign document a user writes (the acceptance evidence)

A campaign that sweeps one signal over one instrument/window across **three
risk regimes** — the new capability:

```json
{
  "format_version": 1,
  "kind": "campaign",
  "name": "sma-cross across three vol stops",
  "data": {
    "instruments": ["GER40"],
    "windows": [{ "from_ms": 1725148800000, "to_ms": 1727740799999 }]
  },
  "risk": [
    { "vol": { "length": 3, "k": 1.5 } },
    { "vol": { "length": 3, "k": 2.0 } },
    { "vol": { "length": 3, "k": 3.0 } }
  ],
  "strategies": [
    { "ref": { "content_id": "<sma-blueprint-hash>" },
      "axes": { "fast.length": { "kind": "i64", "values": [2, 3] } } }
  ],
  "process": { "ref": { "content_id": "<sweep-process-hash>" } },
  "seed": 0,
  "presentation": { "persist_taps": [], "emit": ["family_table"] }
}
```

Running it produces one family per `(strategy, instrument, window, regime)` —
three families here, each a sweep over `fast.length ∈ {2,3}` at that regime's
stop. Every member line carries its resolved stop in the manifest; the three
regimes' results sit side by side in the family table, compared, never collapsed
by an argmax. "Best regime" is read off the compared families (the most robust
out-of-sample R floor across a plateau of stops) — a comparison, not a search.

The **absent-`risk` parity case** — the document the sweep sugar generates and
every stored campaign document written to date:

```json
{ "...": "no risk section", "data": { "...": "..." }, "strategies": ["..."] }
```

runs exactly one regime equal to the baked default (length 3, k 2.0),
behaviour-identical to today, and its content id is byte-unchanged (the field
absent-serializes).

### `RiskRegime` — the new closed vocabulary (`aura-research`)

```rust
/// A protective-stop regime: a serializable, content-addressable mirror of the
/// runtime `StopRule` structural axis (C10/C20). The sole implemented variant is
/// the vol-stop; the fixed-stop rule is admitted as a future additive variant
/// (it ships as a composite today but is not yet campaign-reachable). Tagged so
/// adding `Fixed` is additive — no content-id churn on stored `Vol` regimes.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "snake_case")]
pub enum RiskRegime {
    Vol { length: i64, k: f64 },
}
```

Wire form (serde external tagging): `{ "vol": { "length": 3, "k": 2.0 } }`.

### `CampaignDoc.risk` — the optional top-level field

```rust
// before → after (crates/aura-research/src/lib.rs:425)
 pub struct CampaignDoc {
     pub format_version: u32,
     pub kind: DocKind,
     pub name: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
     pub data: DataSection,
+    /// Structural risk-execution axis: the finite list of stop regimes the
+    /// matrix runs each cell under. Absent or empty = one implicit default
+    /// regime (the runtime baked constants). Absent-serializes → content-id
+    /// parity for every risk-less document.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub risk: Vec<RiskRegime>,
     pub strategies: Vec<StrategyEntry>,
     pub process: ProcessRef,
     pub seed: u64,
     pub presentation: Presentation,
 }
```

`DataSection` is **unchanged** — the regime is a risk-execution concern, kept
out of the "which instruments over which windows" data section (invariant 7).

### `CellSpec.regime` — the fourth structural coordinate (`aura-campaign`)

```rust
// before → after (crates/aura-campaign/src/lib.rs:26)
 pub struct CellSpec {
     pub strategy_ordinal: usize,
     pub strategy_id: String,
     pub blueprint_json: String,
     pub axes: BTreeMap<String, Axis>,
     pub instrument: String,
     pub window_ms: (i64, i64),
+    /// The cell's risk regime. `None` = the member runner's baked default (the
+    /// absent/empty-`risk` case); `Some` = an explicit document regime.
+    pub regime: Option<RiskRegime>,
+    /// The regime's ordinal in the resolved regime list (0 for the default),
+    /// used to key the generalize unit and discriminate family names.
+    pub regime_ordinal: usize,
 }
```

### Matrix loop + nominee key (`aura-campaign/src/exec.rs`)

```rust
// before → after (exec.rs:124 + the strategy×instrument×window loop at :125)
- let mut nominees: BTreeMap<(usize, usize), Vec<(String, Nominee)>> = BTreeMap::new();
+ let mut nominees: BTreeMap<(usize, usize, usize), Vec<(String, Nominee)>> = BTreeMap::new();
+ // Absent/empty risk resolves to a single default cell (regime = None, ord 0);
+ // a non-empty list maps each regime to Some. The default's value is the member
+ // runner's; the doc is never mutated (content id hashes with risk absent).
+ let regimes: Vec<(usize, Option<RiskRegime>)> = if campaign.risk.is_empty() {
+     vec![(0, None)]
+ } else {
+     campaign.risk.iter().copied().enumerate().map(|(i, r)| (i, Some(r))).collect()
+ };
  for (strategy_ordinal, ...) in campaign.strategies.iter().zip(strategies).enumerate() {
      for instrument in &campaign.data.instruments {
          for (window_ordinal, window) in campaign.data.windows.iter().enumerate() {
+             for (regime_ordinal, regime) in &regimes {
                  let cell = CellSpec { /* ...as before... */,
+                     regime: *regime, regime_ordinal: *regime_ordinal };
                  let (outcome, realization) = run_cell(&cell, ...)?;
                  nominees
-                     .entry((strategy_ordinal, window_ordinal))
+                     .entry((strategy_ordinal, window_ordinal, *regime_ordinal))
                      .or_default()
                      .push((instrument.clone(), outcome.nominee.clone()));
                  /* ... */
+             }
          }
      }
  }
```

The campaign-scope generalize loop (exec.rs:164-195) iterates the same
now-3-tuple key, so each `(strategy, window, regime)` gets its own
generalize-across-instruments grade. `CampaignGeneralization` gains a
`regime_ordinal: usize` field beside `strategy_ordinal` / `window_ordinal`.

### Family naming — the regime discriminator (collision fix)

The family name (exec.rs:250 / :352) carries no regime component today, so two
regimes for the same `(strategy, instrument, window, stage)` would collide and
overwrite in the registry:

```rust
// before → after (exec.rs:250, :352)
- "{campaign_prefix}-{}-{}-w{window_ordinal}-s{stage_ordinal}",
+ "{campaign_prefix}-{}-{}-w{window_ordinal}-r{regime_ordinal}-s{stage_ordinal}",
```

`campaign_cell_key` (campaign_run.rs:558) gains the regime ordinal by the same
reasoning (report-name isolation across regimes):

```rust
// before → after
- fn campaign_cell_key(strategy: &str, instrument: &str, window_ordinal: usize) -> String
+ fn campaign_cell_key(strategy: &str, instrument: &str, window_ordinal: usize, regime_ordinal: usize) -> String
```

### `wrap_r` bound-stop arm + the member-runner thread (`aura-cli`)

`wrap_r`'s sixth argument stops being a bare `stop_open: bool` and becomes a
`StopArm` that carries the bound stop's value:

```rust
// new CLI-internal enum
enum StopArm {
    /// Open vol-stop: the two knobs land in param_space as sweep axes (the r-sma
    /// verb's gridded-stop path).
    Open,
    /// Bound vol-stop with these params (single run, blueprint/campaign member).
    Bound(StopRule),
}

// before → after (main.rs:2691 stop arm inside wrap_r)
- let exec = g.add(if stop_open {
-     risk_executor_vol_open(1.0)
- } else {
-     risk_executor(StopRule::Vol { length: R_SMA_STOP_LENGTH, k: R_SMA_STOP_K }, 1.0)
- });
+ let exec = g.add(match stop {
+     StopArm::Open => risk_executor_vol_open(1.0),
+     StopArm::Bound(rule) => risk_executor(rule, 1.0),
+ });
```

The signature change propagates to `wrap_r`'s five call sites (compiler-
enumerated). `r_sma_graph` (main.rs:2622) keeps its `stop_open: bool` and maps
at its single `wrap_r` call, localizing the default constants to the Rust-built
path:

```rust
// r_sma_graph's wrap_r call
+ if stop_open { StopArm::Open }
+ else { StopArm::Bound(StopRule::Vol { length: R_SMA_STOP_LENGTH, k: R_SMA_STOP_K }) }
```

`run_blueprint_member` (main.rs:2877) gains a `stop: StopRule` parameter, passes
`StopArm::Bound(stop)` to `wrap_r`, and stamps the stop into the manifest (next
shape). `CliMemberRunner::run_member` (campaign_run.rs:215) maps the cell's
regime to the runtime rule and threads it in:

```rust
// campaign_run.rs run_member — the RiskRegime → StopRule map at the runtime boundary
+ let stop = match cell.regime {
+     None => StopRule::Vol { length: crate::R_SMA_STOP_LENGTH, k: crate::R_SMA_STOP_K },
+     Some(RiskRegime::Vol { length, k }) => StopRule::Vol { length, k },
+ };
  let mut report = crate::run_blueprint_member(signal, &point, &space, sources,
-     (from, to), 0, geo.pip_size, &cell.strategy_id, self.env);
+     (from, to), 0, geo.pip_size, &cell.strategy_id, self.env, stop);
```

### Manifest stamp — closing the C18 gap (additive, like the instrument stamp)

`run_blueprint_member` builds its manifest from `zip_params(space, point)` —
the signal axes only (main.rs:2896), so the campaign member manifest records no
stop today. The resolved stop is appended, matching the single-run manifest
shape (`stop_length` i64 / `stop_k` f64, main.rs:3608-3609):

```rust
// before → after (main.rs:2896, inside run_blueprint_member)
  let named = zip_params(space, point);
+ let named = { let mut p = named;
+     if let StopRule::Vol { length, k } = stop {
+         p.push(("stop_length".into(), Scalar::i64(length)));
+         p.push(("stop_k".into(), Scalar::f64(k)));
+     }
+     p };
  let mut manifest = sim_optimal_manifest(named, window, seed, pip);
```

**Ratified contract extension.** `family_member_line` serializes the full
`RunManifest.params` (main.rs:1601-1606), so this additive stamp changes the
dissolved-sweep member-line output. That a campaign member manifest carries **no**
stop param today is a currently-green characterization pin,
`sweep_real_blueprint_member_manifest_carries_no_stop_param_today`
(cli_run.rs) — added as this cycle's grounding ratification, since the older
`sweep_real_blueprint_member_lines_pin_the_dissolved_contract` locates each
binding by `find` and so never pinned the *absence*. The stamp flips that
characterization pin to **require** the stop key — the deliberate C18-gap
closure the milestone exists to perform, an additive stamp exactly like the
instrument stamp cycle 0110 added ("full parity modulo an additive stamp", #210
decision 5), not accidental drift. The older `find`-based pin also gains the
default stop in its member lines (its `find` assertions stay green; it is
extended to assert the new key). The change is ratified here, not silent.

### `translate_sweep` — sugar parity (no `risk` emitted)

```rust
// verb_sugar.rs:76 generated CampaignDoc — the risk field defaults to absent
  CampaignDoc { /* ...unchanged... */, data: DataSection { ... },
+     risk: vec![],   // absent-serializes → sweep-sugar doc byte-unchanged
      strategies: vec![one], ... }
```

## Components

- **`aura-research`**: `RiskRegime` enum (new); `CampaignDoc.risk` field;
  `validate_campaign` regime check (new `DocFault::BadRegime { index, detail }`);
  `CAMPAIGN_SECTIONS` gains an optional `std::risk` section descriptor;
  `open_slots_campaign` treats `risk` as optional (never an open slot — absence
  is legal). `metric_vocabulary` untouched.
- **`aura-campaign`**: `CellSpec.regime` + `regime_ordinal`; exec.rs regime
  expansion, 3-tuple nominee key, generalize per `(strategy, window, regime)`;
  `CampaignGeneralization.regime_ordinal`; family-name regime discriminator.
- **`aura-cli`**: `StopArm` enum; `wrap_r` signature; `r_sma_graph` bool→arm
  map; `run_blueprint_member` `stop` param + manifest stamp;
  `CliMemberRunner::run_member` regime→rule map; `campaign_cell_key` regime arg.
- **`verb_sugar`**: `translate_sweep` sets `risk: vec![]`.
- **Design ledger**: a C10/C20 amendment note — the risk regime realized as a
  structural campaign axis (kept-separate, compared not selected), and the
  ratified parity break (cross-regime argmax is structurally unavailable; the
  verbs' `--stop-length`/`--stop-k` joint grid is retired as a methodology).

## Data flow

document (`risk` list) → parse (serde, `risk` known/optional) → `validate_campaign`
(regime params sane) → content id (risk absent-serializes) → `execute`:
for each `(strategy, instrument, window, regime)` cell → `run_member` maps
`regime → StopRule` → `run_blueprint_member` binds the signal point, runs with
the bound stop, stamps `stop_length`/`stop_k` into the manifest → nominee keyed
`(strategy, window, regime)` → per-`(strategy, window, regime)` generalize across
instruments → family table rows carry the regime in `family_id` → presentation
compares regimes side by side.

## Error handling

- A `Vol` regime with `length < 1` or `k <= 0` (or non-finite `k`) → the new
  `DocFault::BadRegime { index, detail }` at `validate_campaign`, phrased by the
  CLI like the sibling `EmptyAxis` / `BadWindow` faults (by-identifier, display-
  free in the library).
- `risk: []` (explicit empty) is **valid** — it means the default regime,
  identical to an absent `risk` (both round-trip to absent under
  `skip_serializing_if`). No refusal.
- No duplicate-regime detection, matching the existing non-dedup of instruments
  and windows (consistency, not a new invariant).
- An unknown top-level key stays refused by `CampaignDoc`'s
  `deny_unknown_fields`; `risk` is now a *known* optional key.

## Testing strategy

- **Unit (`aura-research`)**: `RiskRegime` serde round-trip + wire-form pin
  (`{"vol":{"length":3,"k":2.0}}`); `validate_campaign` accepts a risk section
  and refuses a bad regime; **content-id parity** — a doc with `risk` absent and
  the same doc with `risk: []` both hash to the pre-feature content id (the
  absent-serialize guarantee).
- **E2E (`aura-cli`)**: a real-data campaign with two distinct regimes runs both
  families; each member manifest stamps its regime's `stop_length`/`stop_k`; the
  two families' `family_id`s differ by the `-r{ordinal}` discriminator (no
  collision/overwrite); the per-`(strategy, window, regime)` generalize grades
  are independent.
- **Parity (`aura-cli`)**: the dissolved `aura sweep <blueprint> --real` over an
  absent-`risk` generated document still runs one default regime; its member
  lines now additionally carry `stop_length:3`/`stop_k:2.0` — the characterization
  pin `sweep_real_blueprint_member_manifest_carries_no_stop_param_today` flips
  from asserting the stop's absence to requiring it, and the `find`-based 0110 pin
  is extended to assert the new key; the generated doc's content id is unchanged.

## Acceptance criteria

- The intended audience — a researcher authoring a campaign — writes a `risk`
  list and gets one family per regime, compared side by side (the worked example
  above is the empirical evidence).
- Every member manifest records its resolved stop, default included → each run
  is reproducible from its own manifest (C18); the executed stop is auditable.
- Regimes are kept separate (per-regime generalize) and compared at
  presentation; no cross-regime argmax exists (the structural framing forecloses
  the cross-R-unit comparison — C10).
- Absent/empty `risk` = byte-identical document content id **and** behaviour
  parity (one default regime); `aura sweep` sugar emits no `risk`.
- No new failure class against the core constraints: determinism (the regime is
  static structural data, bound at bootstrap), causality (unaffected), and the
  no-look-ahead / one-merge invariants are untouched.