siloqy/prod/docs/UV_MASTER_SPEC_20260702.md

# UV (ULTRAVIOLET) MASTER SPEC — 2026-07-02

**Author:** Fable (Claude Fable 5; read Fable/Claude-4.8 history as one unit).
**Supersedes:** `~/.claude/plans/drifting-knitting-zebra.md` (2026-06-29, the approved C0–C9 plan)
— this doc IS that plan, amended with verified 2026-07-02 findings. Commit into `/root/violet.git`
main at T0.
**Companions (unchanged, still binding):** `uv/UV_DEV_LOOP.md` (dev loop), `uv/specs/SPEC_00_*`
+ 11 hook specs + PASS4 WIRE specs, `prod/docs/UV_BLUE_PRIME_SHM_RESHAPE_SPEC.md`,
`prod/docs/UV_BLUE_PRIME_ZINC_SHADOW_SPEC.md`, `prod/docs/AI_DEV_DOCTRINE.md`,
`prod/docs/TESTING_DOCTRINE.md`.

---

## 1. Mission — the finish line, spelled out

ULTRAVIOLET = BLUE's alpha (certified at full algorithmic parity) on a modern substrate:
DITAv2 execution kernel, ASEx lock-free seam, Zinc shm transport, GraalPy-bound, TUI-first.
BLUE-PRIME is the parity **oracle** (instrumented read-only copy of BLUE); UV is certified
against PRIME; PRIME is certified against live BLUE by data diff — never by touching BLUE.

**This spec is DONE only when (end-state acceptance, Wave 4 §9):**
1. UV places and manages **real BingX VST testnet orders through DITAv2 as the exchange-exec
   kernel, with the ASEx improvements underneath** (single-writer, lock-free, no async seams).
2. Every UV trade's decision chain is traceable to the **certified-BLUE algorithm at Q=scan**
   (journaled in `dolphin_uv.uv_decisions`; the parity differ stays green in shadow while
   UV trades).
3. SL/TP and protective market action execute **faster than eigenscan cadence** (rate-parity
   stage 2 unlock) — demonstrably, with measured action latency in the journal.
4. Soak-proven on VST: N days, zero orphan positions, reconciler-clean, DARK→armed ladder
   respected at every step.
5. Everything built **Graal-ready** (§10) — the Graal migration itself is a separate later
   dev-ops spec, but no wave may ship code that violates the §10 constraints.

"UV stood up with BLUE parity" (end of Wave 3) is the midpoint of this spec, not its end.

## 2. Rate-parity doctrine (three stages; Q is a first-class dial)

1. **Parity cert:** UV may run a fast internal clock but the decision surface is downsampled
   through a **Q factor** to BLUE's NG7 eigenscan cadence (~6 s), so ALL timing-derived
   affordances (bars_held, max_hold_bars, staleness windows, EFSM post-win windows, dedup)
   match BLUE **warts and all**. Parity diffs join on **scan identity, never wall clock**.
2. **Post-cert:** SL/TP + market action execute FASTER than eigenscan (DITAv2/ASEx);
   alpha decisions stay scan-quantized. This is the economic point of UV.
3. **Far:** Graal substrate; the Q layer itself loosened **gradually**, parity-guarded
   (certified-Q config stays runnable as the rollback baseline). Hard ceiling today: NG7
   eigenscan generation compute. Operator caution (doctrine): the 6 s @ 15 m correlation
   rhythm may itself carry alpha — loosening Q is an experiment, never an assumption.

