From 36e161f9f94eb828d531411dde7cb87e36e98019 Mon Sep 17 00:00:00 2001
From: Cam Pedersen <cam@campedersen.com>
Date: Sat, 11 Jul 2026 13:00:03 -0400
Subject: [PATCH 1/3] Persist predict_physics claims: physics_specs + receipt
 re-verification

Mirror the clearance-claim persistence loop for static-physics assertions:

- vcad-ir: PhysicsSpec (label, part/domain_box, loads, supports, material
  props, limits, fidelity) + Document.physics_specs, ts-rs exported
- predict_physics gains `label`: upserts the spec on the document (part
  persisted by resolved root id); requires document_id + at least one limit
- physicsReceiptClaims re-solves each spec at its stored fidelity and emits
  physics.static.<label>.{displacement,stress} claims with basis
  predicted/verified and a re-runnable StoredPhysicsClaim in details
- verifyPhysicsClaims re-solves and classifies Holds/Stale/Violated;
  fail-closed: unresolvable part, non-converged solve, or missing payload
  is Violated (unverifiable at build time), never a silent pass
- build_receipt/verify_receipt wired; verify_receipt tool handler now
  passes the engine (clearance re-verification via the live tool needed it
  too)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../2026-07-11-physics-spec-persistence.json  |  10 +
 crates/vcad-ir/src/lib.rs                     | 103 +++++
 packages/ir/src/generated.ts                  | 108 ++++-
 .../mcp/src/__tests__/physics-claims.test.ts  | 270 +++++++++++
 .../src/__tests__/tool-surface.fixture.json   |  12 +-
 packages/mcp/src/tools/ecad.ts                |  53 ++-
 packages/mcp/src/tools/physics.ts             | 428 ++++++++++++++++--
 scripts/gen-ir-types.mjs                      |   2 +-
 8 files changed, 921 insertions(+), 65 deletions(-)
 create mode 100644 changelog/entries/2026-07-11-physics-spec-persistence.json
 create mode 100644 packages/mcp/src/__tests__/physics-claims.test.ts

diff --git a/changelog/entries/2026-07-11-physics-spec-persistence.json b/changelog/entries/2026-07-11-physics-spec-persistence.json
new file mode 100644
index 000000000..0269d236e
--- /dev/null
+++ b/changelog/entries/2026-07-11-physics-spec-persistence.json
@@ -0,0 +1,10 @@
+{
+  "id": "2026-07-11-physics-spec-persistence",
+  "version": "0.9.4",
+  "date": "2026-07-11",
+  "category": "feat",
+  "title": "Persisted physics assertions re-verify via receipts",
+  "summary": "predict_physics gains a label arg: the spec persists on the document, build_receipt re-solves it as physics.static claims, and verify_receipt classifies Holds/Stale/Violated.",
+  "features": ["physics", "receipt", "verification"],
+  "mcpTools": ["predict_physics", "build_receipt", "verify_receipt"]
+}
diff --git a/crates/vcad-ir/src/lib.rs b/crates/vcad-ir/src/lib.rs
index 603666d59..282f12a49 100644
--- a/crates/vcad-ir/src/lib.rs
+++ b/crates/vcad-ir/src/lib.rs
@@ -1807,6 +1807,10 @@ pub struct Document {
     /// `check_clearance` and receipt verification whenever geometry changes.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub clearance_specs: Vec<ClearanceSpec>,
+    /// Named static-physics assertions (loads, supports, limits), re-solved by
+    /// `predict_physics` and receipt verification whenever geometry changes.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub physics_specs: Vec<PhysicsSpec>,
 }
 
 /// A named minimum-clearance assertion between two groups of parts.
@@ -1829,6 +1833,104 @@ pub struct ClearanceSpec {
     pub min_mm: f64,
 }
 
+/// Axis-aligned box region (mm, world frame, Z-up) selecting FEA grid nodes.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS))]
+#[cfg_attr(feature = "ts-rs", ts(export, export_to = "bindings/"))]
+pub struct PhysicsRegion {
+    /// Minimum corner `[x, y, z]` in mm.
+    pub min: [f64; 3],
+    /// Maximum corner `[x, y, z]` in mm.
+    pub max: [f64; 3],
+}
+
+/// A load for static analysis: total force spread over a box region.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS))]
+#[cfg_attr(feature = "ts-rs", ts(export, export_to = "bindings/"))]
+pub struct PhysicsLoad {
+    /// Region the force is distributed over.
+    pub region: PhysicsRegion,
+    /// Total force vector `[fx, fy, fz]` in N.
+    pub force: [f64; 3],
+}
+
+/// A fixed (anchored) region for static analysis.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS))]
+#[cfg_attr(feature = "ts-rs", ts(export, export_to = "bindings/"))]
+pub struct PhysicsSupport {
+    /// Region whose grid nodes are anchored.
+    pub region: PhysicsRegion,
+    /// Which translations are fixed `[x, y, z]`; absent means all fixed.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub fix: Option<[bool; 3]>,
+}
+
+/// Solve tier for a persisted physics spec: which resolution the assertion is
+/// re-verified at, and which claim basis the resulting claims carry
+/// (`predict` → predicted/provisional, `verify` → verified).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS))]
+#[cfg_attr(feature = "ts-rs", ts(export, export_to = "bindings/"))]
+pub enum PhysicsFidelity {
+    /// Coarse fast solve; claims stamped `basis: predicted`.
+    Predict,
+    /// Fine solve, same oracle; claims stamped `basis: verified`.
+    Verify,
+}
+
+/// A named static-structural assertion (voxel FEA) persisted on the document.
+///
+/// Stores everything needed to re-run the solve — loads, supports, material
+/// properties, limits, and fidelity — so `build_receipt` re-emits it as
+/// `physics.static.<label>.*` claims and `verify_receipt` re-solves and
+/// classifies it Holds / Stale / Violated as geometry changes.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS))]
+#[cfg_attr(feature = "ts-rs", ts(export, export_to = "bindings/"))]
+pub struct PhysicsSpec {
+    /// Unique human-readable name, e.g. "bracket-load".
+    pub label: String,
+    /// Part id (stringified root node id) whose evaluated volume is analyzed.
+    /// Mutually exclusive with `domain_box`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub part: Option<String>,
+    /// Analyze a solid box instead of a part. Mutually exclusive with `part`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub domain_box: Option<PhysicsRegion>,
+    /// Applied loads.
+    pub loads: Vec<PhysicsLoad>,
+    /// Fixed supports.
+    pub supports: Vec<PhysicsSupport>,
+    /// Young's modulus in MPa; absent means the kernel default (6061 Al).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub youngs_modulus_mpa: Option<f64>,
+    /// Poisson's ratio; absent means the kernel default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub poisson: Option<f64>,
+    /// Voxels along the longest axis; absent means the fidelity-tier default.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub resolution: Option<u32>,
+    /// Solve tier the assertion is (re-)verified at.
+    pub fidelity: PhysicsFidelity,
+    /// Optional limit: max displacement ≤ this, in mm.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub max_displacement_mm: Option<f64>,
+    /// Optional limit: max von Mises stress ≤ this, in MPa.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "ts-rs", ts(optional))]
+    pub max_von_mises_mpa: Option<f64>,
+}
+
 impl Default for Document {
     fn default() -> Self {
         Self {
@@ -1848,6 +1950,7 @@ impl Default for Document {
             parameters: HashMap::new(),
             bindings: Bindings::new(),
             clearance_specs: Vec::new(),
+            physics_specs: Vec::new(),
         }
     }
 }
diff --git a/packages/ir/src/generated.ts b/packages/ir/src/generated.ts
index b7243cef0..934757bf2 100644
--- a/packages/ir/src/generated.ts
+++ b/packages/ir/src/generated.ts
@@ -1035,7 +1035,12 @@ bindings?: Bindings,
  * Named clearance/clash assertions between part groups, re-measured by
  * `check_clearance` and receipt verification whenever geometry changes.
  */
-clearance_specs?: Array<ClearanceSpec>, };
+clearance_specs?: Array<ClearanceSpec>, 
+/**
+ * Named static-physics assertions (loads, supports, limits), re-solved by
+ * `predict_physics` and receipt verification whenever geometry changes.
+ */
+physics_specs?: Array<PhysicsSpec>, };
 
 /**
  * A canonicalized DRC summary: total, per-rule counts (sorted), and the
@@ -2213,6 +2218,107 @@ netTies?: Array<NetTie>, };
  */
 export type PcbLayer = "FCu" | "BCu" | "In1Cu" | "In2Cu" | "In3Cu" | "In4Cu" | "In5Cu" | "In6Cu" | "FSilkS" | "BSilkS" | "FMask" | "BMask" | "FPaste" | "BPaste" | "FFab" | "BFab" | "FCrtYd" | "BCrtYd" | "EdgeCuts" | "UserDrawings" | "UserComments";
 
