@firedrill-tools/unified 0.1.1

package/test/conformance.mjs

@@ -0,0 +1,39 @@
+// Unified.to Tool conformance target: a scripted Tool test, not a model-driven agent. Node built-ins only.
+// Reads the drill task from stdin, picks the flow named in the instruction and runs it against the provider-shaped
+// REST routes (FIREDRILL_HTTP_URL, bearer FIREDRILL_HTTP_TOKEN) and the MCP endpoint (FIREDRILL_MCP_URL).
+import { connections, mcpAliases } from "./flows/connections.mjs";
+import { errorCoverage } from "./flows/coverage.mjs";
+import { crm } from "./flows/crm.mjs";
+import { bounds, largeChannels, manyWorkspaces, rateLimited, writeCommittedLost, writeUnavailable } from "./flows/faults.mjs";
+import { denied, fresh, ghost, scoped } from "./flows/identity.mjs";
+import { messaging } from "./flows/messaging.mjs";
+import { sizeBounds } from "./flows/size.mjs";
+
+let task = "";
+for await (const chunk of process.stdin) task += chunk;
+const invocation = JSON.parse(task);
+const instruction = String(invocation.instruction ?? invocation.task?.instruction ?? "");
+
+const flows = {
+  crm,
+  messaging,
+  connections,
+  mcp: mcpAliases,
+  scoped,
+  ghost,
+  denied,
+  fresh,
+  "error-coverage": errorCoverage,
+  "rate-limited": rateLimited,
+  "write-unavailable": writeUnavailable,
+  "write-committed-lost": writeCommittedLost,
+  bounds,
+  "many-workspaces": manyWorkspaces,
+  "large-channels": largeChannels,
+  "size-bounds": sizeBounds,
+};
+
+const selected = /Run the ([a-z-]+) flow/.exec(instruction)?.[1];
+if (selected === undefined || !Object.hasOwn(flows, selected)) throw new Error(`Unknown drill instruction: ${instruction}`);
+await flows[selected]();
+process.stdout.write(JSON.stringify({ completed: true, flow: selected }));

package/test/flows/connections.mjs

