feat(e-audit-02): FlowCanvas isValidConnection from compatible_edges RPC

Closes cppmega-mlx-ofd2 (E-AUDIT-02): FlowCanvas accepted an
isValidConnection prop but App.tsx never threaded one — incompatible
brick edges only failed at server-side verify.

- cppmega_v4/spec/shape_contract.py: new compatible_edges() helper
  enumerates (src_kind, dst_kind) pairs the contract layer considers
  well-typed (src.outputs non-empty AND dst.inputs non-empty; opaque
  shapes universally compatible). Exported in __all__.
- cppmega_v4/jsonrpc/catalog_methods.py: catalog.list_options grows
  a 'compatible_edges' branch that returns one option per pair with
  name='src->dst', paper_ref=src, summary=dst. LRU-cached.
- vbgui/src/hooks/useCompatibleEdges.ts: fetches the pair set once
  on mount; makeIsValidConnection(pairs, brickKindOf) returns a
  React-Flow-compatible predicate (allows everything when fetch
  fails — server-side verify is the fallback).
- vbgui/src/App.tsx: imports the hook + isValidConnection callback;
  threads it into <FlowCanvas isValidConnection={...} />. Already
  declared in FlowCanvasProps.
- tests/v4/test_compatible_edges_catalog.py: helper round-trip,
  attention→mlp pair present, RPC envelope shape.
- vbgui/tests/useCompatibleEdges.test.ts: 4 vitest cases covering
  empty-set fallback, reject path, accept path, unknown-id reject.
- vbgui/e2e/scenarios/90_compatible_edges.spec.ts: real RPC call
  returns non-empty options; preset load + hook fetch fires no
  page errors.

Author: apstenku123

cppmega_v4/jsonrpc/catalog_methods.py

@@ -63,13 +63,34 @@ def catalog_list_options(
     *,
     cache: LRUCache | None = None,
 ) -> CatalogListOptionsResult:
-    """Return compact summaries for every entry in ``params.category``."""
+    """Return compact summaries for every entry in ``params.category``.
+
+    Special category ``compatible_edges`` (V7-E-AUDIT-02): returns one
+    option per (src_kind, dst_kind) pair where the shape contracts
+    indicate the edge is well-typed. Each option's ``name`` is
+    ``"src_kind->dst_kind"``, ``summary`` is ``dst_kind``, and
+    ``paper_ref`` is ``src_kind`` so the UI can split with a single
+    str.split('->').
+    """
     cache_key = ("catalog.list_options", params.category)
     if cache is not None:
         hit = cache.get(cache_key)
         if hit is not None:
             return hit  # type: ignore[return-value]
 
