refactor(sp22): H6 Phase 3 α cleanup + runbook revision for atom-shift design

Same-session cleanup of Phase 3b scalar-bias residue (commit cb80b74ce's
additions that became architecturally redundant under the 2026-05-13
atom-shift revision). The scalar-bias α design is mathematically
ineffective in C51 distributional Q-learning (softmax-shift-invariance
→ W gradient = 0 → never trains). The revised design threads
`aux_atom_shift[b, a] = W[a] * state_121[b]` through compute_expected_q
+ c51_loss_kernel + c51_grad_kernel + mag_concat_qdir; dW + dstate
gradients integrate into c51_grad_kernel's projection backward.

Files
─────
- crates/ml/build.rs:
    Removed `aux_to_q_dir_bias_kernel.cu` + `aux_to_q_dir_bias_backward_kernel.cu`
    from kernels_with_common. Replaced with comment block documenting
    C51 softmax-invariance reason + spec/audit pointers.

- crates/ml/src/cuda_pipeline/gpu_dqn_trainer.rs:
    Removed `pub(crate) static SP22_AUX_TO_Q_DIR_BIAS_CUBIN` and
    `SP22_AUX_TO_Q_DIR_BIAS_BWD_CUBIN` static declarations.
    Removed 3 struct fields (aux_to_q_dir_bias_kernel,
    aux_to_q_dir_bias_backward_dw_kernel,
    aux_to_q_dir_bias_backward_dstate_kernel) and their new()
    loading blocks + struct construction entries.
    KEPT: w_aux_to_q_dir + adam_m_w_aux + adam_v_w_aux + dw_aux_buf
    (still needed for atom-shift Adam-trained W).
    Updated W doc-comment to describe atom-shift threading (was
    scalar-bias) and structural-prior initialization `[-0.5, 0.0,
    +0.5, 0.0]`.

- crates/ml/src/cuda_pipeline/aux_to_q_dir_bias_kernel.cu +
  crates/ml/src/cuda_pipeline/aux_to_q_dir_bias_backward_kernel.cu:
    Source files stay on disk as committed dead code (commit
    464bc5f7a history preserved). nvcc no longer compiles them
    (build.rs unregistered). No `include_bytes!` references remain.

- docs/plans/2026-05-13-sp22-h6-phase3-alpha-beta-runbook.md:
    Tasks A3/A4/A5 marked SUPERSEDED; A5 retains cleanup instructions.
    Task B9 Steps 4-10 rewritten as Steps 4 (cleanup), 5 (W structural
    prior init), 6 (compute_expected_q atom-shift threading),
    7 (c51_loss_kernel), 8 (c51_grad_kernel backward dW + dstate),
    9 (mag_concat_qdir), 10 (quantile_q_select/iqn_dual_head
    investigation), 11 (Adam wireup), 12 (verify + capture).
    Task C1 rewritten: collector passes 4 more args through
    existing compute_expected_q launcher (NO new kernel).

- docs/dqn-wire-up-audit.md:
    Cleanup-commit entry documenting the runbook revision and the
    code-cleanup actions.

Verification
────────────
- cargo check -p ml --features cuda: 0 errors, 21 pre-existing
  warnings (Phase 3b baseline parity).
- Build script no longer compiles the deleted-registration kernels.

Phase 3-final scope (~40-60 hr engineering — unchanged)
───────────────────────────────────────────────────────
Implementation per the revised runbook: atom-shift threading
through 4-5 kernels (compute_expected_q, c51_loss_kernel,
c51_grad_kernel, mag_concat_qdir, possibly quantile_q_select/
iqn_dual_head) + Adam wireup + collector launcher arg passing +
A2 eval-side + SP11 controller extension + HEALTH_DIAG telemetry
+ verification gates + atomic Phase F commit + smoke + verdict.

Refs
────
- docs/plans/2026-05-12-sp22-h6-phase3-alpha-beta.md (spec α section
  revised 2026-05-13 — commit 648078ce2)
