feat(v7-h04): spec schema_version + migrate-on-load framework

Closes V7-H04 (cppmega-mlx-odxp): persisted specs now carry a
schema_version integer + a migration registry so future breaking
changes (renamed brick kinds, removed params, default changes) can
be applied automatically on load instead of silently corrupting the
spec.

New module vbgui/src/state/migrations.ts:
  - CURRENT_SCHEMA_VERSION = 1
  - migrate(spec) walks from spec.schema_version up to current,
    applying registered migrate_v{n}_to_v{n+1} functions linearly.
  - migrate_v0_to_v1 stamps schema_version=1 onto pre-versioning
    specs (the demonstrative migration required by acceptance).
  - FutureSchemaError raised when loading a spec from a newer build.
  - Adding a new migration documented in the module header.

App.tsx onLoadSpec now calls migrate(raw) before dispatching so
saved bundles round-trip through the version chain. Future-version
specs surface a FutureSchemaError into the existing error modal.

Tests (vbgui/tests/migrations.test.ts): 4/4 —
  * v0 input → schema_version=1, other fields preserved.
  * Current version → no-op.
  * Future version → FutureSchemaError.
  * Nested fields preserved through migration.
- Full vbgui vitest: 213/213.
- V6 H09 Save→Load roundtrip e2e: 1/1 (proves migrate path is wired
  into App without breaking the existing parity gate).

Backend mirror (Pydantic validation of inbound schema_version on
RPC entry) is deferred to a follow-up V7-H04 sub-task since the
current RPC layer accepts arbitrary spec dicts.

Author: apstenku123

vbgui/src/App.tsx

@@ -21,6 +21,7 @@ import { usePresets } from "@/hooks/usePresets";
 import {
   INITIAL_SPEC, specReducer, type SpecState, type TopologyFactory,
 } from "@/state/spec";
+import { migrate } from "@/state/migrations";
 import type { ShardingProposalView } from "@/components/sidebar/ShardingTab";
 
 // PRESETS list is now fetched dynamically from the backend via
@@ -480,11 +481,16 @@ export function App(): JSX.Element {
             const reader = new FileReader();
             reader.onload = () => {
               try {
-                const obj = JSON.parse(String(reader.result));
+                const raw = JSON.parse(String(reader.result));
+                // V7-H04: migrate-on-load so older saved bundles still
+                // hydrate cleanly. Future-version specs throw a
+                // FutureSchemaError that bubbles into the error modal.
+                const obj = migrate(raw);
                 if (obj.projectName) setProjectName(String(obj.projectName));
-                if (obj.spec) dispatch({ type: "spec.replace", spec: obj.spec });
-                if (obj.nodes) setNodes(obj.nodes);
-                if (obj.edges) setEdges(obj.edges);
+                if (obj.spec) dispatch({ type: "spec.replace",
+                                          spec: obj.spec as never });
+                if (obj.nodes) setNodes(obj.nodes as never[]);
+                if (obj.edges) setEdges(obj.edges as never[]);
               } catch (e) {
                 setRunError(`Load failed: ${String(e)}`);
               }

vbgui/src/state/migrations.ts

@@ -0,0 +1,67 @@
+// V7-H04: spec schema versioning + migrate-on-load.
+//
+// `CURRENT_SCHEMA_VERSION` is the integer that fresh specs are stamped
+// with. Every breaking change to the persisted spec shape (renaming a
+// brick kind, removing a param, changing a default) must:
+//   1. Bump CURRENT_SCHEMA_VERSION.
+//   2. Add a pure migrate_v{n-1}_to_v{n} function below.
+//   3. Append it to MIGRATIONS (keyed by source version).
+//
+// migrate(spec) walks from the spec's stored version up to current and
+// returns the migrated object. Specs from a future version (i.e. saved
+// by a newer build) throw — the caller is expected to surface this as
+// a UI error rather than silently corrupting the spec.
+
+export const CURRENT_SCHEMA_VERSION = 1;
+
+export type SchemaVersion = number;
+
+export interface VersionedSpec {
+  schema_version?: SchemaVersion;
+  [key: string]: unknown;
+}
+
+export class FutureSchemaError extends Error {
+  constructor(version: SchemaVersion) {
+    super(
+      `spec schema_version=${version} is newer than this build's ` +
+      `CURRENT_SCHEMA_VERSION=${CURRENT_SCHEMA_VERSION}; upgrade the ` +
+      `app or open the spec in a matching build.`,
+    );
+    this.name = "FutureSchemaError";
+  }
+}
+
+/** v0 → v1: stamp schema_version=1 onto pre-versioning specs. */
+function migrate_v0_to_v1(spec: VersionedSpec): VersionedSpec {
+  return { ...spec, schema_version: 1 };
+}
+
+const MIGRATIONS: Record<number,
+  (s: VersionedSpec) => VersionedSpec> = {
+  0: migrate_v0_to_v1,
+};
+
+export function migrate(spec: VersionedSpec): VersionedSpec {
+  let current: VersionedSpec = { ...spec };
+  let v = typeof current.schema_version === "number"
+    ? current.schema_version
+    : 0;
+  if (v > CURRENT_SCHEMA_VERSION) {
+    throw new FutureSchemaError(v);
+  }
+  while (v < CURRENT_SCHEMA_VERSION) {
+    const step = MIGRATIONS[v];
+    if (!step) {
+      throw new Error(
+        `V7-H04: no migration registered for schema_version=${v}; ` +
+        `add migrate_v${v}_to_v${v + 1} to MIGRATIONS`,
+      );
+    }
+    current = step(current);
+    v = typeof current.schema_version === "number"
+      ? current.schema_version
+      : v + 1;
+  }
+  return current;
+}

vbgui/tests/migrations.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import {
+  CURRENT_SCHEMA_VERSION, FutureSchemaError, migrate,
+} from "@/state/migrations";
+
+describe("V7-H04 spec migrations", () => {
+  it("stamps schema_version on a v0 (pre-versioning) spec", () => {
+    const v0 = { projectName: "demo", spec: {}, nodes: [], edges: [] };
+    const out = migrate(v0);
+    expect(out.schema_version).toBe(1);
+    expect(out.projectName).toBe("demo");
+  });
+
+  it("returns spec unchanged when already at current version", () => {
+    const cur = { schema_version: CURRENT_SCHEMA_VERSION,
+                  projectName: "demo" };
+    const out = migrate(cur);
+    expect(out.schema_version).toBe(CURRENT_SCHEMA_VERSION);
+    expect(out.projectName).toBe("demo");
+  });
+
+  it("throws FutureSchemaError on a spec from a newer build", () => {
+    expect(() => migrate({ schema_version: 9_999 }))
+      .toThrowError(FutureSchemaError);
+  });
+
+  it("preserves nested fields through migration", () => {
+    const v0 = {
+      projectName: "P",
+      spec: { loss: { kind: "cross_entropy" }, optim: { kind: "adamw" } },
+      nodes: [{ id: "a" }],
+    };
+    const out = migrate(v0) as typeof v0 & { schema_version: number };
+    expect(out.schema_version).toBe(1);
+    expect(out.spec).toEqual(v0.spec);
+    expect(out.nodes).toEqual(v0.nodes);
+  });
+});