+/**
+ * Solve tier for a persisted physics spec: which resolution the assertion is
+ * re-verified at, and which claim basis the resulting claims carry
+ * (`predict` → predicted/provisional, `verify` → verified).
+ */
+export type PhysicsFidelity = "predict" | "verify";
+
+/**
+ * A load for static analysis: total force spread over a box region.
+ */
+export type PhysicsLoad = { 
+/**
+ * Region the force is distributed over.
+ */
+region: PhysicsRegion, 
+/**
+ * Total force vector `[fx, fy, fz]` in N.
+ */
+force: [number, number, number], };
+
+/**
+ * Axis-aligned box region (mm, world frame, Z-up) selecting FEA grid nodes.
+ */
+export type PhysicsRegion = { 
+/**
+ * Minimum corner `[x, y, z]` in mm.
+ */
+min: [number, number, number], 
+/**
+ * Maximum corner `[x, y, z]` in mm.
+ */
+max: [number, number, number], };
+
+/**
+ * A named static-structural assertion (voxel FEA) persisted on the document.
+ *
+ * Stores everything needed to re-run the solve — loads, supports, material
+ * properties, limits, and fidelity — so `build_receipt` re-emits it as
+ * `physics.static.<label>.*` claims and `verify_receipt` re-solves and
+ * classifies it Holds / Stale / Violated as geometry changes.
+ */
+export type PhysicsSpec = { 
+/**
+ * Unique human-readable name, e.g. "bracket-load".
+ */
+label: string, 
+/**
+ * Part id (stringified root node id) whose evaluated volume is analyzed.
+ * Mutually exclusive with `domain_box`.
+ */
+part?: string, 
+/**
+ * Analyze a solid box instead of a part. Mutually exclusive with `part`.
+ */
+domain_box?: PhysicsRegion, 
+/**
+ * Applied loads.
+ */
+loads: Array<PhysicsLoad>, 
+/**
+ * Fixed supports.
+ */
+supports: Array<PhysicsSupport>, 
+/**
+ * Young's modulus in MPa; absent means the kernel default (6061 Al).
+ */
+youngs_modulus_mpa?: number, 
+/**
+ * Poisson's ratio; absent means the kernel default.
+ */
+poisson?: number, 
+/**
+ * Voxels along the longest axis; absent means the fidelity-tier default.
+ */
+resolution?: number, 
+/**
+ * Solve tier the assertion is (re-)verified at.
+ */
+fidelity: PhysicsFidelity, 
+/**
+ * Optional limit: max displacement ≤ this, in mm.
+ */
+max_displacement_mm?: number, 
+/**
+ * Optional limit: max von Mises stress ≤ this, in MPa.
+ */
+max_von_mises_mpa?: number, };
+
+/**
+ * A fixed (anchored) region for static analysis.
+ */
+export type PhysicsSupport = { 
+/**
+ * Region whose grid nodes are anchored.
+ */
+region: PhysicsRegion, 
+/**
+ * Which translations are fixed `[x, y, z]`; absent means all fixed.
+ */
+fix?: [boolean, boolean, boolean], };
+
 /**
  * A single pin's identity within a package.
  */