@@ -0,0 +1,87 @@
+// Drills unified-connections-flow and unified-mcp-core-aliases (admin, baseline).
+import { ALIASES, ALL_OPERATIONS, C, NEW, NONE, NOW, WS, apiError, assert, del, get, ids, mcp, mcpError, mcpInit, patch, post, put, rpc, walk } from "../lib.mjs";
+
+const U = "/unified/connection";
+
+export async function connections() {
+  const listed = (await get(U)).json;
+  assert.deepEqual(ids(listed), [C.main, C.readonly, C.chat, C.mail, C.paused, C.broken, C.hris], "Sandbox connections are hidden by default");
+  for (const row of listed) assert.ok(!Object.hasOwn(row.auth, "token") && !Object.hasOwn(row.auth, "access_token"), "auth carries no secrets");
+  assert.deepEqual(ids((await get(`${U}?env=Sandbox`)).json), [C.sandbox, C.omni]);
+  assert.deepEqual(ids((await get(`${U}?env=Sandbox&categories=crm,messaging`)).json), [C.omni], "a connection may carry several categories");
+  assert.deepEqual((await get(`/crm/${C.omni}/contact`)).json, [], "the omni Sandbox connection holds no data");
+  assert.deepEqual((await get(`/messaging/${C.omni}/channel`)).json, []);
+  assert.deepEqual(ids((await get(`${U}?categories=messaging`)).json), [C.chat, C.mail]);
+  assert.deepEqual((await get(`${U}?categories=crm,messaging`)).json, [], "every listed category must be present");
+  assert.deepEqual(ids((await get(`${U}?external_xref=acct-northwind`)).json), [C.readonly]);
+  assert.equal((await get(`${U}?sort=name&order=asc`)).json[0].integration_name, "BambooHR");
+  assert.deepEqual(ids((await get(`${U}?updated_gte=2026-09-12T00:00:00Z`)).json), [C.main, C.chat, C.mail]);
+  assert.equal((await walk(U, 2, [2, 2, 2, 1])).length, 7);
+  await apiError("GET", `${U}?env=Staging`, 400, "env must be Production or Sandbox");
+  await apiError("GET", `${U}?categories=parking`, 400, "not a supported category");
+  const chat = (await get(`${U}/${C.chat}`)).json;
+  assert.equal(chat.integration_type, "slack");
+  assert.equal(chat.workspace_id, WS);
+  await apiError("GET", `${U}/${NONE}`, 404, "Connection not found");
+
+  await apiError("POST", U, 400, "integration_type is required", { body: {} });
+  await apiError("POST", U, 400, "requires the messaging category", { body: { integration_type: "zoho", categories: ["crm"], permissions: ["messaging_message_read"] } });
+  await apiError("POST", U, 400, "not a supported category", { body: { integration_type: "zoho", categories: ["parking"] } });
+  await apiError("POST", U, 400, "Invalid value for integration_type", { body: { integration_type: "Zoho CRM", categories: ["crm"] } });
+  const zoho = (await post(U, { integration_type: "zoho", categories: ["crm"], permissions: ["crm_contact_read", "crm_contact_write"], external_xref: "acct-zoho", auth: { name: "Zed", emails: ["zed@example.org"], user_id: "u-zed" } })).json;
+  assert.equal(zoho.id, NEW(1));
+  assert.equal(zoho.integration_name, "Zoho");
+  assert.equal(zoho.is_paused, false);
+  assert.equal(zoho.environment, "Production");
+  assert.equal(zoho.last_healthy_at, NOW);
+  assert.equal(zoho.created_at, NOW);
+  assert.deepEqual(zoho.auth, { name: "Zed", emails: ["zed@example.org"], user_id: "u-zed" });
+  assert.equal((await get(U)).json.length, 8, "seven Production connections plus the new one");
+
+  const Z = `/crm/${NEW(1)}`;
+  assert.deepEqual((await get(`${Z}/contact`)).json, [], "a new connection starts empty");
+  const first = (await post(`${Z}/contact`, { name: "First" })).json;
+  assert.equal(first.id, NEW(2));
+  const narrowed = (await patch(`${U}/${NEW(1)}`, { permissions: ["crm_contact_read"] })).json;
+  assert.deepEqual(narrowed.permissions, ["crm_contact_read"]);
+  await apiError("POST", `${Z}/contact`, 403, "crm_contact_write", { body: { name: "Second" } });
+  assert.equal((await get(`${Z}/contact`)).json.length, 1);
+  await apiError("PATCH", `${U}/${NEW(1)}`, 400, "cannot be changed", { body: { categories: ["hris"] } });
+  await apiError("PATCH", `${U}/${NEW(1)}`, 400, "requires the messaging category", { body: { permissions: ["messaging_message_read"] } });
+  await apiError("PATCH", `${U}/${NONE}`, 404, "Connection not found", { body: { external_xref: "x" } });
+  const relabelled = (await put(`${U}/${NEW(1)}`, { external_xref: "acct-z2", environment: "Sandbox" })).json;
+  assert.equal(relabelled.external_xref, "acct-z2");
+  assert.equal(relabelled.environment, "Sandbox");
+  assert.deepEqual(relabelled.permissions, ["crm_contact_read"], "PUT merges like PATCH");
+  assert.equal((await get(U)).json.length, 7, "the connection moved to Sandbox");
+  await apiError("DELETE", `${U}/${NONE}`, 404, "Connection not found");
+  assert.deepEqual((await del(`${U}/${NEW(1)}`)).json, {});
+  await apiError("GET", `${Z}/contact`, 404, "Connection not found");
+  await apiError("GET", `${U}/${NEW(1)}`, 404, "Connection not found");
+  assert.equal((await get(`${U}?env=Sandbox`)).json.length, 2);
+}
+
+export async function mcpAliases() {
+  await mcpInit();
+  const tools = (await rpc("tools/list", {})).tools.map((tool) => tool.name);
+  for (const alias of ALIASES) assert.ok(tools.includes(alias), `alias ${alias} missing`);
+  for (const operationId of ALL_OPERATIONS) assert.ok(tools.includes(`unified.${operationId}`), `canonical unified.${operationId} missing`);
+  assert.equal(tools.length, ALIASES.length + ALL_OPERATIONS.length);
+
+  const first = (await mcp("list_unified_connections", { limit: 3 })).result;
+  assert.deepEqual(ids(first), [C.main, C.readonly, C.chat]);
+  const rest = (await mcp("list_unified_connections", { limit: 3, offset: 3 })).result;
+  assert.deepEqual(ids(rest), [C.mail, C.paused, C.broken]);
+  assert.deepEqual(ids((await mcp("list_unified_connections", { offset: 6 })).result), [C.hris]);
+  assert.equal((await mcp("get_unified_connection", { id: C.mail })).integration_type, "gmail");
+  const created = await mcp("create_unified_connection", { integration_type: "zoho", categories: ["crm"], permissions: ["crm_contact_read"], external_xref: "acct-mcp" });
+  assert.equal(created.id, NEW(1));
+  assert.equal(created.integration_name, "Zoho");
+  const updated = await mcp("update_unified_connection", { id: NEW(1), external_xref: "acct-mcp-2" });
+  assert.equal(updated.external_xref, "acct-mcp-2");
+  assert.equal((await mcp("unified.connections.get", { id: NEW(1) })).external_xref, "acct-mcp-2", "canonical name sees the alias write");
+  assert.deepEqual(await mcp("remove_unified_connection", { id: NEW(1) }), {});
+  await mcpError("get_unified_connection", { id: NONE }, "NOT_FOUND");
+  await mcpError("get_unified_connection", { id: NEW(1) }, "NOT_FOUND");
+  assert.equal((await mcp("list_unified_connections", {})).result.length, 7);
+}

package/test/flows/coverage.mjs

