@company-semantics/contracts 62.11.0 → 63.0.0

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 -->
 

package/src/identity/__tests__/agent.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  AGENT_PRINCIPAL,
+  CS_AGENT,
+  CS_AGENT_HANDLE,
+  PrincipalRefSchema,
+  isAgentPrincipal,
+  principalKey,
+  userPrincipal,
+} from "../agent.js";
+
+const USER_ID = "33333333-3333-4333-8333-333333333333";
+
+describe("CS_AGENT", () => {
+  // The point of the constant: the renderers derive the glyph rather than
+  // retyping it, so this assertion is what keeps them honest.
+  it("the glyph is derived from the handle", () => {
+    expect(CS_AGENT.glyph).toBe(`[${CS_AGENT.handle}]`);
+  });
+
+  it("names the agent once — handle, displayName and the constant agree", () => {
+    expect(CS_AGENT.handle).toBe(CS_AGENT_HANDLE);
+    expect(CS_AGENT.displayName).toBe(CS_AGENT_HANDLE);
+  });
+});
+
+describe("PrincipalRefSchema", () => {
+  it("accepts the agent arm with no id", () => {
+    expect(PrincipalRefSchema.parse({ kind: "agent" })).toEqual({
+      kind: "agent",
+    });
+  });
+
+  it("accepts a user arm carrying a userId", () => {
+    expect(PrincipalRefSchema.parse({ kind: "user", userId: USER_ID })).toEqual(
+      {
+        kind: "user",
+        userId: USER_ID,
+      },
+    );
+  });
+
+  // Strict, not stripping: a stray userId on an agent ref means the caller
+  // believes the agent has a users row. Refuse rather than silently drop it.
+  it("an agent ref rejects a userId", () => {
+    expect(
+      PrincipalRefSchema.safeParse({ kind: "agent", userId: "x" }).success,
+    ).toBe(false);
+  });
+
+  it("a user ref requires a userId", () => {
+    expect(PrincipalRefSchema.safeParse({ kind: "user" }).success).toBe(false);
+  });
+
+  it("rejects an unknown kind", () => {
+    expect(PrincipalRefSchema.safeParse({ kind: "system" }).success).toBe(
+      false,
+    );
+  });
+
+  // Mirrors the comments boundary rather than the uuid-tight rest of this
+  // domain: tightening here would reject ids the server considers valid.
+  it("does not require the userId to be a uuid", () => {
+    expect(
+      PrincipalRefSchema.safeParse({ kind: "user", userId: "u_1" }).success,
+    ).toBe(true);
+  });
+});
+
+describe("principal helpers", () => {
+  it("AGENT_PRINCIPAL parses as the agent arm", () => {
+    expect(PrincipalRefSchema.parse(AGENT_PRINCIPAL)).toEqual({
+      kind: "agent",
+    });
+  });
+
+  it("userPrincipal builds a parseable user ref", () => {
+    expect(PrincipalRefSchema.parse(userPrincipal(USER_ID))).toEqual({
+      kind: "user",
+      userId: USER_ID,
+    });
+  });
+
+  it("isAgentPrincipal narrows the agent arm only", () => {
+    expect(isAgentPrincipal(AGENT_PRINCIPAL)).toBe(true);
+    expect(isAgentPrincipal(userPrincipal(USER_ID))).toBe(false);
+  });
+
+  it("principalKey is stable and cannot collide across arms", () => {
+    expect(principalKey(AGENT_PRINCIPAL)).toBe("agent");
+    expect(principalKey(userPrincipal(USER_ID))).toBe(`user:${USER_ID}`);
+    expect(new Set([principalKey(AGENT_PRINCIPAL), "agent"]).size).toBe(1);
+  });
+});