feat(v7-c03): ckpt.inspect RPC + TopBar metadata display on Load

UI honest-closure gap: ckpt metadata writer existed (stages.py:2020,
write_ckpt_metadata) and reader existed (read_ckpt_metadata:2083),
but the UI Load flow had no surface that exposed arch_hash / opt_kind
/ cppmega_version before the user committed to a warm-start.

- cppmega_v4/jsonrpc/ckpt_inspect_method.py: thin Pydantic-typed
  wrapper around read_ckpt_metadata. Returns {exists, has_metadata,
  cppmega_version, arch_hash, opt_kind, opt_lr, global_step, raw}.
- dispatcher.py + schema.py: registers 'ckpt.inspect' in _ROUTES
  and METHOD_REGISTRY.
- TopBar: 300ms-debounced inspect on ckpt-load-path change, renders
  arch_hash (truncated 12+…), opt_kind+lr, global_step, version.
  Surfaces 'file not found' / 'no cppmega metadata' branches too.
- App.tsx: passes onInspectCheckpoint callback wrapping rpc.call.
- tests/v4/test_ckpt_inspect_method.py: round-trip via FastAPI
  TestClient — missing-file, no-metadata, full-metadata.
- e2e 81: visual assertion — type path → block shows arch / opt /
  step / version testids without question-mark fallback values.

Author: apstenku123

cppmega_v4/jsonrpc/ckpt_inspect_method.py