**Engineering rule:** the Q-quantizer is ONE explicit component with an interface (human-defined
boundary per AI_DEV_DOCTRINE #8), never cadence assumptions scattered through modules.

## 3. Verified repo topology (2026-07-02 — trust this, not older status docs)

- **Canonical bare origin:** `/root/violet.git`. `main` @ `15fb189` = 11 hooks + WIRE.1/2/3 +
  WIRE.5 journal + pi's comprehensive hook tests.
- **Unmerged, to integrate at T0:** `uv/wire-4-live-inputs` @ `2fd1f9d` (live_inputs + EFSM
  mirror); `docs/uv-blue-prime-shm-reshape` @ `ee4e5eb` (snapshot contract + zinc_shadow +
  1078 tests; branched from `ba7e12e`, so it lacks WIRE.4/5).
- **Divergent clone line:** `/root/uv-wt/uv` + `/root/uv-wt/blue-prime` @ `1902e4b` (5 unpushed
  commits forked at `5d583e4`): TUI v2, EFSM CH-mirror fix `6156e17`, real /dev/shm zinc region
  writer `01e35c4`. Salvage-review at T0. **The live soak (zellij `UV_BLUE-PRIME_TUI`) runs this
  line** — real ZINC_REG region `/dev/shm/zinc_uv_shadow_state`, seq advancing at scan cadence.
- **RETIRED as wrong:** `/root/uv-wt/uv/prod/docs/UV_DEV_CURRENT_STATUS_2026-07-01.md`'s claim
  that `/root/uv-wt/uv` is canonical/"ahead" — it is a fork missing hooks/WIRE/reshape. Its
  UV-core / PRIME-oracle / VIOLET-substrate *conceptual* distinction remains correct and adopted.
- Dev loop stays as `UV_DEV_LOOP.md`: local disk only, clone-per-chunk off the bare, branch
  `uv/<name>`, push → scoped CI, **Fable integrates to main**.

## 4. Amended chunk map (C-numbers preserved from the approved plan)

| Chunk | Status / definition |
|---|---|
| C0 off-CIFS + CI | ✅ DONE |
| C3 probe registry, C4 TUI harness, C5 scan_tick | ✅ DONE (P1) |
| C6 BLUE-PRIME | ✅ built, ❗ split across 3 lines → **T0 integration**; then **C6.5 (NEW): pollution neutralization** → T1 |
| **C6.5 pollution guard (NEW)** | PRIME must be provably write-free toward BLUE's namespaces (CH `dolphin.*`, HZ, shared spool). See `UV_TASK_T1`. |
| C7 parity instrument (**REDEFINED**) | Not an entry_signal probe. C7a = journal hardening + differ core (T2). C7b = differ tests + TUI parity panel (T3). C7c = certification reporter (T4). |
| C8 BingX reconciler | Wave 2, SHRUNK: verify/adapt DITAv2's existing reconcile logic under UV's `u-` prefix + rate-budget tests — not a new build (§8). |
| C10 (NEW) DITAv2 exec seam | Wave 2: certified-PRIME decision path promoted to active + KernelIntent → DITAv2 → VST, v4-runner pattern as template (§8). |
| C11 (NEW) SL/TP fast clock | Wave 2, post-canary unlock (§8). **Empirical justification (2026-07-02 forensics):** scan-cadence stop overshoot is real — FET −2,433 exited at 1.61% adverse vs 1.2% stop (+34% overshoot), WIN −1,920 at 1.32% (+10%); ≈$800/wk excess on 3 stops alone. **Millisecond forensics on the FET stop (dolphin.obf_universe @130ms):** price approached the stop visibly for 19s (0.87%→1.20%), breached at 16:08:15.9, next eigenscan not until 16:08:19.6 (measured scan gaps 11–12s, not 6s) → entire overshoot lived inside one scan gap; exec latency after the scan was <1s (mechanism healthy). Book stayed orderly throughout (spread pinned 5.4bps, top-5 depth $140–200K both-sides) → breach-time exit was executable; like-for-like save ≈$500–580 on this trade. Faster-than-scan SL action recovers this by construction. NOTE: `dolphin.obf_fast_intrade` (in-trade fast OB feed) has 0 rows — dead wiring in BLUE; UV's fast clock must not repeat this (a populated fast feed is the C11 sensor). |
| C1 UV Zinc plane + Q-dial, C2 GraalPy smoke, C9 DITAv2 probe | **DEFERRED** post-first-trade (§9). Graal-readiness is enforced NOW via §10 instead. |
| UV core runtime (separate rewrite) | **CANCELLED as churn** — UV v1 IS the certified PRIME path promoted (§8). `uv/blue_prime/` freezes as oracle at certification. |

## 5. Certification protocol (BLUE ↔ PRIME, then PRIME ↔ UV)

No harnessing of BLUE. PRIME runs read-only beside live BLUE; certification is a
**tick-aligned data diff**:
- PRIME's per-scan record: `dolphin_uv.prime_decisions` (WIRE.5 journal: inputs, 11 hook
  effects, decision) + zinc snapshot.