@@ -0,0 +1,64 @@
+// Drill unified-error-coverage (admin, baseline): every data operation answers 404 (unknown connection), 501 (wrong
+// category), 403 (paused CRM connection / permission-less messaging connection) and 400 (malformed connection_id);
+// connection operations answer 400 and 404.
+import { C, CH, CO, D, K, MSG, NEW, NONE, PL, apiError, assert, del, post } from "../lib.mjs";
+
+/** [operation, method, path builder (connection id -> path), body] for the 24 connection-scoped operations. */
+const DATA_CALLS = [
+  ["contacts.list", "GET", (c) => `/crm/${c}/contact`],
+  ["contacts.get", "GET", (c) => `/crm/${c}/contact/${K.elena}`],
+  ["contacts.create", "POST", (c) => `/crm/${c}/contact`, { name: "Probe" }],
+  ["contacts.update", "PATCH", (c) => `/crm/${c}/contact/${K.elena}`, { title: "Probe" }],
+  ["contacts.remove", "DELETE", (c) => `/crm/${c}/contact/${K.elena}`],
+  ["companies.list", "GET", (c) => `/crm/${c}/company`],
+  ["companies.get", "GET", (c) => `/crm/${c}/company/${CO.northwind}`],
+  ["companies.create", "POST", (c) => `/crm/${c}/company`, { name: "Probe Co" }],
+  ["companies.update", "PUT", (c) => `/crm/${c}/company/${CO.northwind}`, { industry: "Probe" }],
+  ["companies.remove", "DELETE", (c) => `/crm/${c}/company/${CO.northwind}`],
+  ["deals.list", "GET", (c) => `/crm/${c}/deal`],
+  ["deals.get", "GET", (c) => `/crm/${c}/deal/${D.q4}`],
+  ["deals.create", "POST", (c) => `/crm/${c}/deal`, { name: "Probe deal" }],
+  ["deals.update", "PATCH", (c) => `/crm/${c}/deal/${D.q4}`, { description: "Probe" }],
+  ["deals.remove", "DELETE", (c) => `/crm/${c}/deal/${D.q4}`],
+  ["pipelines.list", "GET", (c) => `/crm/${c}/pipeline`],
+  ["pipelines.get", "GET", (c) => `/crm/${c}/pipeline/${PL.sales}`],
+  ["channels.list", "GET", (c) => `/messaging/${c}/channel`],
+  ["channels.get", "GET", (c) => `/messaging/${c}/channel/${CH.general}`],
+  ["messages.list", "GET", (c) => `/messaging/${c}/message`],
+  ["messages.get", "GET", (c) => `/messaging/${c}/message/${MSG(1)}`],
+  ["messages.create", "POST", (c) => `/messaging/${c}/message`, { message: "probe", channels: [{ id: CH.sales }] }],
+  ["messages.update", "PATCH", (c) => `/messaging/${c}/message/${MSG(1)}`, { message: "probe" }],
+  ["messages.remove", "DELETE", (c) => `/messaging/${c}/message/${MSG(1)}`],
+];
+
+const isCrm = (path) => path.startsWith("/crm/");
+
+export async function errorCoverage() {
+  // A messaging connection without any permission: every messaging operation answers 403 on it.
+  const bare = (await post("/unified/connection", { integration_type: "teams", categories: ["messaging"], permissions: [] })).json;
+  assert.equal(bare.id, NEW(1));
+  for (const [, method, pathFor, body] of DATA_CALLS) {
+    const options = body === undefined ? {} : { body };
+    await apiError(method, pathFor(NONE), 404, "Connection not found", options);
+    await apiError(method, pathFor(C.hris), 501, "not supported by this integration", options);
+    await apiError(method, pathFor("notahexid"), 400, "Invalid connection_id", options);
+    const sample = pathFor(C.main);
+    if (isCrm(sample)) await apiError(method, pathFor(C.paused), 403, "paused", options);
+    else await apiError(method, pathFor(NEW(1)), 403, "lacks the required permissions", options);
+  }
+  // Connection operations: malformed ids and unknown ids.
+  await apiError("GET", "/unified/connection?limit=0", 400, "limit must be a positive integer");
+  await apiError("GET", "/unified/connection/notahexid", 400, "Invalid connection_id");
+  await apiError("GET", `/unified/connection/${NONE}`, 404, "Connection not found");
+  await apiError("POST", "/unified/connection", 400, "integration_type is required", { body: {} });
+  await apiError("POST", "/unified/connection", 400, "Unknown field", { body: { integration_type: "zoho", categories: ["crm"], token: "secret" } });
+  await apiError("PATCH", "/unified/connection/notahexid", 400, "Invalid connection_id", { body: { external_xref: "x" } });
+  await apiError("PATCH", `/unified/connection/${NONE}`, 404, "Connection not found", { body: { external_xref: "x" } });
+  await apiError("PATCH", `/unified/connection/${C.chat}`, 400, "cannot be changed", { body: { integration_type: "zoho" } });
+  await apiError("DELETE", "/unified/connection/notahexid", 400, "Invalid connection_id");
+  await apiError("DELETE", `/unified/connection/${NONE}`, 404, "Connection not found");
+  // Broken connection: 401 from the Tool for a CRM read and a CRM write.
+  await apiError("GET", `/crm/${C.broken}/company`, 401, "likely broken");
+  await apiError("POST", `/crm/${C.broken}/deal`, 401, "likely broken", { body: { name: "x" } });
+  assert.deepEqual((await del(`/unified/connection/${NEW(1)}`)).json, {});
+}

package/test/flows/crm.mjs

