@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/org/inbound/directedness.mjs

@@ -0,0 +1,720 @@
+/**
+ * lib/org/inbound/directedness.mjs — "is this org event for ME, and why?"
+ *
+ * PURE. No IO, no network, no clock. Two halves, deliberately split so the
+ * interesting logic is testable with plain objects:
+ *
+ *   1. {@link classifyEvent} — a raw `/v1/events` row → a {@link Candidate}:
+ *      which surface family it belongs to, which ids it names, which member ids
+ *      the payload named OUTRIGHT (`directTo`), and which relational PROBES
+ *      would have to hit for it to be mine.
+ *   2. {@link resolveDirected} — a Candidate + the agent's own resolved
+ *      {@link module:lib/org/inbound/facts Facts} → a typed verdict
+ *      `{ directed, surface, reason }`.
+ *
+ * ── WHY IT HAS TO BE TWO HALVES ──
+ * The org event feed is ORG-WIDE and REDACTED. `/v1/events` is scoped with
+ * `scopeWhere(orgId, {seq:{gt:cursor}})` (hq `src/server/rpc/reads.ts`), so an
+ * agent receives EVERY family's rows, and hq deliberately strips identity from
+ * the payloads: `messaging.send` stores `{actor, channelId, channelKind,
+ * recipientCount, mentionCount, attachmentCount, threaded, ts}` — a COUNT of
+ * mentions, never the list (hq `src/server/actions/messages.ts`,
+ * `src/server/methods/messaging/send.ts`). That redaction is correct — an
+ * org-wide feed must not leak who DMs whom — but it means "is this mine?" is
+ * STRUCTURALLY unanswerable from the event alone for most families. The missing
+ * half is the agent's OWN membership/ownership, which the agent can read for
+ * itself over its OWN entitlements (`messaging.channels`, `board.context`,
+ * `decision.list`, `approval.get`, …). `facts.mjs` fetches exactly that; this
+ * module joins the two.
+ *
+ * ── THE SAFETY INVARIANT (the one that must never regress) ──
+ * An event in a room I am not in must NEVER be directed at me, and must never
+ * even cause a probe. Enforced here as a hard gate, not as an emergent property:
+ *
+ *   - PRIVATE ROOMS (`DM` / `GROUP_DM` / `HUDDLE`): directed ONLY when the room
+ *     id is in `facts.memberChannelIds`. `messaging.channels` returns a private
+ *     room ONLY to its members (hq `methods/messaging/channels.ts` — the OR is
+ *     `kind:"PUBLIC"` OR `members.some({memberId})`), so presence in that set IS
+ *     proof of membership. There is no fallback, no heuristic, no "kind contains
+ *     dm" guess.
+ *   - PRIVATE SPACES (`kind:"PRIVATE"`): same rule — membership required.
+ *   - PUBLIC spaces: an @mention or a thread I am in makes it mine. Mere traffic
+ *     does not.
+ *   - Any channel id NOT in `facts.visibleChannelIds` is INVISIBLE: no verdict,
+ *     no hydration, no history fetch. `facts.mjs` refuses to page a channel that
+ *     is not in that set, so a private room I am not in is never even probed.
+ *
+ * When membership is UNKNOWN (the roster read failed) the resolver stays
+ * conservative for private rooms and answers `false` — the failure mode of
+ * guessing "yes" is an agent barging into other people's private conversation.
+ *
+ * @module lib/org/inbound/directedness
+ */
+
+"use strict";
+
+import { SURFACES } from "./surfaces.mjs";
+
+/** Channel kinds where every message is addressed to the room. */
+export const PRIVATE_ROOM_KINDS = Object.freeze(["DM", "GROUP_DM", "HUDDLE"]);
+
+/** Channel kinds that require explicit membership to be readable at all. */
+export const MEMBERSHIP_REQUIRED_KINDS = Object.freeze([
+  ...PRIVATE_ROOM_KINDS,
+  "PRIVATE",
+]);
+
+/**
+ * The typed reasons a verdict can carry. A daemon switches on `reason` for
+ * triage; it is a closed set so a new value is a deliberate, reviewable change.
+ *
+ * @typedef {"dm"|"mention"|"thread"|"channel"|"participant"|"assignee"
+ *          |"reviewer"|"direct"|"requester"|"approver"|"proposer"|"commenter"
+ *          |"owner"|"shared"|"waiting_on"|"task"|"named"} Reason
+ */
+
+/** Narrow an unknown payload to a readable record (never throws). */
+function obj(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+
+/** Read a non-empty string field, else undefined. */
+function str(p, ...keys) {
+  for (const k of keys) {
+    const v = p[k];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  }
+  return undefined;
+}
+
+/** Coerce a Set / array / null into a Set, or null for "unknown". */
+export function asSet(v) {
+  if (v instanceof Set) return v;
+  if (Array.isArray(v)) return new Set(v.map((x) => String(x)));
+  return null;
+}
+
+/** Does `set` (possibly null == unknown) contain `id`? Unknown → false. */
+function has(set, id) {
+  return !!(set && id && set.has(String(id)));
+}
+
+/**
+ * The family/kind coordinates of a raw event, tolerating both the modern shape
+ * (`{family, kind}`) and the legacy one (`{kind: "messaging.send"}`).
+ * @param {object} ev
+ * @returns {{family:string, kind:string}}
+ */
+export function coordsOf(ev) {
+  const rawKind = String((ev && ev.kind) || "");
+  const family = String((ev && ev.family) || (rawKind.includes(".") ? rawKind.split(".")[0] : ""));
+  let kind = rawKind;
+  if (!ev?.family && rawKind.includes(".")) kind = rawKind.slice(rawKind.indexOf(".") + 1);
+  return { family, kind };
+}
+
+/**
+ * @typedef {Object} Candidate
+ * @property {number|string|null} seq   the per-org ledger cursor position
+ * @property {string} family            hq event family (chain coordinate)
+ * @property {string} kind              hq event kind   (chain coordinate)
+ * @property {string|null} entityId
+ * @property {string} actor             the acting principal's member id
+ * @property {string} at                ISO-8601 append time
+ * @property {string} topic             coarse bucket (see surfaces.mjs)
+ * @property {string[]} surfaces        candidate surface names, most specific first
+ * @property {Record<string,string|undefined>} ids  ids the payload named
+ * @property {string[]} directTo        member ids the PAYLOAD named outright
+ * @property {object} payload           the raw (redacted) payload, passed through
+ */
+
+/**
+ * Classify one raw event row into a Candidate, or null for the many families a
+ * daemon has no business being woken for (presence beats, cost rollups, registry
+ * churn, org admin). The cursor still advances past them — they simply produce
+ * no candidate.
+ *
+ * Read DEFENSIVELY throughout: chain payloads are free-form JSON and historical
+ * rows predate several of these fields. A missing id degrades to "no probe"
+ * (→ dropped) rather than throwing; a classifier crash on one odd historical row
+ * must never kill the pull.
+ *
+ * @param {object} ev raw `/v1/events` row
+ * @returns {Candidate|null}
+ */
+export function classifyEvent(ev) {
+  if (!ev || typeof ev !== "object") return null;
+  const { family, kind } = coordsOf(ev);
+  if (!family) return null;
+  // Prefer the nested payload; tolerate producers that inline the fields.
+  const p = ev.payload && typeof ev.payload === "object" ? obj(ev.payload) : obj(ev);
+  const base = {
+    seq: ev.seq ?? null,
+    family,
+    kind,
+    entityId: ev.entity_id ?? ev.entityId ?? null,
+    actor: String(p.actor || ev.actor || ""),
+    at: ev.at || p.ts || p.at || "",
+    payload: p,
+  };
+
+  // ── messaging: a new message. The BODY never entered the chain; `channelKind`
+  //    is what distinguishes a DM from a space, and the mention LIST is absent —
+  //    it has to come from `messaging.history` (facts.channelPages).
+  if (family === "messaging" && kind.startsWith("send")) {
+    const channelId = str(p, "channelId", "channel");
+    if (!channelId) return null;
+    return {
+      ...base,
+      topic: "message",
+      surfaces: ["dm", "mention", "thread_reply"],
+      ids: {
+        channelId,
+        channelKind: String(p.channelKind || p.channel_kind || "").toUpperCase() || undefined,
+        messageId: base.entityId ?? str(p, "messageId", "id"),
+      },
+      // The redaction leaves two COUNTS behind, and they are load-bearing: a
+      // space message with `mentionCount: 0` and `threaded: false` cannot be a
+      // mention or a thread reply, so it can be dropped WITHOUT paging the
+      // channel at all. That single test is what keeps mention-detection from
+      // costing one `messaging.history` per busy public channel per pull.
+      hints: {
+        mentionCount: Number.isFinite(Number(p.mentionCount)) ? Number(p.mentionCount) : undefined,
+        threaded: typeof p.threaded === "boolean" ? p.threaded : undefined,
+        attachmentCount: Number.isFinite(Number(p.attachmentCount)) ? Number(p.attachmentCount) : undefined,
+      },
+      directTo: [],
+    };
+  }
+
+  // ── calling: an invite/start on a call. Mine when it is in one of my rooms,
+  //    or when the payload named me as an invitee.
+  if (family === "calling") {
+    const callId = str(p, "callId") ?? base.entityId ?? undefined;
+    if (!callId) return null;
+    const invitees = []
+      .concat(Array.isArray(p.invitees) ? p.invitees : [])
+      .concat(Array.isArray(p.participantIds) ? p.participantIds : [])
+      .map(String);
+    return {
+      ...base,
+      topic: "call",
+      surfaces: ["call"],
+      ids: { callId, channelId: str(p, "channelId", "channel"), topic: str(p, "topic") },
+      directTo: invitees,
+    };
+  }
+
+  // ── board: `entityId` is the Task id. Several kinds name the seat outright
+  //    (`assignee` on assign/claim/complete/heartbeat) — prefer that over a
+  //    join, since an assignment IMMEDIATELY reassigned would otherwise be
+  //    missed by a probe against the task's current state.
+  if (family === "board") {
+    const taskId = base.entityId ?? str(p, "itemId", "taskId");
+    if (!taskId) return null;
+    const assignee = str(p, "assignee");
+    const isAssignment = kind === "item.assigned" || kind === "item.claimed";
+    return {
+      ...base,
+      topic: "task",
+      surfaces: isAssignment ? ["task_assigned", "task_comment"] : ["task_comment", "task_assigned"],
+      ids: { taskId, commentId: str(p, "commentId"), channelId: str(p, "channelId") },
+      // `assignee` names the seat only when the event is ABOUT that seat.
+      directTo: assignee && isAssignment ? [assignee] : [],
+    };
+  }
+
+  // ── file (chat attachments): the payload names the room, so channel
+  //    membership is the join. `fileKey` is the opaque handle the read needs.
+  if (family === "file") {
+    const fileKey = str(p, "fileKey");
+    if (!fileKey) return null;
+    return {
+      ...base,
+      topic: "file",
+      surfaces: ["file_comment"],
+      ids: {
+        fileKey,
+        channelId: str(p, "channelId"),
+        commentId: base.entityId ?? undefined,
+        authorId: str(p, "authorId", "pinnedBy", "unpinnedBy"),
+      },
+      directTo: [],
+    };
+  }
+
+  // ── files (workspace docs): `entityId` is the File id and the payload carries
+  //    NOTHING identifying — ownership/shares must be read with `files.get`,
+  //    which is itself ACL'd, so a doc I cannot see is NOT_FOUND rather than a
+  //    leak.
+  if (family === "files") {
+    const fileId = base.entityId ?? str(p, "fileId");
+    if (!fileId) return null;
+    return {
+      ...base,
+      topic: "file",
+      surfaces: ["doc_comment"],
+      ids: { fileId, commentId: str(p, "commentId"), name: str(p, "name") },
+      directTo: [],
+    };
+  }
+
+  // ── decision: the payload names the COMMENT author, never the audience. Mine
+  //    when I proposed it, decided it, or have spoken in its thread.
+  if (family === "decision") {
+    const decisionId = base.entityId ?? str(p, "decisionId");
+    if (!decisionId) return null;
+    return {
+      ...base,
+      topic: "decision",
+      surfaces: ["decision"],
+      ids: {
+        decisionId,
+        commentId: str(p, "commentId"),
+        authorId: str(p, "authorId", "proposedBy", "signedBy"),
+        title: str(p, "title"),
+      },
+      directTo: [],
+    };
+  }
+
+  // ── escalation: `taskId` / `channelId` are the join keys; `waitingOn` (read
+  //    back via escalation.list) can name a seat outright.
+  if (family === "escalation") {
+    const escalationId = base.entityId ?? str(p, "escalationId");
+    if (!escalationId) return null;
+    return {
+      ...base,
+      topic: "escalation",
+      surfaces: ["escalation"],
+      ids: {
+        escalationId,
+        taskId: str(p, "taskId"),
+        channelId: str(p, "channelId"),
+        severity: str(p, "severity"),
+      },
+      directTo: [],
+    };
+  }
+
+  // ── approval: `approval.requested` names ONLY the requester (hq
+  //    `methods/approval/request.ts`) — the approver is on the row, not in the
+  //    payload, so it takes an `approval.get` probe. `approval.approved` /
+  //    `.rejected` name both ends.
+  if (family === "approval") {
+    const approvalId = base.entityId ?? str(p, "approvalId", "id");
+    if (!approvalId) return null;
+    const directTo = [str(p, "requester"), str(p, "approver")].filter(Boolean);
+    return {
+      ...base,
+      topic: "approval",
+      surfaces: ["approval"],
+      ids: { approvalId, taskId: str(p, "itemId"), actionClass: str(p, "actionClass") },
+      directTo,
+    };
+  }
+
+  // ── handoff: the payload names BOTH ends. Zero-join delivery.
+  if (family === "handoff") {
+    const directTo = [str(p, "to"), str(p, "from")].filter(Boolean);
+    if (directTo.length === 0) return null;
+    return {
+      ...base,
+      topic: "handoff",
+      surfaces: ["handoff"],
+      ids: {
+        runId: base.entityId ?? undefined,
+        taskId: str(p, "itemId"),
+        handoffId: str(p, "handoffId"),
+        intent: str(p, "intent"),
+        to: str(p, "to"),
+        from: str(p, "from"),
+      },
+      directTo,
+    };
+  }
+
+  // ── email: the one family whose redacted payload already names its seat
+  //    (`memberId` = the owning mailbox's member). Unrouted mail
+  //    (`memberId: null`) belongs to nobody and is dropped.
+  if (family === "email" && kind === "received") {
+    const memberId = str(p, "memberId");
+    if (!memberId) return null;
+    if (p.autoSubmitted === true) return null; // bounces / vacation autoreplies
+    return {
+      ...base,
+      topic: "email",
+      surfaces: ["email"],
+      ids: {
+        emailMessageId: str(p, "emailMessageId") ?? base.entityId ?? undefined,
+        threadId: str(p, "threadId"),
+        mailboxId: str(p, "mailboxId"),
+      },
+      directTo: [memberId],
+    };
+  }
+
+  return null;
+}
+
+/** A verdict with no delivery. */
+function no(reason) {
+  return { directed: false, surface: null, reason, why: reason };
+}
+
+/** A verdict that delivers. */
+function yes(surface, reason, extra = {}) {
+  return { directed: true, surface, reason, why: reason, ...extra };
+}
+
+/**
+ * Join a Candidate against the agent's own facts and return a typed verdict.
+ * PURE — every fact it needs is on `facts`, which `facts.mjs` resolved from the
+ * agent's own entitled reads.
+ *
+ * @param {Candidate} cand
+ * @param {string} me the agent's member id
+ * @param {import("./facts.mjs").Facts} facts
+ * @param {{enabled?: Record<string,boolean>}} [opts]
+ * @returns {{directed:boolean, surface:string|null, reason:string, why:string}}
+ */
+export function resolveDirected(cand, me, facts = {}, opts = {}) {
+  if (!cand) return no("not_classified");
+  const enabled = opts.enabled || null;
+  const on = (s) => (enabled ? !!enabled[s] : true);
+  const meId = me ? String(me) : "";
+
+  // My OWN echo is never inbound. This is the single most important drop: without
+  // it an agent re-ingests its own replies and holds a conversation with itself.
+  if (meId && cand.actor && cand.actor === meId) return no("own_echo");
+
+  // A payload that named me outright needs no join at all.
+  if (meId && cand.directTo.map(String).includes(meId)) {
+    const surface = cand.surfaces.find(on);
+    if (!surface) return no("surface_disabled");
+    switch (cand.family) {
+      case "approval":
+        // `approval.requested` names only the requester; `approval.approved` /
+        // `.rejected` name both ends. Report which end I am.
+        if (String(cand.payload.approver || "") === meId) return yes(surface, "approver");
+        return yes(surface, "requester");
+      case "handoff":
+        // Offered TO me = work landing on my desk; offered BY me = outcome news.
+        return yes(surface, String(cand.ids.to || "") === meId ? "direct" : "requester");
+      case "board":
+        return yes(surface, "assignee");
+      case "calling":
+        return yes(surface, "participant");
+      default:
+        return yes(surface, "direct");
+    }
+  }
+
+  switch (cand.family) {
+    case "messaging":
+      return resolveMessaging(cand, meId, facts, on);
+    case "calling":
+      return resolveCalling(cand, meId, facts, on);
+    case "board":
+      return resolveBoard(cand, meId, facts, on);
+    case "file":
+      return resolveChatFile(cand, meId, facts, on);
+    case "files":
+      return resolveDoc(cand, meId, facts, on);
+    case "decision":
+      return resolveDecision(cand, meId, facts, on);
+    case "escalation":
+      return resolveEscalation(cand, meId, facts, on);
+    case "approval":
+      return resolveApproval(cand, meId, facts, on);
+    default:
+      return no("no_rule");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-family resolvers
+// ---------------------------------------------------------------------------
+
+/**
+ * Messaging. THE safety-critical one.
+ *
+ * Order of decision:
+ *   1. channel not visible to me            → invisible (no verdict, no probe)
+ *   2. private room + I am a member         → `dm`
+ *   3. private room + I am NOT a member     → NOT directed (hard stop)
+ *   4. private SPACE + I am not a member    → NOT directed (hard stop)
+ *   5. mentions[] (from history) names me   → `mention`
+ *   6. thread root I have spoken in / been named in → `thread_reply`
+ *   7. otherwise                            → ambient chatter, not directed
+ */
+function resolveMessaging(cand, me, facts, on) {
+  const channelId = cand.ids.channelId;
+  const visible = asSet(facts.visibleChannelIds);
+  const members = asSet(facts.memberChannelIds);
+
+  // The channel kind on the event is authoritative for the ROOM CLASS; the
+  // roster's kind is authoritative when the event omitted it.
+  const chan = facts.channels instanceof Map ? facts.channels.get(String(channelId)) : undefined;
+  const channelKind = String(cand.ids.channelKind || (chan && chan.kind) || "").toUpperCase();
+
+  // (1) A channel that is not in my visible roster is a room I cannot read. It
+  //     is never mine, and facts.mjs will never have paged it.
+  if (visible && channelId && !visible.has(String(channelId))) return no("channel_not_visible");
+
+  const isPrivateRoom = PRIVATE_ROOM_KINDS.includes(channelKind);
+  const needsMembership = MEMBERSHIP_REQUIRED_KINDS.includes(channelKind);
+
+  // (2)/(3) Private rooms: membership IS the address.
+  if (isPrivateRoom) {
+    if (!members) return no("membership_unknown");
+    if (!has(members, channelId)) return no("not_a_member");
+    return on("dm") ? yes("dm", "dm") : no("surface_disabled");
+  }
+  // (4) A private SPACE I am not in: hard stop before any mention probe.
+  if (needsMembership && !has(members, channelId)) {
+    return no(members ? "not_a_member" : "membership_unknown");
+  }
+  // An UNKNOWN channel kind (older row, roster miss) is treated as
+  // membership-required — the conservative branch.
+  if (!channelKind && !has(members, channelId)) return no("channel_kind_unknown");
+
+  // Cheap structural drop from the redacted counts, BEFORE any hydration: a
+  // space message that mentions nobody and is not threaded cannot be mine.
+  if (needsSpaceProbe(cand, facts) === false) return no("no_mentions_not_threaded");
+
+  const msg = lookupMessage(facts, channelId, cand.ids.messageId);
+
+  // (5) An explicit @mention of my member id. The mention list is NOT in the
+  //     chain payload; it comes from `messaging.history`, which hq ACLs to rooms
+  //     I may read.
+  if (msg && Array.isArray(msg.mentions) && me && msg.mentions.map(String).includes(me)) {
+    return on("mention") ? yes("mention", "mention") : no("surface_disabled");
+  }
+
+  // (6) A reply in a thread I am in. "In" = I authored a message under that
+  //     root, or I was named in one.
+  const root = msg && (msg.threadRootId || msg.thread_root_id);
+  if (root && facts.myThreadRootIds instanceof Set && facts.myThreadRootIds.has(String(root))) {
+    return on("thread_reply") ? yes("thread_reply", "thread") : no("surface_disabled");
+  }
+
+  // A mention by DISPLAY NAME, when the org has no structured mention row (an
+  // agent addressed as "@Isla" in prose). Only ever consulted for a space I can
+  // already read, and only when the caller supplied its own names.
+  if (msg && matchesMyName(facts, msg.body ?? msg.text)) {
+    return on("mention") ? yes("mention", "named") : no("surface_disabled");
+  }
+
+  if (!msg) return no("message_not_hydrated");
+  return no("ambient_channel_traffic");
+}
+
+/** Calls: an invite in a room I belong to, else not mine. */
+function resolveCalling(cand, me, facts, on) {
+  if (!on("call")) return no("surface_disabled");
+  const members = asSet(facts.memberChannelIds);
+  const visible = asSet(facts.visibleChannelIds);
+  const channelId = cand.ids.channelId;
+  if (channelId) {
+    if (visible && !visible.has(String(channelId))) return no("channel_not_visible");
+    if (has(members, channelId)) return yes("call", "channel");
+    return no("not_a_member");
+  }
+  // A bare call with no room context: only when the payload named me, which the
+  // directTo branch already handled.
+  return no("call_without_room");
+}
+
+/** Board: assignee/reviewer of the item, resolved from `board.context`. */
+function resolveBoard(cand, me, facts, on) {
+  const role = facts.taskRole instanceof Map ? facts.taskRole.get(String(cand.ids.taskId)) : undefined;
+  if (!role) return no(facts.taskRole ? "not_my_task" : "board_unknown");
+  const isAssignment = cand.kind === "item.assigned" || cand.kind === "item.claimed";
+  const surface = isAssignment ? "task_assigned" : "task_comment";
+  if (!on(surface)) return no("surface_disabled");
+  return yes(surface, role);
+}
+
+/** Chat-attached file: the comment landed in a room, so membership is the join. */
+function resolveChatFile(cand, me, facts, on) {
+  if (!on("file_comment")) return no("surface_disabled");
+  const channelId = cand.ids.channelId;
+  const visible = asSet(facts.visibleChannelIds);
+  const members = asSet(facts.memberChannelIds);
+  if (!channelId) {
+    // No room on the payload: fall back to the task-attachment key, which names
+    // a task whose ownership I already know.
+    const taskId = taskIdFromFileKey(cand.ids.fileKey);
+    const role = taskId && facts.taskRole instanceof Map ? facts.taskRole.get(taskId) : undefined;
+    if (role) return yes("file_comment", role);
+    return no("file_without_room");
+  }
+  if (visible && !visible.has(String(channelId))) return no("channel_not_visible");
+  if (!has(members, channelId)) return no("not_a_member");
+  return yes("file_comment", "channel");
+}
+
+/** Workspace doc: ownership or an explicit share, read back via `files.get`. */
+function resolveDoc(cand, me, facts, on) {
+  if (!on("doc_comment")) return no("surface_disabled");
+  const acl = facts.fileAcl instanceof Map ? facts.fileAcl.get(String(cand.ids.fileId)) : undefined;
+  if (!acl) return no(facts.fileAcl ? "file_not_visible" : "files_unknown");
+  if (acl.ownerId && me && String(acl.ownerId) === me) return yes("doc_comment", "owner");
+  if (acl.shared) return yes("doc_comment", "shared");
+  if (acl.mentionsMe) return yes("doc_comment", "named");
+  return no("not_my_doc");
+}
+
+/** Decision: proposer, decider, or a voice already in the thread. */
+function resolveDecision(cand, me, facts, on) {
+  if (!on("decision")) return no("surface_disabled");
+  const d = facts.decisions instanceof Map ? facts.decisions.get(String(cand.ids.decisionId)) : undefined;
+  if (d && me) {
+    if (String(d.proposedBy || "") === me) return yes("decision", "proposer");
+    if (String(d.decidedBy || "") === me) return yes("decision", "direct");
+  }
+  const voices =
+    facts.decisionVoices instanceof Map
+      ? facts.decisionVoices.get(String(cand.ids.decisionId))
+      : undefined;
+  if (voices && me && voices.has(me)) return yes("decision", "commenter");
+  if (!d && !voices) return no("decision_unknown");
+  return no("not_my_decision");
+}
+
+/** Escalation: on my task, in my room, or explicitly waiting on me. */
+function resolveEscalation(cand, me, facts, on) {
+  if (!on("escalation")) return no("surface_disabled");
+  const e = facts.escalations instanceof Map ? facts.escalations.get(String(cand.ids.escalationId)) : undefined;
+  const waitingOn = e && e.waitingOn ? String(e.waitingOn) : "";
+  if (me && waitingOn && waitingOn === me) return yes("escalation", "waiting_on");
+
+  const taskId = cand.ids.taskId || (e && e.taskId) || "";
+  const role = taskId && facts.taskRole instanceof Map ? facts.taskRole.get(String(taskId)) : undefined;
+  if (role) return yes("escalation", role);
+
+  const channelId = cand.ids.channelId || (e && e.channelId) || "";
+  const members = asSet(facts.memberChannelIds);
+  const visible = asSet(facts.visibleChannelIds);
+  if (channelId) {
+    if (visible && !visible.has(String(channelId))) return no("channel_not_visible");
+    if (has(members, channelId)) return yes("escalation", "channel");
+  }
+  return no("not_my_escalation");
+}
+
+/** Approval: the approver seat is on the row, not in the payload — read it back. */
+function resolveApproval(cand, me, facts, on) {
+  if (!on("approval")) return no("surface_disabled");
+  const a = facts.approvals instanceof Map ? facts.approvals.get(String(cand.ids.approvalId)) : undefined;
+  if (!a) return no(facts.approvals ? "approval_not_visible" : "approval_unknown");
+  if (me && String(a.approver || "") === me) return yes("approval", "approver");
+  if (me && String(a.requester || "") === me) return yes("approval", "requester");
+  return no("not_my_approval");
+}
+
+// ---------------------------------------------------------------------------
+// Small pure helpers (exported so the tests can pin them)
+// ---------------------------------------------------------------------------
+
+/**
+ * Would a SPACE message need its channel paged to decide directedness?
+ *
+ * `true`  — it might mention me or be threaded; page the channel.
+ * `false` — the redacted counts PROVE it cannot be mine (0 mentions, not
+ *           threaded); drop it without a single RPC.
+ * `null`  — the counts are absent (older row / other producer); page to be safe.
+ *
+ * Prose-name matching, when the caller enabled it, always needs the body — so a
+ * caller with `myNames` gets `null` rather than `false`.
+ *
+ * @param {Candidate} cand
+ * @param {{myNames?: string[]}} [facts]
+ * @returns {boolean|null}
+ */
+export function needsSpaceProbe(cand, facts = {}) {
+  const h = (cand && cand.hints) || {};
+  if (Array.isArray(facts.myNames) && facts.myNames.length > 0) return null;
+  if (h.mentionCount === undefined || h.threaded === undefined) return null;
+  if (h.mentionCount > 0) return true;
+  if (h.threaded) return true;
+  return false;
+}
+
+/** Find a hydrated message row in `facts.channelPages`. */
+export function lookupMessage(facts, channelId, messageId) {
+  if (!(facts.channelPages instanceof Map) || !channelId || !messageId) return null;
+  const page = facts.channelPages.get(String(channelId));
+  if (!page || !(page.byId instanceof Map)) return null;
+  return page.byId.get(String(messageId)) || null;
+}
+
+/**
+ * Does this prose name me? Used ONLY as a last resort, for surfaces where hq
+ * stores no structured mention row (decision/file comment prose). Matches on a
+ * word boundary, case-insensitively, with or without a leading `@`.
+ *
+ * @param {{myNames?: string[]}} facts
+ * @param {unknown} text
+ * @returns {boolean}
+ */
+export function matchesMyName(facts, text) {
+  const names = Array.isArray(facts && facts.myNames) ? facts.myNames : [];
+  if (names.length === 0) return false;
+  const body = typeof text === "string" ? text : "";
+  if (!body) return false;
+  const lower = body.toLowerCase();
+  for (const raw of names) {
+    const n = String(raw || "").trim().toLowerCase();
+    if (n.length < 2) continue;
+    let from = 0;
+    for (;;) {
+      const i = lower.indexOf(n, from);
+      if (i === -1) break;
+      const before = i > 0 ? lower[i - 1] : "";
+      const after = lower[i + n.length] || "";
+      const boundaryBefore = !before || before === "@" || !/[a-z0-9_]/.test(before);
+      const boundaryAfter = !after || !/[a-z0-9_]/.test(after);
+      if (boundaryBefore && boundaryAfter) return true;
+      from = i + 1;
+    }
+  }
+  return false;
+}
+
+/**
+ * hq encodes a chat attachment's surface in the opaque fileKey
+ * (`message-attachment:` / `task-attachment:` / `pinned-file:` — see
+ * `src/server/llm-responder/comments.ts`). Recover the task id from a
+ * task-attachment key so a comment on my task's attachment is still mine when
+ * the payload carried no channel.
+ *
+ * @param {string|undefined} fileKey
+ * @returns {string} the task id, or "" when the key is a different surface
+ */
+export function taskIdFromFileKey(fileKey) {
+  const k = typeof fileKey === "string" ? fileKey : "";
+  const m = /^task-attachment:([^:]+)/.exec(k);
+  return m ? m[1] : "";
+}
+
+/** The surface definition for a verdict (or null). */
+export function surfaceDef(name) {
+  return (name && SURFACES[name]) || null;
+}
+
+export default {
+  PRIVATE_ROOM_KINDS,
+  MEMBERSHIP_REQUIRED_KINDS,
+  classifyEvent,
+  resolveDirected,
+  coordsOf,
+  asSet,
+  needsSpaceProbe,
+  lookupMessage,
+  matchesMyName,
+  taskIdFromFileKey,
+  surfaceDef,
+};