feat(probe-b): contract_probe runner + alternatives + dry-forward gate

Stage B of the Contract Probe epic (cppmega-mlx-728). Adds the
solver, requirements tables, alternative generator, and synthetic
dry-forward gate.

- requirements.py: BRICK_REQUIREMENTS (covers every BLOCK_BUILDERS
  key — engram needs call_edges, csa_hca needs type_edges, the other
  23 bricks accept input_ids only) + LOSS_REQUIREMENTS (CE/MTP/IFIM/
  MHC/CUSTOM with explicit satisfied_by chains).
- alternatives.py: deterministic generator (swap_loss, swap_tokenizer,
  add_column, drop_brick, relax_requirement). Capped at 3 per finding,
  ordered by cost (low→medium→high).
- dry_forward.py: synthetic (B=1, S=8, H=64) walk through the
  instantiated graph; mean-reduce predecessors at fan-in for
  parallel-block topologies. Never raises — returns a verdict tuple.
- probe.py: contract_probe() composes capability snapshots + per-
  component evaluation + dry-forward into one read-only
  ContractProbeReport with is_clean / blocking accessors.

Tests (39): every brick kind has a requirements entry, satisfied-by
alternative-key logic, end-to-end probe on llama3_8b with CE/IFIM/
MTP/MHC variants, alternative shape + cap + cost-ordering, dry_forward
on linear and parallel-block graphs, sub-2s gate on qwen3_235b_a22b.

Full v4 regression: 1927 passed / 5 skipped / 15 xfailed / 0 failed.

Closes cppmega-mlx-728.2.

Author: apstenku123

cppmega_v4/probe/__init__.py

@@ -9,18 +9,40 @@
 
 from __future__ import annotations
 
+from cppmega_v4.probe.alternatives import Alternative, generate_alternatives
 from cppmega_v4.probe.capabilities import (
     ColumnSpec,
     ParquetCapabilities,
     TokenizerCapabilities,
     introspect_parquet,
     introspect_tokenizer,
 )
+from cppmega_v4.probe.dry_forward import DryForwardResult, dry_forward
+from cppmega_v4.probe.probe import (
+    ContractProbeReport,
+    ProbeFinding,
+    contract_probe,
+)
+from cppmega_v4.probe.requirements import (
+    BRICK_REQUIREMENTS,
+    LOSS_REQUIREMENTS,
+    DataRequirement,
+)
 
 __all__ = [
+    "Alternative",
+    "BRICK_REQUIREMENTS",
     "ColumnSpec",
+    "ContractProbeReport",
+    "DataRequirement",
+    "DryForwardResult",
+    "LOSS_REQUIREMENTS",
     "ParquetCapabilities",
+    "ProbeFinding",
     "TokenizerCapabilities",
+    "contract_probe",
+    "dry_forward",
+    "generate_alternatives",
     "introspect_parquet",
     "introspect_tokenizer",
 ]

cppmega_v4/probe/alternatives.py