@@ -0,0 +1,124 @@
+// Drill unified-crm-flow (admin, baseline): contacts, companies, deals, pipelines, permissions and connection states.
+import { C, CO, D, K, NEW, NONE, NOW, PL, apiError, assert, del, get, ids, noneHas, patch, post, put, walk } from "../lib.mjs";
+
+const M = `/crm/${C.main}`;
+
+export async function crm() {
+  // Listing, paging and parameter validation.
+  const all = (await get(`${M}/contact`)).json;
+  assert.deepEqual(ids(all), [K.elena, K.tomas, K.priya, K.jonas, K.ravi, K.ana, K.liwei, K.sam]);
+  assert.ok(noneHas(all, "raw") && noneHas(all, "connection_id"), "default projection hides raw and connection_id");
+  assert.equal((await walk(`${M}/contact`, 3, [3, 3, 2])).length, 8);
+  assert.deepEqual((await get(`${M}/contact?offset=50`)).json, []);
+  for (const bad of ["limit=0", "limit=x", "offset=-1", "sort=email", "order=up", "updated_gte=2026-13-01", "query=%ZZ%FF", "company_id=notanid"]) {
+    await apiError("GET", `${M}/contact?${bad}`, 400, "");
+  }
+  assert.equal((await get(`${M}/contact?limit=500`)).json.length, 8, "limit above 100 is capped, not rejected");
+  assert.deepEqual(ids((await get(`${M}/contact?query=northwind`)).json), [K.elena, K.tomas], "query matches e-mail domains");
+  assert.deepEqual(ids((await get(`${M}/contact?query=JONAS`)).json), [K.jonas], "query is case-folded and matches names");
+  assert.deepEqual(ids((await get(`${M}/contact?company_id=${CO.northwind}`)).json), [K.elena, K.tomas]);
+  assert.deepEqual(ids((await get(`${M}/contact?deal_id=${D.pilot}`)).json), [K.priya]);
+  assert.deepEqual(ids((await get(`${M}/contact?user_id=u-maya`)).json), [K.tomas]);
+  assert.deepEqual(ids((await get(`${M}/contact?updated_gte=2026-09-10`)).json), [K.elena, K.tomas, K.liwei, K.sam], "zone-less updated_gte is UTC midnight");
+  assert.equal(ids((await get(`${M}/contact?sort=name&order=desc`)).json)[0], K.liwei, "CJK name sorts last by code point");
+  assert.equal(ids((await get(`${M}/contact?sort=updated_at&order=asc`)).json)[0], K.ravi);
+  const projected = (await get(`${M}/contact?fields=id,name,emails`)).json;
+  for (const row of projected) assert.deepEqual(Object.keys(row).sort(), ["emails", "id", "name"]);
+  const withRaw = (await get(`${M}/contact?fields=raw&limit=1`)).json[0];
+  assert.deepEqual(withRaw, { id: K.elena, raw: { hs_object_id: "501" } });
+
+  // Point reads.
+  const elena = (await get(`${M}/contact/${K.elena}`)).json;
+  assert.equal(elena.name, "Elena Marsh");
+  assert.equal(elena.emails.length, 2);
+  assert.equal(elena.address.city, "Bristol");
+  assert.deepEqual(elena.deal_ids, [D.q4, D.renewal]);
+  await apiError("GET", `${M}/contact/${NONE}`, 404, "Contact not found");
+  await apiError("GET", `${M}/contact/notahexid`, 400, "Invalid contact id");
+
+  // Create with symmetric associations, merge updates (PATCH and PUT), remove with detachment.
+  await apiError("POST", `${M}/contact`, 400, "At least one of name", { body: {} });
+  await apiError("POST", `${M}/contact`, 400, "Unknown company id", { body: { name: "Ghost", company_ids: [NONE] } });
+  await apiError("POST", `${M}/contact`, 400, "emails[0].email", { body: { name: "Bad mail", emails: [{ email: "nope" }] } });
+  const lena = (await post(`${M}/contact`, { first_name: "Lena", emails: [{ email: "lena@example.org", type: "WORK" }], company_ids: [CO.contoso] })).json;
+  assert.equal(lena.id, NEW(1));
+  assert.equal(lena.name, "Lena", "name derives from first_name");
+  assert.equal(lena.created_at, NOW);
+  assert.deepEqual(lena.company_ids, [CO.contoso]);
+  assert.deepEqual((await get(`${M}/company/${CO.contoso}`)).json.contact_ids, [K.priya, NEW(1)], "company gained the reverse link");
+  const renamed = (await patch(`${M}/contact/${NEW(1)}`, { last_name: "Ortiz", company_ids: [] })).json;
+  assert.equal(renamed.name, "Lena Ortiz");
+  assert.deepEqual((await get(`${M}/company/${CO.contoso}`)).json.contact_ids, [K.priya], "company lost the reverse link");
+  const jonas = (await put(`${M}/contact/${K.jonas}`, { title: "Director" })).json;
+  assert.equal(jonas.title, "Director");
+  assert.equal(jonas.name, "Jonas Weber", "PUT merges instead of replacing");
+  assert.deepEqual((await del(`${M}/contact/${K.elena}`)).json, {});
+  assert.deepEqual((await get(`${M}/deal/${D.q4}`)).json.contact_ids, [K.tomas], "deal dropped the removed contact");
+  assert.deepEqual((await get(`${M}/company/${CO.northwind}`)).json.contact_ids, [K.tomas]);
+  await apiError("GET", `${M}/contact/${K.elena}`, 404, "Contact not found");
+  assert.deepEqual((await get(`${M}/contact?deal_id=${D.q4}`)).json.map((row) => row.id), [K.tomas]);
+
+  // Companies.
+  await apiError("POST", `${M}/company`, 400, "name", { body: {} });
+  const woodgrove = (await post(`${M}/company`, { name: "Woodgrove", domains: ["woodgrove.example.org"] })).json;
+  assert.equal(woodgrove.id, NEW(2));
+  assert.equal(woodgrove.is_active, true);
+  assert.deepEqual(ids((await get(`${M}/company?query=woodgrove.example`)).json), [NEW(2)], "query matches company domains");
+  assert.deepEqual((await get(`${M}/company?contact_id=${K.elena}`)).json, []);
+  assert.equal((await get(`${M}/company`)).json.length, 6);
+  assert.equal((await get(`${M}/company?query=山田`)).json[0].id, CO.yamada);
+  assert.equal((await patch(`${M}/company/${NEW(2)}`, { employees: 12 })).json.employees, 12);
+  await apiError("PUT", `${M}/company/${CO.fabrikam}`, 400, "Invalid value for name", { body: { name: null } });
+  await apiError("GET", `${M}/company/${NONE}`, 404, "Company not found");
+  assert.deepEqual((await del(`${M}/company/${NEW(2)}`)).json, {});
+
+  // Deals: pipeline and stage derivation.
+  await apiError("POST", `${M}/deal`, 400, "name", { body: {} });
+  const deal = (await post(`${M}/deal`, { name: "New", stages: [{ id: PL.negotiation }], company_ids: [CO.contoso] })).json;
+  assert.equal(deal.id, NEW(3));
+  assert.deepEqual(deal.pipelines, [{ id: PL.sales, name: "Sales Pipeline", type: null }], "pipeline derived from the stage");
+  assert.equal(deal.stages[0].name, "Negotiation");
+  assert.equal(deal.probability, 70, "probability defaults from the stage");
+  assert.deepEqual((await get(`${M}/company/${CO.contoso}`)).json.deal_ids, [D.pilot, NEW(3)]);
+  await apiError("POST", `${M}/deal`, 400, "does not belong to pipeline", { body: { name: "Bad", pipelines: [{ id: PL.renewals }], stages: [{ id: PL.negotiation }] } });
+  const won = (await patch(`${M}/deal/${D.q4}`, { stages: [{ id: PL.won }] })).json;
+  assert.equal(won.closed_at, NOW, "entering a closed stage stamps closed_at with virtual time");
+  assert.equal(won.probability, 100);
+  const reopened = (await patch(`${M}/deal/${D.q4}`, { stages: [{ id: PL.proposal }] })).json;
+  assert.equal(reopened.closed_at, null);
+  assert.equal(reopened.probability, 40);
+  await apiError("PATCH", `${M}/deal/${D.q4}`, 400, "currency", { body: { currency: "usd" } });
+  assert.deepEqual(ids((await get(`${M}/deal?pipeline_id=${PL.renewals}`)).json), [D.renewal]);
+  assert.deepEqual(ids((await get(`${M}/deal?company_id=${CO.northwind}`)).json), [D.q4, D.renewal]);
+  assert.equal((await get(`${M}/deal`)).json.length, 7);
+  await apiError("GET", `${M}/deal?sort=amount`, 400, "sort must be one of");
+  assert.equal((await put(`${M}/deal/${NEW(3)}`, { amount: 1000, currency: "USD" })).json.amount, 1000);
+  assert.deepEqual((await del(`${M}/deal/${NEW(3)}`)).json, {});
+  assert.deepEqual((await get(`${M}/company/${CO.contoso}`)).json.deal_ids, [D.pilot]);
+  await apiError("GET", `${M}/deal/${NEW(3)}`, 404, "Deal not found");
+
+  // Pipelines (read-only reference data).
+  const pipelines = (await get(`${M}/pipeline`)).json;
+  assert.deepEqual(ids(pipelines), [PL.sales, PL.renewals]);
+  assert.deepEqual(pipelines[0].stages.map((stage) => stage.name), ["Qualification", "Proposal", "Negotiation", "Closed Won", "Closed Lost"]);
+  assert.equal((await get(`${M}/pipeline/${PL.sales}`)).json.name, "Sales Pipeline");
+  await apiError("GET", `${M}/pipeline/${NONE}`, 404, "Pipeline not found");
+
+  // Connection states: permissions, paused, broken, wrong category, Sandbox, unknown, absent route.
+  assert.deepEqual(ids((await get(`/crm/${C.readonly}/contact`)).json), [K.dana]);
+  await apiError("POST", `/crm/${C.readonly}/contact`, 403, "crm_contact_write", { body: { name: "Nope" } });
+  await apiError("GET", `/crm/${C.readonly}/deal`, 403, "crm_deal_read");
+  await apiError("GET", `/crm/${C.readonly}/pipeline`, 403, "crm_pipeline_read");
+  await apiError("GET", `/crm/${C.paused}/contact`, 403, "paused");
+  await apiError("GET", `/crm/${C.broken}/contact`, 401, "likely broken");
+  await apiError("GET", `/crm/${C.hris}/contact`, 501, "not supported by this integration");
+  assert.deepEqual(ids((await get(`/crm/${C.sandbox}/contact`)).json), [K.sandbox]);
+  await apiError("GET", `/crm/${NONE}/contact`, 404, "Connection not found");
+  assert.equal((await api404(`${M}/lead`)), 404);
+}
+
+async function api404(path) {
+  const response = await fetch(`${process.env.FIREDRILL_HTTP_URL}${path}`, { method: "POST", headers: { authorization: `Bearer ${process.env.FIREDRILL_HTTP_TOKEN}`, "content-type": "application/json" }, body: "{}" });
+  await response.text();
+  return response.status;
+}

