From 0c57a5a31f33b8887db83930cb83419ff9713e19 Mon Sep 17 00:00:00 2001 From: jgrusewski Date: Fri, 8 May 2026 23:04:41 +0200 Subject: [PATCH] =?UTF-8?q?docs(sp17-3.3):=20Phase=203=20close-out=20?= =?UTF-8?q?=E2=80=94=20canonical=20HEALTH=5FDIAG=20line=20+=20pearl?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 3.3 finalises the SP17 dueling-Q diagnostic chain. Canonical HEALTH_DIAG line (already emitted by Phase 3.2 commit b6b17d46b) matches the plan's exact format spec at line 1064-1066: 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] Reader parsing table added to audit doc, Phase 4 smoke gate criteria documented: - 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` filed (MEMORY.md updated separately as it's a user-private file outside the worktree). Documents the SP17 Phase 3.2 test-data trap discovered during the advantage_clip_bound oracle test: `sp4_histogram_p99`'s documented "1/(256×32) loss for typical signals" qualifies on signal distribution; lockstep-uniform synthetic patterns violate the assumption. Fix is per-element jitter in test data — NOT atomicAdd (which would violate `feedback_no_atomicadd`). Real |A_centered| in production is continuous, so the issue is test-only. Phase 3 commit chain (atomic per `feedback_no_partial_refactor`): - 1e70cd5e5 Phase 3.1: A_var_ema + 1 GPU oracle test - b6b17d46b Phase 3.2: V_share + advantage_clip_bound + 2 GPU oracles - this commit: closeout audit doc 13/13 SP17 GPU oracle tests pass on RTX 3050 Ti in 2.4s. Phase 3 is observability-only — NO consumer path is modified. The clip bound is producer-tracked but NOT yet wired as an actual clip on any kernel; that's Phase 5 follow-up. Plan: docs/superpowers/plans/2026-05-08-sp17-dueling-q-network.md Phase 3.3. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/dqn-wire-up-audit.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) 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`.