@company-semantics/contracts 62.11.0 → 63.1.0

package/src/comments/README.md

@@ -181,8 +181,39 @@ it stays inside the vocabulary-guard's rules — request bodies still do not.
   Offsets are nullable — treat null as "highlight nothing", not as an error.
   Mentions written since ADR-BE-522 carry a real range; older rows carry null
   permanently, since recovering one would mean searching the body for a name.
+- **EVERY ACTOR HERE IS A `PrincipalRef`, NOT A USER ID** (ADR-CONTRACTS-160). A
+  comment's `author`, a mention's `target` and a picker candidate's `principal`
+  are all `{kind:'user', userId} | {kind:'agent'}`, because the agent is a legal
+  author and a legal mention target and has no users row to be keyed by — a
+  surface keyed on ids could only name people, which is why the mark used to be
+  re-derived from the body characters under the range, the exact
+  identity-from-body inversion this domain exists to prevent. `author` is
+  nullable for ONE reason only, a USER author whose record is gone; an agent
+  author is never null, so reading null as "the agent wrote this" attributes
+  every anonymous comment to it. No legacy id survives beside a ref — pre-launch,
+  an optional or duplicated field is how one consumer quietly keeps a second
+  opinion.
+- **`origin` says what ACT made a thread; `createdByUserId` says who.** They are
+  not the same question, and only `origin` distinguishes a thread somebody wrote
+  from one a mention in the DOCUMENT BODY brought into being — a body-born thread
+  shown as an ordinary comment tells a reader that someone said something they
+  never said. `introducedAt` on the `doc_mention` arm is when the mention
+  appeared in the body and is deliberately NOT the thread's `createdAt`: the
+  thread is materialised when the mention is noticed, which can be after replies
+  have already answered it.
+- **`pending` COMES FROM THE DURABLE TRIGGER ROW, and `unanswered` is
+  system-owned.** Every mention of the agent leaves exactly one `AgentOutcome`,
+  because a mention that simply goes quiet reads as "still thinking" forever.
+  Deriving `pending` from worker state or an SSE stream is wrong in both
+  directions — a reader who connects after the turn began sees nothing, and a
+  reader watching for a reply that a dead worker will never send spins
+  indefinitely. `reason` is published as VOCABULARY only; the app owns the
+  sentence for each one, so wording changes need no release here. As with the
+  redaction rule, "`reason` non-null iff terminal-unanswered" and
+  "`replyCommentId` non-null iff `replied`" are documented and writer-enforced
+  rather than expressed as Zod refinements.
 - **These shapes are MIRRORED from the backend route boundary, not authored
-  here.** Every bound matches
+  here — with ONE declared lead.** Every bound matches
   `company-semantics-backend/src/api/http/routes/comments/comments.schemas.ts`,
   and therefore matches the generated `components["schemas"]` view in `../api`.
   The accept/reject corpus in `__tests__/fixtures/comment-anchors.json` is
@@ -192,7 +223,14 @@ it stays inside the vocabulary-guard's rules — request bodies still do not.
   test run, so the corpus cannot be edited here quietly. A change made at the
   boundary is NOT caught from this repo — nothing in a single-repo CI run can
   see that file, and this package must not depend on the backend to look. See
-  ADR-CONTRACTS-116 for the split and for where the upstream gate belongs.
+  ADR-CONTRACTS-116 for the split and for where the upstream gate belongs. The
+  lead is the principal vocabulary above: `target`, `author`, `principal`,
+  `origin` and `agentOutcomes` land HERE FIRST by the contracts-first protocol of
+  ADR-CONT-029, so until the backend adopts them `../api` still carries the
+  superseded id-keyed fields. Nothing mechanical notices — the parity guard
+  compares the spec to the backend, never to this directory — so the divergence
+  is recorded in prose here and in `./schemas.ts`, and both notes come out when
+  the spec agrees.
 - **Request bodies are NOT here** (ADR-CONT-029), and one of them must never
   be: the mention set on a write is validated against a candidate list the
   server derives from `effective_acl_grants`, so nothing a client sends may