package/test/flows/faults.mjs

@@ -0,0 +1,82 @@
+// Fault and bound drills: rate-limited, write-unavailable, write-committed-lost, bounds, many-workspaces, large-channels.
+import { C, CH, CO, NEW, apiError, assert, get, ids, mcpError, mcpInit, post } from "../lib.mjs";
+import { ALL_CALLS, expectAll } from "./identity.mjs";
+
+const M = `/crm/${C.main}`;
+const H = `/messaging/${C.chat}`;
+
+export async function rateLimited() {
+  const results = await expectAll(429, "Too many requests to Unified.to");
+  for (const [operationId, result] of results) {
+    assert.equal(result.headers.get("retry-after"), "1", `${operationId}: Retry-After header`);
+    assert.equal(result.json.error, "Too Many Requests");
+  }
+  await mcpInit();
+  await mcpError("list_unified_connections", {}, "RATE_LIMITED");
+}
+
+export async function writeUnavailable() {
+  const writes = ALL_CALLS.filter(([operationId]) => /\.(create|update|remove)$/.test(operationId));
+  assert.equal(writes.length, 15);
+  for (const [, method, path, body] of writes) {
+    const result = await apiError(method, path, 500, "Internal Server Error", body === undefined ? {} : { body });
+    assert.equal(result.json.error, "Internal Server Error");
+  }
+  // PUT routes share the operation with PATCH: both are unavailable.
+  await apiError("PUT", `${M}/contact/68c800000000000000000501`, 500, "Internal Server Error", { body: { title: "x" } });
+  assert.equal((await get(`${M}/contact`)).json.length, 8, "reads keep working and nothing was written");
+  assert.equal((await get("/unified/connection")).json.length, 7);
+}
+
+export async function writeCommittedLost() {
+  await apiError("POST", `${H}/message`, 500, "Internal Server Error", { body: { message: "Ship it", channels: [{ id: CH.sales }] } });
+  const latest = (await get(`${H}/message?channel_id=${CH.sales}&sort=created_at&order=desc&limit=1`)).json;
+  assert.deepEqual(ids(latest), [NEW(1)], "the message was committed although the response was lost");
+  assert.equal(latest[0].message, "Ship it");
+  // A blind client retry posts a duplicate.
+  await apiError("POST", `${H}/message`, 500, "Internal Server Error", { body: { message: "Ship it", channels: [{ id: CH.sales }] } });
+  assert.deepEqual(ids((await get(`${H}/message?channel_id=${CH.sales}&query=ship`)).json), [NEW(1), NEW(2)]);
+  assert.equal((await get(`${H}/message?channel_id=${CH.sales}`)).json.length, 7);
+}
+
+export async function bounds() {
+  const contacts = await apiError("GET", `${M}/contact`, 500, "State exceeds the supported bound of 5 rows for contacts");
+  assert.equal(contacts.json.error, "Internal Server Error");
+  await apiError("GET", `${H}/message?limit=1`, 500, "bound of 5 rows for messages");
+  await apiError("GET", "/unified/connection", 500, "bound of 5 rows for connections");
+  assert.equal((await get(`${M}/company`)).json.length, 5, "a namespace within the bound still lists");
+  await apiError("POST", `${M}/contact`, 500, "bound of 5 rows for contacts", { body: { name: "Over" } });
+  await apiError("DELETE", `/unified/connection/${C.main}`, 500, "bound of 5 rows", {});
+  assert.equal((await get(`/unified/connection/${C.main}`)).json.id, C.main, "the cascade refused instead of half-deleting");
+}
+
+export async function manyWorkspaces() {
+  const results = await expectAll(500, "State exceeds the supported bound of 100 rows for workspaces");
+  assert.equal(results.length, 29);
+  await mcpInit();
+  await mcpError("list_unified_connections", {}, "FAILED_PRECONDITION");
+}
+
+export async function largeChannels() {
+  const tooLarge = await apiError("GET", `${H}/channel`, 413, "Response exceeds 1 MB");
+  assert.equal(tooLarge.json.error, "Payload Too Large");
+  await apiError("GET", `${H}/channel?limit=100`, 413, "Response exceeds 1 MB");
+  const sizes = [];
+  const seen = [];
+  for (let offset = 0; ; offset += 1) {
+    const result = await get(`${H}/channel?limit=1&offset=${offset}`);
+    assert.ok(Buffer.byteLength(result.text) <= 900000, "each page stays within the budget");
+    sizes.push(result.json.length);
+    seen.push(...ids(result.json));
+    if (result.json.length < 1) break;
+  }
+  assert.equal(seen.length, 6, "every channel appears exactly once when paged");
+  assert.equal(new Set(seen).size, 6);
+  const projected = (await get(`${H}/channel?fields=id,name,description`)).json;
+  assert.equal(projected.length, 6, "a projection without members fits one page");
+  assert.equal(projected.filter((row) => row.name.startsWith("all-hands-")).length, 2);
+  assert.equal((await get(`${H}/channel?fields=id,name&limit=100`)).json.length, 6);
+  assert.equal((await get(`${H}/channel?limit=1&offset=4`)).json[0].members.length, 350);
+  assert.equal((await get(`${H}/channel/68c800000000000000070000`)).json.members.length, 350);
+  assert.equal((await get(`${M}/company`)).json.length, 5, CO.northwind);
+}

