// crates/ml/src/cuda_pipeline/aux_w_prior_init_kernel.cu
//
// SP22 H6 Phase 3 α (2026-05-13) — DORMANT, superseded by Phase D below.
// SP22 H6 vNext Phase D (2026-05-14): structural-prior initialization for
// the Adam-trained `w_aux_to_q_dir [b0_size=4, K=3] = 12` weight matrix.
//
// K=3 outcome-conditioned atom-shift structural prior (12 weights):
//   For each direction action a ∈ {Short, Hold, Long, Flat} and each
//   outcome k ∈ {Profit, Stop, Timeout}, W[a*K + k] biases the Q-target
//   atom position for action a when aux predicts outcome k with high
//   probability.
//
//                  W[Profit]   W[Stop]   W[Timeout]
//   Short (a=0)     +0.5       -0.5       0.0
//   Hold  (a=1)      0.0       +0.5       0.0
//   Long  (a=2)     +0.5       -0.5       0.0
//   Flat  (a=3)      0.0       +0.5       0.0
//
// Semantic rationale:
//   - Trade-directional actions (Short, Long) get atom-shift +0.5 when
//     aux predicts Profit (the trade WILL succeed) — encourages taking
//     the trade. Get -0.5 when aux predicts Stop (the trade WILL fail)
//     — discourages taking the trade. Timeout = 0 (uncertain).
//   - Non-directional actions (Hold, Flat) get atom-shift +0.5 when aux
//     predicts Stop — encourages staying flat/holding rather than
//     entering a doomed trade. Get 0 on Profit (no need to bias toward
//     no-action when a profitable trade is available). Timeout = 0.
//
// Replaces the Phase 3 K=2 prior {Short=-0.5, Hold=0, Long=+0.5, Flat=0}
// which was based on directional `p_up` — that hypothesis was FALSIFIED
// (smoke train-xrkb7 @ ebc7144434, WR=0.4346 = baseline). The K=3
// outcome-conditioned prior is the vNext replacement, aligned with the
// system's multi-bar trade decisions.
//
// Rationale (audit doc Phase 3c α revision, spec doc α section):
// state_121 ∈ [-1, +1] is the recentered aux p_up. When aux predicts
// up (state_121 = +1):
//   - W[Short] * state_121 = -0.5 → Q_short atoms shift DOWN by 0.5
//     → action selection avoids Short.
//   - W[Long]  * state_121 = +0.5 → Q_long  atoms shift UP   by 0.5
//     → action selection biases toward Long.
//   - Hold / Flat: unchanged.
//
// When aux predicts down (state_121 = -1): symmetrically biases
// toward Short and away from Long.
//
// Adam refines W from this prior via projection backward in
// c51_grad_kernel.cu (B9 Step 8 — the dz_shift gradient flows to
// dW via per-action block tree-reduce).
//
// Discipline
// ──────────
// - One-time init call at trainer construction; NOT in the captured
//   training loop.
// - No HtoD per `feedback_no_htod_htoh_only_mapped_pinned.md` (pure
//   GPU compute; hardcoded values in the kernel).
// - 4 threads, single block — trivial cost (<1 µs).
// - Capture-safety: the kernel is not invoked from inside any
//   captured graph (per-step or per-fold), so capture rules don't
//   apply; conventional kernel discipline (no atomicAdd, no host
//   branches inside the kernel body) preserved anyway.
//
// Launch: grid=(1, 1, 1), block=(12, 1, 1). Each thread writes one slot.

#include <cuda_runtime.h>

extern "C" __global__ void aux_w_prior_init(
    /* [b0_size=4, K=3] f32 output buffer (12 elements row-major); overwrites
     * alloc_zeros'd content with the structural prior values. */
    float* __restrict__ w_aux_to_q_dir
) {
    int idx = threadIdx.x;
    if (idx >= 12) return;

    /* SP22 H6 vNext Phase D (2026-05-14) — K=3 outcome-conditioned
     * structural prior. Indexed as `w[a * K + k]` where a is the
     * direction action (Short=0, Hold=1, Long=2, Flat=3) and k is the
     * outcome class (Profit=0, Stop=1, Timeout=2).
     *
     * The prior is DORMANT-by-design — values land in W at trainer
     * construction but the atom-shift Q-target modulation is gated by
     * the K=3 head's softmax outputs in state[121..124). At cold-start
     * those slots are 0.0 (no Profit/Stop/Timeout prediction yet) so
     * the atom-shift is effectively zero even with W populated. After
     * the K=3 head trains and emits real probs, the prior's structural
     * bias kicks in; Adam refines W from there.
     *
     * Adam refines W from this prior via the per-(a, k) gradient
     * computed in c51_aux_dw_kernel + applied in adam_w_aux_kernel
     * (both extended to 12 weights in this phase).
     */
    float prior_values[12] = {
        /* Short × {Profit, Stop, Timeout} */ +0.5f, -0.5f, 0.0f,
        /* Hold  × {Profit, Stop, Timeout} */  0.0f, +0.5f, 0.0f,
        /* Long  × {Profit, Stop, Timeout} */ +0.5f, -0.5f, 0.0f,
        /* Flat  × {Profit, Stop, Timeout} */  0.0f, +0.5f, 0.0f,
    };
    w_aux_to_q_dir[idx] = prior_values[idx];
}
