feat(vbgui-fa): JSON-RPC 2.0 contract + FastAPI server + LRU cache

Stage F-A of the Visual Builder GUI epic (cppmega-mlx-o0k). New
cppmega_v4.jsonrpc package exposes the backend stack
(VBSpec / MBSpec / PSpec / Probe) over a single JSON-RPC 2.0 wire
format per VisualBuilderPlan.md §5.

- schema.py: Pydantic v2 models for the wire format. JsonRpcRequest/
  Response/Error envelopes, all extra="forbid" for GUI-stable shape.
  Covers verify/suggest_sharding/suggest_adapters/build_preset_specs/
  probe.run params + results, pipeline.run skeleton, event taxonomy
  + method registry constants, ErrorCode reservations (-32700..-32099).
- cache.py: LRU(50) keyed on SHA-256 of canonical_json(payload) with
  layout fields (x/y/position) stripped before hashing — drag ops
  never bust the cache. Thread-safe via Lock; hits/misses tracked.
- methods.py: pure-Python handlers wrapping verify_and_estimate,
  suggest_sharding, suggest_adapters, build_preset_specs and
  contract_probe. Each handler accepts an optional cache and emits a
  Pydantic result model.
- dispatcher.py: transport-agnostic router. Folds ValidationError /
  ValueError / Exception into JSON-RPC error envelopes per VBPlan
  §5.3; never raises.
- server.py: FastAPI app with POST /rpc and WS /ws transports plus
  /health, /schema/methods, /cache/stats, /cache/clear. WS owns a
  1 Hz backend.status heartbeat task scoped to the connection.

Tests: 70 across 5 files (schema, cache, methods, dispatcher,
server) — Pydantic round-trips, LRU semantics, golden verify
result, sub-100ms latency, distributed-memory branch with sharding,
cache invariance to layout drift, HTTP + WebSocket transports.

Perf measured: verify cold 0.22ms / warm 0.025ms (target <100ms).

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

pyproject.toml: new optional-deps group "gui" pulls in pydantic /
fastapi / uvicorn / httpx / jsonschema.

Closes cppmega-mlx-o0k.1.

Author: apstenku123

cppmega_v4/jsonrpc/__init__.py

@@ -0,0 +1,63 @@
+"""JSON-RPC 2.0 contract + Python server for the Visual Builder GUI.
+
+See ``VisualBuilderPlan.md`` §3.3 and §5 for the design.
+
+Stage F-A surface (this commit):
+  - schema: Pydantic v2 models for all request/response payloads
+  - cache: LRU(50) keyed on canonical sha256(spec without layout)
+  - methods: pure-Python handlers (verify / suggest_sharding /
+    suggest_adapters / build_preset_specs / probe.run)
+  - dispatcher: transport-agnostic JSON-RPC 2.0 router
+  - server: FastAPI app exposing /rpc + /ws + heartbeat
+"""
+
+from __future__ import annotations
+
+from cppmega_v4.jsonrpc.cache import LRUCache, canonical_json, canonical_sha256
+from cppmega_v4.jsonrpc.dispatcher import dispatch
+from cppmega_v4.jsonrpc.schema import (
+    EVENT_TAXONOMY,
+    METHOD_REGISTRY,
+    SCHEMA_VERSION,
+    BuildPresetSpecsParams,
+    BuildPresetSpecsResult,
+    ErrorCode,
+    JsonRpcError,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    ProbeRunParams,
+    ProbeRunResult,
+    SuggestAdaptersParams,
+    SuggestAdaptersResult,
+    SuggestShardingParams,
+    SuggestShardingResult,
+    VerifyParams,
+    VerifyResult,
+)
+from cppmega_v4.jsonrpc.server import create_app, serve
+
+__all__ = [
+    "BuildPresetSpecsParams",
+    "BuildPresetSpecsResult",
+    "EVENT_TAXONOMY",
+    "ErrorCode",
+    "JsonRpcError",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    "LRUCache",
+    "METHOD_REGISTRY",
+    "ProbeRunParams",
+    "ProbeRunResult",
+    "SCHEMA_VERSION",
+    "SuggestAdaptersParams",
+    "SuggestAdaptersResult",
+    "SuggestShardingParams",
+    "SuggestShardingResult",
+    "VerifyParams",
+    "VerifyResult",
+    "canonical_json",
+    "canonical_sha256",
+    "create_app",
+    "dispatch",
+    "serve",
+]

