@company-semantics/contracts 62.11.0 → 63.1.0

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);
+  });
+});

package/src/identity/agent.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+/**
+ * THE AGENT PRINCIPAL (control INVARIANTS.md, INV-AGENT-IDENTITY).
+ *
+ * One identity constant. The glyph is DERIVED from the handle so this package
+ * carries exactly one literal; the ASCII/email renderers and the app's avatar
+ * read it from here, never retype it.
+ *
+ * SINGLETON, BY DECISION: `{ kind: 'agent' }` carries no id because there is
+ * exactly one agent principal, forever. A second agent is a new decision and a
+ * MAJOR that adds `agentId`; nothing is pre-added now (ADR-CONTRACTS-160).
+ *
+ * NOT the ACL `Principal` in src/permissions/share-api.ts. That one names a
+ * GRANTEE on a share (user | unit | org, discriminated by `type`); this one
+ * names WHO authored an utterance or was mentioned in one (user | agent,
+ * discriminated by `kind`). Different axis — do not conflate or extend either
+ * into the other.
+ *
+ * `userId` is a bare `z.string()`, not `.uuid()`, deliberately diverging from
+ * the rest of this domain (Person, IdentityLink and PositionRef are all
+ * uuid-tight). It mirrors the comments boundary, where the shapes in this
+ * package mirror the backend's looseness rather than tightening past it:
+ * a ref that rejects an id the server considers valid is a client-side outage
+ * for no security gain. Do not "fix" this to `.uuid()`.
+ *
+ * Zero-dependency (zod only): every domain that speaks principals imports this
+ * module, so it must never import one of them back.
+ */
+export const CS_AGENT_HANDLE = "c_S" as const;
+
+/**
+ * The agent's identity, in the three forms a surface needs: the handle a
+ * mention is typed as, the name a chip renders, and the glyph a monospace or
+ * plain-text surface draws. `glyph` is a template over the handle — the single
+ * point of truth the renderers derive from.
+ */
+export const CS_AGENT = {
+  handle: CS_AGENT_HANDLE,
+  displayName: CS_AGENT_HANDLE,
+  glyph: `[${CS_AGENT_HANDLE}]`,
+} as const;
+
+/**
+ * A principal: a person by id, or the one agent.
+ *
+ * STRICT on both arms, following the comment-anchor precedent: the failure
+ * modes worth having are real refusals, not silent coercions. A non-strict
+ * object would STRIP a stray `userId` off an agent ref and hand the caller a
+ * ref that parsed cleanly while meaning something it did not say.
+ */
+export const PrincipalRefSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("user"), userId: z.string() }),
+  z.strictObject({ kind: z.literal("agent") }),
+]);
+export type PrincipalRef = z.infer<typeof PrincipalRefSchema>;
+
+/** The one agent principal. There is no second value of this shape. */
+export const AGENT_PRINCIPAL: PrincipalRef = { kind: "agent" };
+
+/** A person as a principal. */
+export function userPrincipal(userId: string): PrincipalRef {
+  return { kind: "user", userId };
+}
+
+/** Narrows a ref to the agent arm. */
+export function isAgentPrincipal(ref: PrincipalRef): ref is { kind: "agent" } {
+  return ref.kind === "agent";
+}
+
+/**
+ * Stable key for Set/Map use: 'agent' | 'user:<id>'.
+ *
+ * The agent needs no id to be keyable precisely because it is a singleton;
+ * `'agent'` cannot collide with `'user:<id>'` because a user key is prefixed.
+ */
+export function principalKey(ref: PrincipalRef): string {
+  return ref.kind === "agent" ? "agent" : `user:${ref.userId}`;
+}

package/src/identity/index.ts

@@ -94,3 +94,17 @@ export type { Person } from "./person";
 // Identity Link — external system id → Person (provider is an open string)
 export { IdentityLinkSchema } from "./identity-link";
 export type { IdentityLink } from "./identity-link";
+
+// Agent Principal — CS_AGENT (the one identity constant, glyph derived from the
+// handle) and PrincipalRef, the only vocabulary for an author, a mention target
+// or a picker candidate (ADR-CONTRACTS-160, INV-AGENT-IDENTITY).
+export {
+  CS_AGENT,
+  CS_AGENT_HANDLE,
+  PrincipalRefSchema,
+  AGENT_PRINCIPAL,
+  userPrincipal,
+  isAgentPrincipal,
+  principalKey,
+} from "./agent";
+export type { PrincipalRef } from "./agent";

package/src/index.ts

@@ -204,6 +204,20 @@ export type { Person } from "./identity/index";
 export { IdentityLinkSchema } from "./identity/index";
 export type { IdentityLink } from "./identity/index";
 
+// Agent Principal — CS_AGENT and PrincipalRef (ADR-CONTRACTS-160).
+// Not the ACL `Principal` in src/permissions: that names a share grantee, this
+// names who authored an utterance or was mentioned in one.
+export {
+  CS_AGENT,
+  CS_AGENT_HANDLE,
+  PrincipalRefSchema,
+  AGENT_PRINCIPAL,
+  userPrincipal,
+  isAgentPrincipal,
+  principalKey,
+} from "./identity/index";
+export type { PrincipalRef } from "./identity/index";
+
 // Auth domain types
 export type { AuthStartMode, AuthStartResponse } from "./auth/index";
 export { OTPErrorCode } from "./auth/index";
