@company-semantics/contracts 45.2.0 → 45.3.0

package/src/notifications/__tests__/definition.test.ts

@@ -110,10 +110,11 @@ describe("compose reads ambient state from the context", () => {
       brand: { name: "Umbrella Corp", copyrightYear: 2026 },
     });
 
-    // Ten of the eleven kinds footer "sent via <brand>"; security.alert has no
-    // notice at all, on purpose.
+    // Every kind but ONE footers "sent via <brand>"; security.alert has no
+    // notice at all, on purpose. The literal count is the tripwire: a kind
+    // added without a branded notice lands here rather than in production.
     const branded = KINDS.filter((kind) => kind !== "security.alert");
-    expect(branded).toHaveLength(10);
+    expect(branded).toHaveLength(12);
 
     for (const kind of branded) {
       const notices = elementsOf(compose(kind, context)).filter(

package/src/notifications/__tests__/fixtures.ts

@@ -238,5 +238,39 @@ add("companyMd.access_request_denied", "No reason", {
   docTitle: "Engineering Handbook",
 });
 
+// Both comment kinds vary on the SAME axis — whether the thread is anchored to
+// a passage — because that is the only branch either `compose` has.
+add("comment.mention", "Text-anchored", {
+  actorName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  subjectTitle: "Engineering Handbook",
+  quotedText: "ship the quarterly goals",
+  commentExcerpt:
+    "Should this say Q3 or Q4? @Sam Chen you owned this last time.",
+  threadUrl: `${APP}/doc/handbook?thread=th_123`,
+});
+add("comment.mention", "Document-level", {
+  actorName: "Jordan Lee",
+  subjectTitle: "Engineering Handbook",
+  commentExcerpt:
+    "Adding @Sam Chen — this whole doc needs a pass before Friday.",
+  threadUrl: `${APP}/doc/handbook?thread=th_456`,
+});
+
+add("comment.reply", "Text-anchored", {
+  actorName: "Alex Rivera",
+  recipientName: "Sam Chen",
+  subjectTitle: "Engineering Handbook",
+  quotedText: "ship the quarterly goals",
+  commentExcerpt: "Q4 — we moved it at the last planning session.",
+  threadUrl: `${APP}/doc/handbook?thread=th_123`,
+});
+add("comment.reply", "Document-level", {
+  actorName: "Alex Rivera",
+  subjectTitle: "Engineering Handbook",
+  commentExcerpt: "Started on the onboarding section.",
+  threadUrl: `${APP}/doc/handbook?thread=th_456`,
+});
+
 /** The corpus — every implemented kind × representative variants. */
 export const NOTIFICATION_FIXTURES: readonly NotificationFixture[] = fixtures;

package/src/notifications/__tests__/kinds.test.ts

@@ -1,7 +1,10 @@
 /**
- * `NotificationKind` is the migration's central claim: that the eleven things
- * the email layer could actually SAY are notifications, not emails
- * (ADR-CONTRACTS-085).
+ * `NotificationKind` is the migration's central claim: that the things the
+ * email layer could actually SAY are notifications, not emails
+ * (ADR-CONTRACTS-085). It has grown since — `comment.mention` and
+ * `comment.reply` joined with ADR-CONTRACTS-116 — which is the ordinary way
+ * this union changes and exactly what the frozen list below is here to make
+ * visible.
  *
  * WHAT THESE TESTS USED TO DO, AND WHY THEY NO LONGER DO IT. Membership was
  * asserted against `IMPLEMENTED_EMAIL_KINDS`, and the union's deliberate
@@ -49,15 +52,19 @@ const ALL_NOTIFICATION_KINDS: Record<NotificationKind, true> = {
   "companyMd.access_requested": true,
   "companyMd.access_request_approved": true,
   "companyMd.access_request_denied": true,
+  "comment.mention": true,
+  "comment.reply": true,
 };
 
 const KINDS = Object.keys(ALL_NOTIFICATION_KINDS).sort();
 
 describe("NotificationKind", () => {
-  it("has exactly the eleven kinds with something to say", () => {
+  it("has exactly the kinds with something to say", () => {
     expect(KINDS).toEqual([
       "auth.otp",
       "chat.shared",
+      "comment.mention",
+      "comment.reply",
       "companyMd.access_request_approved",
       "companyMd.access_request_denied",
       "companyMd.access_requested",

package/src/notifications/__tests__/registry.test.ts

@@ -9,9 +9,9 @@
  * The new one is TOTALITY. `getEmailKindDefinition` could hand back a definition
  * whose kind then threw at render; `getNotificationKindDefinition` cannot,
  * because a kind with no `compose` cannot reach the union. That is the whole
- * reason `NotificationKind` has eleven members where `EmailKind` had twelve, and
- * it is only true as long as every definition here actually composes — which the
- * last test checks by calling all of them rather than trusting the type.
+ * reason `NotificationKind` excluded a member `EmailKind` had, and it is only
+ * true as long as every definition here actually composes — which the last test
+ * checks by calling all of them rather than trusting the type.
  *
  * And the ABSENCES: `subject`, `plainTextRequired` and `htmlSupported` are gone.
  * Asserting a field is missing looks pedantic until someone re-adds `subject`
@@ -51,6 +51,8 @@ describe("NOTIFICATION_DEFINITIONS", () => {
     expect([...KINDS].sort()).toEqual([
       "auth.otp",
       "chat.shared",
+      "comment.mention",
+      "comment.reply",
       "companyMd.access_request_approved",
       "companyMd.access_request_denied",
       "companyMd.access_requested",
@@ -86,7 +88,7 @@ describe("NOTIFICATION_DEFINITIONS", () => {
 
   it("names no destination for any kind", () => {
     // Capability is asked of a renderer, never declared on a definition —
-    // otherwise every new surface is a rewrite of all eleven definitions.
+    // otherwise every new surface is a rewrite of every definition.
     for (const definition of Object.values(NOTIFICATION_DEFINITIONS)) {
       expect(Object.keys(definition).sort()).toEqual(["compose", "kind"]);
     }
@@ -94,7 +96,7 @@ describe("NOTIFICATION_DEFINITIONS", () => {
 
   it("composes for every kind, so the registry is total in practice and not just in type", () => {
     // The claim that makes `getNotificationKindDefinition` safe where
-    // `getEmailKindDefinition` was not. Calling all eleven is the only way to
+    // `getEmailKindDefinition` was not. Calling every one is the only way to
     // know it: a type says a `compose` exists, not that it returns content.
     for (const kind of KINDS) {
       const compose = NOTIFICATION_DEFINITIONS[kind].compose as (

package/src/notifications/__tests__/render-snapshot.test.ts

@@ -238,6 +238,42 @@ add("companyMd.access_request_denied", "No reason", {
   docTitle: "Engineering Handbook",
 });
 
+// The anchored/unanchored branch, across every channel: the `Passage` row is
+// present only when the payload carries a quote, because a document-level
+// thread is anchored to nothing in particular and an empty row would state
+// something false rather than omit something absent.
+add("comment.mention", "Text-anchored", {
+  actorName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  subjectTitle: "Engineering Handbook",
+  quotedText: "ship the quarterly goals",
+  commentExcerpt:
+    "Should this say Q3 or Q4? @Sam Chen you owned this last time.",
+  threadUrl: `${APP}/doc/handbook?thread=th_123`,
+});
+add("comment.mention", "Document-level", {
+  actorName: "Jordan Lee",
+  subjectTitle: "Engineering Handbook",
+  commentExcerpt:
+    "Adding @Sam Chen — this whole doc needs a pass before Friday.",
+  threadUrl: `${APP}/doc/handbook?thread=th_456`,
+});
+
+add("comment.reply", "Text-anchored", {
+  actorName: "Alex Rivera",
+  recipientName: "Sam Chen",
+  subjectTitle: "Engineering Handbook",
+  quotedText: "ship the quarterly goals",
+  commentExcerpt: "Q4 — we moved it at the last planning session.",
+  threadUrl: `${APP}/doc/handbook?thread=th_123`,
+});
+add("comment.reply", "Document-level", {
+  actorName: "Alex Rivera",
+  subjectTitle: "Engineering Handbook",
+  commentExcerpt: "Started on the onboarding section.",
+  threadUrl: `${APP}/doc/handbook?thread=th_456`,
+});
+
 // "email render", not "notification render": the snapshot keys are
 // `email render > {kind} · {name} 1`, and renaming the describe would orphan
 // every one of them — regenerating the whole .snap to prove nothing changed is

package/src/notifications/kinds/comment-mention.ts

@@ -0,0 +1,82 @@
+/**
+ * Comment-mention notification — sent to someone named in a comment
+ * (ADR-CONTRACTS-116).
+ *
+ * Leads with WHO named you and WHERE, because that is what decides whether the
+ * recipient opens it; the comment text follows as a reproduced turn rather than
+ * a body paragraph, so a channel that can depict a conversation depicts one.
+ *
+ * The anchored passage is shown as a key-value row and only when the payload
+ * carries it: a document-level thread is anchored to nothing in particular, and
+ * a "Passage: —" row would state something false rather than omit something
+ * absent.
+ */
+
+import type { NotificationDefinition } from "../definition";
+
+export const commentMentionDefinition: NotificationDefinition<"comment.mention"> =
+  {
+    kind: "comment.mention",
+    compose: (payload, context) => {
+      const {
+        actorName,
+        recipientName,
+        subjectTitle,
+        quotedText,
+        commentExcerpt,
+        threadUrl,
+      } = payload;
+
+      return {
+        metadata: {
+          kind: "comment.mention",
+          title: `${actorName} mentioned you in a comment`,
+        },
+        sections: [
+          {
+            elements: [
+              { type: "greeting", ...(recipientName ? { recipientName } : {}) },
+              {
+                type: "body",
+                text: `${actorName} mentioned you in a comment on "${subjectTitle}".`,
+              },
+              {
+                type: "chatUnit",
+                items: [
+                  {
+                    type: "message",
+                    role: "user",
+                    text: commentExcerpt,
+                    from: actorName,
+                  },
+                  {
+                    type: "callToAction",
+                    label: "VIEW COMMENT",
+                    href: threadUrl,
+                  },
+                ],
+              },
+              {
+                type: "keyValueTable",
+                rows: [
+                  { label: "From", value: actorName },
+                  { label: "On", value: `"${subjectTitle}"` },
+                  ...(quotedText
+                    ? [{ label: "Passage", value: `"${quotedText}"` }]
+                    : []),
+                ],
+              },
+              {
+                type: "notice",
+                lines: [
+                  `This notification was sent via ${context.brand.name}.`,
+                  "You were named in this comment.",
+                ],
+              },
+              { type: "signature" },
+            ],
+          },
+        ],
+      };
+    },
+  };

package/src/notifications/kinds/comment-reply.ts

@@ -0,0 +1,79 @@
+/**
+ * Comment-reply notification — sent to the other participants of a thread when
+ * it gets a new comment (ADR-CONTRACTS-116).
+ *
+ * Deliberately a near-twin of `./comment-mention` with a DIFFERENT closing
+ * line, and the difference is the whole point of keeping two definitions: a
+ * mention says "you were named", a reply says "a thread you took part in moved
+ * on". Collapsing them into one kind with a flag would put that editorial
+ * choice inside a conditional, where the two would slowly converge.
+ *
+ * The sender guarantees a person receives at most one of the two for any one
+ * comment; nothing here needs to know that, which is why neither payload
+ * carries the other's audience.
+ */
+
+import type { NotificationDefinition } from "../definition";
+
+export const commentReplyDefinition: NotificationDefinition<"comment.reply"> = {
+  kind: "comment.reply",
+  compose: (payload, context) => {
+    const {
+      actorName,
+      recipientName,
+      subjectTitle,
+      quotedText,
+      commentExcerpt,
+      threadUrl,
+    } = payload;
+
+    return {
+      metadata: {
+        kind: "comment.reply",
+        title: `${actorName} replied in a thread you are part of`,
+      },
+      sections: [
+        {
+          elements: [
+            { type: "greeting", ...(recipientName ? { recipientName } : {}) },
+            {
+              type: "body",
+              text: `${actorName} replied in a comment thread on "${subjectTitle}".`,
+            },
+            {
+              type: "chatUnit",
+              items: [
+                { type: "continuation" },
+                {
+                  type: "message",
+                  role: "user",
+                  text: commentExcerpt,
+                  from: actorName,
+                },
+                { type: "callToAction", label: "VIEW THREAD", href: threadUrl },
+              ],
+            },
+            {
+              type: "keyValueTable",
+              rows: [
+                { label: "From", value: actorName },
+                { label: "On", value: `"${subjectTitle}"` },
+                ...(quotedText
+                  ? [{ label: "Passage", value: `"${quotedText}"` }]
+                  : []),
+              ],
+            },
+            {
+              type: "notice",
+              lines: [
+                `This notification was sent via ${context.brand.name}.`,
+                "You are part of this thread.",
+              ],
+            },
+            { type: "signature" },
+          ],
+        },
+      ],
+    };
+  },
+};

package/src/notifications/kinds/index.ts

@@ -11,6 +11,8 @@ export { accessDeniedDefinition } from "./company-md-access-denied";
 export { accessRequestedDefinition } from "./company-md-access-requested";
 export { authOtpDefinition } from "./auth-otp";
 export { chatSharedDefinition } from "./chat-shared";
+export { commentMentionDefinition } from "./comment-mention";
+export { commentReplyDefinition } from "./comment-reply";
 export { orgInviteDefinition } from "./org-invite";
 export { ownershipTransferCompletedDefinition } from "./ownership-transfer-completed";
 export { ownershipTransferDefinition } from "./ownership-transfer";

package/src/notifications/kinds.ts

@@ -33,8 +33,9 @@
  * - domain: auth, org, security, chat, share, companyMd
  * - type: specific notification variant
  *
- * This union is exactly the kinds with a `compose` implementation — the 11 the
- * email layer could render, and deliberately NOT the 12 its `EmailKind` had.
+ * This union is exactly the kinds with a `compose` implementation — it started
+ * as the 11 the email layer could render, and deliberately NOT the 12 its
+ * `EmailKind` had.
  * `auth.magic_link` was registered with a subject but never had a template, so
  * the old `renderEmail("auth.magic_link", …)` type-checked and then threw at
  * runtime. Excluding it closes that hole by construction: a kind IS its
@@ -65,4 +66,12 @@ export type NotificationKind =
   | "share.granted"
   | "companyMd.access_requested"
   | "companyMd.access_request_approved"
-  | "companyMd.access_request_denied";
+  | "companyMd.access_request_denied"
+  // Comment activity (ADR-CONTRACTS-116). These two names also exist in
+  // `../user-notifications`'s `UserNotificationKind`, and the overlap is
+  // deliberate and already precedented by the three `companyMd.*` members
+  // above: the message that LEAVES THE BUILDING and the durable row you come
+  // back to are two different things about one event, with two lifecycles.
+  // Neither union is derived from the other.
+  | "comment.mention"
+  | "comment.reply";

package/src/notifications/payloads.ts

@@ -158,6 +158,55 @@ export interface NotificationPayloads {
      */
     message?: string;
   };
+  /**
+   * Sent to someone named in a comment (ADR-CONTRACTS-116).
+   *
+   * FACTS ONLY, AND DELIBERATELY NOT THE ANCHOR. A notification says who,
+   * where and what was written; it does not carry the machinery for placing a
+   * highlight, because a composed message has no document to place it in. The
+   * anchor's `quote` is passed as ordinary prose (`quotedText`) precisely so
+   * this layer cannot grow an opinion about anchors.
+   */
+  "comment.mention": {
+    /** Display name of the person who wrote the comment naming the recipient. */
+    actorName: string;
+    /** Display name of the recipient (optional; falls back to a neutral greeting) */
+    recipientName?: string;
+    /** Human-readable label for the thing commented on, e.g. "Engineering Handbook". */
+    subjectTitle: string;
+    /**
+     * The passage the thread is anchored to, as plain text. Absent for a
+     * document-level thread, which is anchored to nothing in particular.
+     */
+    quotedText?: string;
+    /** The comment body, already excerpted by the sender. Never the whole thread. */
+    commentExcerpt: string;
+    /** Full URL that opens the subject with this thread selected. */
+    threadUrl: string;
+  };
+  /**
+   * Sent to the other participants of a thread when it gets a new comment
+   * (ADR-CONTRACTS-116).
+   *
+   * ONE COMMENT NEVER PRODUCES TWO MESSAGES FOR ONE PERSON: a participant who
+   * was also mentioned receives `comment.mention` and not this. The sender
+   * resolves that, not `compose` — which is why the two payloads are separate
+   * shapes rather than one with a flag.
+   */
+  "comment.reply": {
+    /** Display name of the person who replied. */
+    actorName: string;
+    /** Display name of the recipient (optional; falls back to a neutral greeting) */
+    recipientName?: string;
+    /** Human-readable label for the thing commented on, e.g. "Engineering Handbook". */
+    subjectTitle: string;
+    /** The passage the thread is anchored to. Absent for a document-level thread. */
+    quotedText?: string;
+    /** The reply body, already excerpted by the sender. */
+    commentExcerpt: string;
+    /** Full URL that opens the subject with this thread selected. */
+    threadUrl: string;
+  };
   /** Sent to the requester when an owner denies (ADR-BE-338). */
   "companyMd.access_request_denied": {
     /** Display name of the owner who denied */

package/src/notifications/registry.ts

@@ -27,6 +27,8 @@ import {
   accessRequestedDefinition,
   authOtpDefinition,
   chatSharedDefinition,
+  commentMentionDefinition,
+  commentReplyDefinition,
   orgInviteDefinition,
   ownershipTransferCompletedDefinition,
   ownershipTransferDefinition,
@@ -43,8 +45,8 @@ import {
  * The registry's shape: `Record<NotificationKind, NotificationDefinition>` made
  * per-kind precise.
  *
- * A plain `Record` would widen every `compose` to accept a union of all eleven
- * payloads, and — since `compose` is an arrow property, checked contravariantly
+ * A plain `Record` would widen every `compose` to accept a union of every
+ * payload, and — since `compose` is an arrow property, checked contravariantly
  * — no real definition would be assignable to it. The mapped type keeps each
  * kind bound to its own payload, which is what a caller wants anyway.
  */
@@ -75,6 +77,8 @@ export const NOTIFICATION_DEFINITIONS: NotificationDefinitions = {
   "companyMd.access_requested": accessRequestedDefinition,
   "companyMd.access_request_approved": accessApprovedDefinition,
   "companyMd.access_request_denied": accessDeniedDefinition,
+  "comment.mention": commentMentionDefinition,
+  "comment.reply": commentReplyDefinition,
 };
 
 // =============================================================================

package/src/resource-keys.ts

@@ -29,6 +29,27 @@ export type ResourceKey =
   // a bare slug does not identify a document. That field name is a wart to be
   // contained, not propagated — a new key gets the honest name.
   | { type: "companyMdAccessRequests"; orgId: string; docId: string }
+  // The comment threads hanging off ONE subject (ADR-CONTRACTS-116).
+  //
+  // Registered here rather than declared app-locally because THE KEY REGISTRY IS
+  // THE SSE COALESCER'S VOCABULARY: a `resource.invalidated` frame names a key,
+  // and a key the registry does not know cannot be routed through the coalescer
+  // at all. An app-local "commentThreads" would be a second vocabulary the
+  // server could never address.
+  //
+  // The only member with a TWO-SEGMENT identity, and it has to be: a thread
+  // list is addressed by (subjectType, subjectId), and the id alone is not
+  // enough — subject ids are per-class uuids, so two classes could collide and
+  // one subject's invalidation would flush another's cache. `subjectType` is
+  // typed `string` and not the closed `CommentSubjectType`: this is a cache
+  // vocabulary, `fromQueryKey` reconstructs keys from arbitrary wire strings,
+  // and narrowing it here would make that reconstruction a lie.
+  | {
+      type: "commentThreads";
+      orgId: string;
+      subjectType: string;
+      subjectId: string;
+    }
   | { type: "workspace"; orgId: string }
   | { type: "workspaceDomains"; orgId: string }
   | { type: "authSettings"; orgId: string }
@@ -180,6 +201,12 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "companyMdAccessRequests":
       return [key.type, key.orgId, key.docId] as const;
 
+    // Composite identity — subject CLASS then subject id, in that order, so the
+    // two segments read the same way round as the query string that produced
+    // them.
+    case "commentThreads":
+      return [key.type, key.orgId, key.subjectType, key.subjectId] as const;
+
     // OrgUnit identity keys (ADR-BE-120)
     case "orgUnit":
     case "orgUnitChildren":
@@ -250,6 +277,33 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     );
   }
 
+  // Identities with a COMPOSITE (multi-segment) identity. Checked before the
+  // single-field map below, which hard-asserts a two-element `rest` and would
+  // otherwise reject these.
+  //
+  // A map of its own rather than a widening of `identityFields` to a
+  // `string | string[]`: the single-segment case is every other key in the
+  // union, and making it pay for this one would put a branch in the hot path
+  // for no reader's benefit.
+  const compositeIdentityFields: Record<string, readonly string[]> = {
+    commentThreads: ["subjectType", "subjectId"],
+  };
+
+  const compositeFields = compositeIdentityFields[type];
+  if (compositeFields) {
+    // +1 for the orgId that leads every composite key.
+    if (rest.length !== compositeFields.length + 1) {
+      throw new Error(
+        `Invalid query key for '${type}': expected [type, orgId, ${compositeFields.join(", ")}], got ${JSON.stringify(queryKey)}`,
+      );
+    }
+    const key: Record<string, string> = { type, orgId: rest[0] };
+    compositeFields.forEach((field, index) => {
+      key[field] = rest[index + 1];
+    });
+    return key as ResourceKey;
+  }
+
   // Identities with extra field
   const identityFields: Record<string, string> = {
     member: "memberId",
@@ -370,6 +424,20 @@ export function matchesResourceKey(
     parsed.unitId !== targetKey.unitId
   )
     return false;
+  // Both halves of a composite identity, or a comment thread list on one
+  // subject would be invalidated by every other subject in the org.
+  if (
+    "subjectType" in parsed &&
+    "subjectType" in targetKey &&
+    parsed.subjectType !== targetKey.subjectType
+  )
+    return false;
+  if (
+    "subjectId" in parsed &&
+    "subjectId" in targetKey &&
+    parsed.subjectId !== targetKey.subjectId
+  )
+    return false;
   if (
     "scope" in parsed &&
     "scope" in targetKey &&

package/src/user-notifications/kinds.ts

@@ -51,7 +51,7 @@
  *    domain's own authority gate in bulk and returns a tombstone when the
  *    reader may no longer see the referenced entity
  *
- * The three members below are the informational half of the company.md
+ * The first three members are the informational half of the company.md
  * request-access lifecycle. Note what is NOT here:
  * `companyMd.access_request_pending` is an ACTION ITEM — the owner can resolve
  * it, so it is standing state, and modelling it here as well would give one
@@ -64,6 +64,18 @@ export const USER_NOTIFICATION_KINDS = [
   "companyMd.access_request_approved",
   /** Your request was declined. */
   "companyMd.access_request_denied",
+  /**
+   * You were named in a comment (ADR-CONTRACTS-116).
+   *
+   * A fact you can only look at, so it belongs here and not in `ActionItemKind`
+   * — being mentioned asks nothing of you that a system can call resolved. The
+   * producing domain emits at most ONE row per person per comment: a mentioned
+   * participant gets this and NOT `comment.reply`, because the mention is the
+   * more specific fact and the one they were addressed by.
+   */
+  "comment.mention",
+  /** A thread you took part in got a new comment. Never emitted for an edit. */
+  "comment.reply",
 ] as const;
 
 export type UserNotificationKind = (typeof USER_NOTIFICATION_KINDS)[number];