@wenathlan/devthink 2.0.12 → 2.0.14

package/tests/agentwork.test.ts

@@ -0,0 +1,356 @@
+import { describe, expect, it } from "vitest";
+import {
+  aggregatereport,
+  arbitrationcaseof,
+  costentryof,
+  depthlimitof,
+  depthoflineage,
+  interleave,
+  lessondecay,
+  lessonmatches,
+  lessonrecordof,
+  lessonreuse,
+  loadreportof,
+  prioritylaneof,
+  releasecase,
+  scalesuggestion,
+  sharedcostsplit,
+  spawnsubagent,
+} from "../agent.js";
+import {
+  aggregateconflictescalationgate,
+  aggregatemergegrade,
+  arbitrationverdictgate,
+  depthgate,
+  lanechangegate,
+  lessonsecretgate,
+  lessonsanitizestep,
+  scaleconsentgate,
+  spawngate,
+  subsetscopegate,
+} from "../policy.js";
+import type { agentrecord, agentscope, spawnrecord } from "../types.js";
+
+const now = 1_800_000_000_000;
+
+/** Builds one fleet record fixture with every value user chosen. */
+function record(over: Partial<agentrecord> = {}): agentrecord {
+  return {
+    id: "a1",
+    name: "scout",
+    role: "worker",
+    origin: "https://example.com",
+    state: "active",
+    registeredat: now,
+    lastseenat: now,
+    ...over,
+  };
+}
+
+/** Builds one parent scope fixture inside the session grants. */
+function parentscope(over: Partial<agentscope> = {}): agentscope {
+  return {
+    agentid: "a1",
+    origins: ["https://example.com", "https://shop.example"],
+    toolnamespaces: ["browser", "memory"],
+    actionkinds: ["observe", "readtext", "click"],
+    ...over,
+  };
+}
+
+describe("agentwork spawning and depth limits", () => {
+  it("spawns a child under its parent with the copied scope and refuses paused parents and lineage depth jumps", () => {
+    const parent = record({ id: "p1", name: "planner" });
+    const spawned = spawnsubagent({
+      records: [parent],
+      spawns: [],
+      spec: { parentid: "p1", objective: "Read the pricing table", depth: 1 },
+      parentscope: parentscope(),
+      id: "c1",
+      now,
+    });
+    expect(spawned.record.name).toBe("plannersub1");
+    expect(spawned.record.state).toBe("active");
+    expect(spawned.scope.origins).toEqual(["https://example.com", "https://shop.example"]);
+    expect(spawned.scope.actionkinds).toEqual(["observe", "readtext", "click"]);
+    expect(spawned.spawn.objective).toBe("Read the pricing table");
+    expect(subsetscopegate({ child: spawned.scope, parent: parentscope() }).allowed).toBe(true);
+    const narrowed = spawnsubagent({
+      records: [parent],
+      spawns: [],
+      spec: {
+        parentid: "p1",
+        objective: "Read the shop only",
+        depth: 1,
+        narrowscope: { origins: ["https://shop.example"], actionkinds: ["readtext"] },
+      },
+      parentscope: parentscope(),
+      id: "c2",
+      now,
+    });
+    expect(narrowed.scope.origins).toEqual(["https://shop.example"]);
+    expect(narrowed.scope.actionkinds).toEqual(["readtext"]);
+    expect(() =>
+      spawnsubagent({
+        records: [record({ id: "p1", name: "planner", state: "paused" })],
+        spawns: [],
+        spec: { parentid: "p1", objective: "No spawn from a paused parent", depth: 1 },
+        parentscope: parentscope(),
+        id: "c3",
+        now,
+      }),
+    ).toThrow(/paused/i);
+    expect(() =>
+      spawnsubagent({
+        records: [parent],
+        spawns: [],
+        spec: { parentid: "p1", objective: "Depth must stay one level under the parent", depth: 3 },
+        parentscope: parentscope(),
+        id: "c4",
+        now,
+      }),
+    ).toThrow(/exactly one level under/i);
+    expect(
+      spawngate({ parentscope: parentscope(), objectiveorigin: "https://example.com", parentstate: "active" }).allowed,
+    ).toBe(true);
+    expect(
+      spawngate({
+        parentscope: parentscope({ origins: ["https://example.com"] }),
+        objectiveorigin: "https://outside.example",
+        parentstate: "active",
+      }).allowed,
+    ).toBe(false);
+  });
+
+  it("computes the lineage depth from the spawn records and refuses the configured depth limit while an absent limit stays unbounded", () => {
+    const spawns: spawnrecord[] = [
+      { id: "s1", parentid: "p1", childid: "c1", role: "worker", depth: 1, at: now },
+      { id: "s2", parentid: "c1", childid: "g1", role: "worker", depth: 2, at: now },
+      { id: "s3", parentid: "p1", childid: "c2", role: "worker", depth: 1, at: now },
+    ];
+    expect(depthoflineage({ spawns, agentid: "p1" })).toBe(0);
+    expect(depthoflineage({ spawns, agentid: "c1" })).toBe(1);
+    expect(depthoflineage({ spawns, agentid: "g1" })).toBe(2);
+    expect(depthlimitof({ spawns, agentid: "g1", limit: { maxdepth: 3 } }).allowed).toBe(true);
+    const refused = depthlimitof({ spawns, agentid: "g1", limit: { maxdepth: 1 } });
+    expect(refused.allowed).toBe(false);
+    expect(refused.depth).toBe(2);
+    expect(depthlimitof({ spawns, agentid: "g1", limit: {} }).allowed).toBe(true);
+    expect(depthgate({ depth: 3, limit: { maxdepth: 2 } }).allowed).toBe(false);
+    expect(depthgate({ depth: 3, limit: {} }).allowed).toBe(true);
+  });
+});
+
+describe("agentwork aggregation and interleaving", () => {
+  it("merges parallel outputs with per agent provenance, resolves conflicts by policy order and escalates the unresolved", () => {
+    const cells = [
+      { agentid: "a1", runid: "run1", section: "output", output: "The price table holds 14 rows." },
+      { agentid: "a2", runid: "run2", section: "output", output: "The price table holds 15 rows." },
+      { agentid: "a1", runid: "run1", section: "notes", output: "The table sits under the hero." },
+    ];
+    const open = aggregatereport({ id: "agg1", subject: "The pricing table read", cells, now });
+    expect(open.state).toBe("open");
+    expect(open.conflicts).toEqual([{ key: "output" }]);
+    const verdict = aggregateconflictescalationgate({
+      unresolved: open.conflicts
+        .filter((conflict) => conflict.resolvedby === undefined)
+        .map((conflict) => conflict.key),
+    });
+    expect(verdict.allowed).toBe(false);
+    const ordered = aggregatereport({
+      id: "agg2",
+      subject: "The pricing table read",
+      cells,
+      conflictorder: ["a2", "a1"],
+      now,
+    });
+    expect(ordered.state).toBe("merged");
+    expect(ordered.conflicts).toEqual([{ key: "output", resolvedby: "a2" }]);
+    expect(ordered.cells.every((cell) => cell.agentid !== "" && cell.section !== "")).toBe(true);
+    expect(aggregatemergegrade("aggregatereport").allowed).toBe(true);
+    expect(aggregatemergegrade("spawnsubagent").allowed).toBe(false);
+  });
+
+  it("orders the actions of concurrent agents into one timeline while every event keeps its lane visible", () => {
+    const lanes = [
+      { name: "interactive", priority: 10, interactive: true, agentids: ["a1"] },
+      { name: "background", priority: 1, agentids: ["a2"] },
+    ];
+    const events = [
+      { agentid: "a2", kind: "readtext", summary: "The background agent read the table.", at: now + 300 },
+      { agentid: "a1", kind: "click", summary: "The interactive agent opened the pricing page.", at: now + 100 },
+      { agentid: "a2", kind: "observe", summary: "The background agent observed the hero.", at: now + 200 },
+    ];
+    const merged = interleave({ events, lanes });
+    expect(merged.map((event) => event.kind)).toEqual(["click", "observe", "readtext"]);
+    expect(merged[0]?.lane).toBe("interactive");
+    expect(merged[1]?.lane).toBe("background");
+    expect(merged[2]?.lane).toBe("background");
+  });
+});
+
+describe("agentwork lessonshare", () => {
+  it("records sanitized lessons, serves the matching ones, counts reuse and decays the stale", () => {
+    const first = lessonrecordof({
+      id: "l1",
+      agentid: "a1",
+      finding: "The pricing table loads only after the hero settles.",
+      origin: "https://example.com",
+      now,
+    });
+    const second = lessonrecordof({
+      id: "l2",
+      agentid: "a2",
+      finding: "The login form refuses pasted passwords on the shop.",
+      origin: "https://shop.example",
+      now,
+    });
+    expect(first.reusecount).toBe(0);
+    expect(lessonsecretgate({ text: "The api key = sk-abc123def456ghi789 of the shop." }).allowed).toBe(false);
+    expect(lessonsecretgate({ text: "The pricing table loads only after the hero settles." }).allowed).toBe(true);
+    expect(lessonsanitizestep("The token: abc123 loads the pricing table.")).toContain("[redacted]");
+    const lessons = [first, second];
+    const matches = lessonmatches({
+      lessons,
+      task: "Read the pricing table of the hero again",
+      origin: "https://example.com",
+    });
+    expect(matches.map((lesson) => lesson.id)).toContain("l1");
+    expect(matches.map((lesson) => lesson.id)).not.toContain("l2");
+    const reused = lessonreuse({ lessons, id: "l1", now: now + 5000 });
+    expect(reused.find((lesson) => lesson.id === "l1")?.reusecount).toBe(1);
+    expect(reused.find((lesson) => lesson.id === "l1")?.lastusedat).toBe(now + 5000);
+    const decayed = lessondecay({ lessons: reused, now: now + 10_000_000, stalewindow: 1_000_000 });
+    expect(decayed.map((lesson) => lesson.id)).toEqual(["l1"]);
+    const decayedall = lessondecay({ lessons: [first, second], now: now + 10_000_000, stalewindow: 1_000_000 });
+    expect(decayedall.length).toBe(0);
+    expect(lessondecay({ lessons: [first], now }).length).toBe(1);
+  });
+});
+
+describe("agentwork arbitration and lanes", () => {
+  it("grants the first requester by default, honors the priority lane, and releases when the holder finishes", () => {
+    const lanes = [
+      { name: "background", priority: 1, agentids: ["a1"] },
+      { name: "fastlane", priority: 9, agentids: ["a2"] },
+    ];
+    const byfirst = arbitrationcaseof({
+      id: "case1",
+      resource: "https://example.com/pricing",
+      origin: "https://example.com",
+      requesters: ["a1", "a3"],
+      lanes: [],
+      now,
+    });
+    expect(byfirst.verdict?.holderagentid).toBe("a1");
+    expect(byfirst.verdict?.reason).toContain("first requester");
+    const bylane = arbitrationcaseof({
+      id: "case2",
+      resource: "https://example.com/pricing",
+      origin: "https://example.com",
+      requesters: ["a1", "a2"],
+      lanes,
+      now,
+    });
+    expect(bylane.verdict?.holderagentid).toBe("a2");
+    expect(bylane.verdict?.lane).toBe("fastlane");
+    expect(() =>
+      arbitrationcaseof({
+        id: "case3",
+        resource: "https://example.com/pricing",
+        origin: "https://example.com",
+        requesters: ["a1"],
+        lanes,
+        now,
+      }),
+    ).toThrow(/at least two requesting agents/i);
+    expect(
+      arbitrationverdictgate({
+        holderagentid: "a1",
+        origin: "https://example.com",
+        origingrants: ["https://example.com"],
+      }).allowed,
+    ).toBe(true);
+    expect(
+      arbitrationverdictgate({
+        holderagentid: "a1",
+        origin: "https://outside.example",
+        origingrants: ["https://example.com"],
+      }).allowed,
+    ).toBe(false);
+    expect(
+      arbitrationverdictgate({ holderagentid: "a1", origin: "https://example.com", sessionlockholder: "another-run" })
+        .allowed,
+    ).toBe(false);
+    const released = releasecase({ cases: [bylane], id: "case2", holderfinished: true, now: now + 1000 });
+    expect(released.state).toBe("released");
+    expect(released.closedat).toBe(now + 1000);
+    expect(() => releasecase({ cases: [bylane], id: "case2", holderfinished: false, now })).toThrow(
+      /holder.*still works/i,
+    );
+  });
+
+  it("ranks the queue by lane priority, keeps sensitive steps in the interactive lane and prevents lane starvation through the round robin fallback", () => {
+    const lanes = [
+      { name: "interactive", priority: 10, interactive: true },
+      { name: "high", priority: 5 },
+      { name: "low", priority: 1 },
+    ];
+    const tasks = [
+      { id: "high1", lane: "high", priority: 2, enqueuedat: now },
+      { id: "high2", lane: "high", priority: 1, enqueuedat: now + 1 },
+      { id: "low1", lane: "low", priority: 9, enqueuedat: now },
+      { id: "low2", lane: "low", priority: 1, enqueuedat: now + 1 },
+      { id: "sensitive1", lane: "low", priority: 1, sensitive: true, enqueuedat: now },
+    ];
+    const ordered = prioritylaneof({ tasks, lanes });
+    expect(ordered[0]?.id).toBe("sensitive1");
+    expect(ordered[0]?.lane).toBe("interactive");
+    expect(ordered.slice(1).map((task) => task.lane)).toEqual(["high", "low", "high", "low"]);
+    expect(lanechangegate({ lane: { name: "low", priority: 1 }, sensitive: true, confirmed: false }).allowed).toBe(
+      false,
+    );
+    expect(lanechangegate({ lane: { name: "low", priority: 1 }, sensitive: true, confirmed: true }).allowed).toBe(true);
+    expect(lanechangegate({ lane: { name: "low", priority: 1 }, sensitive: false, confirmed: false }).allowed).toBe(
+      true,
+    );
+  });
+});
+
+describe("agentwork scaleworkers and costshare", () => {
+  it("suggests spawning on low load, pausing on throttle, never acting without consent and splitting the shared costs", () => {
+    const reports = [
+      loadreportof({ origin: "https://example.com", concurrency: 1, latency: 80, now }),
+      loadreportof({ origin: "https://shop.example", concurrency: 3, latency: 4500, now }),
+    ];
+    const suggestions = scalesuggestion({ reports, lowthreshold: 200, throttlethreshold: 4000 });
+    expect(suggestions.find((suggestion) => suggestion.origin === "https://example.com")?.suggestion).toBe("spawn");
+    expect(suggestions.find((suggestion) => suggestion.origin === "https://shop.example")?.suggestion).toBe("pause");
+    expect(scaleconsentgate({ userconsented: false, origin: "https://example.com" }).allowed).toBe(false);
+    expect(scaleconsentgate({ userconsented: true, origin: "https://example.com" }).allowed).toBe(true);
+    expect(
+      scalesuggestion({
+        reports: [loadreportof({ origin: "https://example.com", concurrency: 2, latency: 900, now })],
+        lowthreshold: 200,
+        throttlethreshold: 4000,
+      }).map((suggestion) => suggestion.suggestion),
+    ).toEqual(["hold"]);
+    const entries = [
+      costentryof({ agentid: "a1", runid: "run1", units: 4, description: "The pricing table read.", now }),
+      costentryof({ agentid: "a2", runid: "run2", units: 2, description: "The pricing table read.", now }),
+      costentryof({ agentid: "a1", runid: "run1", units: 3, description: "The hero screenshot.", now }),
+    ];
+    const split = sharedcostsplit({ entries });
+    const a1 = split.find((share) => share.agentid === "a1");
+    const a2 = split.find((share) => share.agentid === "a2");
+    expect(a1?.share).toBe(3);
+    expect(a2?.share).toBe(0);
+    expect(a1?.units).toBe(3 + 3);
+    expect(a2?.units).toBe(3);
+    expect(a1?.sharedwith).toEqual(["a2"]);
+    expect(a2?.sharedwith).toEqual(["a1"]);
+    expect(() =>
+      costentryof({ agentid: "a1", units: 0, description: "A zero cost never enters the ledger.", now }),
+    ).toThrow(/positive/i);
+  });
+});