@@ -469,6 +483,8 @@ export {
 export type { SuggestionReceipt } from "./comments/index";
 
 export {
+  AGENT_OUTCOME_REASONS,
+  AgentOutcomeSchema,
   CommentAnchorSchema,
   CommentAnchorTypeSchema,
   CommentMentionSchema,
@@ -481,9 +497,11 @@ export {
   MentionableCandidateSchema,
   MentionableResponseSchema,
   SuggestionSchema,
+  ThreadOriginSchema,
 } from "./comments/index";
 
 export type {
+  AgentOutcome,
   CommentAnchor,
   CommentAnchorType,
   CommentMention,
@@ -499,6 +517,7 @@ export type {
   Suggestion,
   SuggestionOp,
   SuggestionStatus,
+  ThreadOrigin,
 } from "./comments/index";
 
 // Chat domain types
@@ -544,6 +563,11 @@ export type {
   // Page context (PRD-00969, ADR-CONTRACTS-153): where the reader is, as
   // identifiers. Never content, never free text.
   ChatPageContext,
+  // Chat mentions (ADR-CONTRACTS-160): a turn's mention rows are keyed on a
+  // PrincipalRef, so the agent is nameable on the chat surface too, and the
+  // composer's candidate list reuses the comments candidate shape.
+  ChatMessageMention,
+  ChatMentionableResponse,
 } from "./chat/index";
 
 export {
@@ -559,6 +583,11 @@ export {
   // older client reject the whole chat list; this is the ONE place it becomes
   // a ProactiveEventKind. See src/chat/proactive-kind.ts.
   recognizeProactiveKind,
+  // Chat mentions: the mention row a turn carries, and the composer's
+  // candidate envelope (items are `MentionableCandidateSchema`, imported from
+  // comments rather than restated).
+  ChatMessageMentionSchema,
+  ChatMentionableResponseSchema,
 } from "./chat/index";
 
 // Organization domain types

package/src/notifications/renderers/ascii/README.md

@@ -71,5 +71,11 @@ looking for it again with a regex. That is the hack this shape exists to prevent
 
 - `../../content` — `CallToAction`, `ChatTurn`, `ChatUnitItem`. Types only; this
   layer reads the vocabulary and never extends it.
+- `../../../identity/agent` — `CS_AGENT`, for `AVATAR` alone. The agent has one
+  identity and the glyph is DERIVED from it rather than retyped here
+  (INV-AGENT-IDENTITY); a second copy is how the drawing and the chip quietly
+  drift apart. It is a value rather than a type, and it brings `zod` into this
+  layer's transitive imports for the first time — the price of one source of
+  truth, and cheap, because `zod` is already a dependency of the package.
 
 Nothing else. It knows no channel, no colour, no markup and no `Renderer`.

package/src/notifications/renderers/ascii/geometry.ts

@@ -23,8 +23,17 @@
  * promise we are willing to keep.
  */
 
-/** The assistant's avatar, drawn beside the last line of its bubble. */
-export const AVATAR = "[c_S]";
+import { CS_AGENT } from "../../../identity/agent";
+
+/**
+ * The assistant's avatar, drawn beside the last line of its bubble.
+ *
+ * DERIVED from `CS_AGENT.glyph`, never retyped (INV-AGENT-IDENTITY): the agent
+ * has one identity and this layer reads it rather than restating it. Its LENGTH
+ * feeds `indent` below and therefore every box width in this directory — so a
+ * change to the handle re-flows the drawing, which is the intended coupling.
+ */
+export const AVATAR = CS_AGENT.glyph;
 
 /** The recipient's avatar, drawn beside the last line of their bubble. */
 export const KAOMOJI = "(•̀_ರ╮)";

package/src/notifications/renderers/email/chat.ts

@@ -21,6 +21,7 @@
  *   through it.
  */
 
+import { CS_AGENT } from "../../../identity/agent";
 import type { CallToAction, ChatTurn, ChatUnitItem } from "../../content";
 import {
   ruleAscii,
@@ -95,7 +96,7 @@ function renderBubble(turn: ChatTurn, row: ChatRow): ChatPartRender {
 
   const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass(row)}>
   <tr>
-    <td ${styleClass(avatar)}>[c_S]</td>
+    <td ${styleClass(avatar)}>${CS_AGENT.glyph}</td>
     <td ${styleClass(channel)}><table cellpadding="0" cellspacing="0" border="0" ${styleClass("chat-bubble-wrap")}>
       <tr><td ${styleClass(bubble, "bubble")}>${escapeHtml(clamped)}</td></tr>
     </table></td>
@@ -130,7 +131,7 @@ function renderChatCta(
   const stack = `<div ${styleClass("cta-stack")}>${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
   const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-24")}>
   <tr>
-    <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
+    <td ${styleClass("chat-avatar-left-hidden")}>${CS_AGENT.glyph}</td>
     <td ${styleClass(`chat-channel-${align}`)}>${stack}</td>
     <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>
@@ -150,7 +151,7 @@ function renderChatCta(
 function renderChatDots(): ChatPartRender {
   const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" ${styleClass("chat-row-16")}>
   <tr>
-    <td ${styleClass("chat-avatar-left-hidden")}>[c_S]</td>
+    <td ${styleClass("chat-avatar-left-hidden")}>${CS_AGENT.glyph}</td>
     <td ${styleClass("dots-cell", "dots")}>⋮</td>
     <td ${styleClass("chat-avatar-right-hidden")}>(•̀_ರ╮)</td>
   </tr>