package/test/flows/identity.mjs

@@ -0,0 +1,84 @@
+// Drills unified-scoped-token, unified-invalid-workspace, unified-denied, unified-fresh-actor, plus the table of one
+// representative request per operation shared by the whole-surface drills (ghost, rate-limited, many-workspaces).
+import { C, CH, CO, D, K, MSG, NEW, NONE, PL, apiError, assert, get, ids, mcpError, mcpInit, post } from "../lib.mjs";
+
+const M = `/crm/${C.main}`;
+const H = `/messaging/${C.chat}`;
+
+/** One request per operation that succeeds against baseline for the admin actor (used where a fault or identity rule fires first). */
+export const ALL_CALLS = [
+  ["connections.list", "GET", "/unified/connection"],
+  ["connections.get", "GET", `/unified/connection/${C.chat}`],
+  ["connections.create", "POST", "/unified/connection", { integration_type: "zoho", categories: ["crm"], permissions: [] }],
+  ["connections.update", "PATCH", `/unified/connection/${C.chat}`, { external_xref: "probe" }],
+  ["connections.remove", "DELETE", `/unified/connection/${C.hris}`],
+  ["contacts.list", "GET", `${M}/contact`],
+  ["contacts.get", "GET", `${M}/contact/${K.elena}`],
+  ["contacts.create", "POST", `${M}/contact`, { name: "Probe" }],
+  ["contacts.update", "PATCH", `${M}/contact/${K.elena}`, { title: "Probe" }],
+  ["contacts.remove", "DELETE", `${M}/contact/${K.ravi}`],
+  ["companies.list", "GET", `${M}/company`],
+  ["companies.get", "GET", `${M}/company/${CO.northwind}`],
+  ["companies.create", "POST", `${M}/company`, { name: "Probe Co" }],
+  ["companies.update", "PUT", `${M}/company/${CO.northwind}`, { industry: "Probe" }],
+  ["companies.remove", "DELETE", `${M}/company/${CO.tailspin}`],
+  ["deals.list", "GET", `${M}/deal`],
+  ["deals.get", "GET", `${M}/deal/${D.q4}`],
+  ["deals.create", "POST", `${M}/deal`, { name: "Probe deal" }],
+  ["deals.update", "PATCH", `${M}/deal/${D.q4}`, { description: "Probe" }],
+  ["deals.remove", "DELETE", `${M}/deal/${D.inbound}`],
+  ["pipelines.list", "GET", `${M}/pipeline`],
+  ["pipelines.get", "GET", `${M}/pipeline/${PL.sales}`],
+  ["channels.list", "GET", `${H}/channel`],
+  ["channels.get", "GET", `${H}/channel/${CH.general}`],
+  ["messages.list", "GET", `${H}/message`],
+  ["messages.get", "GET", `${H}/message/${MSG(1)}`],
+  ["messages.create", "POST", `${H}/message`, { message: "probe", channels: [{ id: CH.sales }] }],
+  ["messages.update", "PATCH", `${H}/message/${MSG(2)}`, { message: "probe" }],
+  ["messages.remove", "DELETE", `${H}/message/${MSG(4)}`],
+];
+
+/** Sends every representative request expecting the same status and message fragment; returns the responses. */
+export async function expectAll(status, fragment) {
+  const results = [];
+  for (const [operationId, method, path, body] of ALL_CALLS) {
+    const result = await apiError(method, path, status, fragment, body === undefined ? {} : { body });
+    results.push([operationId, result]);
+  }
+  return results;
+}
+
+export async function scoped() {
+  assert.deepEqual(ids((await get("/unified/connection")).json), [C.chat], "a scoped key lists only its connections");
+  await apiError("GET", `/unified/connection/${C.main}`, 404, "Connection not found");
+  await apiError("GET", `${M}/contact`, 404, "Connection not found");
+  assert.equal((await get(`${H}/message`)).json.length, 16);
+  await apiError("POST", "/unified/connection", 403, "Connection-scoped tokens cannot create connections", { body: { integration_type: "zoho", categories: ["crm"] } });
+  await apiError("DELETE", `/unified/connection/${C.main}`, 404, "Connection not found");
+}
+
+export async function ghost() {
+  const results = await expectAll(401, "Unauthorized");
+  assert.equal(results.length, 29);
+  for (const [, result] of results) assert.equal(result.json.error, "Unauthorized");
+  await mcpInit();
+  const failure = await mcpError("list_unified_connections", {}, "UNAUTHORIZED");
+  assert.equal(failure.status, "tool_error");
+}
+
+export async function denied() {
+  for (const [method, path, body] of [["GET", "/unified/connection"], ["GET", `${M}/contact`], ["POST", `${H}/message`, { message: "x", channels: [{ id: CH.sales }] }]]) {
+    const result = await apiError(method, path, 403, "Forbidden", body === undefined ? {} : { body });
+    assert.equal(result.json.error, "Forbidden");
+  }
+}
+
+export async function fresh() {
+  assert.equal((await get("/unified/connection")).json.length, 7, "a fresh-install actor sees the seeded workspace");
+  assert.equal((await get(`${M}/contact`)).json.length, 8);
+  const created = (await post(`${M}/contact`, { name: "Fresh", emails: [{ email: "fresh@example.org" }] })).json;
+  assert.equal(created.id, NEW(1));
+  assert.equal((await get(`${M}/contact/${NEW(1)}`)).json.name, "Fresh");
+  assert.deepEqual(ids((await get(`${M}/contact?updated_gte=2026-09-15`)).json), [K.sam, NEW(1)], "zone-less updated_gte is accepted as UTC");
+  assert.notEqual(NONE, NEW(1));
+}