package/tests/apifreeze.test.ts

@@ -0,0 +1,290 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import {
+  apifreezedate,
+  apifreezerelease,
+  backgroundsurfacemessages,
+  capmanifestdiff,
+  capmanifestof,
+  clisurfacecommands,
+  deprecationnoticeof,
+  deprecatedfields,
+  deprecationwindow,
+  librarysurfaceexports,
+  mcpsurfacekinds,
+  mcpsurfacetools,
+  negotiateprotocol,
+  pagebridgesurfacemessages,
+  permissioncoverage,
+  popupsurfacemessages,
+  protocolmajorof,
+  protocolsupported,
+  sharedprotocolversion,
+  sidepanelsurfacemessages,
+  warnonce,
+} from "../apifreeze.js";
+import { actionkindids, pinnedprotocolversion, protocolmajorversion, protocolversion } from "../types.js";
+import {
+  errorcodetable,
+  framingrules,
+  frozenmessagecatalog,
+  memoryitemframe,
+  responseenvelopeoutcomes,
+  stabilityrules,
+} from "../protocol.js";
+import { alltools, buildtoolcatalog } from "../tools.js";
+import { capmanifestdriftgate, protocolnegotiationgate, unknownfieldsgate } from "../policy.js";
+
+describe("the protocolv2 api freeze of 1.1.91", () => {
+  it("pins the protocol major two across the version constants", () => {
+    expect(protocolmajorversion).toBe(2);
+    expect(pinnedprotocolversion.protocolmajor).toBe(2);
+    expect(pinnedprotocolversion.protocolversion).toBe(protocolversion);
+    expect(protocolsupported).toEqual({ minimum: 2, maximum: 2 });
+    expect(apifreezerelease).toBe("1.1.91");
+    expect(apifreezedate).toBe("2026-08-31");
+  });
+
+  it("negotiates the protocol major with new and future clients and refuses version one below the floor", () => {
+    expect(negotiateprotocol({})).toEqual({ agreed: true, major: 2 });
+    expect(negotiateprotocol({ client: 2 })).toEqual({ agreed: true, major: 2 });
+    expect(negotiateprotocol({ client: "2.0.0" })).toEqual({ agreed: true, major: 2 });
+    /* the 2.0.0 sunset closed the window: a version one declaration refuses below the floor the sunset raised, with the migration path inside the refusal */
+    const legacy = negotiateprotocol({ client: "1.1.54" });
+    expect(legacy.agreed).toBe(false);
+    expect(legacy.reason).toContain("below the supported floor of 2");
+    expect(legacy.reason).toContain("migrateplan");
+    expect(legacy.reason).toContain("docs/migrationguide.md");
+    expect(negotiateprotocol({ client: 1 }).agreed).toBe(false);
+    const future = negotiateprotocol({ client: "3.0.0" });
+    expect(future.agreed).toBe(false);
+    expect(future.reason).toContain("the supported protocol versions are 2 through 2");
+    expect(negotiateprotocol({ client: "0.0.1" }).agreed).toBe(false);
+    expect(protocolmajorof(undefined)).toBeUndefined();
+    expect(protocolmajorof(2)).toBe(2);
+    expect(protocolmajorof("")).toBeUndefined();
+  });
+
+  it("answers the highest shared protocol major of one client list", () => {
+    /* the floor raise filters the version one side away: a list that carries both majors negotiates up to two while a version one only list answers the empty intersection */
+    expect(sharedprotocolversion([1, 2])).toEqual({ shared: true, major: 2 });
+    expect(sharedprotocolversion([2, 3])).toEqual({ shared: true, major: 2 });
+    expect(sharedprotocolversion([1, 3]).shared).toBe(false);
+    expect(sharedprotocolversion([1]).shared).toBe(false);
+    expect(sharedprotocolversion([3, 4]).shared).toBe(false);
+    expect(sharedprotocolversion([3, 4]).reason).toContain("supported range of 2 through 2");
+  });
+
+  it("gates the negotiation and the unknown fields by the negotiated major", () => {
+    expect(protocolnegotiationgate({})).toEqual({
+      allowed: true,
+      major: 2,
+      reason: expect.stringContaining("protocolv2 default"),
+    });
+    /* the 2.0.0 sunset semantics: the version one branch of the gate refuses below the floor and names the conversion path */
+    const legacy = protocolnegotiationgate({ client: "1.1.54" });
+    expect(legacy.allowed).toBe(false);
+    expect(legacy.major).toBeUndefined();
+    expect(legacy.reason).toContain("below the supported floor");
+    expect(legacy.reason).toContain("migrateplan");
+    expect(legacy.reason).toContain("docs/migrationguide.md");
+    expect(protocolnegotiationgate({ client: "3.0.0" }).allowed).toBe(false);
+    expect(protocolnegotiationgate({ client: "3.0.0" }).reason).toContain(
+      "supported protocol versions are 2 through 2",
+    );
+    expect(unknownfieldsgate({ unknown: [], major: 2 }).allowed).toBe(true);
+    expect(unknownfieldsgate({ unknown: ["mysteryfield"], major: 2 }).allowed).toBe(false);
+    expect(unknownfieldsgate({ unknown: ["mysteryfield"], major: 2 }).reason).toContain("Strict schema validation");
+    /* the version one tolerance closed with the window: the strict refusal answers every major the line accepts and the closed branch records the sunset */
+    expect(unknownfieldsgate({ unknown: ["mysteryfield"], major: 1 }).allowed).toBe(false);
+    expect(unknownfieldsgate({ unknown: ["mysteryfield"], major: 1 }).reason).toContain("closed at 2.0.0");
+    expect(capmanifestdriftgate({ drift: [] }).allowed).toBe(true);
+    expect(capmanifestdriftgate({ drift: ["removed message capmanifest"] }).allowed).toBe(false);
+  });
+
+  it("records the executed 2.0.0 sunset with the empty registry and the window history", () => {
+    /* the 2.0.0 sunset removed every deprecated field the window carried: the registry hashes as the empty contract while the window record stays as history */
+    expect(deprecatedfields).toEqual([]);
+    expect(deprecationwindow).toEqual({ opens: "1.1.91", closes: "2.0.0" });
+    expect(deprecationnoticeof("umd", "Devthink")).toBeUndefined();
+    expect(deprecationnoticeof("mcp", "protocolversion")).toBeUndefined();
+    /* warnonce stays intact and answers silence for every pair the empty registry no longer registers */
+    const first = warnonce({ warned: new Set<string>(), surface: "umd", field: "Devthink" });
+    expect(first.notice).toBeUndefined();
+    expect(first.warned.has("umd.Devthink")).toBe(false);
+    expect(warnonce({ warned: first.warned, surface: "umd", field: "Devthink" }).notice).toBeUndefined();
+    expect(warnonce({ warned: new Set<string>(), surface: "mcp", field: "protocolversion" }).notice).toBeUndefined();
+    expect(warnonce({ warned: new Set<string>(), surface: "nowhere", field: "unknown" }).notice).toBeUndefined();
+  });
+
+  it("freezes the immutable action kind identifiers with the policy vocabulary", () => {
+    expect(actionkindids.length).toBe(335);
+    expect(new Set(actionkindids).size).toBe(actionkindids.length);
+    for (const kind of actionkindids) expect(kind).toMatch(/^[a-z0-9]+$/);
+  });
+
+  it("freezes the response envelope, the error code table and the framing rules", () => {
+    expect(responseenvelopeoutcomes).toEqual(["success", "error", "cancel"]);
+    expect(errorcodetable.map((entry) => entry.code)).toEqual([
+      "parse",
+      "method",
+      "params",
+      "internal",
+      "consentrefused",
+    ]);
+    for (const entry of errorcodetable) {
+      expect(["never", "immediate", "afterbackoff"]).toContain(entry.retry);
+      expect(entry.semantics.length).toBeGreaterThan(30);
+    }
+    expect(framingrules.stdio).toContain("newline");
+    expect(framingrules.http).toContain("http post");
+    expect(stabilityrules.additive).toContain("additive");
+    expect(stabilityrules.breaking).toContain("new major protocol version");
+    expect(stabilityrules.window).toContain("2.0.0");
+  });
+
+  it("enumerates the frozen message catalog with its schemas and carriers", () => {
+    expect(frozenmessagecatalog.length).toBe(23);
+    const schemas = new Set(frozenmessagecatalog.map((entry) => entry.schema));
+    expect(schemas.size).toBe(10);
+    for (const entry of frozenmessagecatalog) {
+      expect(entry.type).toMatch(/^[a-z]+$/);
+      expect(entry.schema).toMatch(/^schemas\/[a-z]+\.schema\.json$/);
+    }
+  });
+
+  it("accepts the versioned memory item envelope and refuses a foreign version", () => {
+    const provenance = { origin: "https://example.com", runid: "run1", stepid: "step1", capturedat: 1 };
+    const frame = memoryitemframe({ key: "k", value: 1, provenance });
+    expect(frame.provenance.origin).toBe("https://example.com");
+    expect(() => memoryitemframe({ version: "0.0.1", key: "k", value: 1, provenance })).toThrow(
+      "Unsupported protocol version.",
+    );
+  });
+
+  it("verifies every capmanifest matches its surface", async () => {
+    if (!existsSync("dist/caps"))
+      return; /* the capmanifest artifacts ride the build: the pass runs after pnpm build in the validate chain and the ci lanes */
+    for (const surface of ["background", "pagebridge", "sidepanel", "popup", "cli", "library", "mcp"] as const) {
+      const manifest = capmanifestof(surface);
+      const stored = JSON.parse(await readFile(`dist/caps/${surface}.json`, "utf8")) as {
+        surface: string;
+        release: string;
+        protocolmajor: number;
+        messages: string[];
+        kinds: string[];
+        permissions: string[];
+        toolversions?: Record<string, number>;
+      };
+      expect(manifest.surface).toBe(stored.surface);
+      expect(manifest.release).toBe(stored.release);
+      expect(manifest.protocolmajor).toBe(stored.protocolmajor);
+      expect(manifest.messages).toEqual(stored.messages);
+      expect(manifest.kinds).toEqual(stored.kinds);
+      expect(manifest.permissions).toEqual(stored.permissions);
+      expect(manifest.toolversions ?? undefined).toEqual(stored.toolversions ?? undefined);
+      expect(manifest.release).toBe(protocolversion);
+      expect(new Set(manifest.messages).size).toBe(manifest.messages.length);
+    }
+  });
+
+  it("matches the mcp capmanifest with the frozen tool catalog and its per tool versions", () => {
+    const catalog = buildtoolcatalog();
+    const tools = alltools(catalog);
+    const manifest = capmanifestof("mcp");
+    expect(manifest.messages.sort()).toEqual(tools.map((tool) => tool.name).sort());
+    expect(manifest.toolversions).toBeDefined();
+    for (const tool of tools) {
+      expect(manifest.toolversions?.[tool.name]).toBe(tool.version);
+      expect(tool.version).toBeGreaterThanOrEqual(1);
+    }
+    expect(mcpsurfacetools.length).toBe(tools.length);
+    expect(mcpsurfacekinds.every((kind) => actionkindids.includes(kind as never))).toBe(true);
+  });
+
+  it("matches the manifest permissions with the capmanifest declarations", async () => {
+    const manifest = JSON.parse(await readFile("web/manifest.json", "utf8")) as {
+      permissions: string[];
+      optional_permissions: string[];
+      optional_host_permissions: string[];
+    };
+    const declared = new Set([
+      ...capmanifestof("background").permissions,
+      ...capmanifestof("sidepanel").permissions,
+      ...capmanifestof("popup").permissions,
+      ...capmanifestof("mcp").permissions,
+    ]);
+    for (const permission of [
+      ...manifest.permissions,
+      ...manifest.optional_permissions,
+      ...manifest.optional_host_permissions,
+    ]) {
+      expect(declared.has(permission)).toBe(true);
+      expect(permissioncoverage[permission]).toBeDefined();
+    }
+    for (const [permission, coverage] of Object.entries(permissioncoverage)) {
+      expect(coverage.messages.every((message) => backgroundsurfacemessages.includes(message))).toBe(true);
+      expect(coverage.kinds.every((kind) => actionkindids.includes(kind as never))).toBe(true);
+    }
+  });
+
+  it("flags capability drift between two capability manifests", () => {
+    const background = capmanifestof("background");
+    const widened = {
+      ...background,
+      messages: [...background.messages, "newmessage"],
+      permissions: background.permissions.slice(0, -1),
+    };
+    const drift = capmanifestdiff(background, widened);
+    expect(drift).toContain("added message newmessage on the background surface");
+    expect(drift.some((entry) => entry.startsWith("removed permission"))).toBe(true);
+    const mcp = capmanifestof("mcp");
+    const bumped = { ...mcp, toolversions: { ...(mcp.toolversions ?? {}), "browser.click": 3 } };
+    expect(capmanifestdiff(mcp, bumped)).toContain("changed tool browser.click from version 2 to 3 on the mcp surface");
+    expect(capmanifestdiff(background, { ...background })).toEqual([]);
+  });
+
+  it("keeps the frozen surface lists stable and complete", () => {
+    expect(backgroundsurfacemessages.length).toBe(234);
+    expect(backgroundsurfacemessages).toContain("capmanifest");
+    expect(sidepanelsurfacemessages.length).toBe(168);
+    expect(popupsurfacemessages.length).toBe(26);
+    expect(pagebridgesurfacemessages.length).toBe(31);
+    expect(clisurfacecommands).toContain("describe");
+    expect(clisurfacecommands).toContain("commands");
+    expect(librarysurfaceexports.length).toBeGreaterThan(3000);
+    expect(librarysurfaceexports).toContain("capmanifestof");
+    expect(librarysurfaceexports).toContain("parseproposal");
+  });
+
+  it("verifies the schema hash artifact stays stable", async () => {
+    if (!existsSync("dist/schemas"))
+      return; /* the schema artifacts ride the build: the pass runs after pnpm build in the validate chain and the ci lanes */
+    const packagejson = JSON.parse(await readFile("package.json", "utf8")) as { version: string };
+    const artifact = JSON.parse(await readFile("tests/apifreeze.json", "utf8")) as {
+      release: string;
+      frozezat: string;
+      scope: string[];
+      sizes: Record<string, number>;
+      hashes: Record<string, string>;
+    };
+    expect(artifact.release).toBe(packagejson.version);
+    expect(artifact.frozezat).toBe("2026-08-31");
+    expect(artifact.scope).toEqual(["background", "pagebridge", "sidepanel", "popup", "cli", "library", "mcp"]);
+    const schemafiles = (await readdir("dist/schemas")).filter((file) => file.endsWith(".json")).sort();
+    expect(schemafiles).toHaveLength(10);
+    for (const file of schemafiles) {
+      const digest = createHash("sha256")
+        .update(await readFile(`dist/schemas/${file}`))
+        .digest("hex");
+      expect(artifact.hashes[`schemas/${file}`]).toBe(digest);
+    }
+    for (const surface of artifact.scope) {
+      expect(artifact.sizes[surface]).toBeGreaterThan(0);
+    }
+    expect(artifact.hashes["contract/actionkinds"]).toBeDefined();
+    expect(artifact.hashes["contract/librarysurfaceexports"]).toBeDefined();
+  });
+});