From a098962eecb77bde2fdf8eec330e338837ab67fd Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 3 Jul 2026 15:14:38 +0200 Subject: [PATCH] =?UTF-8?q?docs(uv):=20testnet=20push=20=E2=80=94=20T10=20?= =?UTF-8?q?Gate=20A/B=20run=20spec,=20T12=20promotion=20bridge=20spec,=20o?= =?UTF-8?q?perator=20arming=20checklist?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- prod/docs/UV_TESTNET_ARMING_CHECKLIST.md | 54 +++++++++++++++++++ .../UV_TASK_T10_CMD_GATE_AB_RUN.md | 48 +++++++++++++++++ .../UV_TASK_T12_PI_PROMOTION_BRIDGE.md | 40 ++++++++++++++ 3 files changed, 142 insertions(+) create mode 100644 prod/docs/UV_TESTNET_ARMING_CHECKLIST.md create mode 100644 prod/docs/uv_subspecs/UV_TASK_T10_CMD_GATE_AB_RUN.md create mode 100644 prod/docs/uv_subspecs/UV_TASK_T12_PI_PROMOTION_BRIDGE.md diff --git a/prod/docs/UV_TESTNET_ARMING_CHECKLIST.md b/prod/docs/UV_TESTNET_ARMING_CHECKLIST.md new file mode 100644 index 00000000..1a4a6387 --- /dev/null +++ b/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_.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) " > + /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. diff --git a/prod/docs/uv_subspecs/UV_TASK_T10_CMD_GATE_AB_RUN.md b/prod/docs/uv_subspecs/UV_TASK_T10_CMD_GATE_AB_RUN.md new file mode 100644 index 00000000..7c91d791 --- /dev/null +++ b/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_.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. diff --git a/prod/docs/uv_subspecs/UV_TASK_T12_PI_PROMOTION_BRIDGE.md b/prod/docs/uv_subspecs/UV_TASK_T12_PI_PROMOTION_BRIDGE.md new file mode 100644 index 00000000..66d9b88e --- /dev/null +++ b/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.