Regime vNext R&D Runbook
This runbook covers the R&D-ready regime vNext workflow for comparing the legacy direction x volatility grid with the vNext swing axes. It is not a production policy rollout guide.Current Scope
Available for swing/daily R&D backtests:v2_risk_statev2_volatility_changev2_directional_pressure- combined tuple attribution from those three axes
- legacy
by_regime_gridas shadow comparison data
v2_breadth_statev2_correlation_statev2_intraday_structure- macro horizon as an execution gate
feature_binding='prior_session' plus provenance in source_refs. Intraday
snapshots require feature_binding='prior_bar'; if prior-bar structure inputs
are absent, the snapshot reports intraday_structure='unavailable'.
Emitted vs Corrected
Usevariant='emitted' for point-in-time checks and executable historical
backtests. Emitted rows represent what was available at the time.
Use variant='corrected' only for offline diagnostics, distribution studies, and
historical detector analysis. Corrected rows may include backfilled revisions and
must not be used as an executable historical gate.
Latest Legacy vs vNext Comparison
Run fromdata/api:
Five-Year Corrected Diagnostic
Run fromdata/api:
SPY/QQQ Return Overlay
Run fromdata/api:
vNext-Enabled Backtests
Backtest requests must carry explicit v2 pins:regime_engine_version='v2'regime_logic_versionevidence_logic_versionregime_variantregime_horizon_profile='swing'policy_versionevidence_idor an approvedevidence_selector
detailed_metrics when v2 tags are
present:
by_regime_v2_risk_stateby_regime_v2_volatility_changeby_regime_v2_directional_pressureby_regime_v2_tuple
by_regime_grid remains unchanged.
Strategy-Family Outcome Export
Run fromdata/api after a backtest completes:
pnl_dollars when available for win
count, probability of profit, and profit factor. Rows without net P&L are marked
with an explicit fallback note.
Interpreting Evidence
SPY/QQQ overlays answer: how did the benchmark behave under detector states? Strategy-family outcome exports answer: how did a strategy family perform under detector states after the backtester’s costs and fills? Do not use benchmark overlays as proof that a strategy has edge. Use them as context beside strategy-family outcomes.R&D Readiness Checklist
- v2 swing axes are read-only rule context.
- v2 requests require explicit variant/version/evidence pins.
- historical executable reads require
variant='emitted'. - vNext axes derive from raw PIT substrate fields, not legacy grid labels.
- vNext attribution is additive beside
by_regime_grid. - macro is metadata/analysis only.
- intraday requires prior-bar structure and is unavailable until a PIT source is proven.
- diagnostics are marked as R&D evidence unless backed by approved pinned evidence.
Production Policy Checklist
Before treating vNext as executable policy, complete separate approval work:- durable point-in-time evidence construction
- approved evidence aliases to immutable artifact ids
- small-sample, autocorrelation, and multiple-comparison controls
- risk multiplier composition with sleeve sizing and vol targeting
- production artifact persistence and audit review
- operator signoff on policy versions and config versions
Historical exposure of the fabricated-normal defect (data#1607)
Between 2026-06-22 (1ec06874, RiskState introduced) and 2026-08-04 (fail-closed
fix), classify_snapshot resolved missing/non-finite risk inputs to normal and
policy._risk_multiplier would have handed that full 1.0 sizing.
Verified realized exposure: ZERO, across all four possible vehicles (2026-08-04):
- Persisted snapshots —
regime_v2_artifactshad 0 rows on prod; theLocalRegimeArtifactStorefallback dir was absent on compute. - Research artifacts — no producer ever called the classify path; the
research_loop / research_grammar / cross-sectional / discovery pipelines have
zero references to vNext
risk_state, and no freeze/tape schema carries it. - Sealed docs — the only risk_state numbers in sealed evidence
(
2026-06-22-regime-vnext-prereg-reset-evidence.md§2.2) are derived fromregime_archivepercentiles via the backtester resolver, whose non-Nullablevol_pctilemakes the missing-input fallback structurally unreachable there. - Live sizing — no Go service, agent, script, or app surface consumed
risk_state/risk_multiplier_hintduring the window.
RegimeSnapshotV2.risk_classifier_version: absent-or-"risk-v2.0" = pre-fix
semantics (fabricated normal possible), "risk-v2.1" = fail-closed. Research
slicing on vNext risk_state MUST filter or stratify on it.
If snapshots are ever found in regime_v2_artifacts predating the fix
(payload_json lacking the risk_classifier_version key), they are pre-fix
records: treat every normal/calm row as unassessable unless its
complete point-in-time inputs can be reconstructed from source evidence and
re-classified under risk-v2.1. Do NOT filter on unavailable_inputs — the
pre-fix recorder itself was defective: it checked is None only (NaN passed
invisibly) and never recorded drawdown_pct/tail_loss_z at all, so an
empty unavailable_inputs on a pre-fix row proves nothing.
Policy enforces this mechanically: evaluate_policy zero-sizes and blocks any
snapshot whose risk_classifier_version is not in
ACTIONABLE_RISK_CLASSIFIER_VERSIONS, so a legacy payload cannot authorize
sizing regardless of what it displays.