- docs/plans/2026-05-13-sp22-h6-phase3-alpha-beta-runbook.md (runbook
  α tasks revised in this commit)
- 464bc5f7a (Phase A — α kernels added; now committed dead code)
- cb80b74ce (Phase 3b — α struct fields + cubin statics added; cleaned
  up in this commit)
- pearl_no_partial_refactor (atom-shift threading is the new atomic
  contract for direction-branch atom positions)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
jgrusewski
2026-05-13 01:24:15 +02:00
parent 648078ce20
commit 08fd5803c4
4 changed files with 168 additions and 124 deletions

View File

@@ -16978,4 +16978,22 @@ Shifts atom positions state-dependently. C51 Bellman projection re-projects targ
**β + SP11 controller + A2 eval-side + telemetry**: unchanged from previous spec sections — those parts of Phase 3 were architecturally sound. Only the α design needed correction.
Next session: execute the revised α design per the updated spec. The runbook (`docs/plans/2026-05-13-sp22-h6-phase3-alpha-beta-runbook.md`) needs corresponding revision before execution — the runbook's α tasks (B9 Steps 4-9, C1) describe the original scalar-bias implementation and need to be rewritten for atom-shift threading.
Next session: execute the revised α design per the updated spec.
#### Cleanup commit (2026-05-13) — runbook revised, dead scalar-bias kernel registrations removed
Same-session cleanup of Phase 3b scalar-bias residue (commit `cb80b74ce`'s additions that became architecturally redundant under the atom-shift revision):
- `crates/ml/build.rs`: removed `"aux_to_q_dir_bias_kernel.cu"` and `"aux_to_q_dir_bias_backward_kernel.cu"` from `kernels_with_common` registration. Replaced with a comment block documenting the C51 softmax-invariance reason and pointing to the spec/audit references.
- `crates/ml/src/cuda_pipeline/gpu_dqn_trainer.rs`: removed `pub(crate) static SP22_AUX_TO_Q_DIR_BIAS_CUBIN` and `SP22_AUX_TO_Q_DIR_BIAS_BWD_CUBIN` static declarations. Removed 3 struct fields (`aux_to_q_dir_bias_kernel`, `aux_to_q_dir_bias_backward_dw_kernel`, `aux_to_q_dir_bias_backward_dstate_kernel`) and their `new()` loading blocks and struct construction entries. **Kept**: `w_aux_to_q_dir` + `adam_m_w_aux` + `adam_v_w_aux` + `dw_aux_buf` — the Adam-trained W buffer + moments + grad accumulator are still needed for the atom-shift design.
- `crates/ml/src/cuda_pipeline/aux_to_q_dir_bias_kernel.cu` + `aux_to_q_dir_bias_backward_kernel.cu`: source files stay on disk as committed dead code (commit `464bc5f7a` history preserved); future cleanup may delete them. nvcc no longer compiles them (build.rs unregistered). No `include_bytes!` references remain.
Runbook revision (`docs/plans/2026-05-13-sp22-h6-phase3-alpha-beta-runbook.md`):
- Tasks A3, A4, A5 marked SUPERSEDED; A5 retains cleanup instructions for removing the build.rs registrations.
- Task B9 Steps 4-10 rewritten as Steps 4 (cleanup), 5 (W structural prior init), 6-10 (atom-shift threading through compute_expected_q, c51_loss_kernel, c51_grad_kernel, mag_concat_qdir, quantile_q_select/iqn_dual_head investigation), 11 (Adam wireup), 12 (verify + capture-graph integrity).
- Task C1 rewritten for atom-shift threading through the collector's rollout-time `compute_expected_q` launcher (NO new kernel — just pass 4 more args through the existing launcher).
Verification: cargo check 0 errors, 21 pre-existing warnings (Phase 3b baseline parity).
Phase 3-final implementation is now atom-shift design end-to-end. The runbook is consistent with the spec.