@@ -0,0 +1,74 @@
+"""V7-C03 honest-closure: ckpt.inspect RPC.
+
+Reads safetensors metadata at the given path and returns the parsed
+arch / train / opt sub-objects so the UI can render arch_hash,
+opt_kind, cppmega_version on Load before the user commits to the
+warm-start path. Pairs with stages.write_ckpt_metadata + read_ckpt_metadata
+(stages.py:2020-2099) so the round-trip stays in one place.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cppmega_v4.jsonrpc.cache import LRUCache
+
+
+class CkptInspectParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+
+
+class CkptInspectResult(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    exists: bool
+    has_metadata: bool = False
+    cppmega_version: str | None = None
+    arch_hash: str | None = None
+    opt_kind: str | None = None
+    opt_lr: float | None = None
+    global_step: int | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+
+
+def ckpt_inspect(
+    params: CkptInspectParams, *, cache: LRUCache | None = None,
+) -> CkptInspectResult:
+    p = Path(params.path)
+    if not p.exists():
+        return CkptInspectResult(exists=False)
+
+    from cppmega_v4.runner.stages import read_ckpt_metadata
+
+    try:
+        meta = read_ckpt_metadata(str(p))
+    except Exception as exc:
+        return CkptInspectResult(
+            exists=True, has_metadata=False, error=str(exc),
+        )
+    if meta is None:
+        return CkptInspectResult(exists=True, has_metadata=False)
+
+    arch = meta.get("arch") if isinstance(meta.get("arch"), dict) else {}
+    train = meta.get("train") if isinstance(meta.get("train"), dict) else {}
+    opt = meta.get("opt") if isinstance(meta.get("opt"), dict) else {}
+
+    return CkptInspectResult(
+        exists=True,
+        has_metadata=True,
+        cppmega_version=meta.get("cppmega_version"),
+        arch_hash=arch.get("config_hash"),
+        opt_kind=opt.get("kind"),
+        opt_lr=opt.get("lr"),
+        global_step=train.get("global_step"),
+        raw=meta,
+    )
+
+
+__all__ = ["CkptInspectParams", "CkptInspectResult", "ckpt_inspect"]

cppmega_v4/jsonrpc/dispatcher.py

@@ -42,6 +42,9 @@
 from cppmega_v4.jsonrpc.ablation_method import (
     AblationRunParams, ablation_run,
 )
+from cppmega_v4.jsonrpc.ckpt_inspect_method import (
+    CkptInspectParams, ckpt_inspect,
+)
 from cppmega_v4.jsonrpc.schema import (
     BuildPresetSpecsParams,
     CatalogExplainParams,
@@ -124,6 +127,10 @@
         AblationRunParams,
         lambda p, c: ablation_run(p, cache=c),
     ),
+    "ckpt.inspect": (
+        CkptInspectParams,
+        lambda p, c: ckpt_inspect(p, cache=c),
+    ),
 }
 
 

cppmega_v4/jsonrpc/schema.py

@@ -749,6 +749,7 @@ class PipelineRunResult(BaseModel):
     "suggest_optim_groups",
     "data.roundtrip_check",
     "ablation.run",
+    "ckpt.inspect",
 })
 
 

tests/v4/test_ckpt_inspect_method.py

@@ -0,0 +1,93 @@
+"""V7-C03: ckpt.inspect RPC round-trip.
+
+Writes a tiny safetensors checkpoint with the cppmega metadata schema
+produced by stages.write_ckpt_metadata, hits POST /rpc with ckpt.inspect,
+and asserts the parsed sub-objects come back wired so the UI can render
+arch_hash / opt_kind / version on Load.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import mlx.core as mx
+import pytest
+from fastapi.testclient import TestClient
+from safetensors.numpy import save_file as save_safetensors
+
+from cppmega_v4.jsonrpc import create_app
+
+
+@pytest.fixture
+def client():
+    return TestClient(create_app(cache_capacity=2))
+
+
+def _write_ckpt(path: Path, *, version: str = "v1",
+                arch_hash: str = "deadbeef" * 8,
+                opt_kind: str = "adamw", lr: float = 3e-4,
+                step: int = 17) -> None:
+    metadata = {
+        "cppmega_version": version,
+        "arch": json.dumps(
+            {"config_hash": arch_hash, "config_json": {}}, sort_keys=True),
+        "train": json.dumps({"global_step": step}, sort_keys=True),
+        "opt": json.dumps({"kind": opt_kind, "lr": lr}, sort_keys=True),
+    }
+    # Smallest possible payload — one scalar weight.
+    import numpy as np
+    save_safetensors({"w": np.zeros((1,), dtype=np.float32)},
+                     str(path), metadata=metadata)
+
+
+def test_ckpt_inspect_missing_file(client, tmp_path):
+    payload = {
+        "jsonrpc": "2.0", "id": "m1", "method": "ckpt.inspect",
+        "params": {"path": str(tmp_path / "nope.safetensors")},
+    }
+    r = client.post("/rpc", json=payload)
+    assert r.status_code == 200
+    body = r.json()
+    assert body["result"]["exists"] is False
+
+
+def test_ckpt_inspect_no_metadata(client, tmp_path):
+    import numpy as np
+    p = tmp_path / "bare.safetensors"
+    save_safetensors({"w": np.zeros((1,), dtype=np.float32)}, str(p))
+    payload = {
+        "jsonrpc": "2.0", "id": "m2", "method": "ckpt.inspect",
+        "params": {"path": str(p)},
+    }
+    r = client.post("/rpc", json=payload)
+    assert r.status_code == 200
+    body = r.json()
+    assert body["result"]["exists"] is True
+    assert body["result"]["has_metadata"] is False
+
+
+def test_ckpt_inspect_round_trip(client, tmp_path):
+    p = tmp_path / "ckpt.safetensors"
+    _write_ckpt(p, opt_kind="muon_adamw_hybrid", lr=1e-3, step=42)
+
+    payload = {
+        "jsonrpc": "2.0", "id": "m3", "method": "ckpt.inspect",
+        "params": {"path": str(p)},
+    }
+    r = client.post("/rpc", json=payload)
+    assert r.status_code == 200
+    res = r.json()["result"]
+    assert res["exists"] is True
+    assert res["has_metadata"] is True
+    assert res["opt_kind"] == "muon_adamw_hybrid"
+    assert res["opt_lr"] == pytest.approx(1e-3)
+    assert res["global_step"] == 42
+    # arch_hash must be the 64-char sha256 we wrote.
+    assert isinstance(res["arch_hash"], str)
+    assert len(res["arch_hash"]) == 64
+
+
+# Silence the unused mlx warning — keep the import so future tests on
+# the same module can use mlx-backed safetensors without re-importing.
+_ = mx

vbgui/e2e/scenarios/81_ckpt_inspect.spec.ts

