@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/org/param-contract.mjs

@@ -0,0 +1,694 @@
+/**
+ * lib/org/param-contract.mjs — the WIRE PARAM CONTRACT between this SDK and hq.
+ *
+ * THE BUG CLASS THIS EXISTS TO KILL
+ * --------------------------------
+ * hq validates every `/v1/<method>` body with a zod schema that does NOT ship to
+ * the SDK. Nothing on this side knew hq's param NAMES, so they were re-invented
+ * per call site from JSDoc and memory. A wire audit found 18 methods where the
+ * name the SDK sent and the name hq reads had diverged. Two failure modes, both
+ * silent from the agent's point of view:
+ *
+ *   - hard: hq's schema REQUIRES the canonical name → every call came back
+ *     BAD_REQUEST. `messaging.send` (SDK sent `clientMsgId`, hq reads
+ *     `idempotencyId`) meant no agent message from the LLM tool plane had ever
+ *     landed; `approval.request` (SDK sent `kind`, hq reads `actionClass`) meant
+ *     the SDK-side governance gate had filed zero approvals; `registry.register`
+ *     (SDK sent the raw self-entry into a `.strict()` schema) meant no agent had
+ *     ever entered the org directory while the daemon logged "registered … with
+ *     the org mesh" on every boot.
+ *   - soft, and worse: hq's schema is NOT `.strict()`, so zod silently STRIPS the
+ *     unknown key and the call succeeds having discarded the caller's intent —
+ *     `board.createTask` accepted `assignee`/`status`/`description` and created
+ *     unassigned, untriaged, bodyless tasks.
+ *
+ * THE FIX: ONE table, applied at ONE chokepoint. `client.call()` is the single
+ * door every plane goes through — the 2 090 `ui-parity.mjs` wrappers, the curated
+ * `tool-surface.mjs` table, the `org_rpc` escape hatch, and every hand-written
+ * helper in `lib/org/*.mjs`. `normalizeParams` runs there, so a call site cannot
+ * opt out and a newly added wrapper inherits the contract for free.
+ *
+ * WHAT AN ENTRY DECLARES
+ * ----------------------
+ *   serverAccepts [names]           legacy names hq's OWN handler still reads as
+ *                                   aliases (`knowledge.append` takes body|text).
+ *                                   Documentation + the CI surface guard's
+ *                                   allow-list; the normaliser ignores it.
+ *   alias      {legacy: canonical}  rename when the canonical key is absent. The
+ *                                   legacy key STAYS on the wire by default
+ *                                   (harmless: hq's non-strict schemas strip it)
+ *                                   so an older server still reads it.
+ *   strict     [names]              hq's schema is `.strict()` — it REJECTS
+ *                                   unknown keys, so everything outside this list
+ *                                   is dropped (and reported).
+ *   mint       [names]              business-dedup ids hq requires and the caller
+ *                                   cannot be expected to invent (uuid).
+ *   fold       {into, keys}         enrichment hq only persists inside a
+ *                                   container column (knowledge metadata).
+ *   unsupported [names]             hq accepts-and-IGNORES: the param rides along
+ *                                   (an older/newer hq may read it) but is
+ *                                   REPORTED so the loss of intent is never
+ *                                   silent. This is the honest half of fail-open.
+ *   enums      {name: [values]}     hq throws on an out-of-vocabulary value;
+ *                                   we lowercase/normalise what we can and report
+ *                                   what we cannot.
+ *   required   [names]              hq 400s without these (probe + preflight).
+ *   oneOf      [[a,b], …]           hq's `.refine()` demands at least one of each
+ *                                   group.
+ *   transform  (params) => params   last-resort reshape (note→proof, entry→card,
+ *                                   rationale→why.reason, expiresInMs→expiresAt).
+ *
+ * PURE + FAIL-OPEN. Nothing here throws, does I/O, or reaches the network — it is
+ * a string-keyed rewrite over a plain object, unit-testable without a server.
+ * A method with no entry passes through byte-for-byte.
+ *
+ * THE LIVE HALF: a table cannot prove itself right — hq's schemas are the only
+ * authority. `scripts/ci/conformance-org-api.mjs` drives this same table against
+ * a real org and fails on BAD_REQUEST, which is the check that would have caught
+ * all 18 rows.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/org/param-contract
+ */
+
+"use strict";
+
+import { randomUUID } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// hq vocabularies (mirrored from the hq zod enums — the values hq throws on)
+// ---------------------------------------------------------------------------
+
+/** `Task.col` — hq `src/server/validation/task.ts#boardColEnum`. */
+export const BOARD_COLS = [
+  "triage",
+  "backlog",
+  "todo",
+  "scheduled",
+  "ready",
+  "running",
+  "review",
+  "blocked",
+  "done",
+  "archived",
+];
+
+/** `Task.priority` — hq `taskPriorityEnum` (P0 highest .. P4 lowest). */
+export const TASK_PRIORITIES = ["P0", "P1", "P2", "P3", "P4"];
+
+/** Escalation severity — hq `methods/escalation/_shared.ts#SEVERITIES`. */
+export const ESCALATION_SEVERITIES = ["low", "medium", "high", "critical"];
+
+/** `memory.author` memoryClass — hq `methods/memory/_shared.ts#MEMORY_CLASS_VALUES`. */
+export const MEMORY_CLASSES = [
+  "framework",
+  "constitution",
+  "strategy",
+  "policy",
+  "orggraph",
+  "sop",
+  "glossary",
+  "sources",
+  "ledger",
+];
+
+// ---------------------------------------------------------------------------
+// transforms
+// ---------------------------------------------------------------------------
+
+/** Is this a plain (non-array, non-null) object? */
+function isObj(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/** First non-empty string among the candidates, else "". */
+function firstString(...vals) {
+  for (const v of vals) {
+    if (typeof v === "string" && v.trim()) return v.trim();
+    if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  }
+  return "";
+}
+
+/**
+ * Project a rich maestro self-entry onto hq's `.strict()` registerSchema
+ * ({displayName, archetype, humanSponsor, card}). Everything the server does not
+ * model rides under `card` (chain-redacted to a `hasCard` boolean), which is what
+ * that field is for. IDEMPOTENT: an already-projected params object (has `card`,
+ * has no `id`) is returned unchanged, so applying the contract twice is safe.
+ *
+ * @param {object} entry
+ * @returns {object} registerSchema-shaped params
+ */
+export function toRegisterParams(entry) {
+  const e = isObj(entry) ? entry : {};
+  if (e.card !== undefined && e.id === undefined) return { ...e };
+
+  const displayName = firstString(e.fullName, e.name, e.displayName, e.id);
+  // `archetype` is an object in the maestro entry ({function,altitude,label});
+  // hq wants a single string. Prefer the human label, then the function.
+  const arch = e.archetype;
+  const archetype =
+    typeof arch === "string"
+      ? arch
+      : isObj(arch)
+        ? firstString(arch.label, arch.function, arch.altitude)
+        : "";
+  const humanSponsor = firstString(
+    isObj(e.principal) ? e.principal.fullName : "",
+    isObj(e.principal) ? e.principal.title : "",
+    e.humanSponsor,
+  );
+
+  const params = { card: e };
+  if (displayName) params.displayName = String(displayName).slice(0, 200);
+  if (archetype) params.archetype = String(archetype).slice(0, 120);
+  if (humanSponsor) params.humanSponsor = String(humanSponsor).slice(0, 200);
+  return params;
+}
+
+/**
+ * `board.complete` — hq's schema is `.strict()` with `proof: Record<string,unknown>`.
+ * The tool plane offers the model a free-text `note`, which is exactly the shape
+ * hq stores under `why.proof` — so wrap it rather than drop it.
+ */
+function completeProof(p) {
+  const out = { ...p };
+  if (out.proof === undefined) {
+    const note = firstString(out.note, out.summary, out.body, out.text);
+    if (note) out.proof = { note };
+  } else if (typeof out.proof === "string") {
+    out.proof = { note: out.proof };
+  }
+  return out;
+}
+
+/**
+ * `decision.propose` — hq reads the rationale from the `why` provenance block
+ * (`why.reason` → `Decision.rationale`), not a top-level `rationale`. A decision
+ * proposed with a bare `rationale` was recorded with no rationale at all.
+ */
+function decisionWhy(p) {
+  const out = { ...p };
+  const reason = firstString(out.rationale, out.why?.reason);
+  const clause = firstString(out.clause, out.why?.clause);
+  if (reason || clause || isObj(out.why)) {
+    const why = isObj(out.why) ? { ...out.why } : {};
+    if (reason) why.reason = reason;
+    if (clause && !why.clause) why.clause = clause;
+    if (Object.keys(why).length) out.why = why;
+  }
+  return out;
+}
+
+/**
+ * `approval.request` — hq takes an absolute `expiresAt`; the SDK gate speaks in
+ * relative `expiresInMs`. Convert rather than lose the expiry.
+ */
+function approvalExpiry(p) {
+  const out = { ...p };
+  if (out.expiresAt === undefined && Number.isFinite(Number(out.expiresInMs))) {
+    out.expiresAt = new Date(Date.now() + Number(out.expiresInMs)).toISOString();
+  }
+  return out;
+}
+
+/**
+ * `memory.author` — hq requires `{memoryClass (enum), title}`. Callers speak
+ * `{content}`; derive a title from its first line so the entry is not rejected,
+ * and keep the full text as the summary hq persists.
+ */
+function memoryTitle(p) {
+  const out = { ...p };
+  const content = firstString(out.summary, out.content, out.text, out.body);
+  if (content && out.summary === undefined) out.summary = content;
+  if (out.title === undefined && content) {
+    const firstLine = content.split(/\r?\n/, 1)[0].trim();
+    out.title = (firstLine || content).slice(0, 200);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// THE TABLE — one row per method whose hq schema disagrees with a call site,
+// plus every `.strict()` schema an SDK call site reaches.
+// ---------------------------------------------------------------------------
+
+/**
+ * @type {Record<string, {
+ *   alias?: Record<string,string>, serverAccepts?: string[], dropAlias?: boolean, strict?: string[],
+ *   mint?: string[], fold?: {into:string, keys:string[]},
+ *   unsupported?: string[], enums?: Record<string,string[]>,
+ *   required?: string[], oneOf?: string[][], transform?: (p:object)=>object,
+ *   note?: string
+ * }>}
+ */
+export const PARAM_CONTRACT = {
+  // ── messaging ────────────────────────────────────────────────────────────
+  "messaging.send": {
+    alias: {
+      clientMsgId: "idempotencyId",
+      msgId: "idempotencyId",
+      channel: "channelId",
+      threadId: "threadRootId",
+    },
+    mint: ["idempotencyId"],
+    required: ["channelId", "body", "idempotencyId"],
+    note: "hq reads idempotencyId (NOT clientMsgId) — sendMessageSchemaV1.",
+  },
+  "messaging.history": {
+    alias: { channel: "channelId", cursor: "before", since: "after" },
+    required: ["channelId"],
+    // CAUTION for whoever wires a paginating caller: hq's `before`/`after` are
+    // MESSAGE IDS, not timestamps — history.ts resolves the anchor with
+    // `input.before ?? input.after` and 404s ("cursor message X not found in
+    // channel") when it is not a real message id in that channel. `before` loads
+    // older (descending), `after` loads newer (ascending).
+    //
+    // So this alias fixes the NAME, not a type error: passing `since` as an ISO
+    // date or epoch now produces a hard NOT_FOUND where it used to be silently
+    // dropped. No production caller supplies since/cursor today (fetchHistory's
+    // only callers pass channel+limit), so the mapping is dormant — but a
+    // timestamp must be resolved to a message id before it goes on the wire.
+    note: "pagination anchors are MESSAGE IDS (before=older, after=newer), not timestamps.",
+  },
+  "messaging.react": { alias: { channel: "channelId" }, required: ["messageId", "emoji"] },
+  "messaging.edit": { required: ["messageId", "body"] },
+
+  // ── calling ──────────────────────────────────────────────────────────────
+  "calling.start": {
+    alias: {
+      channel: "channelId",
+      invitees: "participantIds",
+      participants: "participantIds",
+      memberIds: "participantIds",
+    },
+    unsupported: ["topic"],
+    oneOf: [["channelId", "participantIds"]],
+    note: "startCallSchema.refine() demands channelId OR a non-empty participantIds.",
+  },
+  "calling.join": { required: ["callId"] },
+  "calling.invite": { alias: { invitees: "memberIds", participantIds: "memberIds" }, required: ["callId", "memberIds"] },
+
+  // ── board ────────────────────────────────────────────────────────────────
+  "board.complete": {
+    strict: ["itemId", "proof"],
+    transform: completeProof,
+    required: ["itemId"],
+    note: "completeSchema is .strict(): a `note` key 400s — it is wrapped as proof.note.",
+  },
+  "board.claim": { strict: ["itemId"], required: ["itemId"] },
+  "board.assign": {
+    alias: { assigneeId: "assignee", memberId: "assignee" },
+    strict: ["itemId", "assignee"],
+    required: ["itemId", "assignee"],
+  },
+  "board.createTask": {
+    alias: {
+      description: "detail",
+      body: "detail",
+      assignee: "assigneeId",
+      status: "col",
+      column: "col",
+    },
+    enums: { col: BOARD_COLS, priority: TASK_PRIORITIES },
+    unsupported: ["dueAt"],
+    required: ["title"],
+    note: "createTaskSchema has NO dueAt — set it with board.updateTask after create.",
+  },
+  "board.updateTask": {
+    alias: { description: "detail", body: "detail", status: "col", column: "col" },
+    enums: { col: BOARD_COLS, priority: TASK_PRIORITIES },
+    unsupported: ["assignee", "assigneeId"],
+    required: ["taskId"],
+    note: "editTaskSchema has NO assignee field — reassign with board.assignTask.",
+  },
+  "board.assignTask": {
+    alias: { assignee: "assigneeId", memberId: "assigneeId" },
+    required: ["taskId", "assigneeId"],
+  },
+  "board.moveTask": {
+    alias: { status: "col", column: "col" },
+    enums: { col: BOARD_COLS },
+    required: ["taskId", "col"],
+  },
+  "board.addTaskComment": { alias: { text: "body", comment: "body" }, required: ["taskId", "body"] },
+
+  // ── decisions ────────────────────────────────────────────────────────────
+  "decision.propose": {
+    alias: { scope: "tag" },
+    transform: decisionWhy,
+    required: ["title"],
+    note: "rationale lives at why.reason; `scope` is hq's `tag`.",
+  },
+  "decision.comment": {
+    alias: { body: "text", comment: "text" },
+    required: ["decisionId", "text"],
+    note: 'hq throws "text is required" — `body` was never read.',
+  },
+  "decision.sign": { required: ["decisionId"] },
+
+  // ── approvals ────────────────────────────────────────────────────────────
+  "approval.request": {
+    alias: {
+      kind: "actionClass",
+      class: "actionClass",
+      payload_hash: "payloadHash",
+      hash: "payloadHash",
+    },
+    transform: approvalExpiry,
+    unsupported: ["requester", "expiresInMs"],
+    required: ["actionClass"],
+    oneOf: [["payload", "payloadHash"]],
+    note: "actionClass is REQUIRED; requester is derived server-side from the actor.",
+  },
+  "approval.resolve": { required: ["id", "decision"] },
+
+  // ── memory / knowledge ───────────────────────────────────────────────────
+  "memory.author": {
+    alias: { kind: "memoryClass", class: "memoryClass", content: "summary", text: "summary" },
+    transform: memoryTitle,
+    enums: { memoryClass: MEMORY_CLASSES },
+    unsupported: ["tags"],
+    required: ["memoryClass", "title"],
+    note: "scopes[] is the ACL field — tags are NOT scopes and are not persisted.",
+  },
+  "knowledge.append": {
+    alias: { text: "body" },
+    serverAccepts: ["text", "group"],
+    fold: { into: "metadata", keys: ["kind", "participants", "links", "refs"] },
+    required: ["body"],
+    note: "hq persists enrichment only inside `metadata`.",
+  },
+  "knowledge.replace": {
+    alias: { text: "body" },
+    serverAccepts: ["text", "group"],
+    fold: { into: "metadata", keys: ["kind", "participants", "links", "refs"] },
+    required: ["id", "body"],
+  },
+  "knowledge.rewrite": { alias: { text: "body" }, serverAccepts: ["text"], required: ["id", "body"] },
+  "knowledge.invalidate": { required: ["id"] },
+  "knowledge.search": {
+    alias: { query: "q" },
+    serverAccepts: ["query", "group"],
+    unsupported: ["kind", "includeInvalid", "lexical"],
+    note: "hq lexical-matches over the RLS-floored set; these three filters are not read.",
+  },
+  "contacts.upsert": {
+    unsupported: ["group"],
+    required: ["displayName"],
+    note: "the ACL group hint is not read by contacts.upsert.",
+  },
+  "meetings.record": { unsupported: ["group"], required: ["title"] },
+
+  // ── registry ─────────────────────────────────────────────────────────────
+  "registry.register": {
+    transform: toRegisterParams,
+    strict: ["displayName", "archetype", "humanSponsor", "card"],
+    dropAlias: true,
+    note: "registerSchema is .strict(): the raw self-entry 400s — it rides under `card`.",
+  },
+  // (hq also ships registry.update against the same strict schema, but the
+  // VENDORED protocol table carries no such method — `call()` would reject it
+  // NOT_FOUND before any network I/O — so there is deliberately no entry for it.
+  // The GUARD test asserts every contracted method is a real protocol method,
+  // which is what caught the phantom entry.)
+
+  // ── members / escalation ─────────────────────────────────────────────────
+  "member.get": {
+    alias: { memberId: "slug", id: "slug", member: "slug" },
+    required: ["slug"],
+    note: "hq resolves a member by SLUG, not id.",
+  },
+  "escalation.create": {
+    alias: { subject: "title", body: "detail", description: "detail" },
+    enums: { severity: ESCALATION_SEVERITIES },
+    required: ["title"],
+    oneOf: [["taskId", "channelId"]],
+    note: "hq requires a title AND a target (taskId or channelId).",
+  },
+
+  // ── leases ───────────────────────────────────────────────────────────────
+  "lease.claim": {
+    alias: { token: "tokenHash" },
+    unsupported: ["holder"],
+    required: ["scope", "resourceId"],
+    note: "the holder is the authenticated actor; hq never reads a client-supplied holder.",
+  },
+  "lease.release": {
+    unsupported: ["leaseToken"],
+    required: ["scope", "resourceId"],
+    note: "ownership is enforced via actor.id — the token never round-trips.",
+  },
+  "lease.heartbeat": { unsupported: ["leaseToken"], required: ["scope", "resourceId"] },
+};
+
+// ---------------------------------------------------------------------------
+// the normaliser
+// ---------------------------------------------------------------------------
+
+/**
+ * Does this method carry a wire contract?
+ * @param {string} method
+ * @returns {boolean}
+ */
+export function hasContract(method) {
+  return Object.prototype.hasOwnProperty.call(PARAM_CONTRACT, String(method || ""));
+}
+
+/**
+ * The contract entry for a method (or null).
+ * @param {string} method
+ * @returns {object|null}
+ */
+export function contractFor(method) {
+  return hasContract(method) ? PARAM_CONTRACT[String(method)] : null;
+}
+
+/**
+ * Normalise a params object onto the names hq actually validates.
+ *
+ * PURE and TOTAL: never throws, never mutates the input, never does I/O. A
+ * method with no contract entry is returned as a shallow copy with an empty
+ * report, so this is safe to run on every call.
+ *
+ * @param {string} method full dotted method name (e.g. "messaging.send")
+ * @param {object} params the caller's params
+ * @param {object} [o] - { mintId?: () => string } (injectable for tests)
+ * @returns {{params:object, renamed:string[], minted:string[], folded:string[],
+ *           dropped:string[], unsupported:string[], missing:string[], notes:string[]}}
+ */
+export function normalizeParams(method, params, o = {}) {
+  const report = {
+    params: isObj(params) ? { ...params } : {},
+    renamed: [],
+    minted: [],
+    folded: [],
+    dropped: [],
+    unsupported: [],
+    missing: [],
+    notes: [],
+  };
+  const c = contractFor(method);
+  if (!c) return report;
+
+  const mintId = typeof o.mintId === "function" ? o.mintId : randomUUID;
+  let p = report.params;
+
+  // (1) transform first — it reshapes on the caller's own vocabulary.
+  if (typeof c.transform === "function") {
+    try {
+      const next = c.transform(p);
+      if (isObj(next)) p = next;
+    } catch {
+      /* fail-open: a transform fault must never lose the call */
+    }
+  }
+
+  // (2) alias: legacy → canonical (only when the canonical key is absent, so an
+  //     explicit canonical value always wins over a legacy one).
+  for (const [legacy, canonical] of Object.entries(c.alias || {})) {
+    if (p[legacy] === undefined) continue;
+    if (p[canonical] === undefined) {
+      p[canonical] = p[legacy];
+      report.renamed.push(`${legacy}→${canonical}`);
+    }
+    // The legacy key stays on the wire by default (hq's non-strict schemas strip
+    // it; an older server may still read it). `.strict()` methods drop it below.
+    if (c.dropAlias) delete p[legacy];
+  }
+
+  // (3) mint the business-dedup ids hq requires.
+  for (const key of c.mint || []) {
+    if (p[key] === undefined || p[key] === null || p[key] === "") {
+      p[key] = mintId();
+      report.minted.push(key);
+    }
+  }
+
+  // (4) fold enrichment into the container hq persists.
+  if (c.fold && Array.isArray(c.fold.keys)) {
+    const bag = isObj(p[c.fold.into]) ? { ...p[c.fold.into] } : {};
+    let touched = false;
+    for (const key of c.fold.keys) {
+      if (p[key] === undefined) continue;
+      if (bag[key] === undefined) bag[key] = p[key];
+      report.folded.push(key);
+      touched = true;
+    }
+    if (touched) p[c.fold.into] = bag;
+  }
+
+  // (5) enum coercion — hq throws on an out-of-vocabulary value. Case-fold and
+  //     match; report (never drop) a value we cannot map, so the server's own
+  //     error message stays the authority.
+  for (const [key, values] of Object.entries(c.enums || {})) {
+    const v = p[key];
+    if (typeof v !== "string") continue;
+    if (values.includes(v)) continue;
+    const hit = values.find((x) => x.toLowerCase() === v.trim().toLowerCase());
+    if (hit) {
+      p[key] = hit;
+      report.renamed.push(`${key}:${v}→${hit}`);
+    } else {
+      report.notes.push(`${key}="${v}" is not one of ${values.join("|")}`);
+    }
+  }
+
+  // (6) strict: hq REJECTS unknown keys — drop everything outside the allow-list.
+  if (Array.isArray(c.strict)) {
+    const allow = new Set(c.strict);
+    for (const key of Object.keys(p)) {
+      if (allow.has(key)) continue;
+      delete p[key];
+      report.dropped.push(key);
+    }
+  }
+
+  // (7) report the params hq accepts-and-ignores. They RIDE ALONG (fail-open —
+  //     an older/newer hq may read them) but the loss of intent is now visible.
+  for (const key of c.unsupported || []) {
+    if (p[key] !== undefined) report.unsupported.push(key);
+  }
+
+  // (8) preflight: what hq will 400 on. Reported, never enforced — the server is
+  //     the authority on its own contract and we must not invent refusals.
+  report.missing = missingRequired(method, p);
+  if (c.note && (report.renamed.length || report.dropped.length || report.unsupported.length)) {
+    report.notes.push(c.note);
+  }
+
+  report.params = p;
+  return report;
+}
+
+/**
+ * Which required / one-of params are absent? Pure; used by the conformance probe
+ * and by `normalizeParams`'s report. Empty array when the method has no contract.
+ *
+ * @param {string} method
+ * @param {object} params
+ * @returns {string[]} human-readable missing-requirement descriptions
+ */
+export function missingRequired(method, params) {
+  const c = contractFor(method);
+  if (!c) return [];
+  const p = isObj(params) ? params : {};
+  const out = [];
+  const present = (k) => {
+    const v = p[k];
+    if (v === undefined || v === null) return false;
+    if (typeof v === "string") return v.trim().length > 0;
+    if (Array.isArray(v)) return v.length > 0;
+    return true;
+  };
+  for (const key of c.required || []) if (!present(key)) out.push(key);
+  for (const group of c.oneOf || []) {
+    if (!group.some(present)) out.push(group.join("|"));
+  }
+  return out;
+}
+
+/**
+ * Was anything worth telling a human about? (renames, drops, ignored intent)
+ * @param {object} report a `normalizeParams` report
+ * @returns {boolean}
+ */
+export function reportIsInteresting(report) {
+  if (!report) return false;
+  return (
+    (report.renamed || []).length > 0 ||
+    (report.dropped || []).length > 0 ||
+    (report.unsupported || []).length > 0 ||
+    (report.notes || []).length > 0
+  );
+}
+
+/**
+ * Render a report as one log line. Pure; returns "" when nothing happened.
+ * @param {string} method
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(method, report) {
+  if (!reportIsInteresting(report)) return "";
+  const bits = [];
+  if (report.renamed.length) bits.push(`renamed ${report.renamed.join(",")}`);
+  if (report.dropped.length) bits.push(`dropped ${report.dropped.join(",")} (hq schema is strict)`);
+  if (report.unsupported.length) bits.push(`NOT READ BY hq: ${report.unsupported.join(",")}`);
+  if (report.folded.length) bits.push(`folded ${report.folded.join(",")} into metadata`);
+  if (report.notes.length) bits.push(report.notes.join("; "));
+  return `${method}: ${bits.join(" | ")}`;
+}
+
+// ---------------------------------------------------------------------------
+// one-shot logging (never silent, never spam)
+// ---------------------------------------------------------------------------
+
+/** Seen (method|signature) pairs — one warning per distinct rewrite per process. */
+const _seen = new Set();
+
+/**
+ * Log a normalisation report ONCE per distinct (method, rewrite) per process.
+ * Silent fail-open has caused every bug in this file's history, so a rewrite is
+ * always reported — but a hot loop must not flood the log.
+ *
+ * @param {string} method
+ * @param {object} report
+ * @param {Function} [logImpl] injectable sink (defaults to console.warn)
+ * @returns {boolean} true when a line was emitted
+ */
+export function logReportOnce(method, report, logImpl) {
+  const line = formatReport(method, report);
+  if (!line) return false;
+  if (_seen.has(line)) return false;
+  _seen.add(line);
+  try {
+    (logImpl || console.warn)(`[org-contract] ${line}`);
+  } catch {
+    /* never throw from logging */
+  }
+  return true;
+}
+
+/** Test seam: forget every one-shot log line. */
+export function _resetLogOnce() {
+  _seen.clear();
+}
+
+export default {
+  PARAM_CONTRACT,
+  BOARD_COLS,
+  TASK_PRIORITIES,
+  ESCALATION_SEVERITIES,
+  MEMORY_CLASSES,
+  hasContract,
+  contractFor,
+  normalizeParams,
+  missingRequired,
+  reportIsInteresting,
+  formatReport,
+  logReportOnce,
+  toRegisterParams,
+};