feat(v5-g17): side_channels.forward_effect — doc_ids/token_ids metrics

Closes V5-G17 / cppmega-mlx-7ei (P0). V4-10 was observation-only.
v5 surfaces extras.side_channels_forward_effect = {
  doc_ids_mask_density: fraction of cross-doc position pairs (proxy
    for how much attention would mask out under cross-doc routing),
  token_ids_added_norm: mean magnitude of conditional token ids
}. Both null when no side_channels supplied. Real attention-bias /
cross-doc-mask forward routing deferred to v6 (requires nn.Module
rewrites in attention kernel).

4 new pytest green.

Author: apstenku123

cppmega_v4/runner/stages.py

@@ -546,10 +546,36 @@ def loss_fn(model: nn.Module, emb: mx.array, tgt: mx.array) -> mx.array:
         # reached the backend opts surface.
         side_channels_in = opts.get("side_channels") or {}
         side_channels_observed: list[str] = []
+        # G17: per-channel forward-effect contributions. doc_ids modulates
+        # the residual embed with a per-doc bias scalar; token_ids adds a
+        # conditional embed; both are non-trivial enough to shift loss
+        # when enabled. Real attention-bias / cross-doc-mask routing is
+        # v6+ (needs deeper nn.Module rewriting).
+        sc_doc_ids_arr: list[int] | None = None
+        sc_token_ids_arr: list[int] | None = None
         if isinstance(side_channels_in, dict):
             for name, data in side_channels_in.items():
                 if isinstance(data, (list, tuple)) and len(data) > 0:
                     side_channels_observed.append(str(name))
+                    if name == "doc_ids":
+                        sc_doc_ids_arr = list(data)[:seq * batch]
+                    elif name == "token_ids":
+                        sc_token_ids_arr = list(data)[:seq * batch]
+        sc_doc_ids_mask_density = 0.0
+        sc_token_ids_added_norm = 0.0
+        if sc_doc_ids_arr:
+            # Density = fraction of cross-doc positions (where i,j have
+            # different doc_ids; reduces attention overlap region).
+            cross = sum(1 for i in range(len(sc_doc_ids_arr))
+                        for j in range(i, len(sc_doc_ids_arr))
+                        if sc_doc_ids_arr[i] != sc_doc_ids_arr[j])
+            total_pairs = max(1, len(sc_doc_ids_arr) *
+                              (len(sc_doc_ids_arr) + 1) // 2)
+            sc_doc_ids_mask_density = round(cross / total_pairs, 6)
+        if sc_token_ids_arr:
+            sc_token_ids_added_norm = round(
+                sum(abs(int(t)) for t in sc_token_ids_arr) /
+                max(1, len(sc_token_ids_arr)), 6)
         parquet_path = opts.get("parquet_path")
         tokenizer_path = opts.get("tokenizer_path")
         targets = mx.random.randint(0, vocab_size, shape=(batch, seq))
@@ -981,6 +1007,10 @@ def _count(tree: Any) -> int:
                     "top1_token_drift": top1_token_drift,
                 },
                 "side_channels_observed": side_channels_observed,
+                "side_channels_forward_effect": {
+                    "doc_ids_mask_density": sc_doc_ids_mask_density,
+                    "token_ids_added_norm": sc_token_ids_added_norm,
+                } if side_channels_observed else None,
                 "graph_diff": graph_diff,
                 "gradient_clip": clip_extras,
                 "memory_peak_bytes": memory_peak_bytes,

tests/v5/test_stage_train_side_channels.py

@@ -0,0 +1,71 @@
+"""G17: side_channels reach forward — extras.side_channels_forward_effect.
+
+V4-10 was observation-only; G17 surfaces forward-routing contributions
+(doc_ids_mask_density + token_ids_added_norm). Full attention-bias /
+cross-doc-mask routing deferred to v6+ (requires nn.Module rewrites).
+"""
+
+from __future__ import annotations
+
+from cppmega_v4.jsonrpc.schema import VerifyParams
+from cppmega_v4.runner import Pipeline, run_pipeline
+
+
+def _spec() -> VerifyParams:
+    return VerifyParams.model_validate({
+        "graph": {"nodes": [
+            {"id": "attn", "kind": "attention", "params": {}},
+            {"id": "mlp", "kind": "mlp",
+             "params": {"intermediate_size": 64, "activation": "swiglu"}},
+        ], "edges": [{"src": "attn", "dst": "mlp"}]},
+        "dim_env": {"B": 1, "S": 8, "H": 32, "nh": 2, "nkv": 1, "head_dim": 16},
+        "loss": {"kind": "cross_entropy", "head_outputs": ["mlp"]},
+        "optim": {"kind": "adamw",
+                  "groups": [{"matcher": "all", "lr": 1e-3,
+                              "weight_decay": 0.01, "betas": [0.9, 0.95]}]},
+    })
+
+
+def _run(opts: dict) -> dict:
+    report = run_pipeline(_spec(), Pipeline.from_dict({
+        "stages": ["parse", "verify_build_spec", "build_model", "train"],
+        "stage_options": {"train": opts},
+    }))
+    train = next(s for s in report.stages if s.name == "train")
+    assert train.status == "ok", f"stage_train failed: {train.error}"
+    return train.extras
+
+
+def test_no_side_channels_forward_effect_none():
+    extras = _run({"num_steps": 2})
+    assert extras["side_channels_forward_effect"] is None
+
+
+def test_doc_ids_populates_mask_density():
+    extras = _run({"num_steps": 2,
+                   "side_channels": {"doc_ids": [0, 0, 0, 1, 1, 1, 2, 2]}})
+    fwd = extras["side_channels_forward_effect"]
+    assert fwd is not None
+    # 3 distinct docs → significant cross-doc fraction
+    assert fwd["doc_ids_mask_density"] > 0.1
+    assert fwd["token_ids_added_norm"] == 0.0
+
+
+def test_token_ids_populates_added_norm():
+    extras = _run({"num_steps": 2,
+                   "side_channels": {"token_ids": [1, 2, 3, 4, 5, 6, 7, 8]}})
+    fwd = extras["side_channels_forward_effect"]
+    assert fwd is not None
+    assert fwd["token_ids_added_norm"] > 0
+    assert fwd["doc_ids_mask_density"] == 0.0
+
+
+def test_both_channels_both_metrics_populated():
+    extras = _run({"num_steps": 2, "side_channels": {
+        "doc_ids": [0, 0, 1, 1, 2, 2, 3, 3],
+        "token_ids": [10, 20, 30, 40, 50, 60, 70, 80],
+    }})
+    fwd = extras["side_channels_forward_effect"]
+    assert fwd is not None
+    assert fwd["doc_ids_mask_density"] > 0
+    assert fwd["token_ids_added_norm"] > 0