@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/org/param-contract.test.mjs

@@ -1,477 +0,0 @@
-/**
- * param-contract.test.mjs — the wire param contract (lib/org/param-contract.mjs).
- *
- * Three layers, all hermetic (no network, no disk):
- *
- *  1. NORMALISER MECHANICS — alias/mint/fold/strict/enum/transform, purity,
- *     idempotence, and the fail-open guarantees.
- *  2. ONE REGRESSION PER DRIFT ROW — every row the 2026-08 wire audit found gets
- *     a test that asserts the canonical name hq validates is on the wire. These
- *     are the tests that would have gone red on the day each bug shipped.
- *  3. SURFACE GUARD — a static sweep of the curated LLM tool table asserting no
- *     tool advertises a param name hq does not read. This is the CI half of
- *     "impossible to ship again": it needs no credentials and no server.
- *
- * Run: node --test lib/org/param-contract.test.mjs
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  PARAM_CONTRACT,
-  BOARD_COLS,
-  TASK_PRIORITIES,
-  MEMORY_CLASSES,
-  ESCALATION_SEVERITIES,
-  hasContract,
-  contractFor,
-  normalizeParams,
-  missingRequired,
-  formatReport,
-  reportIsInteresting,
-  logReportOnce,
-  _resetLogOnce,
-  toRegisterParams,
-} from "./param-contract.mjs";
-import { ORG_TOOLS } from "./tool-surface.mjs";
-import { methodDef } from "./protocol.mjs";
-
-/** Normalise with a deterministic id so wire bodies are comparable. */
-const norm = (method, params) =>
-  normalizeParams(method, params, { mintId: () => "MINTED" });
-/** Just the wire body. */
-const wire = (method, params) => norm(method, params).params;
-
-// ═══════════════════════════════════════════════════════════════════════════
-// 1. normaliser mechanics
-// ═══════════════════════════════════════════════════════════════════════════
-
-test("a method with no contract entry passes through byte-for-byte", () => {
-  const input = { anything: 1, nested: { a: [1, 2] } };
-  const r = norm("presence.beat", input);
-  assert.deepEqual(r.params, input);
-  assert.deepEqual(r.renamed, []);
-  assert.equal(hasContract("presence.beat"), false);
-  assert.equal(contractFor("presence.beat"), null);
-});
-
-test("PURE: the caller's params object is never mutated", () => {
-  const input = { channelId: "C1", body: "hi" };
-  const snapshot = JSON.parse(JSON.stringify(input));
-  norm("messaging.send", input);
-  assert.deepEqual(input, snapshot, "input untouched");
-});
-
-test("TOTAL: null / non-object / unknown method never throw", () => {
-  assert.deepEqual(norm("messaging.send", null).params.body, undefined);
-  assert.doesNotThrow(() => norm(undefined, undefined));
-  assert.doesNotThrow(() => norm("no.such.method", { a: 1 }));
-  assert.deepEqual(norm("no.such.method", { a: 1 }).params, { a: 1 });
-});
-
-test("alias: an EXPLICIT canonical value always beats a legacy one", () => {
-  const w = wire("decision.comment", { body: "legacy", text: "canonical" });
-  assert.equal(w.text, "canonical");
-});
-
-test("alias: the legacy key rides along by default (an older server may read it)", () => {
-  const w = wire("member.get", { memberId: "m-1" });
-  assert.equal(w.slug, "m-1", "canonical name added");
-  assert.equal(w.memberId, "m-1", "legacy name kept — hq's schema is not strict");
-});
-
-test("strict: hq's .strict() schemas drop every unknown key, legacy names included", () => {
-  const r = norm("board.complete", { itemId: "i-1", note: "shipped", stray: 1 });
-  assert.deepEqual(Object.keys(r.params).sort(), ["itemId", "proof"]);
-  assert.deepEqual(r.params.proof, { note: "shipped" });
-  assert.ok(r.dropped.includes("note") && r.dropped.includes("stray"));
-});
-
-test("mint: a required business-dedup id is auto-minted only when absent", () => {
-  assert.equal(wire("messaging.send", { channelId: "C", body: "x" }).idempotencyId, "MINTED");
-  assert.equal(
-    wire("messaging.send", { channelId: "C", body: "x", idempotencyId: "keep" }).idempotencyId,
-    "keep",
-  );
-  // An empty string is not an id — mint over it.
-  assert.equal(wire("messaging.send", { channelId: "C", body: "x", idempotencyId: "" }).idempotencyId, "MINTED");
-});
-
-test("fold: enrichment hq only persists inside a container is moved there", () => {
-  const r = norm("knowledge.append", {
-    body: "note",
-    kind: "call",
-    participants: ["a"],
-    links: ["u"],
-    refs: ["r"],
-  });
-  assert.deepEqual(r.params.metadata, { kind: "call", participants: ["a"], links: ["u"], refs: ["r"] });
-  assert.deepEqual(r.folded.sort(), ["kind", "links", "participants", "refs"]);
-  // A pre-existing metadata bag is merged into, never clobbered.
-  const merged = wire("knowledge.append", { body: "n", metadata: { keep: 1 }, kind: "call" });
-  assert.deepEqual(merged.metadata, { keep: 1, kind: "call" });
-});
-
-test("enums: a case-variant value is coerced; an unmappable one is reported, not dropped", () => {
-  const ok = norm("board.createTask", { title: "t", status: "TODO" });
-  assert.equal(ok.params.col, "todo");
-  const bad = norm("board.createTask", { title: "t", status: "in-progress" });
-  assert.equal(bad.params.col, "in-progress", "left for the server to reject — we do not invent values");
-  assert.ok(bad.notes.some((n) => n.includes("in-progress")));
-});
-
-test("fail-open: a throwing transform loses nothing", () => {
-  const saved = PARAM_CONTRACT["member.get"].transform;
-  PARAM_CONTRACT["member.get"].transform = () => {
-    throw new Error("boom");
-  };
-  try {
-    const w = wire("member.get", { memberId: "m-1" });
-    assert.equal(w.slug, "m-1", "alias still applied after the transform faulted");
-  } finally {
-    if (saved === undefined) delete PARAM_CONTRACT["member.get"].transform;
-    else PARAM_CONTRACT["member.get"].transform = saved;
-  }
-});
-
-test("IDEMPOTENT: normalising twice is the same as normalising once", () => {
-  for (const method of Object.keys(PARAM_CONTRACT)) {
-    const seed = {
-      itemId: "i", taskId: "t", decisionId: "d", channelId: "c", messageId: "msg",
-      callId: "call", memberId: "m", scope: "work-claim", resourceId: "r",
-      id: "x", title: "T", body: "B", text: "X", emoji: "+1", assignee: "a",
-      actionClass: "external_comms", payload: { a: 1 }, decision: "approve",
-      displayName: "D",
-    };
-    const once = normalizeParams(method, seed, { mintId: () => "M" }).params;
-    const twice = normalizeParams(method, once, { mintId: () => "M" }).params;
-    assert.deepEqual(twice, once, `${method} is not idempotent`);
-  }
-});
-
-test("missingRequired: reports absent required names and unmet one-of groups", () => {
-  assert.deepEqual(missingRequired("decision.comment", { decisionId: "d" }), ["text"]);
-  assert.deepEqual(missingRequired("escalation.create", { title: "t" }), ["taskId|channelId"]);
-  assert.deepEqual(missingRequired("escalation.create", { title: "t", channelId: "c" }), []);
-  // An empty string / empty array is not "present".
-  assert.deepEqual(missingRequired("calling.start", { participantIds: [] }), ["channelId|participantIds"]);
-  assert.deepEqual(missingRequired("no.such.method", {}), []);
-});
-
-test("reporting: a rewrite is never silent, and never logged twice", () => {
-  _resetLogOnce();
-  const lines = [];
-  const sink = (l) => lines.push(l);
-  const r = norm("member.get", { memberId: "m-1" });
-  assert.equal(reportIsInteresting(r), true);
-  assert.match(formatReport("member.get", r), /renamed memberId→slug/);
-  assert.equal(logReportOnce("member.get", r, sink), true);
-  assert.equal(logReportOnce("member.get", r, sink), false, "one shot per distinct rewrite");
-  assert.equal(lines.length, 1);
-  // A clean call says nothing.
-  const clean = norm("member.get", { slug: "agent-one" });
-  assert.equal(reportIsInteresting(clean), false);
-  assert.equal(formatReport("member.get", clean), "");
-  assert.equal(logReportOnce("member.get", clean, sink), false);
-});
-
-// ═══════════════════════════════════════════════════════════════════════════
-// 2. one regression per DRIFT row (2026-08 wire audit)
-// ═══════════════════════════════════════════════════════════════════════════
-
-// ── P0: the feature was 100 % dead — every call returned BAD_REQUEST ────────
-
-test("P0/1 messaging.send: hq requires idempotencyId, NOT clientMsgId", () => {
-  const w = wire("messaging.send", { channelId: "C1", body: "hello", clientMsgId: "cm-1" });
-  assert.equal(w.idempotencyId, "cm-1", "the minted dedup id lands on the name hq reads");
-  assert.deepEqual(missingRequired("messaging.send", w), []);
-});
-
-test("P0/2 registry.register: the raw self-entry is projected onto the .strict() schema", () => {
-  // A persona-agnostic fixture: the framework must carry no instance identity.
-  const entry = {
-    id: "A001", name: "agent-one", fullName: "Agent One", title: "Engineer",
-    email: "agent-one@example.test", repo: "example-org/agent-one",
-    archetype: { function: "engineering", altitude: "specialist", label: "Specialist Engineer" },
-    towers: ["eng"], focus: "wire contracts", principal: { fullName: "Sponsor Name" },
-    presence: "online", status: "ACTIVE",
-  };
-  const r = norm("registry.register", entry);
-  assert.deepEqual(Object.keys(r.params).sort(), ["archetype", "card", "displayName", "humanSponsor"]);
-  assert.equal(r.params.displayName, "Agent One");
-  assert.equal(r.params.archetype, "Specialist Engineer", "the archetype OBJECT is flattened to a string");
-  assert.equal(r.params.humanSponsor, "Sponsor Name");
-  assert.deepEqual(r.params.card, entry, "everything hq does not model is preserved under card");
-  // …and every one of those raw top-level keys is gone from the wire.
-  for (const k of ["id", "name", "fullName", "email", "repo", "towers", "focus", "presence", "status"]) {
-    assert.equal(r.params[k], undefined, `${k} would have 400'd the strict schema`);
-  }
-});
-
-test("P0/2b toRegisterParams is idempotent — an already-projected object is untouched", () => {
-  const projected = { displayName: "D", archetype: "A", humanSponsor: "H", card: { x: 1 } };
-  assert.deepEqual(toRegisterParams(projected), projected);
-  assert.deepEqual(toRegisterParams(null), { card: {} });
-});
-
-test("P0/3 memory.author: hq requires {memoryClass (enum), title}", () => {
-  const w = wire("memory.author", { content: "Q3 pricing moved to usage-based.\nDetail follows.", kind: "STRATEGY" });
-  assert.equal(w.memoryClass, "strategy", "kind→memoryClass, case-folded into hq's enum");
-  assert.equal(w.title, "Q3 pricing moved to usage-based.", "a title is derived from the first line");
-  assert.equal(w.summary, "Q3 pricing moved to usage-based.\nDetail follows.");
-  assert.deepEqual(missingRequired("memory.author", w), []);
-  assert.ok(MEMORY_CLASSES.includes(w.memoryClass));
-});
-
-test("P0/3b memory.author: `tags` are NOT scopes — they are reported, never smuggled into the ACL", () => {
-  const r = norm("memory.author", { memoryClass: "ledger", title: "t", tags: ["private", "finance"] });
-  assert.equal(r.params.scopes, undefined, "tags must never become ACL scopes");
-  assert.ok(r.unsupported.includes("tags"));
-});
-
-test("P0/4 escalation.create: hq requires a title AND a target", () => {
-  const w = wire("escalation.create", { severity: "high", subject: "Deploy blocked", body: "CI is red" });
-  assert.equal(w.title, "Deploy blocked");
-  assert.equal(w.detail, "CI is red");
-  assert.deepEqual(missingRequired("escalation.create", w), ["taskId|channelId"]);
-  assert.deepEqual(missingRequired("escalation.create", { ...w, taskId: "t-1" }), []);
-  assert.ok(ESCALATION_SEVERITIES.includes(w.severity));
-});
-
-test("P0/5 member.get: hq resolves by slug, not memberId", () => {
-  assert.equal(wire("member.get", { memberId: "m-1" }).slug, "m-1");
-  assert.equal(wire("member.get", { id: "m-2" }).slug, "m-2");
-});
-
-test("P0/6 decision.comment: hq reads `text`, and threw on `body`", () => {
-  const w = wire("decision.comment", { decisionId: "d-1", body: "agreed" });
-  assert.equal(w.text, "agreed");
-  assert.deepEqual(missingRequired("decision.comment", w), []);
-});
-
-test("P0/7 approval.request: actionClass is REQUIRED; the hash and expiry are renamed", () => {
-  const w = wire("approval.request", {
-    id: "ap-1",
-    kind: "external_comms",
-    subject: "email to a new contact",
-    payload_hash: "a".repeat(64),
-    requester: "acme",
-    expiresInMs: 3_600_000,
-  });
-  assert.equal(w.actionClass, "external_comms", 'hq threw "actionClass is required" on every call');
-  assert.equal(w.payloadHash, "a".repeat(64));
-  assert.ok(Date.parse(w.expiresAt) > Date.now(), "expiresInMs → an absolute expiresAt");
-  assert.deepEqual(missingRequired("approval.request", w), []);
-});
-
-test("P0/7b approval.request: `requester` is server-derived and is reported as not-read", () => {
-  const r = norm("approval.request", { actionClass: "x", payload: {}, requester: "acme" });
-  assert.ok(r.unsupported.includes("requester"));
-});
-
-test("P0/8 calling.start: hq's refine demands channelId or a non-empty participantIds", () => {
-  const w = wire("calling.start", { channel: "C1", invitees: ["m1", "m2"], topic: "standup", id: "i-1" });
-  assert.equal(w.channelId, "C1");
-  assert.deepEqual(w.participantIds, ["m1", "m2"]);
-  assert.deepEqual(missingRequired("calling.start", w), []);
-  // The topic has nowhere to go on hq's schema — say so rather than pretend.
-  assert.ok(norm("calling.start", { channel: "C1", topic: "standup" }).unsupported.includes("topic"));
-});
-
-test("P0/9 board.complete: `note` 400'd the .strict() schema — it is wrapped as proof.note", () => {
-  assert.deepEqual(wire("board.complete", { itemId: "i-1", note: "PR #42 merged" }), {
-    itemId: "i-1",
-    proof: { note: "PR #42 merged" },
-  });
-  // A caller that already speaks `proof` is left alone.
-  assert.deepEqual(wire("board.complete", { itemId: "i-1", proof: { url: "u" } }), {
-    itemId: "i-1",
-    proof: { url: "u" },
-  });
-});
-
-// ── P1: the call SUCCEEDED but silently discarded the caller's intent ───────
-
-test("P1/10 board.createTask: description/assignee/status were stripped by zod", () => {
-  const r = norm("board.createTask", {
-    title: "Ship the probe",
-    description: "wire conformance",
-    assignee: "m-1",
-    status: "todo",
-    priority: "P1",
-    dueAt: "2026-09-01",
-  });
-  assert.equal(r.params.detail, "wire conformance");
-  assert.equal(r.params.assigneeId, "m-1");
-  assert.equal(r.params.col, "todo");
-  assert.equal(r.params.priority, "P1");
-  // createTaskSchema models no dueAt at all — the loss is reported, not hidden.
-  assert.ok(r.unsupported.includes("dueAt"));
-  assert.ok(r.notes.some((n) => n.includes("board.updateTask")));
-});
-
-test("P1/11 board.updateTask: editTaskSchema has NO assignee — reassignment needs board.assignTask", () => {
-  const r = norm("board.updateTask", { taskId: "t-1", status: "review", description: "d", assignee: "m-9" });
-  assert.equal(r.params.col, "review");
-  assert.equal(r.params.detail, "d");
-  assert.ok(r.unsupported.includes("assignee"), "an agent that thought it reassigned a task did not");
-  // The verb that DOES work.
-  assert.deepEqual(missingRequired("board.assignTask", wire("board.assignTask", { taskId: "t-1", assignee: "m-9" })), []);
-  assert.equal(wire("board.assignTask", { taskId: "t-1", assignee: "m-9" }).assigneeId, "m-9");
-});
-
-test("P1/12 decision.propose: the rationale lives at why.reason, and `scope` is hq's `tag`", () => {
-  const w = wire("decision.propose", { title: "Adopt usage pricing", rationale: "margin", scope: "pricing" });
-  assert.deepEqual(w.why, { reason: "margin" });
-  assert.equal(w.tag, "pricing");
-  // An explicit why block is preserved and merged, not overwritten.
-  const merged = wire("decision.propose", { title: "t", why: { options: ["a", "b"] }, rationale: "r" });
-  assert.deepEqual(merged.why, { options: ["a", "b"], reason: "r" });
-});
-
-test("P1/13 messaging.history: hq paginates on before/after — since/cursor were dropped", () => {
-  const w = wire("messaging.history", { channel: "C1", cursor: "m-100", since: "m-1", limit: 50 });
-  assert.equal(w.channelId, "C1");
-  assert.equal(w.before, "m-100");
-  assert.equal(w.after, "m-1");
-  assert.equal(w.limit, 50);
-});
-
-test("P1/14 approval_request: a hash-only request keeps the hash on the name hq binds", () => {
-  const w = wire("approval.request", { actionClass: "external_comms", payload_hash: "b".repeat(64) });
-  assert.equal(w.payloadHash, "b".repeat(64));
-  assert.deepEqual(missingRequired("approval.request", w), [], "payload OR payloadHash satisfies the bind");
-});
-
-// ── P2: dropped enrichment ─────────────────────────────────────────────────
-
-test("P2/15 knowledge.append: kind/participants/links/refs now persist under metadata", () => {
-  const r = norm("knowledge.append", { text: "call notes", kind: "note", participants: ["a", "b"] });
-  assert.equal(r.params.body, "call notes", "hq reads body (text is its accepted alias)");
-  assert.deepEqual(r.params.metadata, { kind: "note", participants: ["a", "b"] });
-});
-
-test("P2/16 knowledge.search: kind/includeInvalid/lexical are not read by hq — reported", () => {
-  const r = norm("knowledge.search", { query: "pricing", kind: "note", includeInvalid: true, lexical: true });
-  assert.equal(r.params.q, "pricing");
-  assert.deepEqual(r.unsupported.sort(), ["includeInvalid", "kind", "lexical"]);
-});
-
-test("P2/17 contacts.upsert / meetings.record: the ACL `group` hint is not read", () => {
-  assert.ok(norm("contacts.upsert", { displayName: "X", group: "org" }).unsupported.includes("group"));
-  assert.ok(norm("meetings.record", { title: "T", group: "org" }).unsupported.includes("group"));
-});
-
-test("P2/18 leases: `holder` and `leaseToken` never round-trip — ownership is the actor", () => {
-  assert.ok(norm("lease.claim", { scope: "work-claim", resourceId: "r", holder: "me" }).unsupported.includes("holder"));
-  assert.ok(norm("lease.release", { scope: "work-claim", resourceId: "r", leaseToken: "t" }).unsupported.includes("leaseToken"));
-  assert.equal(wire("lease.claim", { scope: "s", resourceId: "r", token: "hash" }).tokenHash, "hash");
-});
-
-// ═══════════════════════════════════════════════════════════════════════════
-// 3. surface guard — the offline CI half
-// ═══════════════════════════════════════════════════════════════════════════
-
-test("GUARD: every contracted method is a real protocol method", () => {
-  for (const method of Object.keys(PARAM_CONTRACT)) {
-    assert.ok(methodDef(method), `${method} is not in the vendored protocol table`);
-  }
-});
-
-test("GUARD: no curated tool advertises a param name hq does not read", () => {
-  const offenders = [];
-  for (const t of ORG_TOOLS) {
-    if (!t.binding || t.binding.kind !== "rpc") continue;
-    const c = contractFor(t.binding.method);
-    if (!c || !c.alias) continue;
-    const stillRead = new Set(c.serverAccepts || []);
-    const props = Object.keys((t.input_schema && t.input_schema.properties) || {});
-    for (const p of props) {
-      // A legacy alias key the server does NOT also accept is a name the model
-      // would fill in and hq would ignore (or reject). That is the whole bug.
-      if (Object.prototype.hasOwnProperty.call(c.alias, p) && !stillRead.has(p)) {
-        offenders.push(`${t.name} (${t.binding.method}) advertises "${p}" — hq reads "${c.alias[p]}"`);
-      }
-    }
-  }
-  assert.deepEqual(offenders, [], `curated tools drifted from hq:\n  ${offenders.join("\n  ")}`);
-});
-
-test("GUARD: no curated tool advertises a param hq accepts but never reads", () => {
-  const offenders = [];
-  for (const t of ORG_TOOLS) {
-    if (!t.binding || t.binding.kind !== "rpc") continue;
-    const c = contractFor(t.binding.method);
-    if (!c || !c.unsupported) continue;
-    const props = Object.keys((t.input_schema && t.input_schema.properties) || {});
-    for (const p of props) {
-      if (c.unsupported.includes(p)) {
-        offenders.push(`${t.name} (${t.binding.method}) offers "${p}" — hq discards it`);
-      }
-    }
-  }
-  assert.deepEqual(offenders, [], `tools promise the model things hq drops:\n  ${offenders.join("\n  ")}`);
-});
-
-test("GUARD: a curated tool's REQUIRED params cover everything hq requires", () => {
-  const offenders = [];
-  for (const t of ORG_TOOLS) {
-    if (!t.binding || t.binding.kind !== "rpc") continue;
-    const c = contractFor(t.binding.method);
-    if (!c || !c.required) continue;
-    const props = new Set(Object.keys((t.input_schema && t.input_schema.properties) || {}));
-    for (const need of c.required) {
-      // Minted ids are supplied by the executor, not the model.
-      if ((c.mint || []).includes(need)) continue;
-      if (!props.has(need)) {
-        offenders.push(`${t.name} (${t.binding.method}) cannot supply required "${need}"`);
-      }
-    }
-  }
-  assert.deepEqual(offenders, [], `tools cannot satisfy hq:\n  ${offenders.join("\n  ")}`);
-});
-
-test("GUARD: enum-valued tool params list exactly hq's vocabulary", () => {
-  const byTool = {
-    task_create: { col: BOARD_COLS, priority: TASK_PRIORITIES },
-    task_update: { col: BOARD_COLS, priority: TASK_PRIORITIES },
-    memory_author: { memoryClass: MEMORY_CLASSES },
-    escalation_raise: { severity: ESCALATION_SEVERITIES },
-  };
-  for (const [toolName, expect] of Object.entries(byTool)) {
-    const t = ORG_TOOLS.find((x) => x.name === toolName);
-    assert.ok(t, `${toolName} is in the table`);
-    for (const [param, values] of Object.entries(expect)) {
-      assert.deepEqual(t.input_schema.properties[param].enum, values, `${toolName}.${param}`);
-    }
-  }
-});
-
-test("messaging.send/edit: mentions are coerced to hq's object shape at the ONE chokepoint", () => {
-  const sent = normalizeParams("messaging.send", {
-    channelId: "C-1",
-    body: "b",
-    idempotencyId: "i",
-    mentions: ["M-2", { memberId: "M-2" }, { id: "M-3" }, { memberId: "M-4", offset: 3 }, "", null],
-  });
-  assert.deepEqual(sent.params.mentions, [
-    { memberId: "M-2" },
-    { memberId: "M-3" },
-    { memberId: "M-4", offset: 3 },
-  ]);
-
-  // Idempotent: applying the contract twice must not re-wrap.
-  const twice = normalizeParams("messaging.send", sent.params);
-  assert.deepEqual(twice.params.mentions, sent.params.mentions);
-
-  // An empty list states nothing rather than asserting an empty relation.
-  const none = normalizeParams("messaging.send", { channelId: "C", body: "b", idempotencyId: "i", mentions: [] });
-  assert.equal("mentions" in none.params, false);
-
-  // messaging.edit reuses hq's mentionSchema, so it gets the same coercion.
-  const edited = normalizeParams("messaging.edit", { messageId: "m1", body: "b", mentions: ["M-9"] });
-  assert.deepEqual(edited.params.mentions, [{ memberId: "M-9" }]);
-});