- BLUE's record: `dolphin.trade_events` (+ logs) — entries/exits with asset/side/leverage.
- Continuous signal: per-scan hook/leverage modulation self-consistency; hard gate: **entry
  events**, matched on scan identity, **bit-identity** (PASS2.5 standard: mismatch = bug,
  not tolerance).
- **Gate (restructured 2026-07-02, operator: compute-bound not calendar-bound):**
  - **Gate A — replay-cert (gating):** replay BLUE's RECORDED input history (months of
    eigen-scans, all realized trades) through PRIME's decision path, Q-quantized
    (scan-sequenced, warts and all), vectorized where the kernel allows. Bit-diff every
    decision vs `dolphin.trade_events` — every entry BLUE ever made, not 3. 0 unexplained
    diffs. (Synthetic inputs CANNOT gate BLUE-parity — BLUE has no recorded answer for them.)
  - **Gate B — faultline assault (gating):** Hypothesis/adversarial/fuzz on breakspots
    (vel_div threshold boundary, EFSM transitions incl. post-win LONG overlay, staleness,
    poison) — properties: PRIME-internal consistency + PRIME↔UV agreement.
  - **Gate C — live plumbing (non-gating):** guarded soak keeps running; live HZ reads,
    scan gaps, mirror hydration clean over X hours; any live entry = bonus bit-check.
  - Pollution invariant green throughout; operator signs the cert. Then PRIME freezes as
    oracle; UV certifies against PRIME with the same instruments (Gate A replay + Gate B),
    writing `dolphin_uv.uv_decisions`.
  - **Wave-2+ note (operator):** multi-instance PRIME-[n] clone farms (forkd / workdir.dev
    -class system forks; VIBRASS bandit meta-gov) — design-in now: per-instance CH namespace
    `dolphin_uv_{n}`, per-instance zinc prefix `uv_shadow_{n}`, injectable clock/Q.

## 6. Non-negotiables (carried + extended)

- NEVER edit BLUE (`nautilus_event_trader.py`, kernels, `prod/ch_writer.py` [vendored/shared],
  supervisord, HZ contents, `dolphin.*` tables). PRIME reads BLUE's world; writes NOTHING into it.
- `dolphin_uv.*` is UV/PRIME's only CH namespace. Hard-guarded in code + tests
  (journal URL guard raises on non-dolphin_uv; T1 no_write_guard diverts every other CH write
  to a local audit file; T4 reporter is zero-CH-write; HZ is wrapped read-only).