+    if params.category == "compatible_edges":
+        from cppmega_v4.spec.shape_contract import compatible_edges
+        pairs = compatible_edges()
+        result = CatalogListOptionsResult(options=[
+            CatalogOptionSummary(
+                name=f"{src}->{dst}", summary=dst, paper_ref=src,
+            )
+            for src, dst in pairs
+        ])
+        if cache is not None:
+            cache.set(cache_key, result)
+        return result
+
     entries = list_options(params.category)
     result = CatalogListOptionsResult(options=[
         CatalogOptionSummary(

cppmega_v4/spec/shape_contract.py

@@ -547,10 +547,39 @@ def registered_kinds() -> tuple[str, ...]:
     return tuple(sorted(_CONTRACTS.keys()))
 
 
+def compatible_edges() -> tuple[tuple[str, str], ...]:
+    """V7-E-AUDIT-02: enumerate (src_kind, dst_kind) pairs that the
+    shape-contract layer considers well-typed.
+
+    Rule: edge is compatible iff src declares at least one output AND
+    dst declares at least one input. cppmega bricks use a canonical
+    ``x → y`` channel naming convention; every transformer-block brick
+    can feed every other at the contract layer. Numerical compatibility
+    (dim_env, head_dim, ...) is enforced separately by
+    ``verify_and_estimate``; this helper answers the UI's coarse
+    'can I drop an edge here' question to reject obvious mis-wiring
+    (e.g. dropping an edge into a brick with no inputs).
+    Opaque-shape bricks are universally compatible.
+    """
+    pairs: list[tuple[str, str]] = []
+    kinds = sorted(_CONTRACTS.keys())
+    for src in kinds:
+        src_c = _CONTRACTS[src]
+        for dst in kinds:
+            dst_c = _CONTRACTS[dst]
+            if src_c.opaque_shape or dst_c.opaque_shape:
+                pairs.append((src, dst))
+                continue
+            if src_c.outputs and dst_c.inputs:
+                pairs.append((src, dst))
+    return tuple(pairs)
+
+
 __all__ = [
     "BrickShapeContract",
     "ResolveError",
     "ShapeExpr",
+    "compatible_edges",
     "contract_for",
     "register_contract",
     "registered_kinds",

tests/v4/test_compatible_edges_catalog.py

@@ -0,0 +1,49 @@
+"""E-AUDIT-02 backend: catalog.list_options('compatible_edges')."""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from cppmega_v4.jsonrpc import create_app
+from cppmega_v4.spec.shape_contract import (
+    compatible_edges, registered_kinds,
+)
+
+
+@pytest.fixture
+def client():
+    return TestClient(create_app(cache_capacity=2))
+
+
+def test_compatible_edges_helper_nonempty_and_well_typed():
+    pairs = compatible_edges()
+    assert len(pairs) > 0
+    kinds = set(registered_kinds())
+    for src, dst in pairs:
+        assert src in kinds
+        assert dst in kinds
+
+
+def test_compatible_edges_includes_attention_to_mlp():
+    """attention.outputs and mlp.inputs share the canonical hidden
+    state channel — the most common edge in any transformer block."""
+    pairs = set(compatible_edges())
+    assert ("attention", "mlp") in pairs
+
+
+def test_catalog_endpoint_returns_pair_encoded_options(client):
+    payload = {"jsonrpc": "2.0", "id": "e1",
+               "method": "catalog.list_options",
+               "params": {"category": "compatible_edges"}}
+    r = client.post("/rpc", json=payload)
+    assert r.status_code == 200
+    body = r.json()
+    assert "error" not in body, body
+    opts = body["result"]["options"]
+    assert len(opts) > 0
+    for o in opts[:5]:
+        assert "->" in o["name"]
+        src, dst = o["name"].split("->")
+        assert o["paper_ref"] == src
+        assert o["summary"] == dst

vbgui/e2e/scenarios/90_compatible_edges.spec.ts

@@ -0,0 +1,42 @@
+// E-AUDIT-02: FlowCanvas isValidConnection wired via
+// catalog.list_options('compatible_edges'). After preset load, the
+// edge-compatibility hook has fetched the pair set; FlowCanvas
+// passes it to React Flow's isValidConnection prop. We assert that
+// the catalog endpoint returns at least one pair and that no
+// runtime errors leak into the page (incompatible-drop UI behavior
+// is covered by the vitest unit test).
+
+import { test, expect } from "@playwright/test";
+import { gotoApp, selectPreset } from "../fixtures";
+
+test("E-AUDIT-02: compatible_edges populated after preset load",
+  async ({ page }) => {
+    test.setTimeout(30_000);
+    const errors: string[] = [];
+    page.on("pageerror", (e) => errors.push(String(e)));
+    await gotoApp(page);
+
+    const catalogResp = await page.evaluate(async () => {
+      const r = await fetch("http://127.0.0.1:8767/rpc", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0", id: "c1",
+          method: "catalog.list_options",
+          params: { category: "compatible_edges" },
+        }),
+      });
+      return await r.json();
+    });
+    expect(catalogResp.error).toBeUndefined();
+    const opts = catalogResp.result.options as Array<{
+      name: string; summary: string; paper_ref: string;
+    }>;
+    expect(opts.length).toBeGreaterThan(0);
+    expect(opts[0].name).toContain("->");
+    expect(opts[0].paper_ref).toBe(opts[0].name.split("->")[0]);
+
+    await selectPreset(page, "llama3_8b");
+    // No page errors after preset load + hook fetch.
+    expect(errors).toEqual([]);
+  });

vbgui/src/App.tsx

@@ -28,6 +28,8 @@ import { DataInspector } from "@/components/DataInspector";
 import { BrickContextPanel } from "@/components/BrickContextPanel";
 import { LiveTrainPanel } from "@/components/LiveTrainPanel";
 import { useLiveTrainStream } from "@/hooks/useLiveTrainStream";
+import { useCompatibleEdges, makeIsValidConnection }
+  from "@/hooks/useCompatibleEdges";
 import { useVerifyStream, computeSpecHash } from "@/hooks/useVerifyStream";
 
 import { useRpc } from "@/hooks/useRpc";
@@ -197,6 +199,22 @@ export function App(): JSX.Element {
   // build_id change so a restart with new presets propagates to UI.
   const PRESETS = usePresets(rpc, backendBuildId);
 
+  // V7-E-AUDIT-02: compatible (src_kind, dst_kind) pairs from
+  // catalog.list_options('compatible_edges'). FlowCanvas consults the
+  // resulting predicate to reject incompatible drags client-side.
+  const compatibleEdgePairs = useCompatibleEdges(rpc);
+  const isValidConnection = useCallback(
+    makeIsValidConnection(
+      compatibleEdgePairs,
+      (nodeId: string) => {
+        const n = nodes.find((nn) => nn.id === nodeId);
+        const data = n?.data as { kind?: string } | undefined;
+        return data?.kind ?? null;
+      },
+    ),
+    [compatibleEdgePairs, nodes],
+  );
+
   // V7-F56b / V7-F53: editable dim_env (was a constant MINI_DIM_ENV).
   // Threaded into the verify trigger so changes to H/nh/head_dim
   // re-run verify and surface the F56b mismatch warning.
@@ -1215,6 +1233,7 @@ export function App(): JSX.Element {
                   onConnect={handleConnect}
                   onDropBrick={handleDropBrick}
                   onNodeClick={setSelectedBrickId}
+                  isValidConnection={isValidConnection}
                 />
               </div>
               {selectedBrickId && (() => {

vbgui/src/hooks/useCompatibleEdges.ts

@@ -0,0 +1,53 @@
+// V7-E-AUDIT-02: client-side cache of compatible (src_kind, dst_kind)
+// pairs fetched once from catalog.list_options('compatible_edges').
+// FlowCanvas's isValidConnection callback consults this set to reject
+// incompatible drags client-side (no server round-trip).
+
+import { useEffect, useState } from "react";
+import type { RpcClient } from "@/lib/rpc";
+
+export function useCompatibleEdges(rpc: RpcClient): Set<string> {
+  const [pairs, setPairs] = useState<Set<string>>(new Set());
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const r = await rpc.call<{
+          options: Array<{ name: string; summary: string;
+                            paper_ref: string }>
+        }>("catalog.list_options",
+            { category: "compatible_edges" });
+        if (cancelled) return;
+        const s = new Set<string>();
+        for (const opt of r.options) {
+          // name is "src->dst"; paper_ref=src, summary=dst.
+          s.add(`${opt.paper_ref}→${opt.summary}`);
+        }
+        setPairs(s);
+      } catch {
+        // Empty set => isValidConnection conservatively allows
+        // everything, falling back to server-side verify.
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [rpc]);
+
+  return pairs;
+}
+
+/** isValidConnection predicate built from a compatible-edges set.
+ *  Returns true when the set is empty (load-failure fallback) or when
+ *  the (src, dst) pair is in the set. */
+export function makeIsValidConnection(
+  pairs: Set<string>,
+  brickKindOf: (nodeId: string) => string | null,
+): (conn: { source: string | null; target: string | null }) => boolean {
+  return (conn) => {
+    if (pairs.size === 0) return true;        // server fallback
+    const src = conn.source ? brickKindOf(conn.source) : null;
+    const dst = conn.target ? brickKindOf(conn.target) : null;
+    if (!src || !dst) return false;
+    return pairs.has(`${src}→${dst}`);
+  };
+}

vbgui/tests/useCompatibleEdges.test.ts

@@ -0,0 +1,40 @@
+// E-AUDIT-02 vitest: isValidConnection predicate semantics.
+
+import { describe, expect, it } from "vitest";
+import { makeIsValidConnection } from "../src/hooks/useCompatibleEdges";
+
+
+describe("makeIsValidConnection", () => {
+  it("allows everything when pair set is empty (server fallback)", () => {
+    const isValid = makeIsValidConnection(
+      new Set(),
+      () => "mlp",
+    );
+    expect(isValid({ source: "n1", target: "n2" })).toBe(true);
+  });
+
+  it("rejects when pair is not in the compatible set", () => {
+    const isValid = makeIsValidConnection(
+      new Set(["attention→mlp"]),
+      (id) => (id === "src" ? "attention" : "tokenizer"),
+    );
+    expect(isValid({ source: "src", target: "dst" })).toBe(false);
+  });
+
+  it("accepts when pair is in the compatible set", () => {
+    const isValid = makeIsValidConnection(
+      new Set(["attention→mlp"]),
+      (id) => (id === "src" ? "attention" : "mlp"),
+    );
+    expect(isValid({ source: "src", target: "dst" })).toBe(true);
+  });
+
+  it("rejects when source or target is unknown", () => {
+    const isValid = makeIsValidConnection(
+      new Set(["attention→mlp"]),
+      () => null,
+    );
+    expect(isValid({ source: "x", target: "y" })).toBe(false);
+    expect(isValid({ source: null, target: "y" })).toBe(false);
+  });
+});