package/test/flows/messaging.mjs

@@ -0,0 +1,82 @@
+// Drill unified-messaging-flow (admin, baseline): channels, messages, aliases, threads, filters and author identity.
+import { C, CH, MSG, NEW, NONE, apiError, assert, del, get, ids, noneHas, patch, post, walk } from "../lib.mjs";
+
+const H = `/messaging/${C.chat}`;
+const MAIL = `/messaging/${C.mail}`;
+
+export async function messaging() {
+  // Channels.
+  const channels = (await get(`${H}/channel`)).json;
+  assert.deepEqual(ids(channels), [CH.general, CH.sales, CH.exec, CH.emea]);
+  assert.equal(channels.find((row) => row.id === CH.sales).has_subchannels, true, "has_subchannels computed from parent_id rows");
+  assert.equal(channels.find((row) => row.id === CH.general).has_subchannels, false);
+  assert.ok(noneHas(channels, "alias") && noneHas(channels, "connection_id"), "internal alias field is never returned");
+  assert.deepEqual(ids((await get(`${H}/channel?type=PRIVATE`)).json), [CH.exec]);
+  assert.deepEqual(ids((await get(`${H}/channel?parent_id=${CH.sales}`)).json), [CH.emea]);
+  assert.deepEqual(ids((await get(`${H}/channel?query=exec`)).json), [CH.exec]);
+  assert.deepEqual(ids((await get(`${H}/channel?sort=name&order=desc&limit=2`)).json), [CH.emea, CH.sales]);
+  await apiError("GET", `${H}/channel?type=SECRET`, 400, "type must be one of");
+  assert.equal((await get(`${H}/channel/${CH.exec}`)).json.is_private, true);
+  assert.equal((await get(`${H}/channel/${CH.sales}`)).json.has_subchannels, true);
+  await apiError("GET", `${H}/channel/${NONE}`, 404, "Channel not found");
+
+  // Message filters.
+  assert.equal((await get(`${H}/message?channel_id=${CH.general}`)).json.length, 9);
+  assert.deepEqual(ids((await get(`${H}/message?channel_id=${CH.general}&parent_id=${MSG(1)}`)).json), [MSG(2), MSG(3), MSG(4)]);
+  assert.deepEqual(ids((await get(`${H}/message?type=UNREAD`)).json), [MSG(6), MSG(9)]);
+  assert.deepEqual(ids((await get(`${H}/message?user_id=u-opsbot`)).json), [MSG(5), MSG(13)]);
+  assert.deepEqual(ids((await get(`${H}/message?user_mentioned_id=u-maya`)).json), [MSG(3)]);
+  assert.deepEqual(ids((await get(`${H}/message?start_gte=2026-09-10&end_lt=2026-09-13`)).json), [MSG(7), MSG(8), MSG(16)]);
+  assert.deepEqual(ids((await get(`${H}/message?query=%E5%B1%B1%E7%94%B0`)).json), [MSG(9)], "query matches CJK text");
+  assert.deepEqual((await get(`${H}/message?channel_id=INBOX`)).json, [], "alias without a matching channel matches nothing");
+  assert.deepEqual(ids((await get(`${MAIL}/message?channel_id=INBOX`)).json), [MSG(17), MSG(18)]);
+  assert.deepEqual(ids((await get(`${MAIL}/message?channel_id=SENT`)).json), [MSG(19)]);
+  assert.deepEqual(ids((await get(`${MAIL}/message?channel_id=DRAFT`)).json), [MSG(20)]);
+  assert.deepEqual(ids((await get(`${MAIL}/message?type=UNREAD`)).json), [MSG(17)]);
+  assert.deepEqual(ids((await get(`${MAIL}/message?sort=name&order=asc&limit=1`)).json), [MSG(18)], "sort=name orders messages by subject");
+  await apiError("GET", `${H}/message?channel_id=notahexid`, 400, "channel_id must be a valid id");
+  await apiError("GET", `${H}/message?start_gte=yesterday`, 400, "start_gte");
+  assert.equal(ids((await get(`${H}/message?sort=created_at&order=desc`)).json)[0], MSG(9), "newest chat message first");
+  assert.equal((await walk(`${H}/message`, 5, [5, 5, 5, 1])).length, 16);
+  const long = (await get(`${H}/message/${MSG(8)}`)).json;
+  assert.equal(long.message.length, 2982, "the seeded long-form message round-trips intact");
+  assert.equal((await get(`${H}/message/${MSG(7)}`)).json.attachments[0].filename, "onboarding-deck.pdf");
+  await apiError("GET", `${H}/message/${NONE}`, 404, "Message not found");
+
+  // Create: author from the connection, reply inherits channels, parent has_children maintained.
+  await apiError("POST", `${H}/message`, 400, "One of message", { body: {} });
+  await apiError("POST", `${H}/message`, 400, "Unknown channel id", { body: { message: "x", channels: [{ id: NONE }] } });
+  await apiError("POST", `${H}/message`, 400, "Unknown parent_id", { body: { message: "y", parent_id: NONE } });
+  await apiError("POST", `${H}/message`, 400, "Invalid value for message", { body: { message: "x".repeat(20001), channels: [{ id: CH.sales }] } });
+  await apiError("POST", `${H}/message`, 400, "channels[0].id or parent_id", { body: { message: "no channel" } });
+  const posted = (await post(`${H}/message`, { message: "Deploy done", channels: [{ id: CH.sales }], author_member: { user_id: "spoofed", name: "Spoof" } })).json;
+  assert.equal(posted.id, NEW(1));
+  assert.deepEqual(posted.author_member, { user_id: "u-opsbot", email: null, name: "Ops Bot", image_url: null }, "author comes from the connection, not the body");
+  assert.deepEqual(posted.channels, [{ id: CH.sales, name: "sales" }]);
+  assert.equal(posted.has_children, false);
+  assert.equal(posted.is_unread, false);
+  assert.equal((await get(`${H}/message/${MSG(5)}`)).json.has_children, false);
+  const reply = (await post(`${H}/message`, { message: "re", parent_id: MSG(5) })).json;
+  assert.equal(reply.id, NEW(2));
+  assert.deepEqual(reply.channels, [{ id: CH.general, name: "general" }], "reply inherits the parent's channels");
+  assert.equal((await get(`${H}/message/${MSG(5)}`)).json.has_children, true);
+  assert.deepEqual(ids((await get(`${H}/message?parent_id=${MSG(5)}`)).json), [NEW(2)]);
+
+  // Update and remove.
+  const edited = (await patch(`${H}/message/${NEW(1)}`, { is_unread: true, message: "edited" })).json;
+  assert.equal(edited.message, "edited");
+  assert.equal(edited.is_unread, true);
+  await apiError("PATCH", `${H}/message/${NEW(1)}`, 400, "must remain set", { body: { message: null, message_html: null, message_markdown: null } });
+  assert.equal((await get(`${H}/message/${NEW(1)}`)).json.message, "edited");
+  assert.deepEqual((await del(`${H}/message/${NEW(2)}`)).json, {});
+  assert.equal((await get(`${H}/message/${MSG(5)}`)).json.has_children, false, "parent recomputed after the last reply is removed");
+  await apiError("GET", `${H}/message/${NEW(2)}`, 404, "Message not found");
+  await apiError("DELETE", `${H}/message/${NEW(2)}`, 404, "Message not found");
+  assert.equal((await get(`${H}/message`)).json.length, 17);
+
+  // Category and absent routes.
+  await apiError("GET", `/messaging/${C.main}/channel`, 501, "not supported by this integration");
+  const absent = await fetch(`${process.env.FIREDRILL_HTTP_URL}${H}/channel`, { method: "POST", headers: { authorization: `Bearer ${process.env.FIREDRILL_HTTP_TOKEN}`, "content-type": "application/json" }, body: "{}" });
+  await absent.text();
+  assert.ok(absent.status === 404 || absent.status === 405, `POST channel -> ${absent.status}`);
+}