@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/org/ui-parity.test.mjs

@@ -1,560 +0,0 @@
-/**
- * ui-parity.test.mjs — Agent UI-parity helpers (full human-action mirror).
- *
- * The 360 wrappers in ui-parity.mjs are each a one-liner over call() from
- * client.mjs, so client.test.mjs already proves the transport contract (headers,
- * idempotency, fail-open, frame normalisation). Here we just prove a representative
- * slice across families ROUTES to the correct method name, POSTs the params body,
- * and returns the res frame — using the same injected fetchImpl (no network).
- *
- * Run: node --test lib/org/ui-parity.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  charterUpdateClauses,
-  charterGet,
-  memberCreate,
-  channelCreate,
-  sopCreate,
-  decisionSign,
-  taskUpdate,
-  settingsMintApiKey,
-  filePin,
-  emailSend,
-  emailMarkRead,
-  emailInbox,
-  emailMessage,
-  emailThread,
-  artifactCreate,
-  artifactAct,
-  artifactPatch,
-  artifactGet,
-  artifactList,
-  artifactCatalog,
-} from "./ui-parity.mjs";
-import { PROTOCOL_VERSION } from "./protocol.mjs";
-
-const BASE = "https://org.cohortapp.com";
-const TOKEN = "tok-abc";
-
-// Ambient COHORT_* tokens would leak into header assertions; clear them.
-delete process.env.COHORT_API_TOKEN;
-delete process.env.COHORT_TOKEN;
-
-/** A fake fetch that records calls and returns a canned res frame. */
-function fakeFetch(responder) {
-  const calls = [];
-  const impl = async (url, init) => {
-    calls.push({ url, init, headers: (init && init.headers) || {} });
-    const r = responder ? responder(url, init, calls.length - 1) : null;
-    const status = r && typeof r.status === "number" ? r.status : 200;
-    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
-    const body = r ? r.body : { ok: true, result: null };
-    return {
-      ok,
-      status,
-      headers: { get: (k) => (r && r.respHeaders ? r.respHeaders[k.toLowerCase()] : undefined) },
-      json: async () => body,
-    };
-  };
-  impl.calls = calls;
-  return impl;
-}
-
-// --- representative wrappers route to the right /v1 method -------------------
-
-test("ui-parity helpers route to their /v1 methods (one per family)", async () => {
-  const seen = [];
-  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
-  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
-  await charterUpdateClauses({ channelId: "c", clauses: [] }, o);
-  await charterGet({ memberId: "m" }, o);
-  await memberCreate({ kind: "AI", displayName: "Robin", roleTitle: "Eng", roleLevel: 4, teamId: "t" }, o);
-  await channelCreate({ slug: "ops", name: "Ops", kind: "TEAM" }, o);
-  await sopCreate({ channelId: "c", title: "Runbook" }, o);
-  await decisionSign({ decisionId: "d", memberSlug: "robin" }, o);
-  await taskUpdate({ taskId: "tk", priority: "P1" }, o);
-  await settingsMintApiKey({ name: "ci" }, o);
-  await filePin({ channelId: "c", name: "f.pdf", dataUrl: "data:," }, o);
-  assert.deepEqual(seen, [
-    `${BASE}/api/v1/charter.updateClauses`,
-    `${BASE}/api/v1/charter.get`,
-    `${BASE}/api/v1/member.create`,
-    `${BASE}/api/v1/channel.create`,
-    `${BASE}/api/v1/sop.create`,
-    `${BASE}/api/v1/decision.sign`,
-    `${BASE}/api/v1/board.updateTask`,
-    `${BASE}/api/v1/settings.mintApiKey`,
-    `${BASE}/api/v1/file.pin`,
-  ]);
-});
-
-test("ui-parity wrapper POSTs params + Bearer + x-org-protocol, returns the frame", async () => {
-  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "ch-1" } } }));
-  const frame = await channelCreate(
-    { slug: "ops", name: "Ops", kind: "TEAM" },
-    { base: BASE, token: TOKEN, idempotencyKey: "chan-ops", fetchImpl: f },
-  );
-  assert.deepEqual(frame, { ok: true, result: { id: "ch-1" } });
-  assert.equal(f.calls[0].init.method, "POST");
-  assert.equal(f.calls[0].url, `${BASE}/api/v1/channel.create`);
-  assert.equal(f.calls[0].headers.authorization, `Bearer ${TOKEN}`);
-  assert.equal(f.calls[0].headers["x-org-protocol"], String(PROTOCOL_VERSION));
-  assert.deepEqual(JSON.parse(f.calls[0].init.body), { slug: "ops", name: "Ops", kind: "TEAM" });
-});
-
-test("idempotent wrapper forwards a caller-supplied x-idempotency-key", async () => {
-  // member.create is idempotent but carries no natural id at creation time, so the
-  // caller SHOULD supply a stable key — verify it reaches the wire.
-  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
-  await memberCreate(
-    { kind: "AI", displayName: "Robin", roleTitle: "Eng", roleLevel: 4, teamId: "t" },
-    { base: BASE, token: TOKEN, idempotencyKey: "seed-robin", fetchImpl: f },
-  );
-  assert.equal(f.calls[0].headers["x-idempotency-key"], "seed-robin");
-});
-
-test("read-style method (charter.get) is a POST RPC, sends NO idempotency key", async () => {
-  const f = fakeFetch(() => ({ body: { ok: true, result: { memberId: "m" } } }));
-  const frame = await charterGet({ memberId: "m" }, { base: BASE, token: TOKEN, fetchImpl: f });
-  assert.equal(f.calls[0].init.method, "POST");
-  assert.equal(f.calls[0].headers["x-idempotency-key"], undefined);
-  assert.equal(frame.result.memberId, "m");
-});
-
-test("ui-parity wrappers fail open on transport throw (no throw, INTERNAL frame)", async () => {
-  const thrower = fakeFetch(() => { throw new Error("network"); });
-  const o = { base: BASE, token: TOKEN, fetchImpl: thrower };
-  for (const frame of [
-    await taskUpdate({ taskId: "tk" }, o),
-    await decisionSign({ decisionId: "d", memberSlug: "x" }, o),
-    await filePin({ channelId: "c", name: "f", dataUrl: "data:," }, o),
-  ]) {
-    assert.equal(frame.ok, false);
-    assert.equal(frame.error.code, "INTERNAL");
-  }
-});
-
-test("ui-parity wrapper surfaces a server error frame verbatim (FORBIDDEN_SCOPE 403)", async () => {
-  const f = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "admin only" } } }));
-  const frame = await settingsMintApiKey({ name: "ci" }, { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
-});
-
-// --- email family (companion spec §8 / §9.1) --------------------------------
-
-test("email wrappers route to their /v1 email.* methods and POST the params", async () => {
-  const seen = [];
-  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
-  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
-  await emailSend({ threadId: "t1", text: "re: hi", idempotencyId: "biz-1" }, o);
-  await emailMarkRead({ messageId: "m1" }, o);
-  await emailInbox({ unreadOnly: true, limit: 50 }, o);
-  await emailMessage({ id: "m1" }, o);
-  await emailThread({ threadId: "t1" }, o);
-  assert.deepEqual(seen, [
-    `${BASE}/api/v1/email.send`,
-    `${BASE}/api/v1/email.markRead`,
-    `${BASE}/api/v1/email.inbox`,
-    `${BASE}/api/v1/email.message`,
-    `${BASE}/api/v1/email.thread`,
-  ]);
-});
-
-test("email mutating wrappers carry x-idempotency-key; reads do not", async () => {
-  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
-  await emailSend({ threadId: "t1", text: "x", idempotencyId: "biz-1" }, { base: BASE, token: TOKEN, idempotencyKey: "send-1", fetchImpl: f });
-  assert.equal(f.calls[0].headers["x-idempotency-key"], "send-1");
-  await emailInbox({ limit: 1 }, { base: BASE, token: TOKEN, fetchImpl: f });
-  assert.equal(f.calls[1].headers["x-idempotency-key"], undefined, "sideEffecting:false reads send no key");
-  assert.equal(f.calls[1].init.method, "POST", "email reads are POST METHODS, not GET reads");
-});
-
-test("emailSend surfaces the approval_required result as a NORMAL frame", async () => {
-  const approval = { actionClass: "external_comms", payloadHash: "abc", intent: { to: ["x@y.z"] } };
-  const f = fakeFetch(() => ({ body: { ok: true, result: { status: "approval_required", approval, firstContactRecipients: ["x@y.z"] } } }));
-  const frame = await emailSend({ to: ["x@y.z"], subject: "s", text: "b", idempotencyId: "biz-2" }, { base: BASE, token: TOKEN, idempotencyKey: "k2", fetchImpl: f });
-  assert.equal(frame.ok, true, "approval_required is a result, not an error");
-  assert.equal(frame.result.status, "approval_required");
-  assert.deepEqual(frame.result.approval, approval);
-});
-
-// --- artifact family (GU program 2026-07) -----------------------------------
-
-test("artifact wrappers route to their /v1 artifact.* methods and POST the params", async () => {
-  const seen = [];
-  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
-  const o = { base: BASE, token: TOKEN, fetchImpl: f };
-  const envelope = { genui: "v2", artifact: { class: "ops.status", version: 1, state: "complete", source: { kind: "native" } }, actions: [], root: { type: "card", tone: "neutral", blocks: [] } };
-  await artifactCreate({ channelId: "c1", envelope, clientMsgId: "cm-1" }, o);
-  await artifactAct({ artifactId: "a1", action: "approve", idempotencyKey: "k-1" }, o);
-  await artifactPatch({ artifactId: "a1", toState: "complete", envelope }, o);
-  await artifactGet({ artifactId: "a1" }, o);
-  await artifactList({ channelId: "c1", state: "complete" }, o);
-  await artifactCatalog({}, o);
-  assert.deepEqual(seen, [
-    `${BASE}/api/v1/artifact.create`,
-    `${BASE}/api/v1/artifact.act`,
-    `${BASE}/api/v1/artifact.patch`,
-    `${BASE}/api/v1/artifact.get`,
-    `${BASE}/api/v1/artifact.list`,
-    `${BASE}/api/v1/artifact.catalog`,
-  ]);
-  assert.deepEqual(JSON.parse(f.calls[0].init.body).envelope, envelope, "envelope POSTed verbatim");
-});
-
-test("artifact writes are dispatcher-neutral: business ids in the BODY, no x-idempotency-key header", async () => {
-  // sideEffecting:false at the dispatcher (the hq artifact service self-appends
-  // its ledger) → call() attaches no header even when o.idempotencyKey is set;
-  // dedup rides params.clientMsgId / params.idempotencyKey instead.
-  const f = fakeFetch(() => ({ body: { ok: true, result: { artifactId: "a1", messageId: "m1" } } }));
-  await artifactCreate({ channelId: "c1", envelope: { genui: "v1", root: {} }, clientMsgId: "cm-9" }, { base: BASE, token: TOKEN, idempotencyKey: "ignored", fetchImpl: f });
-  assert.equal(f.calls[0].headers["x-idempotency-key"], undefined);
-  assert.equal(JSON.parse(f.calls[0].init.body).clientMsgId, "cm-9");
-  const held = fakeFetch(() => ({ body: { ok: true, result: { held: true, approvalId: "ap-1" } } }));
-  const frame = await artifactAct({ artifactId: "a1", action: "pay", idempotencyKey: "pay-a1" }, { base: BASE, token: TOKEN, fetchImpl: held });
-  assert.equal(held.calls[0].headers["x-idempotency-key"], undefined);
-  assert.equal(JSON.parse(held.calls[0].init.body).idempotencyKey, "pay-a1");
-  assert.equal(frame.ok, true, "approval-held is a result, not an error");
-  assert.equal(frame.result.held, true);
-});
-
-// --- agent desks (books / calendar / crm / files / email Inbox app / meetings) --
-
-test("desk wrappers route to their /v1 methods and POST the params", async () => {
-  const {
-    emailMailboxes, emailThreads, emailTriage, emailDraftSend,
-    filesList, filesDocWriteRevision,
-    calendarFindATime, calendarRsvp,
-    crmListDeals, crmMoveStage,
-    booksReports, booksInvoiceDraft, booksAsk,
-    meetingsRecapFile,
-  } = await import("./ui-parity.mjs");
-  const seen = [];
-  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
-  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
-  await emailMailboxes({}, o);
-  await emailThreads({ mailboxId: "mb1", folder: "inbox" }, o);
-  await emailTriage({ threadId: "t1", priority: "P1" }, o);
-  await emailDraftSend({ mailboxId: "mb1", to: ["a@b.co"], bodyText: "hi" }, o);
-  await filesList({ q: "plan" }, o);
-  await filesDocWriteRevision({ fileId: "f1", html: "<p>x</p>" }, o);
-  await calendarFindATime({ attendeeMemberIds: ["m1"], durationMinutes: 30, fromDay: "2026-07-27" }, o);
-  await calendarRsvp({ eventId: "e1", rsvp: "ACCEPTED" }, o);
-  await crmListDeals({ openOnly: true }, o);
-  await crmMoveStage({ dealId: "d1", stage: "PROPOSAL" }, o);
-  await booksReports({ report: "pl" }, o);
-  await booksInvoiceDraft({ payeeName: "Acme", description: "Retainer", totalCents: 120000 }, o);
-  await booksAsk({ question: "What is overdue?" }, o);
-  await meetingsRecapFile({ meetingId: "mt1", recap: { bullets: ["done"] } }, o);
-  assert.deepEqual(seen, [
-    `${BASE}/api/v1/email.mailboxes`,
-    `${BASE}/api/v1/email.threads`,
-    `${BASE}/api/v1/email.triage`,
-    `${BASE}/api/v1/email.draftSend`,
-    `${BASE}/api/v1/files.list`,
-    `${BASE}/api/v1/files.docWriteRevision`,
-    `${BASE}/api/v1/calendar.findATime`,
-    `${BASE}/api/v1/calendar.rsvp`,
-    `${BASE}/api/v1/crm.listDeals`,
-    `${BASE}/api/v1/crm.moveStage`,
-    `${BASE}/api/v1/books.reports`,
-    `${BASE}/api/v1/books.invoiceDraft`,
-    `${BASE}/api/v1/books.ask`,
-    `${BASE}/api/v1/meetings.recapFile`,
-  ]);
-});
-
-// --- directory desk (2026-07) -----------------------------------------------
-
-test("directory wrappers route to their /v1 methods and POST the params", async () => {
-  const {
-    directorySearch, directoryListPeople, directoryGetPerson, directoryAsk,
-    directoryAddChannel, directoryProposeCapture, directoryProposeMerge,
-    directoryRequestAwareness, directoryCreateList,
-  } = await import("./ui-parity.mjs");
-  const seen = [];
-  const f = fakeFetch((url) => { seen.push(url); return { body: { ok: true, result: null } }; });
-  const o = { base: BASE, token: TOKEN, idempotencyKey: "k", fetchImpl: f };
-  await directorySearch({ q: "hartmann" }, o);
-  await directoryListPeople({ relationship: "client", sort: "touch" }, o);
-  await directoryGetPerson({ contactId: "c1" }, o);
-  await directoryAsk({ question: "Who owns Fieldstone?" }, o);
-  await directoryAddChannel({ subjectType: "PERSON", subjectId: "c1", type: "EMAIL", value: "a@b.co", verifiedFrom: "SIGNATURE" }, o);
-  await directoryProposeCapture({ kind: "PERSON", payload: { person: { displayName: "Lena" } }, source: "MAIL", sourceFingerprint: "sig:1" }, o);
-  await directoryProposeMerge({ aRef: "contact:c1", bRef: "contact:c2" }, o);
-  await directoryRequestAwareness({ contactId: "c9", reason: "renewal paper" }, o);
-  await directoryCreateList({ name: "Fieldstone renewal" }, o);
-  assert.deepEqual(seen, [
-    `${BASE}/api/v1/directory.search`,
-    `${BASE}/api/v1/directory.listPeople`,
-    `${BASE}/api/v1/directory.getPerson`,
-    `${BASE}/api/v1/directory.ask`,
-    `${BASE}/api/v1/directory.addChannel`,
-    `${BASE}/api/v1/directory.proposeCapture`,
-    `${BASE}/api/v1/directory.proposeMerge`,
-    `${BASE}/api/v1/directory.requestAwareness`,
-    `${BASE}/api/v1/directory.createList`,
-  ]);
-  assert.equal(JSON.parse(f.calls[5].init.body).sourceFingerprint, "sig:1", "the dedup key rides the body");
-});
-
-test("directory reads are POST RPCs with no idempotency key; idempotent writes forward the caller's", async () => {
-  const { directoryListPeople, directoryCreatePerson } = await import("./ui-parity.mjs");
-  const f = fakeFetch(() => ({ body: { ok: true, result: { people: [] } } }));
-  await directoryListPeople({ scope: "external" }, { base: BASE, token: TOKEN, fetchImpl: f });
-  assert.equal(f.calls[0].init.method, "POST", "directory reads are POST METHODS, not GET reads");
-  assert.equal(f.calls[0].headers["x-idempotency-key"], undefined);
-  await directoryCreatePerson({ displayName: "Lena Hartmann" }, { base: BASE, token: TOKEN, idempotencyKey: "seed-lena", fetchImpl: f });
-  assert.equal(f.calls[1].headers["x-idempotency-key"], "seed-lena");
-});
-
-test("a human-gated directory verb surfaces the server's refusal verbatim, never a throw", async () => {
-  // executeMerge / setAwareness / archive* are human-gated in the hq domain
-  // (DECISIONS D-7). An agent seat gets a FORBIDDEN_SCOPE frame — that refusal is
-  // correct behaviour and must reach the caller intact.
-  const { directoryExecuteMerge } = await import("./ui-parity.mjs");
-  const f = fakeFetch(() => ({ ok: false, status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "a human resolves merges" } } }));
-  const frame = await directoryExecuteMerge({ candidateId: "m1", survivorRef: "contact:c1" }, { base: BASE, token: TOKEN, fetchImpl: f });
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
-  assert.match(frame.error.message, /human/);
-});
-
-test("every desk protocol method has exactly one ui-parity wrapper (196 desks / 373 total)", async () => {
-  const fs = await import("node:fs");
-  const path = await import("node:path");
-  const url = await import("node:url");
-  const here = path.dirname(url.fileURLToPath(import.meta.url));
-  const src = fs.readFileSync(path.join(here, "ui-parity.mjs"), "utf8");
-  const called = [...src.matchAll(/return call\("([a-z]+\.[A-Za-z]+)"/g)].map((x) => x[1]);
-  // 2026-08 mobile-parity delta: +16 desk methods (email 5, files 9,
-  // calendar.ask, crm.ask) → 312 → 328.
-  // 2026-08 conversation-parity delta: the module claimed "one per agent-facing
-  // org method the human app exposes" while carrying 6 of messaging's 15 and
-  // NONE of calling's 22 — so the huddle control, the calendar Join, host
-  // mute/lock/remove, hand-raising and in-call chat had no wrapper at all.
-  // +9 messaging +22 calling → 328 → 359.
-  // 2026-08 voice delta: messaging.synthesizeVoiceNote — the agent-plane twin
-  // of the composer's hold-to-record button, which the messaging family had no
-  // wrapper for at all → 360.
-  // 2026-08 mandate delta: the whole accountability spine (11 methods) was
-  // protocol-declared and wrapped nowhere, so `lib/mandate/refresh.mjs` reached
-  // it by spelling the method name out as a string constant of its own → 371.
-  // 2026-08 preference delta: hq built `preference.*` FOR this plane (its own
-  // handler docblock says so) and the SDK wrapped neither half → 373.
-  assert.equal(called.length, 373, "one call() site per wrapper");
-  assert.equal(new Set(called).size, called.length, "no duplicate method bindings");
-  // The two conversation families are now WHOLE, which is what makes the
-  // module docblock's claim true rather than aspirational.
-  for (const fam of ["messaging", "calling"]) {
-    const famMethods = Object.entries((await import("./protocol.mjs")).METHODS)
-      .filter(([, d]) => d.family === fam)
-      .map(([n]) => n);
-    // Whole MINUS the declared daemon-internal exceptions (the same ledger the
-    // sibling test enforces) — e.g. messaging.electResponder is the daemon's
-    // responder-election transport, not a human-app verb.
-    const unwrapped = famMethods.filter((m) => !new Set(called).has(m) && !DELIBERATELY_UNWRAPPED.has(m));
-    assert.deepEqual(unwrapped, [], `every ${fam}.* method is wrapped or declared daemon-internal`);
-  }
-  const p = await import("./protocol.mjs");
-  const deskFams = new Set(["books", "calendar", "crm", "directory", "files"]);
-  const deskMethods = Object.entries(p.METHODS)
-    .filter(([n, d]) => deskFams.has(d.family) || n.startsWith("email.") || n === "meetings.recapFile")
-    .map(([n]) => n);
-  const bound = new Set(called);
-  const missing = deskMethods.filter((m) => !bound.has(m));
-  assert.deepEqual(missing, [], "every desk method is wrapped");
-});
-
-/**
- * The methods in a CLAIMED family that ui-parity deliberately does NOT wrap,
- * with the reason. The module docblock lists its families flatly, which reads as
- * "every method in these families" — so the exceptions have to be written down
- * and enforced, or the docblock is an orphan describing a surface that is not
- * there. Ledger, not an excuse list: each line says which OTHER surface carries
- * the verb.
- */
-const DELIBERATELY_UNWRAPPED = new Map([
-  // board — the agent work kernel; no human control, curated tools instead.
-  ["board.create", "agent work kernel"],
-  ["board.claim", "agent work kernel — curated board_claim"],
-  ["board.heartbeat", "agent work kernel (lease slide)"],
-  ["board.complete", "agent work kernel — curated board_complete"],
-  ["board.block", "agent work kernel"],
-  ["board.comment", "agent work kernel (kanban comments = board.addTaskComment)"],
-  ["board.decompose", "agent work kernel — governance-gated §0.4"],
-  ["board.assign", "agent work kernel — governance-gated §0.4"],
-  ["board.link", "agent work kernel (DAG edge)"],
-  ["board.requestReview", "agent work kernel"],
-  ["board.resolveReview", "agent work kernel"],
-  // A human never calls this: it records where an AGENT is on an ask it took
-  // on. The daemon drives it from its own dispatch path (lib/org/work-ledger)
-  // and a session may nudge it mid-work via the curated `work_track` tool.
-  ["board.track", "agent work kernel — daemon-driven, curated work_track"],
-  // decision — the §0.4 control-plane acts, not the human ledger surface.
-  ["decision.propose", "control plane — curated decision_propose"],
-  ["decision.adopt", "control plane — governance-gated §0.4"],
-  ["decision.supersede", "control plane — governance-gated §0.4"],
-  // the rest — a different artifact or a different plane entirely.
-  ["escalation.ask", "OpenQuestion artifact, not the escalation strip"],
-  ["escalation.answer", "OpenQuestion artifact, not the escalation strip"],
-  ["memory.recall", "semantic retrieval — curated memory_recall"],
-  ["integration.toolsetVersion", "runtime toolset plane (daemon poll)"],
-  ["integration.listAgentTools", "runtime toolset plane (daemon poll)"],
-  ["integration.invokeTool", "runtime toolset plane (executor)"],
-  ["meetings.record", "knowledge plane writer, not the desk verb"],
-  // The responder-election plane: the daemon asks hq who — if anyone — should
-  // answer an undirected channel message. Server-decided and daemon-driven
-  // (scripts/daemon/agent-daemon.mjs, via lib/org/client.electResponder); a human
-  // never elects a responder, so there is no human-app verb to wrap.
-  ["messaging.electResponder", "responder-election plane — daemon-driven (client.electResponder)"],
-]);
-
-test("the claimed families are wrapped WHOLE, minus a declared, self-cleaning exception list", async () => {
-  const fs = await import("node:fs");
-  const path = await import("node:path");
-  const url = await import("node:url");
-  const here = path.dirname(url.fileURLToPath(import.meta.url));
-  const src = fs.readFileSync(path.join(here, "ui-parity.mjs"), "utf8");
-  const wrapped = new Set([...src.matchAll(/return call\("([a-z]+\.[A-Za-z]+)"/g)].map((x) => x[1]));
-  const p = await import("./protocol.mjs");
-
-  // Exactly the families the module docblock names (branding lives in client.mjs).
-  const CLAIMED = [
-    "charter", "member", "team", "channel", "persona", "profile", "sop",
-    "escalation", "annotation", "contact", "file", "memory", "compact",
-    "notification", "decision", "messaging", "calling", "board", "invitation",
-    "user", "settings", "billing", "org", "integration", "email", "artifact",
-    "books", "calendar", "crm", "directory", "files", "meetings", "mandate",
-    "preference",
-  ];
-  const undeclared = [];
-  for (const name of Object.keys(p.METHODS)) {
-    const fam = name.slice(0, name.indexOf("."));
-    if (!CLAIMED.includes(fam)) continue;
-    if (wrapped.has(name)) continue;
-    if (DELIBERATELY_UNWRAPPED.has(name)) continue;
-    undeclared.push(name);
-  }
-  // If this fails: add the wrapper, or add a DELIBERATELY_UNWRAPPED line saying
-  // which surface carries the verb instead. Silence is the one option gone.
-  assert.deepEqual(undeclared, [], "every method of a claimed family is wrapped or declared");
-
-  // Self-cleaning both ways: a stale exception (now wrapped, or no longer a
-  // real method) must be deleted rather than left as decoration.
-  const nowWrapped = [...DELIBERATELY_UNWRAPPED.keys()].filter((m) => wrapped.has(m));
-  assert.deepEqual(nowWrapped, [], "these are wrapped now — delete their exception lines");
-  const notMethods = [...DELIBERATELY_UNWRAPPED.keys()].filter((m) => !p.methodDef(m));
-  assert.deepEqual(notMethods, [], "these are not protocol methods — delete their exception lines");
-
-  // And the docblock's own numbers stay honest.
-  assert.equal(wrapped.size, 373, "the docblock's wrapper count");
-});
-
-/**
- * THE FAMILIES THIS MODULE DOES NOT CLAIM, and who carries each instead.
- *
- * The guard above is airtight INSIDE `CLAIMED` and blind at its edge: it walks
- * the protocol table and `continue`s on any family not in the list, so a NEWLY
- * DECLARED family lands wrapped by nobody and fails no test. That is not
- * hypothetical — genesis, subagent and mandate all arrived dark in one
- * fortnight and were found by a census, not by CI.
- *
- * So every family in `METHODS` must now appear either in `CLAIMED` or here,
- * with the surface that actually carries it. Two entries deliberately record a
- * REFUSAL rather than a home, and two record a genuine hole; that is the point
- * of a ledger — the honest answer is allowed, silence is not.
- */
-const UNCLAIMED_FAMILIES = new Map([
-  // The org spine: named wrappers live in client.mjs beside the transport they
-  // use, and predate this module. Moving them would break every importer.
-  ["approval", "client.mjs approvalRequest/Resolve/Get/List + lib/org/approvals.mjs; curated approval_request/approval_wait"],
-  ["branding", "client.mjs (said in this module's own docblock); curated design_* tools"],
-  ["contacts", "client.mjs contactsUpsert — the knowledge plane's contact writer"],
-  ["cost", "client.mjs costReport + lib/org/cost-sync.mjs"],
-  ["credential", "client.mjs credentialPut/Lease/List/Revoke + lib/org/keys.mjs — a secret broker, not a pane"],
-  ["governance", "client.mjs governanceStatus/setDecisionRights — the §0.4 control plane"],
-  ["handoff", "client.mjs + lib/org/handoff.mjs — governance-gated delegation"],
-  ["knowledge", "client.mjs + lib/org/knowledge.mjs; curated knowledge_search/knowledge_append"],
-  ["lease", "client.mjs + lib/org/leases.mjs — the work kernel's lock primitive"],
-  ["policy", "client.mjs policyPublish + lib/org/policy.mjs"],
-  ["presence", "client.mjs presenceBeat + lib/org/registry.mjs — the daemon's own heartbeat"],
-  ["registry", "client.mjs register/heartbeat + lib/org/registry.mjs — enrolment, not a click"],
-  ["pairing", "client.mjs pairRequest — PRE-AUTH, deliberately off the authenticated call() path"],
-  ["agent", "agent.wait is the long-poll TRANSPORT rung (lib/org/push.mjs DEFAULT_WAIT_PATH), not a surface"],
-  // The registry family has a home with state a thin wrapper would silently
-  // lose. Reads reach a session through the curated subagent_* tools.
-  ["subagent", "lib/subagents/client.mjs — owns the offline outbox + lock file; curated subagent_list/get/resolve for the reads"],
-  // The venture-deliverable catalogue (2026-08). Its maestro surface is the
-  // CURATED table, not a thin one-liner per method: the eight `resource_*` desk
-  // tools are GENERATED from hq's own desk declaration and parity-tested
-  // against it, because hand-copying a desk table is precisely what produced
-  // the 239-ops-vs-69-tools drift this wave exists to stop. A hand-written
-  // wrapper here would be a third copy of the same eight names.
-  ["resource", "lib/org/tool-surface.mjs — curated resource_* desk tools, GENERATED from hq's desk declaration (never hand-copied) and parity-tested against it"],
-  // REFUSALS, not gaps. hq's `requireGenesisSeat` throws UNAUTHORIZED on any
-  // actor whose kind is not "human" (src/server/methods/genesis/_shared.ts),
-  // and architecture.* imports that same gate. A Genesis run belongs to
-  // (orgId, startedById) — one workspace AND one person — and an api-key
-  // principal is neither. Wrappers here would be dead code that always 401s,
-  // which is a worse surface than an honest absence.
-  ["genesis", "hq refuses every non-human actor (requireGenesisSeat) — unreachable from a bearer key by design"],
-  ["architecture", "same gate as genesis (it imports requireGenesisSeat) — unreachable from a bearer key by design"],
-  // HOLES, recorded as holes. Both are admin-scope writes with no SDK caller
-  // today; neither is reachable below the CEO tier even through org_rpc.
-  ["admin", "GAP — the deactivate/reactivate kill switch has no wrapper and no tool; admin scope, operator console only"],
-  ["hierarchy", "GAP — hierarchy.set (admin scope) has no wrapper; reporting edges are set in hq's own org chart today"],
-]);
-
-test("every protocol family is CLAIMED or has a written line saying who carries it", async () => {
-  const p = await import("./protocol.mjs");
-
-  // Kept in step with the guard above by construction: read the same list.
-  const CLAIMED = new Set([
-    "charter", "member", "team", "channel", "persona", "profile", "sop",
-    "escalation", "annotation", "contact", "file", "memory", "compact",
-    "notification", "decision", "messaging", "calling", "board", "invitation",
-    "user", "settings", "billing", "org", "integration", "email", "artifact",
-    "books", "calendar", "crm", "directory", "files", "meetings", "mandate",
-    "preference",
-  ]);
-
-  const families = new Set(Object.values(p.METHODS).map((d) => d.family));
-  const undeclared = [...families]
-    .filter((f) => !CLAIMED.has(f) && !UNCLAIMED_FAMILIES.has(f))
-    .sort();
-  // If this fails, a family was added to protocol.mjs and nothing on this plane
-  // noticed. Wrap it (and add it to CLAIMED), or add an UNCLAIMED_FAMILIES line
-  // naming the surface that carries it. "It's reachable via org_rpc" is not an
-  // answer: org_rpc is access:"admin" and does not exist below the CEO tier.
-  assert.deepEqual(undeclared, [], "every protocol family is claimed or declared");
-
-  // Self-cleaning: a declared family that has since been claimed, or that is no
-  // longer a protocol family at all, must lose its line rather than rot.
-  const nowClaimed = [...UNCLAIMED_FAMILIES.keys()].filter((f) => CLAIMED.has(f));
-  assert.deepEqual(nowClaimed, [], "these are claimed now — delete their ledger lines");
-  const gone = [...UNCLAIMED_FAMILIES.keys()].filter((f) => !families.has(f));
-  assert.deepEqual(gone, [], "these are not protocol families — delete their ledger lines");
-
-  // The two CLAIMED lists must stay identical, or one guard silently narrows.
-  const src = (await import("node:fs")).readFileSync(
-    (await import("node:path")).join(
-      (await import("node:path")).dirname(
-        (await import("node:url")).fileURLToPath(import.meta.url),
-      ),
-      "ui-parity.test.mjs",
-    ),
-    "utf8",
-  );
-  const blocks = [...src.matchAll(/const CLAIMED = (?:new Set\()?\[([\s\S]*?)\]/g)].map((m) =>
-    [...m[1].matchAll(/"([a-z]+)"/g)].map((x) => x[1]).sort().join(","),
-  );
-  assert.equal(blocks.length, 2, "both guards declare a CLAIMED list");
-  assert.equal(blocks[0], blocks[1], "the two CLAIMED lists must not drift apart");
-});