@@ -209,12 +247,15 @@ it stays inside the vocabulary-guard's rules — request bodies still do not.
 | `CommentThreadStatusSchema`       | Zod mirror of `COMMENT_THREAD_STATUSES`                                        |
 | `COMMENT_SUBJECT_TYPES`           | What a thread can hang off — closed, sized to what admits comments             |
 | `CommentSubjectTypeSchema`        | Zod mirror of `COMMENT_SUBJECT_TYPES`                                          |
-| `CommentMentionSchema`            | One mention: user id, nullable UTF-16 range, read-time display name            |
+| `CommentMentionSchema`            | One mention: `PrincipalRef` target, nullable UTF-16 range, display name        |
 | `CommentSchema`                   | One comment; `body` null iff soft-deleted (infers `CommentProjection`)         |
+| `ThreadOriginSchema`              | `{comment}` \| `{doc_mention, byUser, introducedAt}` — what ACT made a thread  |
+| `AGENT_OUTCOME_REASONS`           | Why the agent will not reply — vocabulary only; the app owns the sentence      |
+| `AgentOutcomeSchema`              | One durable outcome per trigger; `pending` comes from the trigger row          |
 | `CommentThreadSummarySchema`      | A thread without its comments — the resolve/reopen response                    |
 | `CommentThreadSchema`             | A thread with all its comments, oldest-first, tombstones included              |
 | `CommentThreadListResponseSchema` | `GET /api/comments`                                                            |
-| `MentionableCandidateSchema`      | One offerable mention target — no email, no access level                       |
+| `MentionableCandidateSchema`      | One offerable mention target — a `PrincipalRef`; no email, no access level     |
 | `MentionableResponseSchema`       | `GET /api/company-md/docs/{id}/mentionable`                                    |
 | `COMMENT_THREAD_KINDS`            | `comment` \| `suggestion` — a suggestion IS a comment thread                   |
 | `SUGGESTION_OPS`                  | `insert` \| `delete` \| `replace` — what a suggestion proposes                 |
@@ -262,7 +303,14 @@ it stays inside the vocabulary-guard's rules — request bodies still do not.
   projection from it without a cycle. `./receipt` is a leaf for the same
   reason — zod only, no reach for the anchor or the ladder — so anything in this
   directory can import it later without one.
-- Nothing outside this directory is imported: the
+- `../identity/agent` — `PrincipalRefSchema`, imported at RUNTIME by
+  `./schemas`. This directory once imported nothing outside itself; it now
+  imports exactly one thing, and deliberately. A locally-declared user-or-agent
+  union would be a second description of who the agent is, in the one package
+  whose job is to have exactly one — and `../identity/agent` is a zod-only leaf,
+  so the dependency adds no reach. The arrow runs comments → identity and never
+  back.
+- Nothing else outside this directory is imported: the
   comment vocabulary binds to the existing `commenter` band of
   `../permissions`'s `AccessLevel` and introduces no access level of its own, so
   it needs no import to say so.

package/src/comments/__tests__/README.md

