@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/execution/surface-policy.mjs

@@ -0,0 +1,446 @@
+/**
+ * lib/execution/surface-policy.mjs — what the agent is ALLOWED to do, per surface.
+ *
+ * `lib/org/inbound/surfaces.mjs` answers "what kinds of thing can arrive?" and
+ * `lib/org/inbound/directedness.mjs` answers "is this one mine?". Neither answers
+ * the question this layer exists for: **given that it IS mine, what should happen
+ * to it?** A DM and a bounced email are both "directed at me" and must not be
+ * treated the same way — one wants a reply inside a minute, the other wants a
+ * task on a queue and no reply at all.
+ *
+ * This table is that answer expressed as data, one row per surface, so adding a
+ * surface is a data edit rather than a new branch in the decision ladder.
+ *
+ * Columns:
+ *
+ *   `respondable`   Can the agent post a conversational reply on this surface at
+ *                   all? `false` means "react_now" is structurally impossible and
+ *                   the ladder must pick schedule/delegate/escalate/ignore.
+ *   `replyMethod`   The protocol method a react_now would use. Null when not
+ *                   respondable. This is a HINT for the driver, not a promise —
+ *                   the session may choose a different tool.
+ *   `latency`       "now"   the surface has a human waiting in a live UI,
+ *                   "batch" the surface is fine being handled on the next
+ *                           inbox-processor tick,
+ *                   "queue" the surface is work, not conversation; it belongs on
+ *                           the backlog even when it is unambiguously mine.
+ *   `actionClasses` The blast radius of REPLYING here, seeded into the approval
+ *                   gate. Replying to a DM is internal and free; sending an email
+ *                   leaves the org and is `external`; resolving an approval or
+ *                   adopting a decision is `irreversible`. This is the honest
+ *                   reading of §8 "blast radius forces an approval BEFORE any
+ *                   rung executes", applied to the reply itself rather than only
+ *                   to whatever the reply talks about.
+ *   `offlineSafe`   May this surface be handled from a stale mandate cache
+ *                   (§6.4, the >72h rung)? Anything that speaks outside the org
+ *                   or commits the org is false.
+ *   `selfApprove`   `false` means the agent may never be the terminal decider on
+ *                   this surface — approvals and decisions land as `escalate`
+ *                   even when the payload names the agent as the approver. This
+ *                   is the same anti-self-grading law as `mandate.adopt`.
+ *   `maxChainDepth` How many consecutive agent turns are allowed in one thread
+ *                   before the ladder calls it a ping-pong loop and stops. Lower
+ *                   for broadcast surfaces (a space) than for a private DM.
+ *   `ambientDrop`   When the event is visible but NOT directed, is dropping it
+ *                   correct (`true`), or should it be parked for the ambient
+ *                   sweep (`false`)? An @mention that misfired is worth a second
+ *                   look; a board heartbeat on someone else's task is not.
+ *
+ * Pure data + pure lookups. No IO, no imports beyond the surface vocabulary.
+ *
+ * @module lib/execution/surface-policy
+ */
+
+"use strict";
+
+import { SURFACES, SURFACE_NAMES } from "../org/inbound/surfaces.mjs";
+
+/**
+ * The five things that can happen to a directed event. Ordered from cheapest to
+ * most expensive; the ladder in `disposition.mjs` returns exactly one.
+ *
+ * `ignore` is a FIRST-CLASS outcome, not an error path. An agent that replies to
+ * everything is as broken as one that replies to nothing, so every ignore
+ * carries a machine-readable reason and is journaled like any other decision.
+ */
+export const DISPOSITIONS = Object.freeze([
+  "react_now",
+  "schedule",
+  "delegate",
+  "escalate",
+  "ignore",
+]);
+
+/** True when `d` is one of the five dispositions. */
+export function isDisposition(d) {
+  return typeof d === "string" && DISPOSITIONS.includes(d);
+}
+
+/**
+ * The conservative row applied to any surface not named below — including a
+ * surface the parallel inbound workflow adds after this file was written. It is
+ * deliberately the most restrictive useful row: never auto-reply, never speak
+ * externally, queue the work and let a human or a later tick sort it out. A new
+ * surface therefore degrades to "safe and visible", never to "silently dropped"
+ * and never to "free to email the world".
+ */
+export const DEFAULT_POLICY = Object.freeze({
+  respondable: false,
+  replyMethod: null,
+  latency: "queue",
+  actionClasses: Object.freeze([]),
+  offlineSafe: true,
+  selfApprove: true,
+  maxChainDepth: 2,
+  ambientDrop: true,
+  unknown: true,
+});
+
+/**
+ * Per-surface policy for the surfaces `lib/org/inbound/surfaces.mjs` names.
+ * Keys MUST be exactly `SURFACE_NAMES`; the coverage test asserts every shipped
+ * surface has a row so a new surface cannot silently inherit DEFAULT_POLICY
+ * without someone deciding that is right.
+ */
+export const ORG_SURFACE_POLICY = Object.freeze({
+  // ── conversation ────────────────────────────────────────────────────────
+  /** A private room. Someone typed at me and is watching for a reply. */
+  dm: Object.freeze({
+    respondable: true,
+    replyMethod: "messaging.send",
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 4,
+    ambientDrop: true,
+  }),
+  /** @mention in a space. Public, so a wrong reply is expensive — tighter chain. */
+  mention: Object.freeze({
+    respondable: true,
+    replyMethod: "messaging.send",
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: false,
+  }),
+  /** A reply in a thread I am part of. Same room, same tightness as a mention. */
+  thread_reply: Object.freeze({
+    respondable: true,
+    replyMethod: "messaging.send",
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: false,
+  }),
+
+  // ── calls ───────────────────────────────────────────────────────────────
+  /**
+   * A call invite. NOT respondable as a conversational turn: hq owns the live
+   * call floor (SPEC §6.1, §10.8) and a laptop daemon reached over HTTP cannot
+   * hold it. The right disposition is to schedule — accept/decline the invite,
+   * put the slot on the calendar — never to "answer" the call here.
+   */
+  call: Object.freeze({
+    respondable: false,
+    replyMethod: null,
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: false,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+
+  // ── work ────────────────────────────────────────────────────────────────
+  /** A board item assigned to me. This is work, not conversation: it queues. */
+  task_assigned: Object.freeze({
+    respondable: false,
+    replyMethod: null,
+    latency: "queue",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+  /**
+   * A comment/block/move on an item I own or review. A comment addressed at me
+   * deserves an answer in the comment thread, so this one IS respondable — but
+   * on the batch tick, because nobody sits watching a board comment the way they
+   * watch a DM.
+   */
+  task_comment: Object.freeze({
+    respondable: true,
+    replyMethod: "board.comment",
+    latency: "batch",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: false,
+  }),
+  /** A comment on a chat-attached file. Answer in the room it was attached to. */
+  file_comment: Object.freeze({
+    respondable: true,
+    replyMethod: "messaging.send",
+    latency: "batch",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: false,
+  }),
+  /** A comment/suggestion on a workspace doc. Same, via the doc's comment lane. */
+  doc_comment: Object.freeze({
+    respondable: true,
+    replyMethod: "files.comment",
+    latency: "batch",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: false,
+  }),
+
+  // ── governance ──────────────────────────────────────────────────────────
+  /**
+   * An approval on my desk. `selfApprove:false` is the load-bearing bit: an
+   * agent NEVER resolves an approval, no matter how confident it is or how
+   * explicitly the payload named it the approver. It escalates to a human.
+   * Resolving one is `irreversible` because the single-use `consumedAt` latch
+   * means there is no second attempt.
+   */
+  approval: Object.freeze({
+    respondable: false,
+    replyMethod: null,
+    latency: "now",
+    actionClasses: Object.freeze(["irreversible"]),
+    offlineSafe: false,
+    selfApprove: false,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+  /** A decision I proposed / must sign. Adoption commits the org: never self-signed. */
+  decision: Object.freeze({
+    respondable: false,
+    replyMethod: null,
+    latency: "batch",
+    actionClasses: Object.freeze(["irreversible"]),
+    offlineSafe: false,
+    selfApprove: false,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+  /**
+   * An escalation waiting on me. Respondable — answering an escalation IS the
+   * work — but it is `now` latency because by construction something is blocked
+   * behind it.
+   */
+  escalation: Object.freeze({
+    respondable: true,
+    replyMethod: "escalation.resolve",
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: true,
+  }),
+  /** A delegation offered to me (or mine being accepted/declined). Accept/decline promptly. */
+  handoff: Object.freeze({
+    respondable: true,
+    replyMethod: "handoff.accept",
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: true,
+  }),
+
+  // ── outside the org ─────────────────────────────────────────────────────
+  /**
+   * Inbound email. The only default surface whose reply LEAVES the org, so it
+   * carries `external` and is not offline-safe: a stale-mandate agent must not
+   * be emailing counterparties on yesterday's instructions.
+   */
+  email: Object.freeze({
+    respondable: true,
+    replyMethod: "email.send",
+    latency: "batch",
+    actionClasses: Object.freeze(["external"]),
+    offlineSafe: false,
+    selfApprove: true,
+    maxChainDepth: 2,
+    ambientDrop: true,
+  }),
+});
+
+/**
+ * Surfaces this layer decides for that the org inbound table does NOT name yet.
+ *
+ * Three of them exist, and each is a real event class that reaches an agent
+ * today with no policy at all:
+ *
+ *   `calendar` the protocol ships nine `calendar.*` methods and hq's classifier
+ *              gains a `calendar` topic (SPEC §3), but `directedness.classifyEvent`
+ *              has no `calendar` branch — an invite where I am an attendee is
+ *              currently policy-less.
+ *   `alert`    a LOCAL fact, not an org event: `lib/diagnostics/alerts.mjs` and
+ *              `lib/telemetry/alerts.mjs` derive `{id, severity, detail}` records
+ *              that have never had a route to a decision — they were emitted to a
+ *              sink and that was the end of them.
+ *   `mandate`  the frame that tells a daemon its mandate moved (SPEC §6.4: "cache
+ *              is refreshed on every `topic:"mandate"` frame").
+ *
+ * Kept in a SEPARATE table rather than merged into the literal above so the
+ * "every org surface has a row" coverage assertion stays exact, and so the day
+ * the parallel inbound workflow adds `calendar` to `SURFACES` the drift guard
+ * {@link adoptedExtendedSurfaces} fires and someone MOVES the row instead of
+ * quietly ending up with two definitions of the same surface.
+ */
+export const EXTENDED_SURFACE_POLICY = Object.freeze({
+  /**
+   * A meeting invite / reschedule / cancellation naming me as an attendee. Not
+   * respondable: the answer is an RSVP (`calendar.rsvp`), not a sentence. It is
+   * `now` latency because a 9am invite answered on tomorrow's batch tick is a
+   * missed meeting, and NOT offline-safe because accepting commits the
+   * principal's time — and `calendar.write` queues real invite/update/cancel
+   * mail, which leaves the org.
+   */
+  calendar: Object.freeze({
+    // `replyMethod` is null because it is null for every non-respondable row:
+    // it names the method a CONVERSATIONAL reply would use, and an RSVP is an
+    // action the ladder routes, not a turn in a conversation. The routing hint
+    // lives on the obligation's `uses[]`, where it belongs.
+    respondable: false,
+    replyMethod: null,
+    latency: "now",
+    actionClasses: Object.freeze(["external"]),
+    offlineSafe: false,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+  /**
+   * A local health / budget / freshness alert about this agent. `offlineSafe` is
+   * TRUE and deliberately so: a partition is exactly when alerts matter, and an
+   * alert costs nothing outside the box. Never respondable — an alert is not a
+   * conversation, it is a work item or an escalation.
+   */
+  alert: Object.freeze({
+    respondable: false,
+    replyMethod: null,
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+  /**
+   * "Your mandate moved." The recovery surface: handling it is what REFRESHES
+   * the cache, so it is offline-safe, carries no action class, and is exempt
+   * from the staleness ladder (see `RECOVERY_SURFACES` in disposition.mjs).
+   * Gating it on mandate freshness would be a deadlock — the one event that
+   * fixes staleness cannot be the one staleness blocks.
+   */
+  mandate: Object.freeze({
+    respondable: false,
+    replyMethod: null,
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
+});
+
+/** Extended surface names, sorted. */
+export const EXTENDED_SURFACE_NAMES = Object.freeze(Object.keys(EXTENDED_SURFACE_POLICY).sort());
+
+/**
+ * The whole policy table — org surfaces plus the extended ones. This is what
+ * {@link policyFor} looks up, so there is exactly ONE lookup path and no caller
+ * ever has to know which half a surface lives in.
+ */
+export const SURFACE_POLICY = Object.freeze({
+  ...ORG_SURFACE_POLICY,
+  ...EXTENDED_SURFACE_POLICY,
+});
+
+/**
+ * Look up the policy row for a surface. Never throws and never returns null —
+ * an unknown surface gets {@link DEFAULT_POLICY} with `unknown:true` set, which
+ * the ladder logs as a degradation rather than swallowing.
+ *
+ * @param {string|null|undefined} surface
+ * @returns {typeof DEFAULT_POLICY}
+ */
+export function policyFor(surface) {
+  const key = typeof surface === "string" ? surface : "";
+  const row = Object.prototype.hasOwnProperty.call(SURFACE_POLICY, key)
+    ? SURFACE_POLICY[key]
+    : null;
+  return row || DEFAULT_POLICY;
+}
+
+/**
+ * The surfaces that have no policy row (should always be empty in a shipped
+ * tree). Exported so `verify` and the coverage test can assert on it rather than
+ * re-deriving the set.
+ * @returns {string[]}
+ */
+export function uncoveredSurfaces() {
+  return SURFACE_NAMES.filter((n) => !Object.prototype.hasOwnProperty.call(SURFACE_POLICY, n));
+}
+
+/**
+ * The policy rows that name a surface which is neither in the inbound
+ * vocabulary nor a declared extended surface — the other direction of the same
+ * drift. Should always be empty.
+ * @returns {string[]}
+ */
+export function orphanPolicies() {
+  return Object.keys(SURFACE_POLICY)
+    .filter(
+      (n) =>
+        !Object.prototype.hasOwnProperty.call(SURFACES, n) &&
+        !Object.prototype.hasOwnProperty.call(EXTENDED_SURFACE_POLICY, n),
+    )
+    .sort();
+}
+
+/**
+ * Extended surfaces the org inbound table has SINCE adopted. Non-empty means two
+ * definitions of one surface now exist and the row must be MOVED from
+ * {@link EXTENDED_SURFACE_POLICY} into {@link ORG_SURFACE_POLICY}. The coverage
+ * test asserts this is empty, so the merge fails loudly rather than leaving the
+ * spread order to decide which definition wins.
+ * @returns {string[]}
+ */
+export function adoptedExtendedSurfaces() {
+  return EXTENDED_SURFACE_NAMES.filter((n) =>
+    Object.prototype.hasOwnProperty.call(SURFACES, n),
+  );
+}
+
+export default {
+  DISPOSITIONS,
+  isDisposition,
+  DEFAULT_POLICY,
+  SURFACE_POLICY,
+  ORG_SURFACE_POLICY,
+  EXTENDED_SURFACE_POLICY,
+  EXTENDED_SURFACE_NAMES,
+  policyFor,
+  uncoveredSurfaces,
+  orphanPolicies,
+  adoptedExtendedSurfaces,
+};

package/lib/execution/surface-policy.test.mjs

@@ -0,0 +1,162 @@
+/**
+ * surface-policy.test.mjs — every inbound surface has a decided policy.
+ * Run: node --test lib/execution/surface-policy.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { SURFACES, SURFACE_NAMES } from "../org/inbound/surfaces.mjs";
+import {
+  SURFACE_POLICY,
+  ORG_SURFACE_POLICY,
+  EXTENDED_SURFACE_POLICY,
+  EXTENDED_SURFACE_NAMES,
+  DEFAULT_POLICY,
+  DISPOSITIONS,
+  isDisposition,
+  policyFor,
+  uncoveredSurfaces,
+  orphanPolicies,
+  adoptedExtendedSurfaces,
+} from "./surface-policy.mjs";
+
+test("every shipped inbound surface has an explicit policy row", () => {
+  // The point of this test: a new surface added by the inbound workflow must not
+  // silently inherit DEFAULT_POLICY. Someone has to decide what it means.
+  assert.deepEqual(uncoveredSurfaces(), [], "surfaces with no policy row");
+  assert.deepEqual(orphanPolicies(), [], "policy rows for surfaces that no longer exist");
+  assert.equal(
+    Object.keys(SURFACE_POLICY).length,
+    SURFACE_NAMES.length + EXTENDED_SURFACE_NAMES.length,
+    "the merged table is exactly the org surfaces plus the declared extended ones",
+  );
+});
+
+test("an extended surface adopted by the inbound layer fails loudly instead of double-defining", () => {
+  // `calendar`, `alert` and `mandate` are decided here but not (yet) named by
+  // `lib/org/inbound/surfaces.mjs`. The day that workflow adds one, the row must
+  // MOVE — leaving both definitions in place would make the spread order decide
+  // which one wins, silently.
+  assert.deepEqual(
+    adoptedExtendedSurfaces(),
+    [],
+    "these extended surfaces now exist in the inbound table — move their rows into ORG_SURFACE_POLICY",
+  );
+  for (const name of EXTENDED_SURFACE_NAMES) {
+    assert.ok(ORG_SURFACE_POLICY[name] === undefined, `${name} is defined twice`);
+  }
+});
+
+test("the extended surfaces are all inward-facing or gated, never free to speak out", () => {
+  // They bypass parts of the ladder (`mandate` and `alert` skip the staleness
+  // gate), so none of them may be a surface that can talk outside the org.
+  for (const [name, p] of Object.entries(EXTENDED_SURFACE_POLICY)) {
+    assert.equal(p.respondable, false, `${name} must not be conversationally respondable`);
+    if (p.actionClasses.includes("external")) {
+      assert.equal(p.offlineSafe, false, `${name} speaks externally but claims to be offline-safe`);
+    }
+  }
+  // The two staleness-exempt surfaces in particular must cost nothing outside.
+  for (const name of ["mandate", "alert"]) {
+    assert.deepEqual(EXTENDED_SURFACE_POLICY[name].actionClasses, [], `${name} must carry no action class`);
+    assert.equal(EXTENDED_SURFACE_POLICY[name].offlineSafe, true);
+  }
+});
+
+test("every policy row is structurally complete and internally consistent", () => {
+  for (const [name, p] of Object.entries(SURFACE_POLICY)) {
+    assert.equal(typeof p.respondable, "boolean", `${name}.respondable`);
+    assert.ok(["now", "batch", "queue"].includes(p.latency), `${name}.latency=${p.latency}`);
+    assert.ok(Array.isArray(p.actionClasses), `${name}.actionClasses`);
+    assert.equal(typeof p.offlineSafe, "boolean", `${name}.offlineSafe`);
+    assert.equal(typeof p.selfApprove, "boolean", `${name}.selfApprove`);
+    assert.ok(Number.isInteger(p.maxChainDepth) && p.maxChainDepth >= 1, `${name}.maxChainDepth`);
+    assert.equal(typeof p.ambientDrop, "boolean", `${name}.ambientDrop`);
+    // A respondable surface must name the method it replies with, and a
+    // non-respondable one must not pretend it can.
+    if (p.respondable) assert.ok(p.replyMethod, `${name} is respondable but names no reply method`);
+    else assert.equal(p.replyMethod, null, `${name} is not respondable but names ${p.replyMethod}`);
+  }
+});
+
+test("anything that speaks outside the org is external and not offline-safe", () => {
+  // email is the only default surface whose reply leaves the org.
+  assert.ok(SURFACE_POLICY.email.actionClasses.includes("external"));
+  assert.equal(SURFACE_POLICY.email.offlineSafe, false);
+  // and nothing internal is mislabelled as external
+  assert.deepEqual(SURFACE_POLICY.dm.actionClasses, []);
+  assert.deepEqual(SURFACE_POLICY.mention.actionClasses, []);
+});
+
+test("the agent may never be the terminal decider on approvals or decisions", () => {
+  assert.equal(SURFACE_POLICY.approval.selfApprove, false);
+  assert.equal(SURFACE_POLICY.decision.selfApprove, false);
+  // ...and both are irreversible, so they also carry an approval gate.
+  assert.ok(SURFACE_POLICY.approval.actionClasses.includes("irreversible"));
+  assert.ok(SURFACE_POLICY.decision.actionClasses.includes("irreversible"));
+  // Every other surface is self-decidable, or the agent could do nothing at all.
+  const decidable = Object.entries(SURFACE_POLICY).filter(([, p]) => p.selfApprove);
+  assert.ok(decidable.length >= SURFACE_NAMES.length - 2);
+});
+
+test("hq keeps the live call floor: `call` is never conversationally respondable", () => {
+  assert.equal(SURFACE_POLICY.call.respondable, false);
+  assert.equal(SURFACE_POLICY.call.replyMethod, null);
+});
+
+test("public surfaces have a tighter ping-pong ceiling than private ones", () => {
+  assert.ok(
+    SURFACE_POLICY.mention.maxChainDepth < SURFACE_POLICY.dm.maxChainDepth,
+    "a wrong answer in a space is more expensive than in a DM",
+  );
+});
+
+test("policyFor: unknown surface degrades to the restrictive default, flagged", () => {
+  const p = policyFor("surface_from_the_future");
+  assert.equal(p, DEFAULT_POLICY);
+  assert.equal(p.unknown, true);
+  // The restrictive default must not be able to speak, and must not be able to
+  // speak EXTERNALLY in particular.
+  assert.equal(p.respondable, false);
+  assert.deepEqual(p.actionClasses, []);
+  // negatives
+  assert.equal(policyFor(null).unknown, true);
+  assert.equal(policyFor(undefined).unknown, true);
+  assert.equal(policyFor(42).unknown, true);
+  assert.equal(policyFor("").unknown, true);
+});
+
+test("policyFor: a real surface never returns the default", () => {
+  for (const name of SURFACE_NAMES) {
+    const p = policyFor(name);
+    assert.notEqual(p.unknown, true, `${name} fell through to the default`);
+  }
+});
+
+test("policyFor: prototype keys do not resolve to a policy", () => {
+  // `hasOwnProperty` guard, not a bare lookup — "constructor" must not be a surface.
+  assert.equal(policyFor("constructor").unknown, true);
+  assert.equal(policyFor("toString").unknown, true);
+  assert.equal(policyFor("__proto__").unknown, true);
+});
+
+test("the disposition vocabulary is exactly the five documented outcomes", () => {
+  assert.deepEqual([...DISPOSITIONS].sort(), ["delegate", "escalate", "ignore", "react_now", "schedule"]);
+  assert.ok(isDisposition("ignore"));
+  assert.equal(isDisposition("maybe"), false);
+  assert.equal(isDisposition(null), false);
+  assert.equal(isDisposition(undefined), false);
+});
+
+test("surface topics stay aligned with the inbound vocabulary", () => {
+  // Guards the seam: if the inbound layer renames a surface, this fails rather
+  // than the policy silently applying to nothing. Extended surfaces are exempt
+  // by construction — they exist precisely because the inbound layer has no row
+  // for them — and `orphanPolicies` above is what keeps that list honest.
+  for (const name of Object.keys(SURFACE_POLICY)) {
+    if (EXTENDED_SURFACE_NAMES.includes(name)) continue;
+    assert.ok(SURFACES[name], `policy names ${name}, which the inbound layer does not define`);
+  }
+});