- **Separate-install direction (operator, 2026-07-02):** before UV's first VST trade (C10),
  UV's own writes move to a DEDICATED CH instance (own port/datadir or container) — namespace
  isolation is the guard, instance isolation is the wall. UV needs NO HZ writes in wave 1
  (reads BLUE's HZ read-only); if UV ever needs its own KV plane, it gets its own instance —
  never keys in BLUE's cluster.
- VST only; `ALLOW_MAINNET=0`; DARK until operator arms.
- Testing doctrine: mutation litmus, poison/edges/concurrency, no green-by-pollution,
  run your own suite before push. AI_DEV doctrine: one problem/one branch/one PR,
  explicit staging, docs > chat.
- Vendored-drift gate: VENDOR.lock components edited only upstream + `vendor_sync.sh`.

## 7. Agents, handles, wave-1 tasks

| Handle (h5i) | Who | Wave-1 task | Sub-spec |
|---|---|---|---|
| **Fable** | Claude Fable 5 (architect/integrator; successor of `claude`/4.8 + `cc-ultrav-1`) | **T0**: git integration pass (main + wire-4 + reshape + clone salvage → main); commit this spec; correct/retire stale status doc | this doc §3–4 |
| **codex** | Codex 5.4mini | **T1 (CRITICAL)**: pollution forensics + neutralization + PRIME relaunch | `UV_TASK_T1_CODEX_POLLUTION_GUARD.md` |
| **mm_VIOLET1** | mimocode (slow, precise) | **T2**: journal hardening + C7a differ core | `UV_TASK_T2_MM_JOURNAL_DIFFER.md` |
| **pi_nvnemo** | PI harness (Nemotron) | **T3**: C7b differ test suite + TUI parity panel | `UV_TASK_T3_PI_PARITY_TESTS_TUI.md` |
| **cmd-PASS1.1** | Command Code / DeepSeek (operator fires instance) | **T4**: C7c certification reporter | `UV_TASK_T4_CMD_CERT_REPORTER.md` |

Sequencing: T0 (Fable) first — T1 Phase A (read-only forensics) may start immediately; T1
Phase B code, T2/T3/T4 branch off **post-T0 main**. All reporting on the canonical h5i bus
(`/mnt/dolphinng5_predict`); reply to **Fable**. Sub-specs live in
`prod/docs/uv_subspecs/` (committed to the violet repo at T0).

## 8. Wave 2 — UV = certified PRIME promoted to active, trading on VST (FAST PATH)

**Anti-churn rule (operator, 2026-07-02): this spec is the FASTEST route to testnet.**
No rewrites of things that already work. Concretely:

- **NO new UV decision core.** PRIME already runs BLUE's real engine + 11 hooks + EFSM mirror
  + live inputs. The day PRIME certifies, **UV v1 = the certified PRIME decision path promoted
  from shadow to active** (new process/config, journals `dolphin_uv.uv_decisions`, DARK) +
  a KernelIntent emitter. Zero algorithm code rewritten between certification and first trade.
- **NO new exec layer.** DITAv2 is already VST-proven (PINK burn-in; VIOLET v4 runner
  precedent — reuse its KernelIntent→DITAv2 wiring pattern as a NEW instance; never edit the
  live v4 runner). DITAv2 stays vendored (VENDOR.lock; improvements upstream + vendor_sync).
  ASEx improvements ride along inside DITAv2's existing integration — the single-writer /
  no-async-seam guarantees are why it's the kernel; we do not re-plumb them.
- **NO new reconciler from scratch.** Adopt DITAv2's existing reconcile logic (PINK ownership-
  filter lineage) under UV's own VST account/clientOrderId prefix (`u-`); C8 shrinks to
  "verify + adapt + rate-budget test", not "build".
- **Arming ladder (operator-gated per rung):** DARK (journal-only) → observe-only → VST canary
  (min size, single slot) → staged size. `ALLOW_MAINNET=0` throughout; mainnet is out of scope.
- **Decision-vs-execution parity split:** decision layer must bit-match certified-BLUE at
  Q=scan (differ green in shadow while UV trades); execution quality is judged by
  reconciler-clean + DITAv2 accounting integrity (fill-price PnL doctrine), since BLUE's
  "fills" are in-memory bookkeeping and UV's are real VST mechanics.
- **C11 SL/TP fast clock** (rate-parity stage 2 — protective actions faster than eigenscan,
  alpha stays at Q=scan): unlocked AFTER first clean canary trades, not before.
- **Exit = §1 end-state acceptance.** That is the whole spec.

## 9. Deferred (post-first-trade; separate specs — do NOT build in this spec's waves)

