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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user