diff --git a/packages/mcp/src/__tests__/physics-claims.test.ts b/packages/mcp/src/__tests__/physics-claims.test.ts
new file mode 100644
index 000000000..1d0ee96fc
--- /dev/null
+++ b/packages/mcp/src/__tests__/physics-claims.test.ts
@@ -0,0 +1,270 @@
+/**
+ * Persisted physics specs: predict_physics + label stores a PhysicsSpec on the
+ * document, build_receipt re-solves it as physics.static.<label>.* claims, and
+ * verify_receipt re-verifies those claims as Holds / Stale / Violated —
+ * mirroring the mech.clearance persistence loop. Fail-closed throughout: an
+ * unresolvable part or a solve that cannot run is Violated/unverifiable, never
+ * a silent pass.
+ */
+import { describe, it, expect, beforeAll, beforeEach } from "vitest";
+import { Engine } from "@vcad/engine";
+import type { DesignReceipt, Document, ReceiptClaim } from "@vcad/ir";
+import { predictPhysicsTool } from "../tools/physics.js";
+import { buildReceipt, verifyReceipt } from "../tools/ecad.js";
+import { documents, getSession, openDocument } from "../tools/session.js";
+
+let engine: Engine;
+
+beforeAll(async () => {
+  engine = await Engine.init();
+});
+
+beforeEach(() => {
+  documents.clear();
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function out(result: { content: Array<{ type: string; text: string }> }): any {
+  return JSON.parse(result.content[0].text);
+}
+
+/** An 80×10×10 mm aluminum cantilever beam as a single Cube part. */
+function beamDocument(length: number): Document {
+  return {
+    version: "0.1",
+    nodes: {
+      "1": {
+        id: 1,
+        name: "beam",
+        op: { type: "Cube", size: { x: length, y: 10, z: 10 } },
+      },
+    },
+    materials: {},
+    part_materials: {},
+    roots: [{ root: 1, material: "aluminum" }],
+  } as unknown as Document;
+}
+
+function openBeam(length: number): string {
+  const opened = out(openDocument({ initial: beamDocument(length) }));
+  return opened.document_id as string;
+}
+
+/** Tip load + fixed root for a beam of the given length. */
+const beamCase = (length: number, extra: Record<string, unknown>) => ({
+  part: "beam",
+  loads: [
+    {
+      region: { min: [length, 0, 0], max: [length, 10, 10] },
+      force: [0, 0, -100],
+    },
+  ],
+  supports: [{ region: { min: [0, 0, 0], max: [0, 10, 10] } }],
+  ...extra,
+});
+
+describe("predict_physics label persistence", () => {
+  it("persists the spec on the document and reports spec_saved", () => {
+    const docId = openBeam(80);
+    const res = out(
+      predictPhysicsTool(
+        { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) },
+        engine,
+      ),
+    );
+    expect(res.spec_saved).toBe(true);
+    expect(res.label).toBe("tip-load");
+    const doc = getSession(docId);
+    expect(doc.physics_specs).toHaveLength(1);
+    const spec = doc.physics_specs![0];
+    expect(spec.label).toBe("tip-load");
+    expect(spec.part).toBe("1"); // resolved root id, survives renames
+    expect(spec.fidelity).toBe("predict");
+    expect(spec.max_displacement_mm).toBe(0.5);
+  });
+
+  it("upserts by label instead of duplicating", () => {
+    const docId = openBeam(80);
+    const args = { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) };
+    out(predictPhysicsTool(args, engine));
+    out(
+      predictPhysicsTool(
+        { ...args, max_displacement_mm: 0.4, fidelity: "verify" },
+        engine,
+      ),
+    );
+    const specs = getSession(docId).physics_specs!;
+    expect(specs).toHaveLength(1);
+    expect(specs[0].max_displacement_mm).toBe(0.4);
+    expect(specs[0].fidelity).toBe("verify");
+  });
+
+  it("rejects a label without limits or without a document", () => {
+    const docId = openBeam(80);
+    expect(() =>
+      predictPhysicsTool({ document_id: docId, ...beamCase(80, { label: "x" }) }, engine),
+    ).toThrow(/at least one limit/);
+    expect(() =>
+      predictPhysicsTool(
+        {
+          label: "x",
+          max_displacement_mm: 1,
+          domain_box: { min: [0, 0, 0], max: [10, 10, 10] },
+          loads: [{ region: { min: [10, 0, 0], max: [10, 10, 10] }, force: [0, 0, -1] }],
+          supports: [{ region: { min: [0, 0, 0], max: [0, 10, 10] } }],
+        },
+        engine,
+      ),
+    ).toThrow(/requires `document_id`/);
+  });
+});
+
+describe("build_receipt with physics specs", () => {
+  async function buildFor(docId: string): Promise<DesignReceipt> {
+    const res = out(await buildReceipt({ document_id: docId }, engine));
+    expect(res.unified).toBeTruthy();
+    return res.unified as DesignReceipt;
+  }
+
+  it("emits physics.static claims at the stored fidelity/basis", async () => {
+    const docId = openBeam(80);
+    out(
+      predictPhysicsTool(
+        {
+          document_id: docId,
+          ...beamCase(80, {
+            label: "tip-load",
+            max_displacement_mm: 0.5,
+            max_von_mises_mpa: 100,
+          }),
+        },
+        engine,
+      ),
+    );
+    const unified = await buildFor(docId);
+    const phys = unified.claims.filter((c: ReceiptClaim) =>
+      c.id.startsWith("physics.static."),
+    );
+    expect(phys.map((c) => c.id).sort()).toEqual([
+      "physics.static.tip-load.displacement",
+      "physics.static.tip-load.stress",
+    ]);
+    for (const c of phys) {
+      expect(c.verdict).toBe("pass");
+      expect(c.basis).toBe("predicted");
+      expect(c.details).toBeTruthy(); // re-runnable payload
+    }
+  });
+
+  it("fail-closed: a spec whose part vanished yields unverifiable claims", async () => {
+    const docId = openBeam(80);
+    out(
+      predictPhysicsTool(
+        { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) },
+        engine,
+      ),
+    );
+    const doc = getSession(docId);
+    doc.roots = [];
+    const unified = await buildFor(docId);
+    const phys = unified.claims.filter((c: ReceiptClaim) =>
+      c.id.startsWith("physics.static."),
+    );
+    expect(phys).toHaveLength(1);
+    expect(phys[0].verdict).toBe("unverifiable");
+  });
+});
+
+describe("verify_receipt physics claims", () => {
+  async function receiptFor(docId: string): Promise<DesignReceipt> {
+    const res = out(await buildReceipt({ document_id: docId }, engine));
+    return res.unified as DesignReceipt;
+  }
+
+  it("Holds on unchanged geometry", async () => {
+    const docId = openBeam(80);
+    out(
+      predictPhysicsTool(
+        { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) },
+        engine,
+      ),
+    );
+    const unified = await receiptFor(docId);
+    const res = out(await verifyReceipt({ document_id: docId, receipt: unified }, engine));
+    expect(res.status).toBe("Holds");
+    expect(res.physics.checks).toHaveLength(1);
+    expect(res.physics.checks[0].status).toBe("Holds");
+  });
+
+  it("Stale when geometry changed but the limit still holds", async () => {
+    const docId = openBeam(80);
+    out(
+      predictPhysicsTool(
+        { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) },
+        engine,
+      ),
+    );
+    const unified = await receiptFor(docId);
+    // Thicken the beam: stiffer, deflection drops — limit still holds, and
+    // the stored load region at the x=80 tip still touches the structure.
+    const doc = getSession(docId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (doc.nodes["1"] as any).op.size.z = 12;
+    const res = out(await verifyReceipt({ document_id: docId, receipt: unified }, engine));
+    expect(res.status).toBe("Stale");
+    expect(res.physics.checks[0].status).toBe("Stale");
+    expect(res.physics.checks[0].measured).toBeLessThan(res.physics.checks[0].stored);
+  });
+
+  it("Violated when the re-solve exceeds the limit", async () => {
+    const docId = openBeam(80);
+    out(
+      predictPhysicsTool(
+        { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) },
+        engine,
+      ),
+    );
+    const unified = await receiptFor(docId);
+    // Lengthen the beam far enough that tip deflection blows the 0.5 mm limit.
+    const doc = getSession(docId);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (doc.nodes["1"] as any).op.size.x = 160;
+    const res = out(await verifyReceipt({ document_id: docId, receipt: unified }, engine));
+    expect(res.status).toBe("Violated");
+    expect(res.physics.checks[0].status).toBe("Violated");
+  });
+
+  it("Violated (fail-closed) when the part can no longer be resolved", async () => {
+    const docId = openBeam(80);
+    out(
+      predictPhysicsTool(
+        { document_id: docId, ...beamCase(80, { label: "tip-load", max_displacement_mm: 0.5 }) },
+        engine,
+      ),
+    );
+    const unified = await receiptFor(docId);
+    getSession(docId).roots = [];
+    const res = out(await verifyReceipt({ document_id: docId, receipt: unified }, engine));
+    expect(res.status).toBe("Violated");
+    expect(res.physics.checks[0].reason).toMatch(/not found|empty/i);
+  });
+
+  it("Violated when a stored claim has no re-runnable payload", async () => {
+    const docId = openBeam(80);
+    const receipt: DesignReceipt = {
+      schema: "vcad.receipt/1",
+      claims: [
+        {
+          id: "physics.static.tip-load.displacement",
+          domain: "mechanical",
+          description: "tampered",
+          oracle: { id: "vcad-kernel-topopt/static-fea", version: "0.9.4" },
+          verdict: "pass",
+        },
+      ],
+    };
+    const res = out(await verifyReceipt({ document_id: docId, receipt }, engine));
+    expect(res.status).toBe("Violated");
+    expect(res.physics.checks[0].reason).toMatch(/no re-verifiable payload/);
+  });
+});
diff --git a/packages/mcp/src/__tests__/tool-surface.fixture.json b/packages/mcp/src/__tests__/tool-surface.fixture.json
index 05b4e2764..33ab1da0c 100644
--- a/packages/mcp/src/__tests__/tool-surface.fixture.json
+++ b/packages/mcp/src/__tests__/tool-surface.fixture.json
@@ -1694,13 +1694,13 @@
   {
     "name": "predict_physics",
     "title": "Predict Physics",
-    "description": "Fast static structural analysis (voxel FEA): max displacement, max von Mises stress, and compliance for a part or box under world-frame loads (N) and supports, in ~100 ms at fidelity=predict. Pass max_displacement_mm / max_von_mises_mpa limits to get receipt claims: predict-tier claims carry basis=predicted and roll up as a PROVISIONAL receipt — use them to iterate on a design cheaply. When the design settles, re-run with fidelity=verify (same solver, fine grid) to upgrade the claims to basis=verified and a certifiable pass. Loads/supports are box regions (mm, Z-up); zero-thickness boxes select a face. Voxel FEA smears stress concentrations — treat stress as an estimate near fillets.",
+    "description": "Fast static structural analysis (voxel FEA): max displacement, max von Mises stress, and compliance for a part or box under world-frame loads (N) and supports, in ~100 ms at fidelity=predict. Pass max_displacement_mm / max_von_mises_mpa limits to get receipt claims: predict-tier claims carry basis=predicted and roll up as a PROVISIONAL receipt — use them to iterate on a design cheaply. When the design settles, re-run with fidelity=verify (same solver, fine grid) to upgrade the claims to basis=verified and a certifiable pass. Give it a `label` to persist the assertion on the document: build_receipt then re-solves it as physics.static claims and verify_receipt re-verifies it as Holds / Stale / Violated when geometry changes. Loads/supports are box regions (mm, Z-up); zero-thickness boxes select a face. Voxel FEA smears stress concentrations — treat stress as an estimate near fillets.",
     "inputSchema": {
       "type": "object",
       "properties": {
         "document_id": {
           "type": "string",
-          "description": "Session document. Required with `part`."
+          "description": "Session document. Required with `part` or `label`."
         },
         "part": {
           "type": "string",
@@ -1860,6 +1860,10 @@
         "max_von_mises_mpa": {
           "type": "number",
           "description": "Optional limit: assert max von Mises stress ≤ this (claim physics.static.stress). E.g. yield/safety-factor."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional assertion name (e.g. 'bracket-load'). When given (with at least one limit and a document_id), the spec — loads, supports, material, limits, fidelity — is persisted on the document and re-solved by build_receipt / verify_receipt whenever geometry changes."
         }
       },
       "required": [
@@ -5950,7 +5954,7 @@
   {
     "name": "build_receipt",
     "title": "Build Receipt",
-    "description": "Build a re-runnable verification Receipt for the session PCB: a content hash, the DRC backend, a canonicalized DRC summary, and per-part provenance — a durable proof that round-trips and re-verifies later as Holds / Stale / Violated. Persisted clearance specs (check_clearance with a label) join the unified ledger as mech.clearance claims — a CAD-only session with specs gets a mechanical receipt, no PCB needed. Renders as an audit ledger in the inline viewer.",
+    "description": "Build a re-runnable verification Receipt for the session PCB: a content hash, the DRC backend, a canonicalized DRC summary, and per-part provenance — a durable proof that round-trips and re-verifies later as Holds / Stale / Violated. Persisted clearance specs (check_clearance with a label) join the unified ledger as mech.clearance claims, and persisted physics specs (predict_physics with a label) as physics.static claims re-solved at their stored fidelity — a CAD-only session with specs gets a mechanical receipt, no PCB needed. Renders as an audit ledger in the inline viewer.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -5998,7 +6002,7 @@
   {
     "name": "verify_receipt",
     "title": "Verify Receipt",
-    "description": "Re-run a prior receipt (from build_receipt) against the session's current document and return the verdict — Holds (unchanged, clean), Stale (changed but claims still hold), or Violated. Covers the PCB Receipt (board hash + DRC diff) and mech.clearance claims (re-measured against current geometry); worst verdict wins. Powers the ledger's Re-run button.",
+    "description": "Re-run a prior receipt (from build_receipt) against the session's current document and return the verdict — Holds (unchanged, clean), Stale (changed but claims still hold), or Violated. Covers the PCB Receipt (board hash + DRC diff), mech.clearance claims (re-measured against current geometry), and physics.static claims (re-solved at their stored fidelity); worst verdict wins. Powers the ledger's Re-run button.",
     "inputSchema": {
       "type": "object",
       "properties": {
diff --git a/packages/mcp/src/tools/ecad.ts b/packages/mcp/src/tools/ecad.ts
index 80dcb08c1..5282f6b72 100644
--- a/packages/mcp/src/tools/ecad.ts
+++ b/packages/mcp/src/tools/ecad.ts
@@ -43,6 +43,11 @@ import {
   hasClearanceClaims,
   verifyClearanceClaims,
 } from "./clearance.js";
+import {
+  hasPhysicsClaims,
+  physicsReceiptClaims,
+  verifyPhysicsClaims,
+} from "./physics.js";
 import { getNodePcb, getPcbNodeIds, buildEntry, agentView, diffViolations } from "@vcad/core";
 import {
   computeRatsnest,
@@ -11986,23 +11991,28 @@ export async function buildReceipt(args: Record<string, unknown>, engine?: Engin
   const ctx = resolveDocInput(args);
   const pcb = getDocPcb(ctx.doc);
   const clearanceSpecs = ctx.doc.clearance_specs ?? [];
+  const physicsSpecs = ctx.doc.physics_specs ?? [];
   if (!pcb) {
-    if (clearanceSpecs.length === 0) {
+    if (clearanceSpecs.length === 0 && physicsSpecs.length === 0) {
       return {
         content: [
           {
             type: "text" as const,
-            text: "Error: Document has no PCB and no clearance specs — nothing to certify. (Persist mechanical assertions with check_clearance + label first.)",
+            text: "Error: Document has no PCB and no clearance or physics specs — nothing to certify. (Persist mechanical assertions with check_clearance + label, or predict_physics + label, first.)",
           },
         ],
         isError: true,
       };
     }
-    // Mechanical-only receipt: re-measure every persisted clearance spec.
+    // Mechanical-only receipt: re-measure every persisted clearance spec and
+    // re-solve every persisted physics spec.
     const unified: DesignReceipt = {
       schema: RECEIPT_SCHEMA,
       ...(ctx.documentId ? { document_id: ctx.documentId } : {}),
-      claims: clearanceReceiptClaims(ctx.doc, engine),
+      claims: [
+        ...clearanceReceiptClaims(ctx.doc, engine),
+        ...physicsReceiptClaims(ctx.doc, engine),
+      ],
     };
     return {
       content: [
@@ -12074,6 +12084,9 @@ export async function buildReceipt(args: Record<string, unknown>, engine?: Engin
   if (clearanceSpecs.length > 0) {
     unified.claims.push(...clearanceReceiptClaims(ctx.doc, engine));
   }
+  if (physicsSpecs.length > 0) {
+    unified.claims.push(...physicsReceiptClaims(ctx.doc, engine));
+  }
 
   // The receipt rides in structuredContent so the inline viewer renders it
   // as an audit ledger (the only carrier ChatGPT's widget bridge exposes);
@@ -12133,7 +12146,8 @@ function worstStatus(statuses: ReceiptStatus[]): ReceiptStatus {
  *  verdict: Holds (unchanged, clean), Stale (document changed but claims still
  *  hold), or Violated. Handles the re-runnable PCB Receipt (board hash + DRC
  *  diff), the unified DesignReceipt's mech.clearance claims (re-measured
- *  against current geometry), or both at once — worst verdict wins. */
+ *  against current geometry) and physics.static claims (re-solved at their
+ *  stored fidelity), or all at once — worst verdict wins. */
 export async function verifyReceipt(args: Record<string, unknown>, engine?: Engine) {
   const ctx = resolveDocInput(args);
   const raw = args.receipt as Record<string, unknown> | undefined;
@@ -12172,13 +12186,14 @@ export async function verifyReceipt(args: Record<string, unknown>, engine?: Engi
     }
   }
   const clearanceReceipt = unified && hasClearanceClaims(unified) ? unified : undefined;
+  const physicsReceipt = unified && hasPhysicsClaims(unified) ? unified : undefined;
 
-  if (!legacy && !clearanceReceipt) {
+  if (!legacy && !clearanceReceipt && !physicsReceipt) {
     return {
       content: [
         {
           type: "text" as const,
-          text: "Error: `receipt` carries nothing re-verifiable — pass a PCB Receipt (board_hash) or a unified DesignReceipt with mech.clearance claims, as produced by build_receipt.",
+          text: "Error: `receipt` carries nothing re-verifiable — pass a PCB Receipt (board_hash) or a unified DesignReceipt with mech.clearance or physics.static claims, as produced by build_receipt.",
         },
       ],
       isError: true,
@@ -12228,10 +12243,28 @@ export async function verifyReceipt(args: Record<string, unknown>, engine?: Engi
     statuses.push(clearance.status);
   }
 
+  let physics: ReturnType<typeof verifyPhysicsClaims> | undefined;
+  if (physicsReceipt) {
+    if (!engine) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "Error: physics re-verification needs the kernel engine; unavailable in this context",
+          },
+        ],
+        isError: true,
+      };
+    }
+    physics = verifyPhysicsClaims(ctx.doc, engine, physicsReceipt);
+    statuses.push(physics.status);
+  }
+
   const payload = {
     status: worstStatus(statuses),
     ...(boardHash ? { board_hash: boardHash } : {}),
     ...(clearance ? { clearance } : {}),
+    ...(physics ? { physics } : {}),
   };
   return {
     content: [{ type: "text" as const, text: JSON.stringify(payload) }],
@@ -12739,7 +12772,7 @@ export const toolDefs: ToolDef[] = [
     name: "build_receipt",
     pack: "ecad",
     description:
-      "Build a re-runnable verification Receipt for the session PCB: a content hash, the DRC backend, a canonicalized DRC summary, and per-part provenance \u2014 a durable proof that round-trips and re-verifies later as Holds / Stale / Violated. Persisted clearance specs (check_clearance with a label) join the unified ledger as mech.clearance claims \u2014 a CAD-only session with specs gets a mechanical receipt, no PCB needed. Renders as an audit ledger in the inline viewer.",
+      "Build a re-runnable verification Receipt for the session PCB: a content hash, the DRC backend, a canonicalized DRC summary, and per-part provenance \u2014 a durable proof that round-trips and re-verifies later as Holds / Stale / Violated. Persisted clearance specs (check_clearance with a label) join the unified ledger as mech.clearance claims, and persisted physics specs (predict_physics with a label) as physics.static claims re-solved at their stored fidelity \u2014 a CAD-only session with specs gets a mechanical receipt, no PCB needed. Renders as an audit ledger in the inline viewer.",
     inputSchema: buildReceiptSchema,
     handler: (a, c) =>
       buildReceipt(a, c.engine) as ToolResult | Promise<ToolResult>,
@@ -12749,9 +12782,9 @@ export const toolDefs: ToolDef[] = [
     name: "verify_receipt",
     pack: "ecad",
     description:
-      "Re-run a prior receipt (from build_receipt) against the session's current document and return the verdict \u2014 Holds (unchanged, clean), Stale (changed but claims still hold), or Violated. Covers the PCB Receipt (board hash + DRC diff) and mech.clearance claims (re-measured against current geometry); worst verdict wins. Powers the ledger's Re-run button.",
+      "Re-run a prior receipt (from build_receipt) against the session's current document and return the verdict \u2014 Holds (unchanged, clean), Stale (changed but claims still hold), or Violated. Covers the PCB Receipt (board hash + DRC diff), mech.clearance claims (re-measured against current geometry), and physics.static claims (re-solved at their stored fidelity); worst verdict wins. Powers the ledger's Re-run button.",
     inputSchema: verifyReceiptSchema,
-    handler: (a) => verifyReceipt(a) as ToolResult | Promise<ToolResult>,
+    handler: (a, c) => verifyReceipt(a, c.engine) as ToolResult | Promise<ToolResult>,
     behavior: behavior({ widgetCallable: true }),
   },
   {
diff --git a/packages/mcp/src/tools/physics.ts b/packages/mcp/src/tools/physics.ts
index fbee21e15..04e328a14 100644
--- a/packages/mcp/src/tools/physics.ts
+++ b/packages/mcp/src/tools/physics.ts
@@ -8,10 +8,24 @@
  * at fine resolution and stamps `basis: verified`. A receipt whose passing
  * claims rest on predictions rolls up `provisional`, never `pass`
  * (crates/vcad-receipt) — predictions steer, verification certifies.
+ *
+ * Give a run a `label` (with limits) and the assertion persists on the
+ * document as a {@link PhysicsSpec}, mirroring `check_clearance`: persisted
+ * specs are re-solved by `build_receipt` (as `physics.static.<label>.*`
+ * DesignReceipt claims) and re-verified by `verify_receipt`
+ * (Holds / Stale / Violated), so structural limits stop being one-off hand
+ * checks that silently rot when geometry changes.
  */
 
 import type { Engine, StaticAnalysisSpec, StaticAnalysisResult } from "@vcad/engine";
-import type { DesignReceipt, ReceiptClaim, OracleRef } from "@vcad/ir";
+import type {
+  DesignReceipt,
+  Document,
+  OracleRef,
+  PhysicsSpec,
+  ReceiptClaim,
+  ReceiptStatus,
+} from "@vcad/ir";
 import { getSession } from "./session.js";
 import { behavior, type ToolDef } from "./tool-def.js";
 import { resolvePartMesh } from "./topopt.js";
@@ -20,9 +34,17 @@ import { RECEIPT_SCHEMA, summarize, unverifiableClaim } from "../receipt-unified
 const PHYSICS_DOMAIN = "mechanical";
 const ORACLE: OracleRef = { id: "vcad-kernel-topopt/static-fea", version: "0.9.4" };
 
+/** Claim-id prefix for persisted physics specs (`physics.static.<label>.<metric>`). */
+export const PHYSICS_CLAIM_PREFIX = "physics.static.";
+
 /** Resolution per fidelity tier. Same solver; the grid is the only dial. */
 const TIER_RESOLUTION = { predict: 32, verify: 72 } as const;
 
+/** The voxel FEA is deterministic for identical inputs, so a re-solve on
+ *  unchanged geometry reproduces the stored value exactly; any relative
+ *  difference beyond float noise means the geometry (or grid) changed. */
+const STALE_REL_EPS = 1e-9;
+
 const regionSchema = {
   type: "object" as const,
   required: ["min", "max"],
@@ -50,7 +72,7 @@ export const predictPhysicsSchema = {
   properties: {
     document_id: {
       type: "string" as const,
-      description: "Session document. Required with `part`.",
+      description: "Session document. Required with `part` or `label`.",
     },
     part: {
       type: "string" as const,
@@ -143,6 +165,15 @@ export const predictPhysicsSchema = {
         "Optional limit: assert max von Mises stress ≤ this (claim " +
         "physics.static.stress). E.g. yield/safety-factor.",
     },
+    label: {
+      type: "string" as const,
+      description:
+        "Optional assertion name (e.g. 'bracket-load'). When given (with at " +
+        "least one limit and a document_id), the spec — loads, supports, " +
+        "material, limits, fidelity — is persisted on the document and " +
+        "re-solved by build_receipt / verify_receipt whenever geometry " +
+        "changes.",
+    },
   },
 };
 
@@ -158,10 +189,97 @@ interface PhysicsArgs {
   poisson?: number;
   max_displacement_mm?: number;
   max_von_mises_mpa?: number;
+  label?: string;
 }
 
 const round5 = (v: number) => Number(v.toPrecision(5));
 
+/** The re-runnable payload riding in a persisted physics claim's `details`,
+ *  so a stored receipt re-verifies without external context. */
+export interface StoredPhysicsClaim {
+  spec: PhysicsSpec;
+  /** Which limit this claim asserts. */
+  metric: "displacement" | "stress";
+  limit: number;
+  measured: number;
+}
+
+/**
+ * Core solve for a spec: resolve the part (or box) and run the voxel FEA at
+ * the spec's fidelity. Pure of MCP plumbing so `predict_physics`,
+ * `build_receipt`, and `verify_receipt` share one implementation.
+ */
+export function solvePhysicsSpec(
+  spec: PhysicsSpec,
+  engine: Engine,
+  doc: Document | undefined,
+): { result?: StaticAnalysisResult; subject?: string; error?: string } {
+  const analysisSpec: StaticAnalysisSpec = {
+    loads: spec.loads,
+    supports: spec.supports,
+    resolution: spec.resolution ?? TIER_RESOLUTION[spec.fidelity],
+    youngs_modulus_mpa: spec.youngs_modulus_mpa,
+    poisson: spec.poisson,
+  };
+  try {
+    if (spec.part) {
+      if (!doc) return { error: "spec targets a part but no document is available" };
+      const resolved = resolvePartMesh(doc, engine, spec.part);
+      return {
+        result: engine.analyzeStaticsMesh(resolved.mesh, analysisSpec),
+        subject: `part:${resolved.name ?? spec.part}`,
+      };
+    }
+    if (!spec.domain_box) return { error: "spec has neither `part` nor `domain_box`" };
+    return {
+      result: engine.analyzeStaticsBox(spec.domain_box.min, spec.domain_box.max, analysisSpec),
+      subject: "domain_box",
+    };
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** Insert or replace the named spec on the document (upsert by label). */
+function upsertPhysicsSpec(doc: Document, spec: PhysicsSpec): void {
+  const specs = doc.physics_specs ?? [];
+  const idx = specs.findIndex((s) => s.label === spec.label);
+  if (idx >= 0) specs[idx] = spec;
+  else specs.push(spec);
+  doc.physics_specs = specs;
+}
+
+/** The limits a spec asserts, as (metric, claim-id-suffix, limit) tuples. */
+function specLimits(spec: PhysicsSpec): Array<{
+  metric: StoredPhysicsClaim["metric"];
+  limit: number;
+  unit: string;
+  what: string;
+}> {
+  const out: ReturnType<typeof specLimits> = [];
+  if (spec.max_displacement_mm != null) {
+    out.push({
+      metric: "displacement",
+      limit: spec.max_displacement_mm,
+      unit: "mm",
+      what: "max displacement under load",
+    });
+  }
+  if (spec.max_von_mises_mpa != null) {
+    out.push({
+      metric: "stress",
+      limit: spec.max_von_mises_mpa,
+      unit: "MPa",
+      what: "max von Mises stress",
+    });
+  }
+  return out;
+}
+
+function measuredFor(result: StaticAnalysisResult, metric: StoredPhysicsClaim["metric"]): number {
+  return metric === "displacement" ? result.maxDisplacementMm : result.maxVonMisesMpa;
+}
+
 function limitClaim(
   id: string,
   description: string,
@@ -171,6 +289,7 @@ function limitClaim(
   unit: string,
   basis: "predicted" | "verified",
   converged: boolean,
+  details?: string,
 ): ReceiptClaim {
   if (!converged || !Number.isFinite(actual)) {
     return {
@@ -189,9 +308,205 @@ function limitClaim(
     basis,
     predicted: { value: limit, unit },
     measured: { value: round5(actual), unit },
+    ...(details ? { details } : {}),
   };
 }
 
+/** Emit the claims for one solved spec (labeled → `physics.static.<label>.<metric>`). */
+function claimsForSpec(
+  spec: PhysicsSpec,
+  solved: ReturnType<typeof solvePhysicsSpec>,
+): ReceiptClaim[] {
+  const basis = spec.fidelity === "verify" ? ("verified" as const) : ("predicted" as const);
+  return specLimits(spec).map(({ metric, limit, unit, what }) => {
+    const id = spec.label
+      ? `${PHYSICS_CLAIM_PREFIX}${spec.label}.${metric}`
+      : `${PHYSICS_CLAIM_PREFIX}${metric === "displacement" ? "displacement" : "stress"}`;
+    const description = spec.label
+      ? `physics "${spec.label}": ${what} ≤ ${limit} ${unit}`
+      : `${what} ≤ ${limit} ${unit}`;
+    if (solved.error || !solved.result) {
+      return {
+        ...unverifiableClaim(
+          id,
+          PHYSICS_DOMAIN,
+          description,
+          ORACLE,
+          solved.error ?? "static analysis could not run",
+        ),
+        basis,
+        ...(solved.subject ? { subject: solved.subject } : {}),
+      };
+    }
+    const measured = measuredFor(solved.result, metric);
+    const stored: StoredPhysicsClaim = { spec, metric, limit, measured: round5(measured) };
+    return limitClaim(
+      id,
+      description,
+      solved.subject,
+      limit,
+      measured,
+      unit,
+      basis,
+      solved.result.converged,
+      JSON.stringify(stored),
+    );
+  });
+}
+
+/**
+ * Re-solve every persisted physics spec and emit unified receipt claims,
+ * mirroring {@link clearanceReceiptClaims}: id `physics.static.<label>.<metric>`,
+ * limit as predicted, solve result as measured, basis from the spec's stored
+ * fidelity, and the typed {@link StoredPhysicsClaim} riding in `details` so a
+ * stored receipt re-verifies without external context. A spec that cannot be
+ * solved (missing part, non-converged solve) yields an unverifiable claim —
+ * fail-closed, never a silent skip.
+ */
+export function physicsReceiptClaims(doc: Document, engine: Engine | undefined): ReceiptClaim[] {
+  const specs = doc.physics_specs ?? [];
+  return specs.flatMap((spec) => {
+    if (!engine) {
+      return specLimits(spec).map(({ metric, limit, unit, what }) => ({
+        ...unverifiableClaim(
+          `${PHYSICS_CLAIM_PREFIX}${spec.label}.${metric}`,
+          PHYSICS_DOMAIN,
+          `physics "${spec.label}": ${what} ≤ ${limit} ${unit}`,
+          ORACLE,
+          "static analysis needs the kernel engine; unavailable in this context",
+        ),
+        basis: spec.fidelity === "verify" ? ("verified" as const) : ("predicted" as const),
+      }));
+    }
+    return claimsForSpec(spec, solvePhysicsSpec(spec, engine, doc));
+  });
+}
+
+/** Per-assertion outcome of re-verifying a stored physics claim. */
+export interface PhysicsCheckStatus {
+  /** Claim id suffix, e.g. "bracket-load.displacement". */
+  label: string;
+  status: ReceiptStatus;
+  limit?: number;
+  /** Value recorded in the stored receipt. */
+  stored?: number;
+  /** Value re-solved against the current document. */
+  measured?: number;
+  reason?: string;
+}
+
+/**
+ * Re-verify the `physics.static.*` claims of a stored DesignReceipt against
+ * the current document by re-running the solve at each claim's stored
+ * fidelity. Per claim: a limit that no longer holds — or a spec that can no
+ * longer be solved (unresolvable part, non-converged solve: fail-closed) —
+ * is Violated; one that still holds but re-solves to a different value is
+ * Stale; an unchanged result Holds. Rollup takes the worst.
+ */
+export function verifyPhysicsClaims(
+  doc: Document,
+  engine: Engine,
+  receipt: DesignReceipt,
+): { status: ReceiptStatus; checks: PhysicsCheckStatus[] } {
+  const checks: PhysicsCheckStatus[] = [];
+  // One spec often carries two claims (displacement + stress) — solve once.
+  const solveCache = new Map<string, ReturnType<typeof solvePhysicsSpec>>();
+  for (const claim of receipt.claims ?? []) {
+    if (!claim.id.startsWith(PHYSICS_CLAIM_PREFIX)) continue;
+    const label = claim.id.slice(PHYSICS_CLAIM_PREFIX.length);
+    const stored = parseStoredClaim(claim);
+    if (!stored) {
+      checks.push({
+        label,
+        status: "Violated",
+        reason:
+          "stored claim carries no re-verifiable payload (details is not a StoredPhysicsClaim)",
+      });
+      continue;
+    }
+    const key = JSON.stringify(stored.spec);
+    let solved = solveCache.get(key);
+    if (!solved) {
+      solved = solvePhysicsSpec(stored.spec, engine, doc);
+      solveCache.set(key, solved);
+    }
+    if (solved.error || !solved.result || !solved.result.converged) {
+      checks.push({
+        label,
+        status: "Violated",
+        limit: stored.limit,
+        stored: stored.measured,
+        reason: solved.error ?? "FE solve did not converge",
+      });
+      continue;
+    }
+    const measured = round5(measuredFor(solved.result, stored.metric));
+    if (!Number.isFinite(measured) || measured > stored.limit) {
+      checks.push({
+        label,
+        status: "Violated",
+        limit: stored.limit,
+        stored: stored.measured,
+        measured,
+        reason: `re-solved ${measured} exceeds the limit ${stored.limit}`,
+      });
+    } else if (
+      Math.abs(measured - stored.measured) >
+      STALE_REL_EPS * Math.max(1, Math.abs(stored.measured))
+    ) {
+      checks.push({
+        label,
+        status: "Stale",
+        limit: stored.limit,
+        stored: stored.measured,
+        measured,
+        reason: "geometry changed since the receipt was built, but the limit still holds",
+      });
+    } else {
+      checks.push({
+        label,
+        status: "Holds",
+        limit: stored.limit,
+        stored: stored.measured,
+        measured,
+      });
+    }
+  }
+  const status: ReceiptStatus = checks.some((c) => c.status === "Violated")
+    ? "Violated"
+    : checks.some((c) => c.status === "Stale")
+      ? "Stale"
+      : "Holds";
+  return { status, checks };
+}
+
+/** Does this unified receipt carry any physics claims to re-verify? */
+export function hasPhysicsClaims(receipt: DesignReceipt): boolean {
+  return (receipt.claims ?? []).some((c) => c.id.startsWith(PHYSICS_CLAIM_PREFIX));
+}
+
+function parseStoredClaim(claim: ReceiptClaim): StoredPhysicsClaim | undefined {
+  if (!claim.details) return undefined;
+  try {
+    const parsed = JSON.parse(claim.details) as Partial<StoredPhysicsClaim>;
+    const spec = parsed.spec as Partial<PhysicsSpec> | undefined;
+    if (
+      spec &&
+      Array.isArray(spec.loads) &&
+      Array.isArray(spec.supports) &&
+      (spec.fidelity === "predict" || spec.fidelity === "verify") &&
+      (parsed.metric === "displacement" || parsed.metric === "stress") &&
+      typeof parsed.limit === "number" &&
+      typeof parsed.measured === "number"
+    ) {
+      return parsed as StoredPhysicsClaim;
+    }
+  } catch {
+    /* not JSON — fall through to undefined */
+  }
+  return undefined;
+}
+
 export function predictPhysicsTool(
   args: Record<string, unknown>,
   engine: Engine,
@@ -206,66 +521,68 @@ export function predictPhysicsTool(
   if (a.part && !a.document_id) {
     throw new Error("predict_physics: `part` requires `document_id`");
   }
+  const label = typeof a.label === "string" && a.label.trim() ? a.label.trim() : undefined;
+  const hasLimit = a.max_displacement_mm !== undefined || a.max_von_mises_mpa !== undefined;
+  if (label && !a.document_id) {
+    throw new Error("predict_physics: `label` requires `document_id` (the spec persists on it)");
+  }
+  if (label && !hasLimit) {
+    throw new Error(
+      "predict_physics: `label` requires at least one limit " +
+        "(max_displacement_mm and/or max_von_mises_mpa) — a persisted spec " +
+        "with nothing to assert cannot be verified",
+    );
+  }
   const fidelity = a.fidelity ?? "predict";
   const basis = fidelity === "verify" ? "verified" : "predicted";
 
-  const spec: StaticAnalysisSpec = {
+  const spec: PhysicsSpec = {
+    label: label ?? "",
     loads: a.loads,
     supports: a.supports,
-    resolution: a.resolution ?? TIER_RESOLUTION[fidelity],
-    youngs_modulus_mpa: a.youngs_modulus_mpa,
-    poisson: a.poisson,
+    fidelity,
+    ...(a.domain_box ? { domain_box: a.domain_box } : {}),
+    ...(a.resolution !== undefined ? { resolution: a.resolution } : {}),
+    ...(a.youngs_modulus_mpa !== undefined
+      ? { youngs_modulus_mpa: a.youngs_modulus_mpa }
+      : {}),
+    ...(a.poisson !== undefined ? { poisson: a.poisson } : {}),
+    ...(a.max_displacement_mm !== undefined
+      ? { max_displacement_mm: a.max_displacement_mm }
+      : {}),
+    ...(a.max_von_mises_mpa !== undefined ? { max_von_mises_mpa: a.max_von_mises_mpa } : {}),
   };
 
   let documentId: string | undefined;
-  let subject: string | undefined;
-  const started = performance.now();
-  let result: StaticAnalysisResult;
+  let doc: Document | undefined;
   if (a.part) {
     documentId = String(a.document_id);
-    const doc = getSession(documentId);
+    doc = getSession(documentId);
+    // Persist by resolved root id so the assertion survives renames.
     const resolved = resolvePartMesh(doc, engine, a.part);
-    subject = `part:${resolved.name ?? a.part}`;
-    result = engine.analyzeStaticsMesh(resolved.mesh, spec);
-  } else {
-    // Box runs are pure computation — no session is touched or minted.
-    if (a.document_id) documentId = String(a.document_id);
-    const box = a.domain_box!;
-    result = engine.analyzeStaticsBox(box.min, box.max, spec);
-    subject = "domain_box";
+    spec.part = String(doc.roots[resolved.rootIndex].root);
+  } else if (a.document_id) {
+    // Box runs are pure computation unless a label persists the spec.
+    documentId = String(a.document_id);
+    if (label) doc = getSession(documentId);
   }
-  const solveMs = Math.round(performance.now() - started);
 
-  const claims: ReceiptClaim[] = [];
-  if (a.max_displacement_mm !== undefined) {
-    claims.push(
-      limitClaim(
-        "physics.static.displacement",
-        `max displacement under load ≤ ${a.max_displacement_mm} mm`,
-        subject,
-        a.max_displacement_mm,
-        result.maxDisplacementMm,
-        "mm",
-        basis,
-        result.converged,
-      ),
-    );
+  const started = performance.now();
+  const solved = solvePhysicsSpec(spec, engine, doc);
+  if (solved.error || !solved.result) {
+    throw new Error(`predict_physics: ${solved.error ?? "static analysis failed"}`);
   }
-  if (a.max_von_mises_mpa !== undefined) {
-    claims.push(
-      limitClaim(
-        "physics.static.stress",
-        `max von Mises stress ≤ ${a.max_von_mises_mpa} MPa`,
-        subject,
-        a.max_von_mises_mpa,
-        result.maxVonMisesMpa,
-        "MPa",
-        basis,
-        result.converged,
-      ),
-    );
+  const result = solved.result;
+  const solveMs = Math.round(performance.now() - started);
+
+  let specSaved = false;
+  if (label && doc) {
+    upsertPhysicsSpec(doc, spec);
+    specSaved = true;
   }
 
+  const claims: ReceiptClaim[] = claimsForSpec(spec, solved);
+
   const receipt: DesignReceipt | undefined = claims.length
     ? { schema: RECEIPT_SCHEMA, document_id: documentId, claims }
     : undefined;
@@ -279,6 +596,7 @@ export function predictPhysicsTool(
             document_id: documentId,
             fidelity,
             basis,
+            ...(label ? { label } : {}),
             solve_ms: solveMs,
             analysis: {
               max_displacement_mm: round5(result.maxDisplacementMm),
@@ -297,6 +615,15 @@ export function predictPhysicsTool(
                     "No limits asserted — pass max_displacement_mm and/or " +
                     "max_von_mises_mpa to get receipt claims.",
                 }),
+            ...(specSaved
+              ? {
+                  spec_saved: true,
+                  note:
+                    "Spec persisted on the document — build_receipt emits it " +
+                    "as physics.static claims and verify_receipt re-solves it " +
+                    "as Holds/Stale/Violated.",
+                }
+              : {}),
             ...(fidelity === "predict"
               ? {
                   next:
@@ -324,10 +651,13 @@ export const toolDefs: ToolDef[] = [
       "claims: predict-tier claims carry basis=predicted and roll up as a PROVISIONAL receipt — " +
       "use them to iterate on a design cheaply. When the design settles, re-run with " +
       "fidelity=verify (same solver, fine grid) to upgrade the claims to basis=verified and a " +
-      "certifiable pass. Loads/supports are box regions (mm, Z-up); zero-thickness boxes select " +
-      "a face. Voxel FEA smears stress concentrations — treat stress as an estimate near fillets.",
+      "certifiable pass. Give it a `label` to persist the assertion on the document: " +
+      "build_receipt then re-solves it as physics.static claims and verify_receipt re-verifies " +
+      "it as Holds / Stale / Violated when geometry changes. Loads/supports are box regions " +
+      "(mm, Z-up); zero-thickness boxes select a face. Voxel FEA smears stress concentrations — " +
+      "treat stress as an estimate near fillets.",
     inputSchema: predictPhysicsSchema,
     handler: (args, ctx) => predictPhysicsTool(args, ctx.engine),
-    behavior: behavior({}),
+    behavior: behavior({ writesDoc: true }),
   },
 ];
diff --git a/scripts/gen-ir-types.mjs b/scripts/gen-ir-types.mjs
index d57877a59..0a1a498f3 100644
--- a/scripts/gen-ir-types.mjs
+++ b/scripts/gen-ir-types.mjs
@@ -80,7 +80,7 @@ if (files.length === 0) {
 //       reader code, e.g. `front !== false`) treats them as optional.
 const FORCE_OPTIONAL = {
   Instance: ["tags"],
-  Document: ["parameters", "bindings", "clearance_specs"],
+  Document: ["parameters", "bindings", "clearance_specs", "physics_specs"],
   DesignRules: ["classRules", "netClassAssignments"],
   BoardOutline: ["cutouts"],
   Zone: ["holes", "priority", "minArea", "fillType", "thermalRelief"],

From e0eec02ff7ad3f1cf1d72ce911371b302ca61fbf Mon Sep 17 00:00:00 2001
From: Cam Pedersen <cam@campedersen.com>
Date: Sat, 11 Jul 2026 17:49:05 -0400
Subject: [PATCH 2/3] Order gate re-verifies persisted physics specs at place
 time

M4 gate 2 now re-solves doc.physics_specs (via physicsReceiptClaims)
alongside clearance specs before money moves: a failing or unverifiable
physics.static claim refuses the debit fail-closed, and the no-specs
"unverified" path only applies when the document carries neither kind
of spec.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/__tests__/place-order-gates.test.ts   | 74 +++++++++++++++++++
 packages/mcp/src/tools/ordering.ts            | 20 +++--
 2 files changed, 87 insertions(+), 7 deletions(-)

diff --git a/packages/mcp/src/__tests__/place-order-gates.test.ts b/packages/mcp/src/__tests__/place-order-gates.test.ts
index 02e97bebb..2deff5bbd 100644
--- a/packages/mcp/src/__tests__/place-order-gates.test.ts
+++ b/packages/mcp/src/__tests__/place-order-gates.test.ts
@@ -5,6 +5,7 @@ import { documents, getSession, openDocument } from "../tools/session.js";
 import { quoteManufacturing } from "../tools/order.js";
 import { authorizeSpend, placeOrder } from "../tools/ordering.js";
 import { checkClearance } from "../tools/clearance.js";
+import { predictPhysicsTool } from "../tools/physics.js";
 import { InMemoryFabricateStore } from "../fabricate/store.js";
 import type { AuthUser } from "../oauth.js";
 import type {
@@ -283,6 +284,79 @@ describe("place_order money gates (doc-hash + receipt, fail-closed)", () => {
     expect((placed!.payload as { receipt_status?: string }).receipt_status).toBe("holds");
   });
 
+  it("refuses receipt_violated: a failing physics claim blocks the debit", async () => {
+    const user: AuthUser = { sub: "u-gate-phys", email: "x@y.z" };
+    const store = new InMemoryFabricateStore();
+    const es = new RecordingEventStore();
+    const docId = out(openDocument({ initial: rotorStatorDocument(5.0) })).document_id;
+    // Persist a physics spec whose displacement limit cannot hold: the rotor
+    // (radius 5, z 1..9) under a 100 N lateral tip load vs a 1e-6 mm limit.
+    // Persisted BEFORE quoting so gate 1 (doc hash) holds and the refusal is
+    // attributable to gate 2 alone.
+    predictPhysicsTool(
+      {
+        document_id: docId,
+        part: "rotor",
+        loads: [{ region: { min: [-5, -5, 9], max: [5, 5, 9] }, force: [100, 0, 0] }],
+        supports: [{ region: { min: [-5, -5, 1], max: [5, 5, 1] } }],
+        label: "overload",
+        max_displacement_mm: 1e-6,
+      },
+      engine,
+    );
+
+    const { orderId, authorizationId } = await quotedAndApproved(docId, store, es, user);
+    const res = await placeOrder(
+      { order_id: orderId, authorization_id: authorizationId },
+      store,
+      es,
+      user,
+      engine,
+    );
+    expect(res.isError).toBe(true);
+    expect(text(res)).toContain("receipt violated");
+    expect(text(res)).toContain("physics.static.overload.displacement");
+    const after = await store.getOrder(orderId, user.sub);
+    expect(after?.state).toBe("QUOTED");
+    expect(after?.receipt_status).toBe("violated");
+    const blocked = es.events.find((e) => e.type === "order_blocked");
+    expect((blocked!.payload as { reason?: string }).reason).toBe("receipt_violated");
+  });
+
+  it("a passing physics spec alone (no clearance specs) re-verifies to 'holds'", async () => {
+    const user: AuthUser = { sub: "u-gate-phys-holds", email: "x@y.z" };
+    const store = new InMemoryFabricateStore();
+    const es = new RecordingEventStore();
+    const docId = out(openDocument({ initial: rotorStatorDocument(5.0) })).document_id;
+    predictPhysicsTool(
+      {
+        document_id: docId,
+        part: "rotor",
+        loads: [{ region: { min: [-5, -5, 9], max: [5, 5, 9] }, force: [100, 0, 0] }],
+        supports: [{ region: { min: [-5, -5, 1], max: [5, 5, 1] } }],
+        label: "tip-load",
+        max_displacement_mm: 10,
+      },
+      engine,
+    );
+
+    const { orderId, authorizationId } = await quotedAndApproved(docId, store, es, user);
+    const res = await placeOrder(
+      { order_id: orderId, authorization_id: authorizationId },
+      store,
+      es,
+      user,
+      engine,
+    );
+    expect(res.isError).toBeFalsy();
+    const body = out(res);
+    expect(body.state).toBe("PAID");
+    // The specs-presence check counts physics specs: this must NOT degrade to
+    // "unverified" just because there are no clearance specs.
+    expect(body.receipt.status).toBe("holds");
+    expect((await store.getOrder(orderId, user.sub))?.receipt_status).toBe("holds");
+  });
+
   it("consumed-authz replay skips the gates: a committed debit finalizes even after drift", async () => {
     const user: AuthUser = { sub: "u-gate-replay", email: "x@y.z" };
     const store = new InMemoryFabricateStore();
diff --git a/packages/mcp/src/tools/ordering.ts b/packages/mcp/src/tools/ordering.ts
index e40e49bb3..e6692a2c3 100644
--- a/packages/mcp/src/tools/ordering.ts
+++ b/packages/mcp/src/tools/ordering.ts
@@ -36,6 +36,7 @@ import { resolveArtifactRefAsync } from "./artifact-store.js";
 import { getSession, hydrateSession } from "./session.js";
 import { docHash } from "./order.js";
 import { clearanceReceiptClaims } from "./clearance.js";
+import { physicsReceiptClaims } from "./physics.js";
 import type { SessionEventStore, SessionStore } from "../session-store.js";
 import type {
   FabArtifactRef,
@@ -400,7 +401,8 @@ export async function placeOrder(
   }
 
   // ── M4 gate 2: the design receipt must hold ──────────────────────────────
-  // Re-verify every persisted clearance spec at place time. Any failing claim
+  // Re-verify every persisted clearance spec (re-measured) and physics spec
+  // (re-solved at its stored fidelity) at place time. Any failing claim
   // refuses; any unverifiable claim refuses too (fail-closed — a claim that
   // can't verify never passes). A document with no claims proceeds flagged
   // "unverified" in the feed; an unavailable document likewise (noted).
@@ -412,10 +414,14 @@ export async function placeOrder(
       "consumed-authz idempotent replay — gates skipped (debit already committed); finalizing the paid order";
   } else if (!sessionDoc) {
     receiptNote = `receipt not re-verified (${docUnavailable ?? "document unavailable"}) — proceeding as unverified`;
-  } else if (!sessionDoc.clearance_specs?.length) {
-    receiptNote = "document carries no clearance specs — receipt status: unverified";
+  } else if (!sessionDoc.clearance_specs?.length && !sessionDoc.physics_specs?.length) {
+    receiptNote =
+      "document carries no clearance or physics specs — receipt status: unverified";
   } else {
-    const claims = clearanceReceiptClaims(sessionDoc, engine);
+    const claims = [
+      ...clearanceReceiptClaims(sessionDoc, engine),
+      ...physicsReceiptClaims(sessionDoc, engine),
+    ];
     const failing = claims.filter((c) => c.verdict === "fail").map((c) => c.id);
     const unverifiable = claims
       .filter((c) => c.verdict === "unverifiable")
@@ -438,7 +444,7 @@ export async function placeOrder(
         claims: failing,
       });
       return err(
-        `receipt violated — clearance claims fail at place time: ${failing.join(", ")}. Fix the design (or re-quote) before money moves.`,
+        `receipt violated — claims fail at place time: ${failing.join(", ")}. Fix the design (or re-quote) before money moves.`,
       );
     }
     if (unverifiable.length > 0) {
@@ -449,11 +455,11 @@ export async function placeOrder(
         claims: unverifiable,
       });
       return err(
-        `receipt unverifiable — clearance claims could not be re-checked: ${unverifiable.join(", ")}. Fail-closed: an unverifiable claim never passes; re-verify with check_clearance / verify_receipt before placing.`,
+        `receipt unverifiable — claims could not be re-checked: ${unverifiable.join(", ")}. Fail-closed: an unverifiable claim never passes; re-verify with check_clearance / predict_physics / verify_receipt before placing.`,
       );
     }
     receiptStatus = "holds";
-    receiptNote = `receipt holds — ${claims.length} clearance claim(s) re-verified at place time`;
+    receiptNote = `receipt holds — ${claims.length} claim(s) re-verified at place time`;
   }
 
   // Bind the fab bundle by reference (provided handle, else whatever the quote

From 215fcb8fed1f6a237710b787942cf1962b06d351 Mon Sep 17 00:00:00 2001
From: Cam Pedersen <cam@campedersen.com>
Date: Sun, 12 Jul 2026 15:15:07 -0400
Subject: [PATCH 3/3] Fix CI timeouts in physics order-gate tests; widen Stale
 epsilon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The two new place-order gate tests hit vitest's 5 s default on CI
  runners (two mesh FEA solves each): solve at resolution 12 — the gate
  semantics don't need FEA accuracy — and allow 30 s.
- STALE_REL_EPS 1e-9 → 1e-6 (review feedback): PCG converges to a
  tolerance, not bit-identical results, so the Holds/Stale boundary now
  sits above iterative-solver noise.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/mcp/src/__tests__/place-order-gates.test.ts |  8 ++++++--
 packages/mcp/src/tools/physics.ts                    | 10 ++++++----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/packages/mcp/src/__tests__/place-order-gates.test.ts b/packages/mcp/src/__tests__/place-order-gates.test.ts
index 2deff5bbd..d89885c35 100644
--- a/packages/mcp/src/__tests__/place-order-gates.test.ts
+++ b/packages/mcp/src/__tests__/place-order-gates.test.ts
@@ -284,7 +284,7 @@ describe("place_order money gates (doc-hash + receipt, fail-closed)", () => {
     expect((placed!.payload as { receipt_status?: string }).receipt_status).toBe("holds");
   });
 
-  it("refuses receipt_violated: a failing physics claim blocks the debit", async () => {
+  it("refuses receipt_violated: a failing physics claim blocks the debit", { timeout: 30_000 }, async () => {
     const user: AuthUser = { sub: "u-gate-phys", email: "x@y.z" };
     const store = new InMemoryFabricateStore();
     const es = new RecordingEventStore();
@@ -301,6 +301,9 @@ describe("place_order money gates (doc-hash + receipt, fail-closed)", () => {
         supports: [{ region: { min: [-5, -5, 1], max: [5, 5, 1] } }],
         label: "overload",
         max_displacement_mm: 1e-6,
+        // Coarse grid: the gate semantics under test don't need FEA accuracy,
+        // and CI runners hit the 5 s default timeout at predict resolution.
+        resolution: 12,
       },
       engine,
     );
@@ -323,7 +326,7 @@ describe("place_order money gates (doc-hash + receipt, fail-closed)", () => {
     expect((blocked!.payload as { reason?: string }).reason).toBe("receipt_violated");
   });
 
-  it("a passing physics spec alone (no clearance specs) re-verifies to 'holds'", async () => {
+  it("a passing physics spec alone (no clearance specs) re-verifies to 'holds'", { timeout: 30_000 }, async () => {
     const user: AuthUser = { sub: "u-gate-phys-holds", email: "x@y.z" };
     const store = new InMemoryFabricateStore();
     const es = new RecordingEventStore();
@@ -336,6 +339,7 @@ describe("place_order money gates (doc-hash + receipt, fail-closed)", () => {
         supports: [{ region: { min: [-5, -5, 1], max: [5, 5, 1] } }],
         label: "tip-load",
         max_displacement_mm: 10,
+        resolution: 12,
       },
       engine,
     );
diff --git a/packages/mcp/src/tools/physics.ts b/packages/mcp/src/tools/physics.ts
index 04e328a14..fd2e2c22b 100644
--- a/packages/mcp/src/tools/physics.ts
+++ b/packages/mcp/src/tools/physics.ts
@@ -40,10 +40,12 @@ export const PHYSICS_CLAIM_PREFIX = "physics.static.";
 /** Resolution per fidelity tier. Same solver; the grid is the only dial. */
 const TIER_RESOLUTION = { predict: 32, verify: 72 } as const;
 
-/** The voxel FEA is deterministic for identical inputs, so a re-solve on
- *  unchanged geometry reproduces the stored value exactly; any relative
- *  difference beyond float noise means the geometry (or grid) changed. */
-const STALE_REL_EPS = 1e-9;
+/** Re-solved values within this relative tolerance of the stored value are
+ *  "same geometry"; beyond it (but still under the limit) the receipt reads
+ *  Stale. The PCG solve converges to a tolerance, not to bit-identical
+ *  results, so this sits above iterative-solver noise while staying far
+ *  below any engineering-meaningful change. */
+const STALE_REL_EPS = 1e-6;
 
 const regionSchema = {
   type: "object" as const,