refactor(sp4): #260 follow-ups — symbolic doc anchors, dedicated q_dir_grad table, p99 helper
3 IMPORTANT items from #260 code-quality review (commit 88ae74ca7), addressed
post-smoke-validation (smoke-test-tkkx6 Succeeded):
1. Stale numeric line-references in 8+ doc-comments replaced with symbolic
code anchors per feedback_trust_code_not_docs. Pre-existing stale
`ISV_TOTAL_DIM = 60` comment also corrected.
2. q_dir_grad launcher allocated dedicated `q_dir_grad_subbuf_table_buf` +
`q_dir_grad_subbuf_counts_buf` (2 entries each) instead of reusing the
shared `oracle_subbuf_table_buf`. Eliminates implicit "must-run-before-
oracle" temporal coupling; removes `K_MAX=4` local redefinition.
3. `launch_sp4_p99_producer_single_buf` helper extracted on GpuDqnTrainer.
Collapses ~30-line boilerplate x 3 call sites (target_q, h_s2,
bw_d_h_s2) into single-line calls. Multi-sub-buffer launchers
(q_dir_grad, param_group_oracle) and shape-distinct producers
(grad_norm 1-thread, atom_pos 4-iter+batched-Pearls) keep their
bespoke shape.
Build clean, 11 SP4 lib tests pass, 16 SP4 GPU tests pass on RTX 3050 Ti.
Refs: #260 code-quality review, smoke-test-tkkx6 (commit 88ae74ca7).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
45da3eac69