@@ -0,0 +1,74 @@
+// V7-C03: ckpt.inspect RPC + TopBar metadata display on Load.
+// Scenario: run a Train with checkpoint_save_path, then a second
+// Train with checkpoint_load_path pointing at the same file —
+// before clicking Train, the TopBar must render arch_hash /
+// opt_kind / version parsed out of the just-written metadata.
+
+import { test, expect } from "@playwright/test";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { gotoApp, selectPreset, closeModal } from "../fixtures";
+
+function tmpCkptPath(): string {
+  const tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "v7c03-"));
+  return path.join(tmpdir, "ckpt.safetensors");
+}
+
+test("V7-C03: ckpt.inspect renders arch_hash + opt_kind + version on Load",
+  async ({ page }) => {
+    test.setTimeout(90_000);
+    const ckptPath = tmpCkptPath();
+    await gotoApp(page);
+    await selectPreset(page, "llama3_8b");
+
+    // Wave 1: train + save.
+    await page.getByTestId("run-pipeline-toggle").click();
+    await page.getByTestId("train-num-steps").fill("2");
+    await page.getByTestId("train-checkpoint-save-path").fill(ckptPath);
+    await page.getByTestId("run-pipeline-train").click();
+    await page.getByTestId("run-result-modal").waitFor({ timeout: 60_000 });
+    await closeModal(page);
+
+    // Wave 2: type the same path into ckpt-load. The TopBar's
+    // debounced effect must fire ckpt.inspect and surface metadata.
+    await page.getByTestId("run-pipeline-toggle").click();
+    await page.getByTestId("train-checkpoint-load-path").fill(ckptPath);
+
+    // Wait for inspect block.
+    await expect(page.getByTestId("ckpt-inspect-info"))
+      .toBeVisible({ timeout: 5_000 });
+
+    const archHashEl = page.getByTestId("ckpt-inspect-arch-hash");
+    await expect(archHashEl).toBeVisible();
+    const archHashText = await archHashEl.textContent();
+    // truncated to 12 chars + ellipsis, but must start with "arch: "
+    expect(archHashText).toMatch(/^arch: [0-9a-f]{12}…$/);
+
+    const optKindEl = page.getByTestId("ckpt-inspect-opt-kind");
+    const optKindText = await optKindEl.textContent();
+    expect(optKindText).toContain("opt: ");
+    expect(optKindText).not.toContain("opt: ?");
+
+    const stepEl = page.getByTestId("ckpt-inspect-step");
+    const stepText = await stepEl.textContent();
+    expect(stepText).not.toContain("step: ?");
+
+    const versionEl = page.getByTestId("ckpt-inspect-version");
+    const versionText = await versionEl.textContent();
+    expect(versionText).not.toContain("v: ?");
+  });
+
+test("V7-C03: ckpt.inspect renders 'file not found' for missing path",
+  async ({ page }) => {
+    test.setTimeout(30_000);
+    await gotoApp(page);
+    await selectPreset(page, "llama3_8b");
+
+    await page.getByTestId("run-pipeline-toggle").click();
+    await page.getByTestId("train-checkpoint-load-path")
+      .fill("/tmp/definitely_does_not_exist_v7c03.safetensors");
+
+    await expect(page.getByTestId("ckpt-inspect-missing"))
+      .toBeVisible({ timeout: 5_000 });
+  });

vbgui/src/App.tsx

@@ -592,6 +592,21 @@ export function App(): JSX.Element {
             };
             reader.readAsText(file);
           }}
+          onInspectCheckpoint={async (path: string) => {
+            // V7-C03: thin pass-through to ckpt.inspect RPC. Errors
+            // surface as the TopBar's "no cppmega metadata" / error
+            // branch — they should not blow up the surrounding menu.
+            return rpc.call<{
+              exists: boolean;
+              has_metadata?: boolean;
+              cppmega_version?: string | null;
+              arch_hash?: string | null;
+              opt_kind?: string | null;
+              opt_lr?: number | null;
+              global_step?: number | null;
+              error?: string | null;
+            }>("ckpt.inspect", { path });
+          }}
           trainDisabled={
             (() => {
               // V3-8/V3-9: gate Train on gotcha severity. The verify RPC