@company-semantics/contracts 62.11.0 → 63.0.0

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>