@@ -0,0 +1,111 @@
+"""Generators for explicit alternatives to unsatisfied requirements.
+
+Each generator is a pure function:
+   (requirement, build_spec, tokenizer_caps, parquet_caps) -> tuple[Alternative, ...]
+
+No side effects, no LLM, no model calls. Alternatives are ranked
+deterministically by ``cost`` (low < medium < high) and then by
+``action`` to keep test output stable across runs.
+
+Each Alternative carries a JSON-Patch-shaped ``diff`` that the GUI/CLI
+applies to the canonical spec representation. The probe never applies
+the diff itself.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Mapping
+
+from cppmega_v4.buildspec.loss_spec import LossKind
+from cppmega_v4.buildspec.model_build_spec import ModelBuildSpec
+from cppmega_v4.probe.capabilities import (
+    ParquetCapabilities,
+    TokenizerCapabilities,
+)
+from cppmega_v4.probe.requirements import DataRequirement
+
+
+_COST_ORDER: dict[str, int] = {"low": 0, "medium": 1, "high": 2}
+
+
+@dataclass(frozen=True)
+class Alternative:
+    """One way the user can resolve an unsatisfied requirement."""
+
+    action: Literal[
+        "swap_loss", "swap_tokenizer", "add_column",
+        "drop_brick", "relax_requirement",
+    ]
+    target: str
+    diff: Mapping[str, object]
+    cost: Literal["low", "medium", "high"]
+    reason: str
+
+
+_MAX_ALTERNATIVES_PER_FINDING: int = 3
+
+
+def generate_alternatives(
+    requirement: DataRequirement,
+    component: str,
+    build_spec: ModelBuildSpec,
+    tokenizer_caps: TokenizerCapabilities,
+    parquet_caps: ParquetCapabilities,
+) -> tuple[Alternative, ...]:
+    """Return ordered alternatives that, if applied, would satisfy
+    ``requirement``. Caps the result at three per design ceiling."""
+    out: list[Alternative] = []
+
+    # Loss-level requirements — most cheaply resolved by swapping loss.
+    if component.startswith("loss:"):
+        if build_spec.loss.kind != LossKind.CROSS_ENTROPY:
+            out.append(Alternative(
+                action="swap_loss", target=component,
+                diff={"op": "replace", "path": "/loss/kind",
+                      "value": LossKind.CROSS_ENTROPY.value},
+                cost="low",
+                reason="cross-entropy has no side-channel data requirements",
+            ))
+        # FIM-specific: suggest tokenizer swap when FIM ids are missing.
+        if requirement.origin == "tokenizer" and requirement.key.startswith("FIM_"):
+            out.append(Alternative(
+                action="swap_tokenizer", target="tokenizer",
+                diff={"op": "replace", "path": "/tokenizer/source",
+                      "value": "<tokenizer with full FIM trio>"},
+                cost="medium",
+                reason=f"need a tokenizer that defines {requirement.key}",
+            ))
+
+    # Brick-level requirements — drop the brick OR add the missing column.
+    if component.startswith("brick:"):
+        brick_name = component.split(":", 1)[1]
+        if requirement.origin == "parquet":
+            out.append(Alternative(
+                action="add_column", target=f"parquet:{requirement.key}",
+                diff={"op": "add", "path": f"/parquet/columns/{requirement.key}",
+                      "value": "<run enrichment pipeline>"},
+                cost="high",
+                reason=f"parquet shard is missing {requirement.key!r}; "
+                       "enrichment scripts live under scripts/nanochat_data/",
+            ))
+            out.append(Alternative(
+                action="drop_brick", target=component,
+                diff={"op": "remove", "path": f"/graph/nodes/{brick_name}"},
+                cost="medium",
+                reason=f"remove brick {brick_name!r} which requires "
+                       f"{requirement.key!r}",
+            ))
+
+    # Universal escape hatch — only when the requirement is non-required.
+    if not requirement.required:
+        out.append(Alternative(
+            action="relax_requirement", target=component,
+            diff={"op": "add", "path": "/probe/allowlist",
+                  "value": requirement.key},
+            cost="low",
+            reason="requirement is soft; explicitly accept missing data",
+        ))
+
+    out.sort(key=lambda a: (_COST_ORDER[a.cost], a.action))
+    return tuple(out[:_MAX_ALTERNATIVES_PER_FINDING])

cppmega_v4/probe/dry_forward.py

@@ -0,0 +1,89 @@
+"""Dry forward pass — synthetic input_ids on the instantiated graph.
+
+Last gate after static checks. Each brick already has a unit test that
+its forward preserves (B, S, H) at small sizes; here we chain the
+instantiated graph and run **one** forward at hidden=64, batch=1, seq=8
+to catch residual brick-to-brick coupling that the resolver missed.
+
+Returns a one-word verdict + an optional exception trace. Never raises.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import mlx.core as mx
+
+from cppmega_v4.fusion.brick_graph import BrickGraph
+from cppmega_v4.models.unified_superblock_v4 import BLOCK_BUILDERS
+
+
+@dataclass(frozen=True)
+class DryForwardResult:
+    verdict: Literal["ok", "shape_mismatch", "exception"]
+    detail: str = ""
+
+
+def dry_forward(
+    graph: BrickGraph,
+    *,
+    hidden_size: int = 64,
+    seq_len: int = 8,
+    batch: int = 1,
+) -> DryForwardResult:
+    """Walk ``graph`` in declared order, forwarding a synthetic activation.
+
+    Parallel-block topologies are handled by averaging branch outputs at
+    the fan-in point — matches the convention BrickGraph uses for
+    Tiny-Aya style ``GQA‖MLP``.
+    """
+    try:
+        # Build modules fresh — caller may have passed instantiate=False.
+        modules: dict[str, object] = {}
+        for node in graph.nodes:
+            builder = BLOCK_BUILDERS.get(node.kind)
+            if builder is None:
+                return DryForwardResult(
+                    verdict="exception",
+                    detail=f"unknown brick kind {node.kind!r}",
+                )
+            modules[node.name] = builder(hidden_size, dict(node.params))
+
+        x0 = mx.random.normal((batch, seq_len, hidden_size))
+        # Topo: pre-compute predecessors map; if a node has multiple
+        # predecessors, mean-reduce their outputs before forwarding.
+        outputs: dict[str, mx.array] = {}
+        roots = [n.name for n in graph.nodes if not graph.predecessors(n.name)]
+        for name in roots:
+            outputs[name] = modules[name](x0)
+        # Iterate remaining nodes in declared order (graph is already a
+        # topological declaration thanks to from_block_specs).
+        for node in graph.nodes:
+            if node.name in outputs:
+                continue
+            preds = graph.predecessors(node.name)
+            if not preds:
+                outputs[node.name] = modules[node.name](x0)
+                continue
+            if len(preds) == 1:
+                inp = outputs[preds[0]]
+            else:
+                stacked = mx.stack([outputs[p] for p in preds], axis=0)
+                inp = mx.mean(stacked, axis=0)
+            outputs[node.name] = modules[node.name](inp)
+
+        last = graph.nodes[-1].name
+        y = outputs[last]
+        if y.shape != (batch, seq_len, hidden_size):
+            return DryForwardResult(
+                verdict="shape_mismatch",
+                detail=f"final shape {y.shape} != "
+                       f"(batch={batch}, seq={seq_len}, H={hidden_size})",
+            )
+        return DryForwardResult(verdict="ok")
+    except Exception as exc:
+        return DryForwardResult(
+            verdict="exception",
+            detail=f"{type(exc).__name__}: {exc}",
+        )