cppmega_v4/jsonrpc/dispatcher.py

@@ -0,0 +1,158 @@
+"""Transport-agnostic JSON-RPC 2.0 dispatcher.
+
+One :func:`dispatch` entry point handles both the HTTP and WebSocket
+transports. Validates the envelope, routes the method, coerces params
+through the matching Pydantic model, calls the handler, packs the
+result back into a JsonRpcResponse, and folds exceptions into the
+error envelope per VBPlan §5.3.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Mapping
+
+from pydantic import BaseModel, ValidationError
+
+from cppmega_v4.jsonrpc.cache import LRUCache
+from cppmega_v4.jsonrpc.methods import (
+    build_preset_specs,
+    probe_run,
+    suggest_adapters,
+    suggest_sharding,
+    verify,
+)
+from cppmega_v4.jsonrpc.schema import (
+    BuildPresetSpecsParams,
+    ErrorCode,
+    JsonRpcError,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    ProbeRunParams,
+    SuggestAdaptersParams,
+    SuggestShardingParams,
+    VerifyParams,
+)
+
+_log = logging.getLogger(__name__)
+
+
+_Handler = Callable[[BaseModel, LRUCache | None], BaseModel]
+
+
+_ROUTES: Mapping[str, tuple[type[BaseModel], _Handler]] = {
+    "verify": (
+        VerifyParams,
+        lambda p, c: verify(p, cache=c),
+    ),
+    "suggest_sharding": (
+        SuggestShardingParams,
+        lambda p, c: suggest_sharding(p, cache=c),
+    ),
+    "suggest_adapters": (
+        SuggestAdaptersParams,
+        lambda p, c: suggest_adapters(p, cache=c),
+    ),
+    "build_preset_specs": (
+        BuildPresetSpecsParams,
+        lambda p, c: build_preset_specs(p, cache=c),
+    ),
+    "probe.run": (
+        ProbeRunParams,
+        lambda p, c: probe_run(p, cache=c),
+    ),
+}
+
+
+def dispatch(
+    payload: Mapping[str, Any] | JsonRpcRequest,
+    *,
+    cache: LRUCache | None = None,
+) -> JsonRpcResponse:
+    """Route one JSON-RPC envelope to its handler.
+
+    Never raises; all errors are folded into ``JsonRpcResponse.error``.
+    """
+    try:
+        request = (
+            payload if isinstance(payload, JsonRpcRequest)
+            else JsonRpcRequest.model_validate(payload)
+        )
+    except ValidationError as exc:
+        return _error_response(
+            request_id=_safe_id(payload),
+            code=ErrorCode.INVALID_REQUEST,
+            message="Invalid JSON-RPC envelope",
+            data={"errors": exc.errors()},
+        )
+    except Exception as exc:
+        return _error_response(
+            request_id=_safe_id(payload),
+            code=ErrorCode.PARSE_ERROR,
+            message="Parse error",
+            data={"type": type(exc).__name__, "detail": str(exc)},
+        )
+
+    if request.method == "backend.status":
+        return JsonRpcResponse(id=request.id, result={"status": "ok"})
+
+    route = _ROUTES.get(request.method)
+    if route is None:
+        return _error_response(
+            request_id=request.id,
+            code=ErrorCode.METHOD_NOT_FOUND,
+            message=f"Method {request.method!r} not found",
+            data={"available": sorted(_ROUTES)},
+        )
+
+    params_model, handler = route
+    try:
+        params = params_model.model_validate(request.params)
+    except ValidationError as exc:
+        return _error_response(
+            request_id=request.id,
+            code=ErrorCode.INVALID_PARAMS,
+            message="Invalid params",
+            data={"type": "ValidationError", "errors": exc.errors()},
+        )
+
+    try:
+        result = handler(params, cache)
+    except ValueError as exc:
+        return _error_response(
+            request_id=request.id,
+            code=ErrorCode.INVALID_PARAMS,
+            message="Invalid params",
+            data={"type": type(exc).__name__, "detail": str(exc)},
+        )
+    except Exception as exc:
+        _log.exception("dispatch handler %s raised", request.method)
+        return _error_response(
+            request_id=request.id,
+            code=ErrorCode.INTERNAL_ERROR,
+            message="Internal error",
+            data={"type": type(exc).__name__, "detail": str(exc)},
+        )
+
+    return JsonRpcResponse(id=request.id, result=result.model_dump(mode="json"))
+
+
+def _safe_id(payload: Any) -> str | int | None:
+    try:
+        if isinstance(payload, Mapping):
+            v = payload.get("id")
+            if isinstance(v, (str, int)):
+                return v
+    except Exception:
+        pass
+    return None
+
+
+def _error_response(
+    *, request_id: str | int | None, code: int, message: str,
+    data: Mapping[str, Any] | None = None,
+) -> JsonRpcResponse:
+    return JsonRpcResponse(
+        id=request_id,
+        error=JsonRpcError(code=code, message=message, data=dict(data) if data else None),
+    )

cppmega_v4/jsonrpc/methods.py

@@ -32,10 +32,29 @@
     AxisAssignment,
     ParallelismKind,
     ShardingSpec,
-    TOPOLOGY_BUILTINS,
+    a100_8x,
+    b100_8x,
+    gb10_quarter,
+    h100_8x,
+    h200_8x,
+    m3_ultra_solo,
     suggest_sharding as _suggest_sharding,
+    tpu_v5p_4,
+    tpu_v6e_8,
     verify_distributed_plan,
 )
+
+
+_TOPOLOGY_FACTORIES = {
+    "h100_8x": h100_8x,
+    "h200_8x": h200_8x,
+    "a100_8x": a100_8x,
+    "b100_8x": b100_8x,
+    "gb10_quarter": gb10_quarter,
+    "tpu_v5p_4": tpu_v5p_4,
+    "tpu_v6e_8": tpu_v6e_8,
+    "m3_ultra_solo": m3_ultra_solo,
+}
 from cppmega_v4.probe import contract_probe as _contract_probe
 from cppmega_v4.probe import to_dict as _probe_to_dict
 from cppmega_v4.spec import (
@@ -117,11 +136,11 @@ def _make_optim(payload: OptimSpecPayload) -> OptimSpec:
 
 
 def _make_topology(payload: TopologyPayload):
-    factory = TOPOLOGY_BUILTINS.get(payload.factory)
+    factory = _TOPOLOGY_FACTORIES.get(payload.factory)
     if factory is None:
         raise ValueError(
             f"unknown topology factory {payload.factory!r}; "
-            f"available: {sorted(TOPOLOGY_BUILTINS)}"
+            f"available: {sorted(_TOPOLOGY_FACTORIES)}"
         )
     return factory(**payload.kwargs)
 
@@ -249,9 +268,11 @@ def verify(params: VerifyParams, *, cache: LRUCache | None = None) -> VerifyResu
         )
         gotcha_payloads = [
             GotchaPayload(
-                id=g.id, severity=g.severity.value if hasattr(g.severity, "value")
-                                                  else str(g.severity),
-                message=g.message, reference=getattr(g, "reference", None),
+                id=g.gotcha_id,
+                severity=g.severity.value if hasattr(g.severity, "value")
+                                          else str(g.severity),
+                message=g.message,
+                reference=getattr(g, "reference", None),
             )
             for g in dverify.gotchas
         ]