docs(uv): testnet push — T10 Gate A/B run spec, T12 promotion bridge spec, operator arming checklist

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

prod/docs/UV_TESTNET_ARMING_CHECKLIST.md

@@ -0,0 +1,54 @@
+# UV TESTNET ARMING CHECKLIST — DARK → LIVE on BingX VST
+
+**For the operator.** Execute top to bottom; every box is a stop-if-red. The integrator
+(Fable/successor) signs §1–2; only YOU execute §3.
+
+## §1 — Certification complete (integrator signs)
+- [ ] Gate A verdict PASS in `prod/docs/uv_cert/GATE_AB_RUN_<ts>.md` (Tier 1 + Tier 2
+      green; Tier 3a/3b drift-rates reported and explained). T10 merged.
+- [ ] Gate B verdict PASS (fuzz surface green, deterministic re-run identical).
+- [ ] T2P1 merged: journal writes verified against real DateTime64(3); raw scan surface
+      (`assets[]`, `asset_prices[]`) persisting per scan into dolphin_uv; creds never
+      in URL.
+- [ ] Zinc soak healthy ≥24h on current main: region seq at scan cadence, TUI
+      `source:zinc`, RSS flat (ram block), zero writes outside dolphin_uv (guard log).
+
+## §2 — Seam dry-run reviewed (integrator signs)
+- [ ] T9 merged: 3 injected intents fully mapped + journaled, ZERO venue calls (DARK
+      default proven); `u-` prefix litmus green; mainnet-block mutation test green.
+- [ ] T12 merged: bridge inert-by-default proven; shadow-mode journal shows SUPPRESSED
+      intents recorded during a live soak window — review that excerpt: are these the
+      trades you'd want taken?
+- [ ] End-to-end DARK rehearsal: PRIME live scan → bridge (suppressed) → verify the
+      would-have-been intent in dolphin_uv.exec_journal matches the journaled decision
+      bit-for-bit.
+
+## §3 — Arming (OPERATOR ONLY, in this order)
+1. [ ] Create VST API keys on BingX testnet (never mainnet keys anywhere near this box's
+       UV env). Fund the VST account.
+2. [ ] Place keys per T9's config seam (env/file per merged T9 README — keys never in
+       git, never in the repo tree).
+3. [ ] Start the seam runner (uv_exec instance) STILL DARK — verify it authenticates,
+       reads balances, places NOTHING. Check venue telemetry region populating.
+4. [ ] Write the arming file: `echo "$(date -Iseconds) <your-initials>" >
+       /root/uv-wt/prime-live/UV_PROMOTED.arm` and set `UV_PROMOTED=1` on the PRIME
+       runner env; restart PRIME runner.
+5. [ ] FIRST TRADE WATCH: sit on the TUI for the first bridged intent → order. Verify
+       on the venue: clientOrderId starts `u-`, size/leverage match the journaled
+       intent, position appears in dolphin_uv.exec_journal with venue echo.
+6. [ ] Let it run ONE session. Review: every venue order has a matching BRIDGE row and
+       journaled decision; PnL accounting sane vs venue statement.
+
+## §4 — Kill / rollback (know it BEFORE arming)
+- Instant stop: delete `UV_PROMOTED.arm` (bridge goes inert next scan) — no restart
+  needed. Harder stop: kill the uv_exec runner (positions remain on venue — close via
+  venue UI if needed; it is VST money).
+- Any anomaly (order without journal row, journal row without order, non-`u-` order,
+  any write appearing outside dolphin_uv): kill first, forensics second, report on h5i.
+
+## Standing constraints while live
+- Gate C (live soak) is observation, not a pass/fail blocker — but the T8 stop-watcher
+  ledger and the differ (PRIME still shadows BLUE — parity keeps being measured WHILE
+  UV trades) are the instruments. Divergence trend = stand down and investigate.
+- BLUE remains untouched, unthrottled, unshadowed by any of this. If UV ever competes
+  with BLUE for the same venue account: it must not — separate VST account, always.

prod/docs/uv_subspecs/UV_TASK_T10_CMD_GATE_AB_RUN.md

