diff --git a/docs/dqn-wire-up-audit.md b/docs/dqn-wire-up-audit.md index a925143b6..2a070dea3 100644 --- a/docs/dqn-wire-up-audit.md +++ b/docs/dqn-wire-up-audit.md @@ -2,6 +2,44 @@ **Status:** Populated during Plan 1 Task 6 (A.5 orphan audit). Updated on every commit per Invariant 7. +## 2026-05-08 — SP17 Phase 3.3: Phase 3 close-out + memory pearl + +Phase 3.3 finalises the SP17 dueling-Q diagnostic chain: + +**Canonical HEALTH_DIAG line format** (per-epoch, alongside `v_a_means`): + +``` +HEALTH_DIAG[N]: dueling [v_share=(d=X m=Y o=Z u=W)] [a_var=(d=A m=B o=C u=D)] [clip=K] +``` + +The 9 ISV slots [474..483) are emitted in this single line, matching the plan's exact format spec at line 1064-1066. Reader parsing pattern: + +| Field | Slot | Meaning | Health interpretation | +|---|---|---|---| +| `v_share=(d= ...)` | 478..482 | Per-branch `\|E[V]\| / (\|E[V]\| + \|E[A_centered, picked]\|)` | ≈0.5 = healthy split; →1.0 with a_var→0 = pre-SP17 V-dominated regression | +| `a_var=(d= ...)` | 474..478 | Per-branch `Var_a(A_centered)` over actions | >0 = policy discriminates; →0 = "all actions equivalent, V dominates" | +| `clip=K` | 482 | Adaptive `p99(\|A_centered\|) × 1.5` | Settles in [0.5, 5.0] for healthy training; outside = degenerate distribution | + +**Phase 4 smoke gate** (Plan Phase 4): the L40S 5-epoch smoke checks +- `a_var > 0.01` per branch throughout (regression detector) +- `v_share ∈ [0.3, 0.7]` per branch (balanced dueling) +- `clip ∈ [0.5, 5.0]` (magnitude scale healthy) + +**Memory pearl**: `pearl_sp4_histogram_warp_tile_undercount.md` documents the test-data trap discovered in Phase 3.2's GPU oracle test for `advantage_clip_bound`. The kernel uses non-atomic per-warp tile binning per `feedback_no_atomicadd`; the documented "1/(256×32) loss" qualifies "for uniformly distributed signals". Lockstep-uniform synthetic test data violates that assumption and undercounts dramatically. Fix: add per-element jitter to test data. Real `|A_centered|` in production is continuous so the issue is test-only. + +**Phase 3 commit chain** (atomic per Phase per `feedback_no_partial_refactor`): + +| Commit | Phase | Producer | LOC | Tests | +|---|---|---|---|---| +| `1e70cd5e5` | 3.1 | A_var_ema (4 branches) | +649 | 1 GPU oracle (Var matches closed-form) | +| `b6b17d46b` | 3.2 | V_share + advantage_clip_bound | +1208 | 2 GPU oracles (V_share closed-form, p99 × safety) | + +All 13 SP17 GPU oracle tests pass on RTX 3050 Ti in 2.4s. + +**Atomicity envelope**: Phase 3 is observability-only. NO consumer path is modified — no kernel reads V_share, a_var, or clip_bound to alter behaviour. The clip bound is producer-tracked but NOT yet wired as an actual clip on any kernel; that's Phase 5 follow-up. The Phase 1 mean-zero contract (commits `eabcf8d52` through `6f53d676f`) is what makes `A_centered` a meaningful signal; this Phase observes it. + +**Plan**: `docs/superpowers/plans/2026-05-08-sp17-dueling-q-network.md` Phase 3. + ## 2026-05-08 — SP17 Phase 3.2: V_share + advantage_clip_bound producers (additive observability) Phase 3.2 lands the remaining two SP17 dueling-Q diagnostic producers atomically with kernel + launcher + Rust wrapper + extended HEALTH_DIAG emit + GPU oracle tests per `feedback_wire_everything_up`.