@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/kpi-sensors.test.mjs

@@ -0,0 +1,275 @@
+/**
+ * lib/kpi-sensors.test.mjs — the sensor registry.
+ *
+ * The load-bearing tests are the NEGATIVES: a sensor that cannot measure must
+ * produce an honest `{ok:false, reason}` that `measureKpi` refuses to turn into
+ * a sample, and that `admit`'s honesty gate therefore refuses to turn into work.
+ * A silent zero here would let an agent invent its own justification for
+ * anything, which is the whole reason the honesty gate exists.
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  SENSOR_SPECS,
+  buildSensorRegistry,
+  reachableCapabilities,
+  refusalFor,
+  hintedCapabilities,
+  reduceGeneric,
+  firstArray,
+  pluck,
+} from "./kpi-sensors.mjs";
+import { measureKpi, recordMeasurement, readSeries } from "./kpi.mjs";
+import { admit } from "./goals/admission.mjs";
+
+const NOW = Date.parse("2026-08-11T12:00:00.000Z");
+const now = () => NOW;
+
+function root() {
+  const d = mkdtempSync(join(tmpdir(), "kpi-sensors-"));
+  mkdirSync(join(d, "config"), { recursive: true });
+  return d;
+}
+
+/** A fake org: capability → error-or-result frame. */
+function fakeExec(table, calls = []) {
+  return async (name, input) => {
+    calls.push({ name, input });
+    const hit = table[name];
+    if (hit === undefined) return { ok: false, error: { code: "NOT_FOUND", message: `no fake for ${name}` } };
+    if (typeof hit === "function") return hit(input);
+    return { ok: true, result: hit };
+  };
+}
+
+const OBJ = (capability, params = {}) => ({
+  key: "k", kind: "GOAL", state: "active", metric: "m", direction: "up",
+  target: 90, tolerance: 2, cadence: "weekly",
+  sensor: { capability, params, source: "method" },
+});
+
+// ---------------------------------------------------------------------------
+// Reductions
+// ---------------------------------------------------------------------------
+
+test("board_ready measures an on-time rate and shows what it walked", async () => {
+  const calls = [];
+  const sensors = buildSensorRegistry({
+    agentRoot: root(), now,
+    executeImpl: fakeExec({ board_ready: { items: [
+      { id: "a", dueAt: "2026-06-01T00:00:00Z" },   // overdue
+      { id: "b", dueAt: "2026-12-01T00:00:00Z" },   // not yet
+      { id: "c", dueAt: null },                      // cannot be late
+      { id: "d", dueAt: null },
+    ] } }, calls),
+  });
+  const m = await measureKpi(OBJ("board_ready", { metric: "on_time_rate" }), { sensors, now });
+  assert.equal(m.ok, true);
+  assert.equal(m.value, 75);
+  assert.equal(m.source, "method");
+  assert.equal(m.evidence.rowCount, 4);
+  assert.equal(m.evidence.detail.overdue, 1);
+  assert.equal(m.evidence.detail.withDueDate, 2);
+  assert.equal(calls[0].name, "board_ready");
+});
+
+test("decision_list distinguishes an honest zero from an absence", async () => {
+  const sensors = (table) => buildSensorRegistry({ agentRoot: root(), now, executeImpl: fakeExec(table) });
+
+  // Rows exist, none undecided → a REAL zero-day backlog.
+  const zero = await measureKpi(OBJ("decision_list"), {
+    sensors: sensors({ decision_list: { decisions: [{ id: "1", status: "adopted", createdAt: "2026-08-01T00:00:00Z", decidedAt: "2026-08-02T00:00:00Z" }] } }),
+    now,
+  });
+  assert.equal(zero.ok, true);
+  assert.equal(zero.value, 0);
+  assert.match(zero.evidence.detail.note, /honest zero/);
+
+  // No rows at all → NOT a zero.
+  const none = await measureKpi(OBJ("decision_list"), { sensors: sensors({ decision_list: { decisions: [] } }), now });
+  assert.equal(none.ok, false);
+  assert.equal(none.value, null);
+  assert.equal(none.reason, "no-rows");
+});
+
+test("email_inbox pairs a reply to its inbound message and never averages silence in as speed", async () => {
+  const sensors = buildSensorRegistry({
+    agentRoot: root(), now,
+    executeImpl: fakeExec({ email_inbox: { messages: [
+      { id: "1", threadId: "t1", direction: "INBOUND", receivedAt: "2026-08-11T00:00:00Z" },
+      { id: "2", threadId: "t1", direction: "OUTBOUND", sentAt: "2026-08-11T02:00:00Z" },
+      { id: "3", threadId: "t2", direction: "INBOUND", receivedAt: "2026-08-10T00:00:00Z" }, // never answered
+    ] } }),
+  });
+  const m = await measureKpi(OBJ("email_inbox"), { sensors, now });
+  assert.equal(m.ok, true);
+  assert.equal(m.value, 2);                       // 2h, not 1h — the unanswered one is excluded
+  assert.equal(m.evidence.detail.answered, 1);
+  assert.equal(m.evidence.detail.unanswered, 1);
+});
+
+test("crm_list_deals never sends hq an illegal stage filter", async () => {
+  const calls = [];
+  const sensors = buildSensorRegistry({
+    agentRoot: root(), now,
+    executeImpl: fakeExec({ crm_list_deals: { deals: [
+      { id: "1", stage: "INBOUND", valueCents: 100_000_000 },
+      { id: "2", stage: "CLOSED", valueCents: 900_000_000 },
+    ] } }, calls),
+  });
+  // "open" is not in hq's enum — it must not reach the wire.
+  const m = await measureKpi(OBJ("crm_list_deals", { stage: "open" }), { sensors, now });
+  assert.deepEqual(calls[0].input, {});
+  assert.equal(m.value, 1_000_000);               // the CLOSED deal is excluded
+  assert.equal(m.evidence.detail.open, 1);
+});
+
+test("reduceGeneric is the escape hatch: filter an array, sum a field", () => {
+  const r = reduceGeneric(
+    { byAgent: [{ agent: "A016", usd: 4384.87 }, { agent: "A017", usd: 3455.27 }] },
+    { arrayPath: "byAgent", where: { key: "agent", equals: "A016" }, sum: "usd" },
+  );
+  assert.equal(r.value, 4384.87);
+  assert.equal(r.rowCount, 1);
+  assert.equal(pluck({ a: { b: [1, 2] } }, "a.b.1"), 2);
+  assert.equal(firstArray({ x: 1, deals: [1, 2, 3] }).key, "deals");
+});
+
+// ---------------------------------------------------------------------------
+// THE NEGATIVES
+// ---------------------------------------------------------------------------
+
+test("NEGATIVE: an unregistered capability yields no-implementation and NO sample", async () => {
+  const dir = root();
+  const sensors = buildSensorRegistry({ agentRoot: dir, now, executeImpl: fakeExec({}) });
+  const o = OBJ("messaging_send");
+  const m = await measureKpi(o, { sensors, now });
+
+  assert.equal(m.ok, false);
+  assert.equal(m.reason, "no-implementation");
+  assert.equal(m.value, null);
+
+  // The loop only records when m.ok — assert the ledger stays empty either way.
+  assert.equal(readSeries(dir, o.key).length, 0);
+});
+
+test("NEGATIVE: a WRITE capability is refused by name, not silently missing", async () => {
+  const sensors = buildSensorRegistry({ agentRoot: root(), now, executeImpl: fakeExec({}) });
+  assert.equal(typeof sensors.task_update, "function", "the derivation can pick it, so it must have an answer");
+  const m = await measureKpi(OBJ("task_update"), { sensors, now });
+  assert.equal(m.ok, false);
+  assert.equal(m.reason, "capability-is-not-a-sensor");
+  assert.match(m.evidence.detail.why, /may not mutate the org/);
+  assert.match(refusalFor("escalation_raise"), /may not mutate the org/);
+  assert.match(refusalFor("approval_wait"), /long-poll/);
+  assert.equal(refusalFor("board_ready"), null);
+});
+
+test("NEGATIVE: a failed org read is a read-failure, never a zero", async () => {
+  const dir = root();
+  const sensors = buildSensorRegistry({
+    agentRoot: dir, now,
+    executeImpl: fakeExec({ board_ready: () => ({ ok: false, error: { code: "UNAUTHORIZED", message: "no org credential" } }) }),
+  });
+  const m = await measureKpi(OBJ("board_ready"), { sensors, now });
+  assert.equal(m.ok, false);
+  assert.equal(m.reason, "read-failed");
+  assert.equal(m.value, null);
+  assert.equal(m.evidence.detail.code, "UNAUTHORIZED");
+});
+
+test("NEGATIVE: a sensor that throws is caught and reported, not propagated", async () => {
+  const sensors = buildSensorRegistry({
+    agentRoot: root(), now,
+    executeImpl: async () => { throw new Error("socket hang up"); },
+  });
+  const m = await measureKpi(OBJ("board_ready"), { sensors, now });
+  assert.equal(m.ok, false);
+  assert.equal(m.reason, "sensor-threw");
+});
+
+test("NEGATIVE: an unmeasurable objective cannot reach the admission honesty gate", async () => {
+  const dir = root();
+  const sensors = buildSensorRegistry({ agentRoot: dir, now, executeImpl: fakeExec({ board_ready: { items: [] } }) });
+  const o = OBJ("board_ready");
+
+  const m = await measureKpi(o, { sensors, now });
+  assert.equal(m.ok, false, "empty board → no measurement");
+
+  // Exactly what the loop does: record ONLY when ok.
+  if (m.ok) recordMeasurement(dir, { objectiveKey: o.key, value: m.value, window: "2026-W33", source: m.source }, { now });
+  const series = readSeries(dir, o.key);
+  assert.equal(series.length, 0);
+
+  const verdict = admit(
+    { title: "do something", advances: [o.key], why: { reason: "kpi-gap" } },
+    { objective: o, gap: { gap: 15, withinTolerance: false, trend: "unknown" }, latestSample: series[series.length - 1] || null, openItems: [], staleness: { outcome: "full" } },
+  );
+  assert.equal(verdict.admitted, false);
+  assert.equal(verdict.gate, "honesty");
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("a MEASURED sample satisfies the honesty gate — the joint, end to end", async () => {
+  const dir = root();
+  const sensors = buildSensorRegistry({
+    agentRoot: dir, now,
+    executeImpl: fakeExec({ board_ready: { items: [{ id: "a", dueAt: "2026-06-01T00:00:00Z" }, { id: "b", dueAt: null }, { id: "c", dueAt: null }, { id: "d", dueAt: null }] } }),
+  });
+  const o = OBJ("board_ready");
+  const m = await measureKpi(o, { sensors, now });
+  assert.equal(m.ok, true);
+  recordMeasurement(dir, { objectiveKey: o.key, value: m.value, window: "2026-W33", source: m.source, evidence: m.evidence }, { now });
+
+  const series = readSeries(dir, o.key);
+  const verdict = admit(
+    { title: "raise the on-time rate", advances: [o.key], why: { reason: "kpi-gap" }, estCents: 50 },
+    { objective: o, gap: { gap: 15, withinTolerance: false, trend: "unknown" }, latestSample: series[series.length - 1], openItems: [], remainingCents: 500, staleness: { outcome: "full" } },
+  );
+  assert.equal(verdict.admitted, true, verdict.reason);
+  assert.equal(series[0].evidence.method, "board_ready");
+  assert.equal(series[0].evidence.rowCount, 4);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// Reachability — the fail-open that must not become fail-closed
+// ---------------------------------------------------------------------------
+
+test("a missing or empty manifest returns undefined, not an empty Set", () => {
+  const dir = root();
+  const logs = [];
+  const log = (l, m) => logs.push(`${l}:${m}`);
+  assert.equal(reachableCapabilities(dir, { log }), undefined);
+  assert.ok(logs.some((l) => /no capability manifest/.test(l)), "the degradation is logged");
+
+  writeFileSync(join(dir, "config", "capability-manifest.json"), JSON.stringify({ entries: [] }));
+  assert.equal(reachableCapabilities(dir, { log }), undefined, "zero reachable entries must not refuse every objective");
+
+  writeFileSync(join(dir, "config", "capability-manifest.json"), "{not json");
+  assert.equal(reachableCapabilities(dir, { log }), undefined);
+
+  writeFileSync(join(dir, "config", "capability-manifest.json"), JSON.stringify({ entries: [{ id: "board_ready", reachable: true }, { id: "task_update", reachable: false }] }));
+  const set = reachableCapabilities(dir, { log });
+  assert.ok(set.has("board_ready"));
+  assert.ok(!set.has("task_update"));
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("every capability the mandate derivation can bind has an answer in the registry", () => {
+  const sensors = buildSensorRegistry({ agentRoot: root(), now, executeImpl: fakeExec({}) });
+  for (const cap of hintedCapabilities()) {
+    assert.equal(typeof sensors[cap], "function", `${cap} is hinted by derive.SENSOR_HINTS but has no registry entry`);
+  }
+  // …and every spec is a READ.
+  for (const cap of Object.keys(SENSOR_SPECS)) {
+    assert.equal(refusalFor(cap), null, `${cap} has a spec so it must not be refused`);
+  }
+});

package/lib/kpi.mjs

@@ -232,6 +232,12 @@ export function recordIntervention(agentRoot, rec, deps = {}) {
     expectedDelta: Number.isFinite(Number(rec && rec.expectedDelta)) ? Number(rec.expectedDelta) : null,
     realizedDelta: Number.isFinite(Number(rec && rec.realizedDelta)) ? Number(rec.realizedDelta) : null,
     measuredAt: (rec && rec.measuredAt) || null,
+    // The measurement window the realized delta was scored in, and how it was
+    // derived. `(taskId, window)` is the idempotency key the loop dedupes on —
+    // without it a second steward pass in the same week double-scores the same
+    // intervention and the planner's "this failed before" count drifts up on its own.
+    window: (rec && rec.window) || null,
+    basis: (rec && rec.basis) || null,
   };
   try {
     const p = interventionsPath(agentRoot);
@@ -306,6 +312,20 @@ export async function measureKpi(objective, deps = {}) {
     return { ok: false, value: null, source: "method", evidence: null, reason: "sensor-threw" };
   }
 
+  // A sensor that CANNOT measure says so in its own words. Collapsing that into
+  // the generic "non-numeric" below would throw away the only diagnostic the
+  // operator has — "no-rows" (the org genuinely has nothing), "read-failed"
+  // (the org said no), "capability-is-not-a-sensor" (the mandate cited a write
+  // tool) and "missing-param" are four different repairs, not one.
+  if (raw && typeof raw === "object" && raw.ok === false) {
+    const reason = String(raw.reason || "sensor-unavailable");
+    logOf(deps)(
+      "warn",
+      `[kpi] sensor "${sensor.capability}" could not measure "${key}": ${reason}${raw.detail ? ` ${JSON.stringify(raw.detail)}` : ""}`
+    );
+    return { ok: false, value: null, source: "method", evidence: { method: sensor.capability, params: sensor.params || {}, detail: raw.detail || null }, reason };
+  }
+
   const value = Number(raw && typeof raw === "object" ? raw.value : raw);
   if (!Number.isFinite(value)) {
     logOf(deps)("warn", `[kpi] sensor "${sensor.capability}" returned a non-numeric result for "${key}"`);
@@ -321,6 +341,9 @@ export async function measureKpi(objective, deps = {}) {
       params: sensor.params || {},
       rowCount: raw && typeof raw === "object" && Number.isFinite(Number(raw.rowCount)) ? Number(raw.rowCount) : null,
       sessionId: (raw && typeof raw === "object" && raw.sessionId) || null,
+      // What the reduction actually walked (metric, scope, rows considered).
+      // Without it "value: 75" is unauditable a week later.
+      detail: (raw && typeof raw === "object" && raw.detail) || null,
     },
     reason: "measured",
   };

package/lib/mandate/audit.mjs

@@ -41,6 +41,9 @@ export const AUDIT_REL = join("state", "mandate", "audit.jsonl");
 export const DECISIONS = Object.freeze([
   "measured",
   "measure_failed",
+  // The learning signal: an in-flight intervention scored against the sample
+  // that just landed (lib/goals/loop.journalRealizedDeltas → kpi.recordIntervention).
+  "intervention_scored",
   "gap",
   "candidate_admitted",
   "candidate_rejected",

package/lib/mandate/contract.mjs

@@ -0,0 +1,277 @@
+/**
+ * lib/mandate/contract.mjs — THE MANDATE BODY CONTRACT (agent half).
+ *
+ * ONE shape, written down twice: here as a JSDoc typedef + runtime validator,
+ * and in hq as TypeScript at `src/server/methods/mandate/_contract.ts`. The two
+ * files carry the SAME `MANDATE_CONTRACT_VERSION` and the SAME key lists, and
+ * each repo's tests pin those literals — so a divergence is a one-line diff
+ * instead of an invisible `undefined`.
+ *
+ * ── WHY THIS FILE EXISTS ──
+ * The two repos disagreed on this body and NOTHING errored. hq emitted
+ * `{memberId, objectives, proposed, generatedAt}`; `compilePlan` read
+ * `{objectives, budgetCentsPerPeriod, collaborators, reactsTo}`. Three of the
+ * four keys were simply absent, so `Number.isFinite(mandate.budgetCentsPerPeriod)`
+ * was false on every server body and EVERY obligation took a hardcoded 500c
+ * allowance against a hardcoded 10000c envelope. No error frame, no log line,
+ * no drift row — the plan ran on fictional money and looked perfectly healthy.
+ *
+ * The rule: a MISSING required key is a contract ERROR (the body cannot be
+ * trusted). A key that is PRESENT AND NULL is a warning (hq looked and had
+ * nothing — the obligation is genuinely unmetered, and hq says why in
+ * `degradations[]`). Those two used to be indistinguishable. They no longer are,
+ * and NOTHING in this codebase may substitute a number for either of them.
+ *
+ * PURE: no fs, no network, no clock. ESM.
+ *
+ * @module lib/mandate/contract
+ */
+
+"use strict";
+
+/** Bump when a key is added, removed or re-typed. Mirrored in hq. */
+export const MANDATE_CONTRACT_VERSION = 1;
+
+/**
+ * The EXACT top-level key set of a v1 body, sorted. Pinned by `contract.test.mjs`
+ * here and by hq's `shared.test.ts` — the two assertions ARE the drift alarm, so
+ * keep the literals identical.
+ */
+export const MANDATE_BODY_KEYS = Object.freeze([
+  "budgetCentsPerPeriod",
+  "budgetPeriod",
+  "budgetSource",
+  "collaborators",
+  "contractVersion",
+  "degradations",
+  "generatedAt",
+  "memberId",
+  "objectives",
+  "proposed",
+  "reactsTo",
+  "seatBudgetCents",
+]);
+
+/**
+ * Keys `compilePlan` READS. A missing one is what made the compiler invent a
+ * number, so a missing one is a hard error — never a warning, never a default.
+ */
+export const MANDATE_REQUIRED_KEYS = Object.freeze([
+  "budgetCentsPerPeriod",
+  "collaborators",
+  "contractVersion",
+  "memberId",
+  "objectives",
+  "reactsTo",
+  "seatBudgetCents",
+]);
+
+/**
+ * @typedef {"DOER"|"CONTRIBUTOR"|"REVIEWER"|"APPROVER"|"INFORMED"} CollaboratorRole
+ *
+ * @typedef {object} MandateCollaborator
+ * @property {string} memberId
+ * @property {CollaboratorRole} role
+ * @property {string} source  the column the edge came out of (provenance)
+ *
+ * @typedef {object} MandateDegradation
+ * @property {string} field   dotted path of the null/empty field
+ * @property {string} reason  why, in one sentence a human can act on
+ *
+ * @typedef {object} ObjectiveWire
+ * @property {string} id
+ * @property {string|null} key
+ * @property {string} kind        PILLAR|OBJECTIVE|GOAL
+ * @property {string} state       proposed|active|at_risk|met|missed|retired
+ * @property {string} text
+ * @property {string|null} memberId
+ * @property {string|null} parentId
+ * @property {string|null} parentKey   the SDK's tree walk joins on KEYS
+ * @property {string|null} charterSectionId
+ * @property {string|null} workstreamId
+ * @property {string|null} metric
+ * @property {string|null} unit
+ * @property {string} direction
+ * @property {number|null} baseline
+ * @property {number|null} target
+ * @property {number|null} value
+ * @property {number|null} tolerance
+ * @property {number} weight
+ * @property {number} progress
+ * @property {string|null} cadence
+ * @property {string|null} dueAt
+ * @property {object|null} sensor
+ * @property {number|null} budgetCentsPerPeriod  this node's share of the seat
+ *                                               envelope, apportioned by weight
+ * @property {MandateCollaborator[]} collaborators
+ * @property {number} version
+ * @property {string|null} proposedById
+ * @property {string|null} adoptedById
+ * @property {string|null} adoptedAt
+ * @property {string} createdAt
+ * @property {string} updatedAt
+ *
+ * @typedef {object} MandateBody
+ * @property {number} contractVersion
+ * @property {string} memberId
+ * @property {ObjectiveWire[]} objectives   adopted — the only compilable nodes
+ * @property {ObjectiveWire[]} proposed     carried for display; never compiled
+ * @property {number|null} budgetCentsPerPeriod  default allowance for ONE
+ *   obligation with no objective behind it. ALWAYS null from hq v1 — hq holds no
+ *   such column. Present so "unmetered, and hq said so" is distinguishable from
+ *   "key missing, so I made a number up".
+ * @property {number|null} seatBudgetCents  the seat's whole envelope per period
+ * @property {"monthly"|null} budgetPeriod
+ * @property {string} budgetSource          provenance of the two figures above
+ * @property {MandateCollaborator[]} collaborators  seat-level edges
+ * @property {object[]} reactsTo            ALWAYS [] from hq v1 (no store)
+ * @property {MandateDegradation[]} degradations    every null above, named
+ * @property {string} generatedAt           newest row's updatedAt; never a clock
+ */
+
+/** Pull the body out of a cache record (`{body}`) or accept a bare body. */
+export function bodyOf(source) {
+  if (!source || typeof source !== "object") return null;
+  if (source.body && typeof source.body === "object" && !Array.isArray(source.body)) {
+    return source.body;
+  }
+  return source;
+}
+
+/**
+ * Validate a mandate body against the contract. Never throws.
+ *
+ * @param {object} source  a cache record (`{body}`) or a bare body
+ * @returns {{
+ *   ok:boolean, contractVersion:number|null, missing:string[],
+ *   errors:string[], warnings:string[], unmetered:boolean
+ * }}
+ *   `ok:false` means DO NOT TRUST THE NUMBERS in this body. `unmetered:true`
+ *   means the body is well-formed and hq truthfully has no budget for it.
+ */
+export function validateMandateContract(source) {
+  const errors = [];
+  const warnings = [];
+  const missing = [];
+  const body = bodyOf(source);
+
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return {
+      ok: false,
+      contractVersion: null,
+      missing: [...MANDATE_REQUIRED_KEYS],
+      errors: ["mandate body is not an object"],
+      warnings: [],
+      unmetered: true,
+    };
+  }
+
+  for (const k of MANDATE_REQUIRED_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(body, k)) missing.push(k);
+  }
+  if (missing.length) {
+    errors.push(
+      `mandate body is missing required key(s): ${missing.join(", ")}. ` +
+        "This is a PRE-CONTRACT body (hq older than mandate contract v1, or a " +
+        "hand-written fixture). Its budgets cannot be trusted and NOTHING may " +
+        "substitute a default for them."
+    );
+  }
+
+  const version = Number.isFinite(body.contractVersion) ? body.contractVersion : null;
+  if (version == null) {
+    if (!missing.includes("contractVersion")) {
+      errors.push(`contractVersion must be a number (got ${JSON.stringify(body.contractVersion)})`);
+    }
+  } else if (version > MANDATE_CONTRACT_VERSION) {
+    // Forward-compat: a newer server is not an error, but the extra keys are
+    // unknown to this compiler and must be announced rather than dropped mute.
+    warnings.push(
+      `mandate body is contract v${version} but this SDK understands v${MANDATE_CONTRACT_VERSION} — ` +
+        "unknown keys are ignored; upgrade the SDK"
+    );
+  }
+
+  if (body.memberId != null && typeof body.memberId !== "string") {
+    errors.push("memberId must be a string or null");
+  }
+  for (const k of ["objectives", "proposed", "collaborators", "reactsTo", "degradations"]) {
+    if (Object.prototype.hasOwnProperty.call(body, k) && !Array.isArray(body[k])) {
+      errors.push(`${k} must be an array (got ${typeof body[k]})`);
+    }
+  }
+  for (const k of ["budgetCentsPerPeriod", "seatBudgetCents"]) {
+    if (!Object.prototype.hasOwnProperty.call(body, k)) continue;
+    const v = body[k];
+    if (v !== null && !Number.isFinite(v)) {
+      errors.push(`${k} must be a finite number or null (got ${JSON.stringify(v)})`);
+    } else if (v !== null && v < 0) {
+      errors.push(`${k} must not be negative (got ${v})`);
+    }
+  }
+
+  const seat = Number.isFinite(body.seatBudgetCents) ? body.seatBudgetCents : null;
+  const perOb = Number.isFinite(body.budgetCentsPerPeriod) ? body.budgetCentsPerPeriod : null;
+  const objectiveBudgets = (Array.isArray(body.objectives) ? body.objectives : [])
+    .map((o) => (o && Number.isFinite(o.budgetCentsPerPeriod) ? o.budgetCentsPerPeriod : null))
+    .filter((v) => v != null);
+  const unmetered = seat == null && perOb == null && objectiveBudgets.length === 0;
+
+  if (seat == null && !missing.includes("seatBudgetCents")) {
+    warnings.push(
+      "seatBudgetCents is null — the seat has no funded envelope, so no budget " +
+        "ceiling can be enforced. hq's reason is in degradations[]."
+    );
+  }
+  if (perOb == null && !missing.includes("budgetCentsPerPeriod")) {
+    warnings.push(
+      "budgetCentsPerPeriod is null — obligations with no objective behind them " +
+        "(standard/archetype cadences, REACTs) compile UNMETERED. They are not " +
+        "worth 500c; they are worth an unknown amount."
+    );
+  }
+  if (seat != null && objectiveBudgets.length) {
+    const sum = objectiveBudgets.reduce((a, b) => a + b, 0);
+    if (sum > seat) {
+      errors.push(
+        `the objective budgets sum to ${sum}c but the seat envelope is ${seat}c — ` +
+          "hq apportioned more than it holds"
+      );
+    }
+  }
+
+  // hq states its absences on the wire; echo them so one log line explains the
+  // nulls above instead of leaving the operator to guess.
+  for (const d of Array.isArray(body.degradations) ? body.degradations : []) {
+    if (d && d.field && d.reason) warnings.push(`hq degradation — ${d.field}: ${d.reason}`);
+  }
+
+  return { ok: errors.length === 0, contractVersion: version, missing, errors, warnings, unmetered };
+}
+
+/**
+ * Validate and LOG. The one call site every consumer should use: the failure
+ * mode this contract exists to kill is a quiet one, so the loud path is the
+ * default path.
+ *
+ * @param {object} source
+ * @param {(level:string,msg:string)=>void} [log]
+ * @param {string} [where]  a tag for the log line, e.g. "compilePlan"
+ * @returns ReturnType<typeof validateMandateContract>
+ */
+export function assertMandateContract(source, log, where = "mandate") {
+  const v = validateMandateContract(source);
+  const emit = typeof log === "function" ? log : () => {};
+  for (const e of v.errors) emit("error", `[${where}] mandate contract violation: ${e}`);
+  for (const w of v.warnings) emit("warn", `[${where}] ${w}`);
+  return v;
+}
+
+export default {
+  MANDATE_CONTRACT_VERSION,
+  MANDATE_BODY_KEYS,
+  MANDATE_REQUIRED_KEYS,
+  bodyOf,
+  validateMandateContract,
+  assertMandateContract,
+};