mcp: glyph_seal — standalone seal companion (0.3.0 push, PR 2/5) (#110)

Tier-2 of the 0.3.0 push.

`glyph_verify` already existed. The missing companion is `glyph_seal`:
emit the provenance block as JSON, no SVG, no embedding. Use cases:
- Store the seal next to an audit log entry; verify later without the
SVG
- Sign with an external key (regulated-industry workflow)
- Pipelines where SVG renders downstream — the seal travels separately

Same hash inputs as the seal embedded in `renderSvg`'s SVG `<metadata>`
block, so a standalone-sealed JSON object verifies cleanly against the
SVG that `glyph_render` produces from the same `(spec, rows, schema)`
tuple.

190/190 MCP tests pass (4 new). Biome clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: seanhanca <infraservice@livepeer.org>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

packages/mcp/src/server.test.ts

@@ -116,6 +116,7 @@ describe("Glyph MCP server", () => {
       "glyph_query",
       "glyph_regression",
       "glyph_render",
+      "glyph_seal",
       "glyph_spec_diff",
       "glyph_spec_patch",
       "glyph_story",
@@ -180,6 +181,7 @@ describe("Glyph MCP server", () => {
       "glyph_query",
       "glyph_regression",
       "glyph_render",
+      "glyph_seal",
       "glyph_spec_diff",
       "glyph_spec_patch",
       "glyph_story",
@@ -2318,6 +2320,79 @@ describe("Glyph MCP server", () => {
     });
   });
 
+  describe("glyph_seal (0.3.0 — standalone seal companion to verify)", () => {
+    const spec = {
+      data: { source: "inline" },
+      layers: [{ mark: "bar", encoding: { x: "a", y: "b" } }],
+    } as const;
+    const schema = [
+      { name: "a", type: "VARCHAR" },
+      { name: "b", type: "INTEGER" },
+    ];
+    const rows: ReadonlyArray<ReadonlyArray<unknown>> = [
+      ["hi", 1],
+      ["bye", 2],
+    ];
+
+    it("returns the provenance block with deterministic hashes", async () => {
+      const r1 = await callText(client, "glyph_seal", { spec, rows, schema });
+      expect(r1.isError).toBeFalsy();
+      const seal = JSON.parse(r1.text);
+      expect(seal.format).toBeDefined();
+      expect(seal.specHash).toMatch(/^[0-9a-f]{64}$/);
+      expect(seal.dataHash).toMatch(/^[0-9a-f]{64}$/);
+      expect(seal.rowCount).toBe(2);
+      // Second call with the same inputs produces the same hashes.
+      const r2 = await callText(client, "glyph_seal", { spec, rows, schema });
+      expect(JSON.parse(r2.text)).toEqual(seal);
+    });
+
+    it("seal matches the one embedded in the rendered SVG (round-trip with glyph_verify)", async () => {
+      const sealResp = await callText(client, "glyph_seal", { spec, rows, schema });
+      const seal = JSON.parse(sealResp.text);
+      const { compileSpec, parseSpec, renderSvg } = await import("@glyph/core");
+      const svg = renderSvg(compileSpec({ spec: parseSpec(spec), rows, schema }));
+      // The embedded seal in the SVG must match the standalone seal byte-for-byte.
+      const embeddedMatch = svg.match(
+        /<metadata id="glyph-provenance"[^>]*>[\s\S]*?<!\[CDATA\[([\s\S]*?)\]\]>[\s\S]*?<\/metadata>/,
+      );
+      expect(embeddedMatch).not.toBeNull();
+      const embedded = JSON.parse(embeddedMatch![1]!);
+      expect(embedded.specHash).toBe(seal.specHash);
+      expect(embedded.dataHash).toBe(seal.dataHash);
+      expect(embedded.scaleDigest).toBe(seal.scaleDigest);
+    });
+
+    it("rejects an invalid spec", async () => {
+      const r = await callText(client, "glyph_seal", {
+        spec: { layers: [{ mark: "not-a-real-mark", encoding: {} }] },
+        rows: [],
+        schema: [],
+      });
+      expect(r.isError).toBe(true);
+      expect(r.text).toContain("spec invalid");
+    });
+
+    it("works for self-contained chart specs with empty rows (e.g. hierarchy / function data)", async () => {
+      // A chart-spec with self-contained data shape — no rows/schema needed.
+      const hierarchySpec = {
+        data: {
+          hierarchy: { name: "root", children: [{ name: "a", value: 1 }] },
+        },
+        layers: [{ mark: "treemap", encoding: {} }],
+      };
+      const r = await callText(client, "glyph_seal", {
+        spec: hierarchySpec,
+        rows: [],
+        schema: [],
+      });
+      expect(r.isError).toBeFalsy();
+      const seal = JSON.parse(r.text);
+      expect(seal.specHash).toMatch(/^[0-9a-f]{64}$/);
+      expect(seal.rowCount).toBe(0);
+    });
+  });
+
   describe("multi-modal sync (PR73 / PLAN 2.1)", () => {
     it("glyph_render with modalities=['chart','table'] returns rows-sample bundle", async () => {
       const r = await callText(client, "glyph_render", {

packages/mcp/src/server.ts

@@ -192,6 +192,8 @@ const MCP_TOOLS = [
   // a verify verb. Without it, the seal is opaque — agents can't ask
   // "is this SVG genuinely from this spec + data?" through MCP.
   { name: "glyph_verify", since: "0.0.21" },
+  // ---- 0.3.0 — `glyph_seal` standalone-seal companion to glyph_verify --
+  { name: "glyph_seal", since: "0.3.0" },
   // ---- Joy of Math PR E5 — natural-language story composer -----------
   // The "bar-raiser" agent-facing endpoint. Same `(intent, audience,
   // theme, duration_ms)` → same JSON; no LLM call. See the
@@ -3393,6 +3395,86 @@ export function createServer(state: ServerState = new ServerState()): {
       }),
   );
 
+  // ----- glyph_seal (0.3.0) ------------------------------------------------
+  // Emit the provenance seal as a standalone JSON object — without
+  // requiring (or producing) an SVG. The companion to glyph_verify:
+  // store the seal next to your audit log, then later prove the SVG you
+  // received matches by re-computing the seal from (spec, rows, schema)
+  // and comparing. Useful in pipelines where the SVG is rendered
+  // downstream (e.g. by a separate worker) and the seal must travel
+  // independently for compliance / audit-trail purposes.
+  //
+  // Pure function — same (spec, rows, schema) → byte-identical seal.
+  // Same hash inputs as the seal embedded in renderSvg's output, so a
+  // standalone-sealed JSON object verifies cleanly against the SVG
+  // returned by glyph_render against the same inputs.
+  server.registerTool(
+    "glyph_seal",
+    {
+      title: "Compute the cryptographic provenance seal for a chart",
+      description:
+        "0.3.0 — emit the provenance seal for a (spec, rows, schema) tuple as JSON, without producing an SVG. Returns `{ format, specHash, dataHash, libraryVersion, rowCount, scaleDigest }` — the same block embedded in `glyph_render`'s SVG `<metadata>`. Use this when you want to store the seal alongside an audit log, sign it with an external key, or send it through a pipeline where the SVG is rendered downstream.",
+      inputSchema: {
+        spec: z.unknown().describe("The Glyph spec to seal."),
+        rows: z
+          .array(z.array(z.unknown()))
+          .default([])
+          .describe(
+            "Positional rows matching `schema`. Pass an empty array for self-contained specs (compose, function-data, hierarchy, …) where the spec carries its own inputs.",
+          ),
+        schema: z
+          .array(z.object({ name: z.string(), type: z.string() }))
+          .default([])
+          .describe(
+            "Column schema (name + DuckDB type) for the rows. Empty for self-contained specs.",
+          ),
+      },
+    },
+    async ({ spec, rows, schema }) =>
+      state.serial(async () => {
+        const parsed = safeParseSpec(spec);
+        if (!parsed.ok) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: `glyph_seal: spec invalid: ${parsed.error.message}`,
+              },
+            ],
+          };
+        }
+        try {
+          const scene = compileSpec({ spec: parsed.spec, rows, schema });
+          const prov = scene.provenance;
+          if (!prov) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text" as const,
+                  text: "glyph_seal: compiler produced a scene without provenance (regression)",
+                },
+              ],
+            };
+          }
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(prov, null, 2) }],
+          };
+        } catch (err) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: `glyph_seal: compile failed: ${(err as Error).message ?? String(err)}`,
+              },
+            ],
+          };
+        }
+      }),
+  );
+
   // ----- glyph_verify (Moat PR1) -------------------------------------------
   // Cryptographic provenance verification. Closes the loop on the seal
   // every renderSvg attaches: an agent passes a spec + the data it