- C1 UV-own Zinc plane + generalized Q-dial (UV v1 runs at scan cadence natively — Q=1:1 —
  so the dial abstraction earns nothing until stage-3 loosening).
- C2 GraalPy smoke rig; C9 DITAv2 innards probe; TUI beyond the existing panels.
- Wave-Graal: the GraalPy/GraalVM/Graal-OS migration dev-ops pass (own spec when VST soak
  is running). Q-loosening experiments (rate-parity stage 3) live there or after.

### 9.1 Sketchlog lane (operator-flagged CRITICAL, 2026-07-02)
Source: `prod/docs/VIOLET_TODO_CRITICAL_DISTRIBUTION_TRACKING_IN_CONSTRAINED_MEMORY.md`
(9 signals mapped to BIBLE integration points; sketchlog = DDSketch/HLL/CMS/DriftSketch,
93 KB constant memory, mergeable monoids, WindowedStreamLog realtime windows, optional C++).
- **Now (observability, zero parity risk):** sketch dimensions (vel_div percentiles,
  signal breadth HLL, reversal freq) added to PRIME snapshot + journal as OBSERVE-ONLY
  columns; T7 replay computes them over full history = instant candidate-feature backtest.
- **Post-cert (alpha, gated):** signals as decision inputs (esp. #3 rolling-MAE tail
  detector → adaptive exits = the left-tail killer; #1 widening; #4 breadth; #6 reversal)
  — UV-divergence features via the certified-Q baseline + diff-guarded rollout. NEVER BLUE.
- Merge algebra fits PRIME-[n] farms (coordination-free merge); pure-Python path = §10 G1 ok.

### 9.2 Control plane (operator directive 2026-07-02: "NATS/iceoryx2 the hell out of it")
One control plane over the WHOLE system: fleet lifecycle (start/stop/arm PRIME-[n]/UV/soaks),
config + Q-dial distribution, heartbeats, gate-ledger events, kill-switch propagation.
- **Split doctrine:** data plane intra-box = Zinc/iceoryx2 (ADR-1, adopted); CONTROL plane
  inter-process/inter-box = message bus. Candidate: NATS (operator-named). NOTE: ADR-2
  reserved Zenoh for inter-box DATA — NATS-for-control vs Zenoh-for-data can coexist;
  Fable authors the control-plane ADR when wave 2 opens.
- NOT on the critical path to first testnet trade; REQUIRED before the clone farm.
- Design-in now (already true): every long-running process publishes a zinc snapshot and
  takes env-injected config — those are the surfaces the control plane will drive.

## 10. Graal-readiness — build constraints binding NOW despite deferred migration (NFR-G)

Cheap guardrails (mostly "don't do X"), enforced in review — so the later migration is a
runtime swap, not a rewrite:

- **G1** No CPython-only C-extensions in UV hot paths (pure-Python, or Rust behind stable FFI).
- **G2** No `__del__`/refcount-timing for correctness — explicit lifecycle (ASEx Drop-reliance
  leak = the cautionary tale).
- **G3** No "GIL makes this safe" — cross-thread state only via single-writer/Zinc/ASEx seams.
- **G4** UV code never imports `hazelcast` directly — HZ quarantined behind the existing
  reader seams (HZBridge direction).
- **G5** No hardcoded paths/creds; env-injected config.
- **G6** Long-running RSS-stable, jemalloc-compatible processes.

## 11. T6 (ACTIVE, HIGH PRIORITY — promoted 2026-07-02): real-Zinc unification

The clone line (banked as branch `salvage/uv-clone-line-1902e4b`) carries the REAL mmap Zinc
region transport (`ZincShadowChannel`, prefix `uv_shadow`, 18 h live soak) + the Textual
`tui_v2`. The merged main publishes the same snapshot via atomic file (cross-process, works
today) + in-memory zinc. T6 = port `ZincShadowChannel` under the reshape snapshot contract as
the transport, re-home `tui_v2` on it. Small, spec to follow; does NOT gate T1-D relaunch.