@company-semantics/contracts 62.11.0 → 63.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "62.11.0",
+  "version": "63.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '9829bca605e4' as const;
-export const SPEC_HASH_FULL = '9829bca605e4a464d73b067d1d063d2a68c5871b9fae570470a43987e481bb3a' as const;
+export const SPEC_HASH = 'e90aa233fbf5' as const;
+export const SPEC_HASH_FULL = 'e90aa233fbf5c821f7a67d53e8da52152166bf1eefb029e1999fde02e8e66a4f' as const;

package/src/api/generated.ts

@@ -4079,6 +4079,19 @@ export interface components {
                 sequenceNumber: number;
                 /** Format: date-time */
                 createdAt: string;
+                mentions: {
+                    target: {
+                        /** @constant */
+                        kind: "user";
+                        userId: string;
+                    } | {
+                        /** @constant */
+                        kind: "agent";
+                    };
+                    startOffset: number | null;
+                    endOffset: number | null;
+                    displayName: string;
+                }[];
             }[];
         };
         SuccessResponse: {

package/src/chat/README.md

@@ -24,6 +24,13 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - Page context carries NO ORG IDENTITY, though the app's org routes have one in the URL. Org scope is derived from the session; a request-supplied org identifier would be an authority claim in a field the server otherwise reads for itself
 - `compactedThroughSequence` on the chat detail is ABSENT or NULL exactly when the conversation has never been compacted. It is never coerced to `0` — sequence numbers are zero-indexed, so `0` is a boundary a chat can really have, and a zero default would make "never compacted" indistinguishable from "compacted through sequence 0". It is optional for the same reason `proactiveKind` is a bare string: a client that does not know the field renders the transcript exactly as before (ADR-CONTRACTS-154)
 - `compactedThroughSequence` is a BOUNDARY MARKER, not a context gauge. It is the one sequence number the summary covers through — never a token count, never a percentage of the context window, and never the summary text itself. The reader's question it answers is "why did it forget the beginning", not "how full is the window" (ADR-CONTRACTS-154)
+- `mentions` on a chat message is REQUIRED, and an empty array is the common value. Absent is not the same as empty — this shipped in a MAJOR precisely so no consumer keeps a second opinion about which one it holds. Contrast the proactive wire fields above, which are optional so consumer object literals survive a minor (ADR-CONTRACTS-160)
+- A mention TARGET is a `PrincipalRef`, never a user id, so the agent — which has no users row to point at — is a legal mention target on the chat surface exactly as on a comment (ADR-CONTRACTS-160)
+- Chat mention offsets are ZERO-BASED UTF-16 CODE UNITS into the exact `content` string with `endOffset` EXCLUSIVE, and no Unicode normalization happens anywhere on the path — the same convention as `CommentMention`, because a mention means the same thing on both surfaces. An astral character counts as TWO units
+- Chat mention offsets are NULLABLE and null means "mentioned somewhere in this turn, highlight nothing", never an error. A user turn carries a real range; an assistant turn's mention is a typed part with no character range, and the nullability is what lets that land with no second schema
+- Identity on a chat mention renders from the mention ROW, never from the content characters under the range. A stale range can only mis-highlight; it can never misattribute
+- `SharedChatMessage` deliberately has NO mentions. The token-only share viewer is granted the CONTENT of a shared chat and nothing else; a mention row is identity, and identity is not in that grant
+- `ChatMentionableResponse` carries `MentionableCandidate` items imported from `comments`, not a chat-flavoured copy. A candidate is a principal, a display name and an avatar on both surfaces — and on both, deliberately no email and no access level, because a picker that returned the band each candidate holds would be a way to enumerate who can do what
 - `CHAT_PAGE_VIEWS` and `CHAT_PAGE_SCOPES` are a projection of the app's `Route` union (`company-semantics-app/src/platform/route-parser.ts`), not a parallel vocabulary. A view the parser can emit but the schema rejects fails the send outright rather than degrading
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
@@ -53,7 +60,11 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatListFilters` _(type)_ — Filters for listing chats.
 - `ChatListResponse` _(type)_ — Response for GET /api/chats
 - `ChatListResponseSchema` — Response for GET /api/chats.
+- `ChatMentionableResponse` _(type)_ — Response for the chat composer's mentionable-candidate endpoint.
+- `ChatMentionableResponseSchema` — Who the chat composer may offer as a mention target.
 - `ChatMessage` _(type)_ — Individual message in a chat response (GET /api/chats/:id).
+- `ChatMessageMention` _(type)_ — One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16 code-unit range into `content`, and a…
+- `ChatMessageMentionSchema` — ONE mention on a chat turn — field-for-field `CommentMentionSchema` (`../comments/schemas`), and deliberately…
 - `ChatMessageSchema` — Individual message in a chat, as returned by GET /api/chats/:id.
 - `ChatOrigin` _(type)_ — How a chat was born: `user` or `proactive` (the system spoke first).
 - `ChatOriginSchema` — How a chat was born: by the user, or by the system speaking first (a proactive occurrence projected onto the…
@@ -117,6 +128,8 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 **Internal domains:**
 
 - `api`
+- `comments`
+- `identity`
 - `proactive`
 
 **External packages:**

package/src/chat/__tests__/message-mentions.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Mentions on a chat turn (ADR-CONTRACTS-160).
+ *
+ * INVARIANTS TESTED:
+ * - `mentions` is REQUIRED on a chat message. Absent is not the same as empty:
+ *   an empty array says "this turn named nobody", a missing key says nothing at
+ *   all, and the whole point of shipping it in a MAJOR is that no consumer gets
+ *   to keep a second opinion about which one it is holding.
+ * - A mention TARGET is a `PrincipalRef`, so the agent — which has no users row
+ *   to point at — is a legal target on the chat surface exactly as on a comment.
+ *   A bare user id is not a target, and never was: that is the shape this
+ *   vocabulary replaced.
+ * - OFFSETS ARE NULLABLE and null is not an error. A user turn carries a real
+ *   range because the composer measured it; an assistant turn's mention (the
+ *   later multi-party phase) is a typed part with no character range at all.
+ *   The nullability is what lets that land with no second schema.
+ * - OFFSETS ARE UTF-16 CODE UNITS into the exact `content` string, `endOffset`
+ *   exclusive. An astral character counts as TWO. Asserted against a real slice
+ *   rather than stated, because a client measuring code POINTS produces ranges
+ *   that look right until an emoji precedes the mention.
+ * - `SharedChatMessageSchema` did NOT gain mentions. The token-only share viewer
+ *   renders content, not identity chips, and a mention row is identity a
+ *   tokenholder was never granted.
+ * - `ChatMentionableResponseSchema` carries `MentionableCandidateSchema` items —
+ *   the comments shape imported, not a chat-flavoured copy of it.
+ */
+import { describe, expect, it } from "vitest";
+import { AGENT_PRINCIPAL, CS_AGENT, userPrincipal } from "../../identity/agent";
+import {
+  ChatMentionableResponseSchema,
+  ChatMessageMentionSchema,
+  ChatMessageSchema,
+  GetChatResponseSchema,
+  SharedChatMessageSchema,
+} from "../schemas.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures — one well-formed value per shape; every negative case spreads it
+// and changes exactly ONE field, so a failure cannot mean something else.
+// ---------------------------------------------------------------------------
+
+const makeMention = (over: Record<string, unknown> = {}) => ({
+  target: userPrincipal("user_1"),
+  startOffset: 0,
+  endOffset: 5,
+  displayName: "Ada",
+  ...over,
+});
+
+const makeMessage = (over: Record<string, unknown> = {}) => ({
+  id: "msg_1",
+  role: "user" as const,
+  content: "Hello",
+  sequenceNumber: 0,
+  createdAt: "2026-09-02T00:00:00.000Z",
+  mentions: [],
+  ...over,
+});
+
+describe("ChatMessageSchema mentions", () => {
+  it("a chat message requires a mentions array", () => {
+    const { mentions: _omitted, ...withoutMentions } = makeMessage();
+
+    const r = ChatMessageSchema.safeParse(withoutMentions);
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.error.issues[0].path).toEqual(["mentions"]);
+  });
+
+  it("an empty mentions array is the common value, not an absence", () => {
+    const parsed = ChatMessageSchema.parse(makeMessage());
+    expect(parsed.mentions).toEqual([]);
+  });
+
+  it("carries the mention rows a turn named", () => {
+    const parsed = ChatMessageSchema.parse(
+      makeMessage({ mentions: [makeMention()] }),
+    );
+
+    expect(parsed.mentions).toHaveLength(1);
+    expect(parsed.mentions[0].target).toEqual({
+      kind: "user",
+      userId: "user_1",
+    });
+  });
+
+  it("rides the transcript in GET /api/chats/:id", () => {
+    const parsed = GetChatResponseSchema.parse({
+      chat: {
+        id: "chat_1",
+        title: "A conversation",
+        interactionId: "int_1",
+        createdAt: "2026-09-02T00:00:00.000Z",
+        updatedAt: "2026-09-02T01:00:00.000Z",
+      },
+      messages: [makeMessage({ mentions: [makeMention()] })],
+    });
+
+    expect(parsed.messages[0].mentions).toHaveLength(1);
+  });
+
+  it("the share viewer's message shape did not gain mentions", () => {
+    // A token holder is granted the CONTENT of a shared chat and nothing else.
+    // Mention rows are identity, and identity is not in the grant.
+    expect(Object.keys(SharedChatMessageSchema.shape)).not.toContain(
+      "mentions",
+    );
+  });
+});
+
+describe("ChatMessageMentionSchema", () => {
+  it("the agent is a legal mention target and needs no user record", () => {
+    const parsed = ChatMessageMentionSchema.parse(
+      makeMention({
+        target: AGENT_PRINCIPAL,
+        displayName: CS_AGENT.displayName,
+      }),
+    );
+
+    expect(parsed.target).toEqual({ kind: "agent" });
+    expect(parsed.displayName).toBe("c_S");
+  });
+
+  it("a bare user id is not a target", () => {
+    // The shape this vocabulary replaced. A string where a ref belongs must
+    // refuse, or the agent silently becomes unnameable again.
+    expect(
+      ChatMessageMentionSchema.safeParse(makeMention({ target: "user_1" }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("null offsets mean highlight nothing, and are never an error", () => {
+    // The assistant-turn case: a typed part with no character range.
+    const parsed = ChatMessageMentionSchema.parse(
+      makeMention({ startOffset: null, endOffset: null }),
+    );
+
+    expect(parsed.startOffset).toBeNull();
+    expect(parsed.endOffset).toBeNull();
+  });
+
+  it("offsets are UTF-16 code units, with endOffset exclusive", () => {
+    // The emoji is TWO code units, so the mention starts at 6. A client
+    // measuring code POINTS (`[...content].indexOf`) would say 5 and slice one
+    // unit early — one unit per preceding astral character.
+    const content = "hi 🎉 @Ada";
+    const startOffset = content.indexOf("@Ada");
+    const mention = ChatMessageMentionSchema.parse(
+      makeMention({ startOffset, endOffset: startOffset + "@Ada".length }),
+    );
+
+    expect(startOffset).toBe(6);
+    expect([...content].indexOf("@")).toBe(5);
+    expect(content.slice(mention.startOffset!, mention.endOffset!)).toBe(
+      "@Ada",
+    );
+  });
+
+  it("rejects a negative startOffset", () => {
+    expect(
+      ChatMessageMentionSchema.safeParse(makeMention({ startOffset: -1 }))
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatMentionableResponseSchema", () => {
+  it("offers the agent alongside people", () => {
+    const parsed = ChatMentionableResponseSchema.parse({
+      items: [
+        {
+          principal: AGENT_PRINCIPAL,
+          displayName: CS_AGENT.displayName,
+          avatarUrl: null,
+        },
+        {
+          principal: userPrincipal("user_1"),
+          displayName: "Ada",
+          avatarUrl: null,
+        },
+      ],
+    });
+
+    expect(parsed.items).toHaveLength(2);
+    expect(parsed.items[0].principal).toEqual({ kind: "agent" });
+  });
+
+  it("an empty candidate list parses", () => {
+    expect(ChatMentionableResponseSchema.parse({ items: [] }).items).toEqual(
+      [],
+    );
+  });
+
+  it("carries the comments candidate shape, not a chat copy of it", () => {
+    // No email and no access level: this is a picker, not an
+    // access-inspection surface.
+    const r = ChatMentionableResponseSchema.safeParse({
+      items: [{ userId: "user_1", displayName: "Ada", avatarUrl: null }],
+    });
+
+    expect(r.success).toBe(false);
+  });
+});

package/src/chat/index.ts

@@ -50,6 +50,10 @@ export type {
   ListSharesResponse,
   UpdateShareResponse,
   ChatMessage,
+  // Mentions on a chat turn (ADR-CONTRACTS-160): a PrincipalRef target, so the
+  // agent is a legal mention target on the chat surface too.
+  ChatMessageMention,
+  ChatMentionableResponse,
   ChatDetail,
   GetChatResponse,
   // Page context (request-side): where the reader is, as identifiers
@@ -91,6 +95,8 @@ export {
   ListSharesResponseSchema,
   UpdateShareResponseSchema,
   ChatMessageSchema,
+  ChatMessageMentionSchema,
+  ChatMentionableResponseSchema,
   ChatDetailSchema,
   GetChatResponseSchema,
   // Page context (request-side) — the schema plus the closed vocabularies it

package/src/chat/schemas.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { IsoDateTime } from "../api/primitives";
+import { MentionableCandidateSchema } from "../comments/schemas";
+import { PrincipalRefSchema } from "../identity/agent";
 
 // =============================================================================
 // Enums
@@ -232,7 +234,65 @@ export const ChatSseEventSchema = z.discriminatedUnion("type", [
 // Message Types
 // =============================================================================
 
-/** Individual message in a chat, as returned by GET /api/chats/:id. */
+/**
+ * ONE mention on a chat turn — field-for-field `CommentMentionSchema`
+ * (`../comments/schemas`), and deliberately the same shape rather than a
+ * chat-flavoured variant: a mention means the same thing on both surfaces, and
+ * two descriptions of it would drift.
+ *
+ * The comments conventions carry over WHOLE and are restated here because a
+ * reader of this file will not necessarily open that one:
+ *
+ * - OFFSETS ARE ZERO-BASED UTF-16 CODE UNITS INTO THE EXACT `content` STRING,
+ *   `endOffset` EXCLUSIVE — plain JavaScript string coordinates, the same ones a
+ *   `textarea`'s `selectionStart` reports. An astral character counts as TWO
+ *   units, so a client measuring in code POINTS slides off the mention by one
+ *   per preceding emoji.
+ * - NO UNICODE NORMALIZATION happens anywhere on this path. Normalising the
+ *   content before measuring changes its length and desynchronises every offset
+ *   after the first composed character.
+ * - IDENTITY RENDERS FROM THIS ROW, NEVER FROM THE CONTENT UNDER THE RANGE. A
+ *   stale range can therefore only mis-HIGHLIGHT; it can never misattribute.
+ *
+ * OFFSETS ARE NULLABLE, and null means "mentioned somewhere in this turn,
+ * highlight nothing" — never an error. A USER turn always carries a real range,
+ * because the composer measured it. An ASSISTANT turn's mention arrives as a
+ * typed part with no character range at all (the later multi-party phase), and
+ * the nullability is what lets that land without a second schema.
+ *
+ * `target` is a `PrincipalRef`, so the agent — which has no users row — is a
+ * legal mention target here exactly as it is on a comment (ADR-CONTRACTS-160).
+ * `displayName` is resolved AT READ TIME and never frozen onto the row: a rename
+ * re-renders with no backfill.
+ */
+export const ChatMessageMentionSchema = z.object({
+  target: PrincipalRefSchema,
+  startOffset: z.number().int().min(0).nullable(),
+  endOffset: z.number().int().min(0).nullable(),
+  displayName: z.string(),
+});
+
+/**
+ * Individual message in a chat, as returned by GET /api/chats/:id.
+ *
+ * `mentions` is REQUIRED, not optional, and an empty array is the common value.
+ * This is the `CommentSchema` side of the choice rather than the
+ * `proactiveChatFields` side directly above: those are optional so consumer
+ * object literals keep compiling across a minor, whereas this ships in a MAJOR
+ * where the whole point is that no consumer keeps a second opinion about
+ * whether a turn has mentions. The server always projects the array; a missing
+ * one is a backend that has not adopted this release, and refusing it is the
+ * intended failure (ADR-CONTRACTS-160).
+ *
+ * MIRRORED, WITH ONE DECLARED LEAD. `mentions` lands HERE FIRST by the
+ * contracts-first protocol of ADR-CONT-029: the schema ships, the backend route
+ * registry adopts it, then `openapi/backend.yaml` and the generated
+ * `components["schemas"]` view in `../api` catch up. Until then `../api` still
+ * describes a chat message without mentions, 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. This paragraph is the whole record of it, and it
+ * comes out when the spec agrees.
+ */
 export const ChatMessageSchema = z.object({
   id: z.string(),
   role: z.enum(["user", "assistant"]),
@@ -240,6 +300,7 @@ export const ChatMessageSchema = z.object({
   parts: z.array(z.unknown()).optional(),
   sequenceNumber: z.number().int(),
   createdAt: IsoDateTime,
+  mentions: z.array(ChatMessageMentionSchema),
 });
 
 // =============================================================================
@@ -357,6 +418,27 @@ export const GetChatResponseSchema = z.object({
   messages: z.array(ChatMessageSchema),
 });
 
+/**
+ * Who the chat composer may offer as a mention target.
+ *
+ * REUSES `MentionableCandidateSchema` from `../comments/schemas` rather than
+ * declaring a chat-shaped twin. A candidate is a principal, a display name and
+ * an avatar on both surfaces, and the reasons that shape carries no email and no
+ * access level hold here identically: it is a picker, not an
+ * access-inspection surface, so returning the band each candidate holds would
+ * turn an autocomplete into a way to enumerate who can do what.
+ *
+ * The ENVELOPE is separate from `MentionableResponseSchema` only because the two
+ * endpoints are separate and may diverge in what rides beside `items` — the item
+ * shape itself is one definition, imported, never copied.
+ *
+ * WHO IS IN THE SET is the server's decision and a client cannot widen it: the
+ * candidates are the chat's participants plus the agent, derived server-side.
+ */
+export const ChatMentionableResponseSchema = z.object({
+  items: z.array(MentionableCandidateSchema),
+});
+
 // =============================================================================
 // Page Context (request-side: where the reader is, as identifiers)
 // =============================================================================

package/src/chat/types.ts

@@ -37,6 +37,8 @@ import {
   ListSharesResponseSchema,
   UpdateShareResponseSchema,
   ChatMessageSchema,
+  ChatMessageMentionSchema,
+  ChatMentionableResponseSchema,
   ChatDetailSchema,
   GetChatResponseSchema,
   ChatPageContextSchema,
@@ -291,6 +293,17 @@ export type UpdateShareResponse = z.infer<typeof UpdateShareResponseSchema>;
 /** Individual message in a chat response (GET /api/chats/:id). */
 export type ChatMessage = z.infer<typeof ChatMessageSchema>;
 
+/**
+ * One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16
+ * code-unit range into `content`, and a read-time display name.
+ */
+export type ChatMessageMention = z.infer<typeof ChatMessageMentionSchema>;
+
+/** Response for the chat composer's mentionable-candidate endpoint. */
+export type ChatMentionableResponse = z.infer<
+  typeof ChatMentionableResponseSchema
+>;
+
 /** Chat detail object in GET /api/chats/:id — includes interactionId for append-on-edit flows. */
 export type ChatDetail = z.infer<typeof ChatDetailSchema>;
 

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