@@ -79,6 +79,13 @@ deleteLength: 0, insert: "" }` is a valid mutation that applies without error
 - **Negative tests mutate ONE field of a well-formed factory result.** A
   hand-built broken object can pass for the wrong reason: it fails because of
   the field nobody was testing.
+- **A field's ABSENCE is pinned by asserting the whole key set, not by hoping.**
+  `Object.keys(...).sort()` on `CommentSchema` and on the candidate element is
+  what makes re-adding a legacy id field beside its `PrincipalRef` a red test.
+  A parse-based test cannot do this job: these shapes
+  are non-strict, so an extra key is accepted silently, and a legacy id kept
+  beside the ref is exactly how one consumer would quietly keep a second opinion
+  about who wrote a comment.
 
 ## Public API
 

package/src/comments/__tests__/schemas.test.ts

@@ -10,6 +10,7 @@
 import { describe, expect, it } from "vitest";
 
 import {
+  AGENT_OUTCOME_REASONS,
   COMMENT_SUBJECT_TYPES,
   COMMENT_THREAD_STATUSES,
   CommentMentionSchema,
@@ -28,7 +29,7 @@ const DOC_ID = "44444444-4444-4444-8444-444444444444";
 
 function makeMention(over: Record<string, unknown> = {}) {
   return {
-    userId: USER_ID,
+    target: { kind: "user", userId: USER_ID },
     startOffset: 0,
     endOffset: 9,
     displayName: "Sam Chen",
@@ -40,7 +41,7 @@ function makeComment(over: Record<string, unknown> = {}) {
   return {
     id: COMMENT_ID,
     threadId: THREAD_ID,
-    authorUserId: USER_ID,
+    author: { kind: "user", userId: USER_ID },
     body: "Should this say Q3 or Q4?",
     editedAt: null,
     deletedAt: null,
@@ -66,6 +67,8 @@ function makeThread(over: Record<string, unknown> = {}) {
       suffix: " by March",
     },
     status: "open",
+    origin: { kind: "comment" },
+    agentOutcomes: [],
     createdByUserId: USER_ID,
     resolvedByUserId: null,
     resolvedAt: null,
@@ -149,9 +152,42 @@ describe("CommentSchema and the redaction invariant", () => {
   });
 
   it("parses an unattributed comment — a tombstoned author is not an error", () => {
+    expect(CommentSchema.safeParse(makeComment({ author: null })).success).toBe(
+      true,
+    );
+  });
+
+  it("parses an agent-authored comment, and the agent ref carries no id", () => {
+    // The whole point of the ref: the agent has no users row, so a comment it
+    // wrote could not previously be attributed at all. `{ kind: 'agent' }` is
+    // the ONLY agent author — a userId beside it is refused rather than
+    // stripped, because a ref that parsed cleanly while carrying an id would
+    // hand the app a second, contradictory identity for a singleton.
     expect(
-      CommentSchema.safeParse(makeComment({ authorUserId: null })).success,
+      CommentSchema.safeParse(makeComment({ author: { kind: "agent" } }))
+        .success,
     ).toBe(true);
+    expect(
+      CommentSchema.safeParse(
+        makeComment({ author: { kind: "agent", userId: USER_ID } }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("carries the author ref and no legacy author id beside it", () => {
+    // A legacy id kept beside the ref is how one consumer quietly keeps a
+    // second opinion about who wrote a comment. Asserting the key set makes
+    // adding it back a red test rather than a silently tolerated extra.
+    expect(Object.keys(CommentSchema.shape).sort()).toEqual([
+      "author",
+      "body",
+      "createdAt",
+      "deletedAt",
+      "editedAt",
+      "id",
+      "mentions",
+      "threadId",
+    ]);
   });
 
   it("requires the mentions array — absent is not the same as empty", () => {
@@ -208,6 +244,20 @@ describe("CommentMentionSchema offsets", () => {
       CommentMentionSchema.safeParse(makeMention({ endOffset: 2.5 })).success,
     ).toBe(false);
   });
+
+  it("names the agent as a target, and rejects a bare user id", () => {
+    // The mark is a PRINCIPAL now, not a string. A bare id could never name the
+    // agent, which is why every surface used to re-derive it from the body
+    // characters under the range — the exact inversion this contract forbids.
+    expect(
+      CommentMentionSchema.safeParse(
+        makeMention({ target: { kind: "agent" }, displayName: "c_S" }),
+      ).success,
+    ).toBe(true);
+    expect(
+      CommentMentionSchema.safeParse(makeMention({ target: USER_ID })).success,
+    ).toBe(false);
+  });
 });
 
 describe("CommentThreadSchema", () => {
@@ -358,6 +408,106 @@ describe("CommentThreadSummarySchema kind and suggestion", () => {
   });
 });
 
+describe("CommentThreadSummarySchema origin and agentOutcomes", () => {
+  it("a thread summary requires origin and agentOutcomes", () => {
+    // REQUIRED, like `kind` and `capabilities`. Optional is how one consumer
+    // keeps a local derivation of what started a thread or whether the agent
+    // answered — and both of those are precisely what this vocabulary exists to
+    // stop being guessed. The backend projects `{kind:'comment'}` and `[]` onto
+    // every thread that predates them, so absence is malformed, not legacy.
+    const { origin: _noOrigin, ...withoutOrigin } = makeThread();
+    expect(CommentThreadSummarySchema.safeParse(withoutOrigin).success).toBe(
+      false,
+    );
+    const { agentOutcomes: _noOutcomes, ...withoutOutcomes } = makeThread();
+    expect(CommentThreadSummarySchema.safeParse(withoutOutcomes).success).toBe(
+      false,
+    );
+  });
+
+  it("parses a thread born from a mention in the document body", () => {
+    // The second origin arm, published ahead of the doc-body work so it needs
+    // no further release. `introducedAt` is when the mention appeared in the
+    // BODY and is deliberately not `createdAt`: the thread is materialised when
+    // the mention is noticed, which can be after replies already answered it.
+    const parsed = CommentThreadSummarySchema.parse(
+      makeThread({
+        origin: {
+          kind: "doc_mention",
+          byUser: { kind: "user", userId: USER_ID },
+          introducedAt: "2026-07-30T08:00:00.000Z",
+        },
+      }),
+    );
+    expect(parsed.origin.kind).toBe("doc_mention");
+    // A tombstoned introducer is not an error, same rule as a comment author.
+    expect(
+      CommentThreadSummarySchema.safeParse(
+        makeThread({
+          origin: {
+            kind: "doc_mention",
+            byUser: null,
+            introducedAt: "2026-07-30T08:00:00.000Z",
+          },
+        }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("rejects a doc_mention origin missing introducedAt", () => {
+    // The discriminant alone must not carry the arm: a `doc_mention` without a
+    // time is a genesis row a client can only place by falling back to
+    // `createdAt`, which is the wrong number.
+    expect(
+      CommentThreadSummarySchema.safeParse(
+        makeThread({ origin: { kind: "doc_mention", byUser: null } }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("carries a terminal unanswered outcome with a reason and no reply", () => {
+    // The marker that makes a trigger terminate VISIBLY. Without it a mention
+    // that will never be answered is indistinguishable from one still being
+    // worked, and the reader waits forever. `reason` is vocabulary only — the
+    // app owns the sentence, so wording changes need no release here.
+    expect([...AGENT_OUTCOME_REASONS]).toContain("delegate_unknown");
+    const parsed = CommentThreadSummarySchema.parse(
+      makeThread({
+        agentOutcomes: [
+          {
+            triggerId: "66666666-6666-4666-8666-666666666666",
+            status: "unanswered",
+            reason: "delegate_unknown",
+            replyCommentId: null,
+          },
+        ],
+      }),
+    );
+    expect(parsed.agentOutcomes[0].status).toBe("unanswered");
+  });
+
+  it("rejects an outcome status or reason outside the published vocabulary", () => {
+    // Both enums are closed. A free string would let the backend invent a
+    // fourth state the app renders as nothing at all — silence again.
+    const outcome = {
+      triggerId: "66666666-6666-4666-8666-666666666666",
+      status: "pending",
+      reason: null,
+      replyCommentId: null,
+    };
+    expect(
+      CommentThreadSummarySchema.safeParse(
+        makeThread({ agentOutcomes: [{ ...outcome, status: "working" }] }),
+      ).success,
+    ).toBe(false);
+    expect(
+      CommentThreadSummarySchema.safeParse(
+        makeThread({ agentOutcomes: [{ ...outcome, reason: "gave_up" }] }),
+      ).success,
+    ).toBe(false);
+  });
+});
+
 describe("CommentThreadListResponseSchema", () => {
   it("parses an empty subject", () => {
     expect(
@@ -377,7 +527,25 @@ describe("MentionableResponseSchema", () => {
   it("parses a candidate list", () => {
     expect(
       MentionableResponseSchema.safeParse({
-        items: [{ userId: USER_ID, displayName: "Sam Chen", avatarUrl: null }],
+        items: [
+          {
+            principal: { kind: "user", userId: USER_ID },
+            displayName: "Sam Chen",
+            avatarUrl: null,
+          },
+        ],
+      }).success,
+    ).toBe(true);
+  });
+
+  it("offers the agent as a candidate — it has no users row to be keyed by", () => {
+    // A picker keyed on user ids could only ever offer people, which is why the
+    // agent had to be typed rather than searched for in the body text.
+    expect(
+      MentionableResponseSchema.safeParse({
+        items: [
+          { principal: { kind: "agent" }, displayName: "c_S", avatarUrl: null },
+        ],
       }).success,
     ).toBe(true);
   });
@@ -386,8 +554,9 @@ describe("MentionableResponseSchema", () => {
     // The candidates ARE the document's readers. Returning the band each one
     // holds would turn an autocomplete into a way to enumerate who can do what,
     // so the field must stay absent from the shape rather than merely unset.
+    // The same assertion pins that `userId` did not survive beside `principal`.
     expect(
       Object.keys(MentionableResponseSchema.shape.items.element.shape).sort(),
-    ).toEqual(["avatarUrl", "displayName", "userId"]);
+    ).toEqual(["avatarUrl", "displayName", "principal"]);
   });
 });

package/src/comments/index.ts

@@ -34,6 +34,8 @@ export {
 export type { AnchorResolution, Occurrence } from "./resolve";
 
 export {
+  AGENT_OUTCOME_REASONS,
+  AgentOutcomeSchema,
   COMMENT_SUBJECT_TYPES,
   COMMENT_THREAD_STATUSES,
   CommentMentionSchema,
@@ -45,9 +47,11 @@ export {
   CommentThreadSummarySchema,
   MentionableCandidateSchema,
   MentionableResponseSchema,
+  ThreadOriginSchema,
 } from "./schemas";
 
 export type {
+  AgentOutcome,
   CommentMention,
   CommentProjection,
   CommentSubjectType,
@@ -57,6 +61,7 @@ export type {
   CommentThreadSummary,
   MentionableCandidate,
   MentionableResponse,
+  ThreadOrigin,
 } from "./schemas";
 
 export {

package/src/comments/schemas.ts

@@ -9,15 +9,26 @@
  *
  * Zod-canonical: the schema is the source of truth, the type is inferred.
  *
- * MIRRORED, NOT INVENTED. Every field below matches the backend route
+ * MIRRORED, WITH ONE DECLARED LEAD. Every field below matches the backend route
  * boundary's response schemas (`src/api/http/routes/comments/comments.schemas.ts`
- * and `.../company-md/mentionable.schemas.ts`) field-for-field, and therefore
- * matches the already-generated `components["schemas"]` view in `../api`. Two
- * descriptions of one wire shape that disagree is worse than one, so where the
- * backend is looser than looks right — `userId` is `z.string()` and not a uuid,
- * mention offsets are nullable — this mirrors the backend and says why.
+ * and `.../company-md/mentionable.schemas.ts`) field-for-field — EXCEPT the
+ * principal vocabulary of ADR-CONTRACTS-160 (`target`, `author`, `principal`,
+ * `origin`, `agentOutcomes`), which lands HERE FIRST by the contracts-first
+ * protocol of ADR-CONT-029: the schema ships, the route registry adopts it,
+ * then `openapi/backend.yaml` and the generated `components["schemas"]` view in
+ * `../api` catch up. Until the backend side lands, `../api` still carries the
+ * superseded id-keyed fields, and NOTHING IN THIS REPO CAN SEE THE DIVERGENCE —
+ * the parity guard that would catch it compares the spec to the backend, never
+ * to this file. So this paragraph is the whole record of it, and it comes out
+ * when the spec agrees.
+ *
+ * Two descriptions of one wire shape that disagree is worse than one, so where
+ * the backend is looser than looks right — a principal's `userId` is
+ * `z.string()` and not a uuid, mention offsets are nullable — this mirrors the
+ * backend and says why.
  */
 import { z } from "zod";
+import { PrincipalRefSchema } from "../identity/agent";
 import { CommentAnchorSchema, CommentAnchorTypeSchema } from "./anchor";
 import { COMMENT_THREAD_KINDS, SuggestionSchema } from "./suggestion";
 
@@ -89,13 +100,16 @@ export type CommentSubjectType = z.infer<typeof CommentSubjectTypeSchema>;
  * identity the reader can no longer resolve arrives as a neutral placeholder
  * rather than failing the whole thread load.
  *
- * `userId` is `z.string()` and not `.uuid()` on purpose — it mirrors the
- * backend boundary exactly. Tightening it here would make this package reject
- * responses the server considers valid, which is a client-side outage for no
- * security gain.
+ * `target` IS A PRINCIPAL, NOT A USER ID (ADR-CONTRACTS-160). The agent is a
+ * legal mention target and has no users row to point at, so a mention keyed on
+ * a bare id could not name it at all — which is how the mark ended up rendered
+ * from body characters everywhere it appeared. A user target's `userId` stays
+ * `z.string()` and not `.uuid()`, mirroring the backend boundary exactly:
+ * tightening it here would make this package reject responses the server
+ * considers valid, which is a client-side outage for no security gain.
  */
 export const CommentMentionSchema = z.object({
-  userId: z.string(),
+  target: PrincipalRefSchema,
   startOffset: z.number().int().min(0).nullable(),
   endOffset: z.number().int().min(0).nullable(),
   displayName: z.string(),
@@ -126,8 +140,12 @@ export type CommentMention = z.infer<typeof CommentMentionSchema>;
  * cannot check. `./__tests__/schemas.test.ts` pins that the redacted projection
  * parses.
  *
- * `authorUserId` is nullable for the same tombstoning reason: an author whose
- * user record is gone leaves the comment readable and unattributed.
+ * `author` is a `PrincipalRef` and nullable, and null keeps EXACTLY ONE
+ * meaning: a USER author whose user record is gone, leaving the comment
+ * readable and unattributed. An agent author is `{ kind: "agent" }` and is
+ * NEVER null — the agent is a singleton with no record to lose
+ * (ADR-CONTRACTS-160), so a client that reads null as "the agent wrote this"
+ * attributes every tombstoned author's comment to the agent.
  *
  * The inferred type is `CommentProjection`, not `Comment`, for the reason
  * `NotificationElement` is not `Element` (`../notifications/content`): `Comment`
@@ -138,7 +156,7 @@ export type CommentMention = z.infer<typeof CommentMentionSchema>;
 export const CommentSchema = z.object({
   id: z.string(),
   threadId: z.string(),
-  authorUserId: z.string().nullable(),
+  author: PrincipalRefSchema.nullable(),
   body: z.string().nullable(),
   editedAt: z.string().nullable(),
   deletedAt: z.string().nullable(),
@@ -151,6 +169,82 @@ export type CommentProjection = z.infer<typeof CommentSchema>;
 // Threads
 // =============================================================================
 
+/**
+ * HOW A THREAD CAME TO EXIST — not WHO made it (`createdByUserId` answers that)
+ * but WHAT ACT did.
+ *
+ * Every thread in existence projects `{ kind: "comment" }`: somebody wrote a
+ * comment. The `doc_mention` arm is the thread that a mention in the DOCUMENT
+ * BODY brings into being, where nobody wrote a comment at all — so
+ * `createdByUserId` alone cannot tell the two apart, and a reader shown a
+ * body-born thread as an ordinary comment is being told someone said something
+ * they never said. Both arms publish NOW so the doc-body work emits the second
+ * one with no further release of this package.
+ *
+ * `byUser` is a `PrincipalRef` and nullable for the same tombstoning reason as
+ * `CommentSchema.author`. `introducedAt` is when the mention appeared in the
+ * BODY, which is NOT the thread's `createdAt`: the thread is materialised when
+ * the mention is noticed, which can be later, and ordering a genesis row by
+ * `createdAt` puts it after replies that answered it.
+ *
+ * NON-STRICT, like the thread shapes it sits inside and unlike
+ * `SuggestionSchema`: a suggestion is a negotiated payload that must grow by a
+ * new `v`, while this is a server projection that mirrors the backend's
+ * looseness rather than tightening past it.
+ */
+export const ThreadOriginSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("comment") }),
+  z.object({
+    kind: z.literal("doc_mention"),
+    byUser: PrincipalRefSchema.nullable(),
+    introducedAt: z.string(),
+  }),
+]);
+export type ThreadOrigin = z.infer<typeof ThreadOriginSchema>;
+
+/** Why the agent will not reply. Vocabulary only — the app owns the sentence. */
+export const AGENT_OUTCOME_REASONS = [
+  "replies_off",
+  "mentioner_unavailable",
+  "delegate_unknown",
+  "subject_unreadable",
+  "rate_capped",
+  "turn_failed",
+] as const;
+
+/**
+ * ONE DURABLE OUTCOME PER TRIGGER — what became of each mention of the agent on
+ * this thread. The array is empty on every thread that never named it.
+ *
+ * `pending` IS DERIVED FROM THE DURABLE TRIGGER ROW, never from worker state
+ * and never from an SSE stream. Both of those are the wrong source in opposite
+ * directions: a client inferring "still working" from a live stream shows
+ * nothing to a reader who connected after the turn began, and a client
+ * inferring it from the absence of a reply spins forever over a worker that
+ * died. The trigger row outlives both, which is why it is the only one.
+ *
+ * `unanswered` IS SYSTEM-OWNED AND TERMINAL: the agent will not reply and
+ * nothing further is queued. It exists so a mention cannot simply go quiet —
+ * silence reads as "still thinking" indefinitely, and the whole point of a
+ * durable outcome is that every trigger terminates visibly. `reason` says which
+ * way, and the APP owns the copy for each one: this package publishes the
+ * vocabulary, not the sentence, so wording changes need no release.
+ *
+ * `reason` is null EXACTLY when `status` is `pending` or `replied`, and
+ * `replyCommentId` is non-null EXACTLY when `status` is `replied`. Both rules
+ * are DOCUMENTED and writer-enforced rather than expressed as refinements, for
+ * the same reason as the redaction invariant above: a refinement would make
+ * this package refuse a response the server is willing to emit, and it cannot
+ * be said in the OpenAPI surface either.
+ */
+export const AgentOutcomeSchema = z.object({
+  triggerId: z.string(),
+  status: z.enum(["pending", "replied", "unanswered"]),
+  reason: z.enum(AGENT_OUTCOME_REASONS).nullable(),
+  replyCommentId: z.string().nullable(),
+});
+export type AgentOutcome = z.infer<typeof AgentOutcomeSchema>;
+
 /**
  * A thread WITHOUT its comments — the shape a resolve/reopen transition returns.
  *
@@ -187,6 +281,13 @@ export type CommentProjection = z.infer<typeof CommentSchema>;
  * thread status `resolved` with `suggestion.status` carrying which way it went
  * (`accepted` | `rejected`), and `resolvedByUserId`/`resolvedAt` double as the
  * decision actor and time — there is no second actor/timestamp pair.
+ *
+ * `origin` and `agentOutcomes` are BOTH REQUIRED, for the reason `kind` and
+ * `capabilities` are: an optional field is how one consumer quietly keeps a
+ * local derivation, and a second opinion about what started a thread or whether
+ * the agent answered is exactly the drift this vocabulary exists to delete. The
+ * backend projects `{ kind: "comment" }` and `[]` onto every thread that
+ * predates them, so absence is a malformed response and not a legacy row.
  */
 export const CommentThreadSummarySchema = z.object({
   id: z.string(),
@@ -197,6 +298,8 @@ export const CommentThreadSummarySchema = z.object({
   anchorType: CommentAnchorTypeSchema,
   anchor: CommentAnchorSchema,
   status: CommentThreadStatusSchema,
+  origin: ThreadOriginSchema,
+  agentOutcomes: z.array(AgentOutcomeSchema),
   createdByUserId: z.string().nullable(),
   resolvedByUserId: z.string().nullable(),
   resolvedAt: z.string().nullable(),
@@ -291,12 +394,15 @@ export type CommentThreadListResponse = z.infer<
  * readers — so returning the band each one holds would turn an autocomplete into
  * a way to enumerate who can do what.
  *
- * `userId` is what the mention row will carry; `displayName` is resolved fresh
- * on every read and never frozen into a stored row, exactly as on
- * `CommentMentionSchema`.
+ * `principal` is what the mention row will carry, and it is a `PrincipalRef`
+ * rather than a user id so that the AGENT is offerable here at all — it holds
+ * no grants of its own and has no users row, so a candidate list keyed on ids
+ * could only ever offer people (ADR-CONTRACTS-160). `displayName` is resolved
+ * fresh on every read and never frozen into a stored row, exactly as on
+ * `CommentMentionSchema`; for the agent it is `CS_AGENT.displayName`.
  */
 export const MentionableCandidateSchema = z.object({
-  userId: z.string(),
+  principal: PrincipalRefSchema,
   displayName: z.string(),
   avatarUrl: z.string().nullable(),
 });

package/src/identity/README.md

@@ -20,6 +20,7 @@ TypeScript types and functions for user identity and display name resolution.
 
 ## Public API
 
+- `AGENT_PRINCIPAL` — The one agent principal.
 - `AccountCancelDeletionResponse` _(type)_
 - `AccountCancelDeletionResponseSchema`
 - `AccountConfirmDeletionResponse` _(type)_
@@ -42,6 +43,8 @@ TypeScript types and functions for user identity and display name resolution.
 - `BannerDismissResponseSchema`
 - `BannerDismissedListResponse` _(type)_
 - `BannerDismissedListResponseSchema`
+- `CS_AGENT` — The agent's identity, in the three forms a surface needs: the handle a mention is typed as, the name a chip…
+- `CS_AGENT_HANDLE` — THE AGENT PRINCIPAL (control INVARIANTS.md, INV-AGENT-IDENTITY).
 - `DeletionBlocker` _(type)_ — Conditions that block account deletion.
 - `ISODateString` _(type)_ — ISO 8601 date-time string.
 - `IdentityLink` _(type)_
@@ -65,6 +68,8 @@ TypeScript types and functions for user identity and display name resolution.
 - `PersonSchema`
 - `PositionRef` _(type)_
 - `PositionRefSchema` — A reference to a POSITION in the org graph.
+- `PrincipalRef` _(type)_
+- `PrincipalRefSchema` — A principal: a person by id, or the one agent.
 - `ProfileResponse` _(type)_
 - `ProfileResponseSchema`
 - `ReportingRelationshipType` _(type)_
@@ -77,8 +82,11 @@ TypeScript types and functions for user identity and display name resolution.
 - `deriveFullName`
 - `extractFirstWord` — Extract the first word from a full name.
 - `generateInitials` — Generate initials from a full name.
+- `isAgentPrincipal` — Narrows a ref to the agent arm.
+- `principalKey` — Stable key for Set/Map use: 'agent' | 'user:id'.
 - `resolveAvatar` — Resolve avatar from user identity.
 - `resolveDisplayName` — Resolve the display name for assistant addressing.
+- `userPrincipal` — A person as a principal.
 
 <!-- END GENERATED: readme-public-api -->