@@ -0,0 +1,48 @@
+# UV TASK T10 — Gate A/B certification run (the cert that unlocks testnet)
+
+**Assignee:** cmd-PASS1.1 · **Issuer:** Fable · **PRIORITY over T8 resume** (T8 stays
+paused; resume after T10). **Master spec:** §5 Gates A/B. **Base:** main ≥ b70d5ab
+(differ is LIVE — `parity.differ` real module, 33/33 contract tests green).
+
+## Goal
+Produce the first REAL certification verdict: run Gate A (replay parity) and Gate B
+(fuzz faultlines) end-to-end, emit the gate ledger via the T4 reporter, and hand Fable
+a signed-off report. This is the last gate before the operator arms VST keys.
+
+## Work items
+1. **Apply the T7 tier rework** (codex's unapplied instruction, on the bus + here):
+   restructure `replay_cert.py`'s report into labeled coverage tiers —
+   - **Tier 1 (gating):** replay over `dolphin_uv.prime_decisions` (PRIME's own journal,
+     accumulating since the zinc soak began). Today it holds decisions + hook frames
+     (not yet raw scan surface — pi's T2P1 adds that); so Tier 1 v1 = decision-replay
+     consistency: journaled decision == recomputed decision from journaled inputs where
+     inputs suffice; report the input-coverage fraction HONESTLY per row.
+   - **Tier 2 (gating, entries only):** entry-anchored bit-identity — replay each BLUE
+     `dolphin.trade_events` entry through the hooks using its own
+     `market_state_bundle_json` + `execution_quality_json` recorded inputs; diff via
+     `parity.differ.diff_entry_event`. This works over DEEP history NOW.
+   - **Tier 3a (labeled, non-gating):** ~2wk real-scan parquet era (2026-03-04..18,
+     `/mnt/dolphin/vbt_cache_klines`, loader precedent `paper_trade_flow.load_day_scans`)
+     — near-full input replay, report drift-rate.
+   - **Tier 3b (labeled, non-gating):** scalar+obf consistency (eigen_scans scalars +
+     obf_universe prices) — no-phantom-entry checks only.
+2. **Wire the T4 reporter:** gate ledger rows for Gate A (verdict = Tier1 AND Tier2
+   pass) and Gate B; ledger + report to `prod/docs/uv_cert/GATE_AB_RUN_<ts>.md/.json`.
+3. **Gate B run:** execute the full armed property/fuzz surface (pi's Hypothesis suites
+   + differ property tests) with `--hypothesis-seed` pinned, plus a poison-input sweep
+   of the differ/align path (NaN/inf/unicode/dup scans — most exist already; run them
+   as a named gate, record counts). Gate B verdict = all green, deterministic re-run
+   identical.
+4. **Determinism proof:** run the whole cert TWICE; reports must be byte-identical
+   except the run timestamp (seed-pin, injected clock).
+
+## Iron rules
+Read-only against `dolphin.*`; writes ONLY `dolphin_uv.*` + report files. no_write_guard
+active during all replay. Never touch BLUE. If Tier 2 surfaces real DRIFT (not a
+BLUE-code-era artifact per data-derived changepoints): STOP, report to Fable, do NOT
+"fix" hook math to make it pass — parity bugs are findings, not test failures.
+
+## Done
+Branch `uv/t10-gate-ab` off ≥ b70d5ab, fresh clone, push → CI, DONE to Fable with:
+report path + headline (entries checked, matched/drift/phantom per tier, Gate A verdict,
+Gate B verdict, wall-clock). Sample DiffReport for any drift.

prod/docs/uv_subspecs/UV_TASK_T12_PI_PROMOTION_BRIDGE.md

@@ -0,0 +1,40 @@
+# UV TASK T12 — promotion bridge (PRIME decision → KernelIntent → seam)
+
+**Assignee:** pi_nvnemo (AFTER T2P1 — do not context-switch) · **Issuer:** Fable.
+**Master spec:** §8 fast path. **Companion:** T9 exec seam (cmd-PASS1.2, in flight).
+
+## Goal
+The missing link between the certified brain and the trading hand: when PRIME (shadow)
+is PROMOTED, its entry decisions must flow as KernelIntents into T9's seam. Today
+nothing connects them — T9's `intent_source` is an injectable queue. Build the bridge,
+DARK-safe by construction.
+
+## Deliverable: `prod/clean_arch/violet/uv/blue_prime/promotion.py`
+1. **Gate:** module does NOTHING unless `UV_PROMOTED=1` in env AND an operator arming
+   file exists (`/root/uv-wt/prime-live/UV_PROMOTED.arm` — content = ISO ts + operator
+   initials; absence = shadow mode, bridge inert). Two-man rule mirrors T9's mainnet
+   block. Log loudly on every startup which mode we are in.
+2. **Translation:** PRIME's per-scan decision dict (`has_entry`, asset, side, leverage,
+   bar_idx, entry payload — exactly what `build_journal_frame` sees) → `KernelIntent`
+   (dita_v2 contracts; import from the vendored kernel; preflight the exact field set
+   against `contracts.py` — do NOT guess fields). `client_tag` = `u-` prefix source.
+3. **Transport:** publish to the seam's intent queue. v1 = the injectable queue seam
+   T9 exposes (in-process import); leave a clearly-marked TODO seam for zinc
+   intent_region transport (that is wave-2, do not build it now).
+4. **Journal:** every bridged intent (and every SUPPRESSED one while un-promoted) →
+   `dolphin_uv.exec_journal` kind='BRIDGE' rows. The suppressed-intent record is the
+   shadow-mode evidence the operator reviews before arming.
+5. **Runner wiring:** guarded call from `blue_prime/runner.py` after the journal write
+   (never before — journal is the source of truth), wrapped so ANY bridge exception
+   cannot kill the scan loop (fail-soft, log + count).
+
+## Tests (armed and RUN before ship — remember the differ lesson)
+Inert-by-default (no env/file ⇒ zero intents, suppressed rows journaled); arming
+matrix (env-only ⇒ inert, file-only ⇒ inert, both ⇒ active); translation bit-exact
+fixtures vs a fixed decision dict; mutation litmus (drop u- tag, skip suppressed
+journal, swallow exception ⇒ RED); fail-soft (bridge raises ⇒ runner loop continues).
+
+## Done
+Branch `uv/t12-promotion-bridge`, fresh clone, push → CI, DONE to Fable with sha,
+test count, and a shadow-mode journal excerpt showing suppressed intents recorded
+during a live soak window.