@company-semantics/contracts 58.1.0 → 58.2.0

package/package.json

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

package/src/__tests__/resource-keys.test.ts

@@ -80,6 +80,36 @@ describe("resource-keys: directGrants (org-scoped)", () => {
   });
 });
 
+describe("resource-keys: orgSystemEvents (org-scoped)", () => {
+  // The banner strip's invalidation key (PRD-00958). Registered in contracts
+  // rather than the app's AppOnlyKey union because the SERVER publishes it over
+  // the user-event stream — and a key the registry does not know cannot be
+  // routed through the SSE coalescer at all.
+  const key: ResourceKey = { type: "orgSystemEvents", orgId: ORG_ID };
+
+  it("toQueryKey produces [type, orgId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["orgSystemEvents", ORG_ID]);
+    expect(qk).toHaveLength(2);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("is recognised by isResourceKeyShape", () => {
+    // The wire-boundary predicate that gates `resource.invalidated` frames; a
+    // key it rejects never reaches the coalescer, so the banner never refreshes.
+    expect(isResourceKeyShape(key)).toBe(true);
+  });
+
+  it("matchesResourceKey is org-scoped: rejects a different orgId", () => {
+    const other = "22222222-2222-4222-8222-222222222222";
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(["orgSystemEvents", other], key)).toBe(false);
+  });
+});
+
 describe("resource-keys: orgUnitMyAuthority (per-unit identity)", () => {
   const UNIT_ID = "33333333-3333-4333-8333-333333333333";
   const key: ResourceKey = {

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 = '49b741e4372d' as const;
-export const SPEC_HASH_FULL = '49b741e4372d56fb1a87312fe62f6e86ffd4987de590d03414ee833a4b6586b0' as const;
+export const SPEC_HASH = 'a69faedfed8f' as const;
+export const SPEC_HASH_FULL = 'a69faedfed8f36af0b36dc657e4f5b2c4e90c137e0f48823debd5578c433c77a' as const;

package/src/api/generated.ts

@@ -3994,7 +3994,12 @@ export interface components {
                 pinnedAt: string | null;
                 titleSource: ("auto" | "manual") | null;
                 titleGeneratedAt: string | null;
+                /** @enum {string} */
+                origin?: "user" | "proactive";
+                unread?: boolean;
+                proactiveKind?: string | null;
             }[];
+            unreadCount?: number;
         };
         CreateChatResponse: {
             chat: {
@@ -4009,6 +4014,10 @@ export interface components {
                 pinnedAt: string | null;
                 titleSource: ("auto" | "manual") | null;
                 titleGeneratedAt: string | null;
+                /** @enum {string} */
+                origin?: "user" | "proactive";
+                unread?: boolean;
+                proactiveKind?: string | null;
             };
         };
         CreateChatRequest: {
@@ -4036,6 +4045,9 @@ export interface components {
                 createdAt: string;
                 /** Format: date-time */
                 updatedAt: string;
+                /** @enum {string} */
+                origin?: "user" | "proactive";
+                unread?: boolean;
             };
             messages: {
                 id: string;
@@ -4166,6 +4178,10 @@ export interface components {
                 /** Format: date-time */
                 updatedAt: string;
                 isShared: boolean;
+                /** @enum {string} */
+                origin?: "user" | "proactive";
+                unread?: boolean;
+                proactiveKind?: string | null;
             };
         } | {
             /** @constant */
@@ -4187,6 +4203,10 @@ export interface components {
                 /** Format: date-time */
                 updatedAt: string;
                 isShared: boolean;
+                /** @enum {string} */
+                origin?: "user" | "proactive";
+                unread?: boolean;
+                proactiveKind?: string | null;
             };
             changed: ("title" | "titleSource" | "pinnedAt")[];
         } | {
@@ -6232,7 +6252,7 @@ export interface components {
                 notification: {
                     id: string;
                     /** @enum {string} */
-                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply";
+                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "proactive.org_became_shared" | "proactive.brief_morning";
                     target: {
                         /** @enum {string} */
                         type: "company_md" | "org_unit" | "org" | "execution";

package/src/chat/README.md

@@ -12,6 +12,11 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - Invalidation events ensure convergence after SSE disconnects
 - Runtime profile labels are vendor-agnostic (no model names in UI)
 - Default runtime profile is `agentic`
+- The proactive wire fields (`origin`, `unread`, `proactiveKind`) ride the extended summary AND both chat SSE event payloads — the app builds a sidebar row from event data alone, so a field missing from an event schema means every pushed chat arrives silently read (PRD-00958, ADR-CONTRACTS-142)
+- `unread` is a ONE-TIME proactive badge, cleared permanently on open; ordinary conversation never sets it again
+- `proactiveKind` is a bare string on the wire so a newly shipped kind cannot make an older client reject the whole chat list; it becomes a `ProactiveEventKind` exactly once, at the edge, via `recognizeProactiveKind`
+- `unreadCount` on the GET /api/chats envelope is the total across all the reader's chats, never derived from the returned page (app ADR slug `feed-mark-on-open-and-paging`)
+- `ProactiveChatResolution` has four bounded states (`ready` / `pending` / `unavailable` / `ineligible`) — never an open-ended "preparing"
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
@@ -25,7 +30,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatChangedField` _(type)_ — Fields that can change on a chat, used in changed array.
 - `ChatChangedFieldSchema`
 - `ChatCreatedEvent` _(type)_ — Emitted exactly once after a chat is successfully persisted.
-- `ChatCreatedEventSchema`
+- `ChatCreatedEventSchema` — Emitted exactly once after a chat is persisted; a pushed proactive chat is announced over this event too.
 - `ChatDeletedEvent` _(type)_ — Emitted when a chat is deleted.
 - `ChatDeletedEventSchema`
 - `ChatDetail` _(type)_ — Chat detail object in GET /api/chats/:id — includes interactionId for append-on-edit flows.
@@ -36,9 +41,11 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatInvalidationEventSchema`
 - `ChatListFilters` _(type)_ — Filters for listing chats.
 - `ChatListResponse` _(type)_ — Response for GET /api/chats
-- `ChatListResponseSchema` — Response for GET /api/chats
+- `ChatListResponseSchema` — Response for GET /api/chats.
 - `ChatMessage` _(type)_ — Individual message in a chat response (GET /api/chats/:id).
 - `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…
 - `ChatRuntimeProfile` _(type)_ — Chat runtime profile — user-selectable orchestration strategy.
 - `ChatRuntimeProfileInfo` _(type)_ — Runtime profile metadata for UI rendering.
 - `ChatShareInfo` _(type)_ — Chat share record with snapshot metadata.
@@ -48,7 +55,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatSuccessResponse` _(type)_ — Generic mutation success confirmation.
 - `ChatSuccessResponseSchema` — Generic success confirmation for mutations that return no entity data.
 - `ChatSummary` _(type)_ — Lightweight chat summary for list views.
-- `ChatSummaryExtended` _(type)_ — Extended chat summary with pin/title status.
+- `ChatSummaryExtended` _(type)_ — Extended chat summary with pin/title status, plus the optional proactive wire fields (`origin`, `unread`…
 - `ChatSummaryExtendedSchema`
 - `ChatSummarySchema`
 - `ChatUpdatedEvent` _(type)_ — Emitted when chat metadata changes (title, pin, etc.) Carries full current state - clients should replace…
@@ -72,6 +79,9 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `IsoDateString` — ISO 8601 datetime string — the runtime safety net for date serialization.
 - `ListSharesResponse` _(type)_ — Response for GET /api/chats/:chatId/shares
 - `ListSharesResponseSchema` — Response for GET /api/chats/:chatId/shares
+- `ProactiveChatResolution` _(type)_ — Resolving an occurrence id to the CURRENT reader's chat — one of the four bounded states `ready` (with…
+- `ProactiveChatResolutionSchema` — Resolving an occurrence id to THIS reader's chat (INV-PROACTIVE-LINK).
+- `RecognizedProactiveKind` _(type)_ — A wire `proactiveKind` after recognition: a kind this contracts version knows, or the raw string it did not —…
 - `SharedChatMessage` _(type)_ — Individual message in a shared chat view.
 - `SharedChatMessageSchema`
 - `SharedChatView` _(type)_ — Shared chat view returned to viewers.
@@ -84,6 +94,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `UpdateShareRequest` _(type)_ — Request to update an existing share.
 - `UpdateShareResponse` _(type)_ — Response for PATCH /api/shares/:shareId
 - `UpdateShareResponseSchema` — Response for PATCH /api/shares/:shareId
+- `recognizeProactiveKind` — Recognize a wire `proactiveKind`.
 
 <!-- END GENERATED: readme-public-api -->
 
@@ -93,7 +104,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 
 **Internal domains:**
 
-_None._
+- `proactive`
 
 **External packages:**
 

package/src/chat/__tests__/proactive-kind.test.ts

@@ -0,0 +1,51 @@
+/**
+ * recognizeProactiveKind — the ONE conversion from the wire-lenient
+ * `proactiveKind` string to a ProactiveEventKind (PRD-00958).
+ *
+ * The wire schema accepts any string so a new kind cannot make an older
+ * client reject the whole chat list; these tests pin that the looseness stops
+ * here, and that "not proactive" and "proactive but unknown" never collapse.
+ */
+import { describe, expect, it } from "vitest";
+import { PROACTIVE_EVENT_KIND_IDS } from "../../proactive/kinds.js";
+import { recognizeProactiveKind } from "../proactive-kind.js";
+
+describe("recognizeProactiveKind", () => {
+  it("returns null for an absent kind (a user-born chat)", () => {
+    expect(recognizeProactiveKind(null)).toBeNull();
+    expect(recognizeProactiveKind(undefined)).toBeNull();
+    expect(recognizeProactiveKind("")).toBeNull();
+  });
+
+  it("recognizes every member of PROACTIVE_EVENT_KIND_IDS as itself", () => {
+    // Total over the vocabulary: a kind added to ../proactive/kinds is
+    // recognized here with no edit, because there is no second list to drift.
+    for (const kind of PROACTIVE_EVENT_KIND_IDS) {
+      expect(recognizeProactiveKind(kind)).toBe(kind);
+    }
+  });
+
+  it("carries an unknown kind as { unknown } rather than dropping it", () => {
+    // Distinct from null: a pushed chat of a kind this version has not learned
+    // must still render as a (generic) proactive chat, never as a user chat.
+    expect(recognizeProactiveKind("future.kind_not_in_this_version")).toEqual({
+      unknown: "future.kind_not_in_this_version",
+    });
+  });
+
+  it("does not recognize an inbox kind string as an event kind", () => {
+    // The inbox kind (`proactive.org_became_shared`) is DELIBERATELY distinct
+    // from the event kind (`org.became_shared`); recognition must not blur
+    // the two unions.
+    expect(recognizeProactiveKind("proactive.org_became_shared")).toEqual({
+      unknown: "proactive.org_became_shared",
+    });
+  });
+
+  it("is pure: the same input yields the same result across calls", () => {
+    expect(recognizeProactiveKind("org.became_shared")).toBe(
+      recognizeProactiveKind("org.became_shared"),
+    );
+    expect(recognizeProactiveKind("x")).toEqual(recognizeProactiveKind("x"));
+  });
+});

package/src/chat/index.ts

@@ -20,9 +20,12 @@ export type {
   // Chat lifecycle types
   TitleSource,
   ChatListFilters,
+  ChatOrigin,
   ChatSummaryExtended,
   TitleGenerationRequest,
   TitleGenerationResponse,
+  // Proactive chat resolution (occurrence id → this reader's chat)
+  ProactiveChatResolution,
   // Event system types
   BaseEvent,
   InvalidationReason,
@@ -61,8 +64,10 @@ export {
   TitleSourceSchema,
   InvalidationReasonSchema,
   ChatChangedFieldSchema,
+  ChatOriginSchema,
   ChatSummarySchema,
   ChatSummaryExtendedSchema,
+  ProactiveChatResolutionSchema,
   TitleGenerationResponseSchema,
   SharedChatMessageSchema,
   ChatShareInfoSchema,
@@ -89,6 +94,10 @@ export {
   GetChatResponseSchema,
 } from "./schemas";
 
+// Recognizing a wire `proactiveKind` — once, at the edge
+export type { RecognizedProactiveKind } from "./proactive-kind";
+export { recognizeProactiveKind } from "./proactive-kind";
+
 // Runtime profile types and constants
 export type {
   ChatRuntimeProfile,

package/src/chat/proactive-kind.ts

@@ -0,0 +1,51 @@
+/**
+ * Recognizing a chat's `proactiveKind` — ONCE, at the edge.
+ *
+ * On the wire `proactiveKind` is a bare `z.string()` (`./schemas`), so a kind
+ * shipped by a newer backend cannot make an older client reject the WHOLE
+ * chat list. That looseness must stop here: the domain model speaks
+ * `ProactiveEventKind`, and this is the only place a raw string is allowed to
+ * become one.
+ *
+ * INVARIANTS:
+ * - Recognition happens ONCE, at the boundary where the parsed wire shape is
+ *   turned into domain state. Downstream code takes the recognized value and
+ *   must never re-derive it from the raw string, and must never treat an
+ *   unrecognised string as a valid current-domain kind — an older client
+ *   renders a generic proactive chat for `{ unknown }` instead.
+ * - `null` means "not a proactive chat" (origin `user`, or an absent field).
+ *   It is distinct from `{ unknown }`, which means "a proactive chat of a kind
+ *   this contracts version has not learned" — the two must not collapse, or a
+ *   pushed chat from a newer kind silently renders as a user chat.
+ * - The vocabulary is `PROACTIVE_EVENT_KIND_IDS` and nothing else; there is no
+ *   second list here to drift from `../proactive`.
+ *
+ * @see ../proactive/kinds.ts
+ */
+
+import { PROACTIVE_EVENT_KIND_IDS } from "../proactive/kinds";
+import type { ProactiveEventKind } from "../proactive/kinds";
+
+/**
+ * A wire `proactiveKind` after recognition: a kind this contracts version
+ * knows, or the raw string it did not — carried, not discarded, so the
+ * unknown can still be logged and rendered generically.
+ */
+export type RecognizedProactiveKind = ProactiveEventKind | { unknown: string };
+
+/**
+ * Recognize a wire `proactiveKind`. Pure, total, and the ONLY sanctioned
+ * conversion from the wire string to `ProactiveEventKind`.
+ *
+ * - `null` / `undefined` / `""` → `null`: not a proactive chat.
+ * - a member of `PROACTIVE_EVENT_KIND_IDS` → that `ProactiveEventKind`.
+ * - anything else → `{ unknown: raw }`: proactive, of a kind not yet known.
+ */
+export function recognizeProactiveKind(
+  raw: string | null | undefined,
+): RecognizedProactiveKind | null {
+  if (!raw) return null;
+  return (PROACTIVE_EVENT_KIND_IDS as readonly string[]).includes(raw)
+    ? (raw as ProactiveEventKind)
+    : { unknown: raw };
+}

package/src/chat/schemas.ts

@@ -24,6 +24,52 @@ export const ChatChangedFieldSchema = z.enum([
   "pinnedAt",
 ]);
 
+/**
+ * How a chat was born: by the user, or by the system speaking first (a
+ * proactive occurrence projected onto the chat surface — `../proactive`).
+ * A CLOSED set on the wire, unlike `proactiveKind`: the two origins are the
+ * whole space, and an older client must know which of the two it holds.
+ */
+export const ChatOriginSchema = z.enum(["user", "proactive"]);
+
+/**
+ * The three proactive wire fields, stated ONCE and spread into every shape
+ * that carries a chat: the extended summary, BOTH chat SSE event payloads and
+ * (origin + unread) the detail. The app's `eventDataToSummary()` builds a full
+ * `ChatSummaryExtended` out of event data — a field on the summary but not on
+ * the event schema means every pushed chat arrives silently READ, with no type
+ * error to catch it. Spreading one definition is what makes that drift a
+ * compile error instead of a bug report.
+ *
+ * All three are OPTIONAL in this wave so consumer object literals (the app's
+ * `insertPendingChat` and `eventDataToSummary`) keep compiling. Dropping
+ * `.optional()` is a later major release.
+ */
+const proactiveChatFields = {
+  /** How the chat was born. Absent means `user`. */
+  origin: ChatOriginSchema.optional(),
+  /**
+   * A ONE-TIME proactive badge, not a general chat-read model.
+   *
+   *   unread  <=>  origin = 'proactive' AND unread_at IS NOT NULL
+   *
+   * Opening the chat clears it permanently; ordinary conversation NEVER makes
+   * the thread unread again. Deliberately a boolean rather than a timestamp:
+   * there is no "new since" semantics in a one-time flag.
+   */
+  unread: z.boolean().optional(),
+  /**
+   * Which ProactiveEventKind produced it; null for `origin: "user"`.
+   *
+   * DELIBERATELY `z.string()`, not `z.enum(PROACTIVE_EVENT_KIND_IDS)` — a newly
+   * shipped kind must not make an older client reject the WHOLE chat list. The
+   * looseness stops at the wire: call `recognizeProactiveKind` (in
+   * `./proactive-kind`) ONCE at the edge, and never treat the raw string as a
+   * current-domain kind downstream.
+   */
+  proactiveKind: z.string().nullable().optional(),
+};
+
 // =============================================================================
 // Core Entities
 // =============================================================================
@@ -41,6 +87,7 @@ export const ChatSummaryExtendedSchema = ChatSummarySchema.extend({
   pinnedAt: IsoDateString.nullable(),
   titleSource: TitleSourceSchema.nullable(),
   titleGeneratedAt: IsoDateString.nullable(),
+  ...proactiveChatFields,
 });
 
 export const TitleGenerationResponseSchema = z.object({
@@ -105,6 +152,14 @@ export const BaseEventSchema = z.object({
   eventId: z.string().optional(),
 });
 
+/**
+ * Emitted exactly once after a chat is persisted; a pushed proactive chat is
+ * announced over this event too.
+ *
+ * The SAME three proactive fields ride both chat event payloads (see
+ * `proactiveChatFields`) because the app builds its sidebar row from `data`
+ * alone.
+ */
 export const ChatCreatedEventSchema = BaseEventSchema.extend({
   type: z.literal("chat.created"),
   data: z.object({
@@ -117,6 +172,7 @@ export const ChatCreatedEventSchema = BaseEventSchema.extend({
     createdAt: IsoDateString,
     updatedAt: IsoDateString,
     isShared: z.boolean(),
+    ...proactiveChatFields,
   }),
 });
 
@@ -132,6 +188,7 @@ export const ChatUpdatedEventSchema = BaseEventSchema.extend({
     createdAt: IsoDateString,
     updatedAt: IsoDateString,
     isShared: z.boolean(),
+    ...proactiveChatFields,
   }),
   changed: z.array(ChatChangedFieldSchema),
 });
@@ -205,11 +262,40 @@ export const ChatByInteractionResponseSchema = z.object({
   chatId: z.string(),
 });
 
-/** Response for GET /api/chats */
+/**
+ * Response for GET /api/chats.
+ *
+ * `unreadCount` rides the ENVELOPE, never derived from the returned page. The
+ * sidebar list is a 50-row page; deriving a badge from it is the windowed-count
+ * failure the app ADR slug `feed-mark-on-open-and-paging` forbids. It is the
+ * total across ALL of this reader's chats, and optional only because an older
+ * backend does not send it (a missing count is "no badge", never "zero").
+ */
 export const ChatListResponseSchema = z.object({
   chats: z.array(ChatSummaryExtendedSchema),
+  unreadCount: z.number().int().nonnegative().optional(),
 });
 
+/**
+ * Resolving an occurrence id to THIS reader's chat (INV-PROACTIVE-LINK). A
+ * banner or inbox row links to the occurrence, not to a chat id, because the
+ * chat is per recipient; the server resolves it for the CURRENT reader.
+ *
+ * Bounded states, never an open-ended "preparing": the first time a chat
+ * projection exhausts its retries while the banner already exists, an
+ * unbounded pending state becomes a dead link.
+ * - `ready`: the reader's chat exists; open it.
+ * - `pending`: the projection is still being written; try again shortly.
+ * - `unavailable`: the projection gave up; the durable inbox row stands alone.
+ * - `ineligible`: the reader is not in the occurrence's frozen audience.
+ */
+export const ProactiveChatResolutionSchema = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("ready"), chatId: z.string() }),
+  z.object({ state: z.literal("pending") }),
+  z.object({ state: z.literal("unavailable") }),
+  z.object({ state: z.literal("ineligible") }),
+]);
+
 /** Response for POST /api/chats */
 export const CreateChatResponseSchema = z.object({
   chat: ChatSummaryExtendedSchema,
@@ -244,6 +330,11 @@ export const ChatDetailSchema = z.object({
   titleGeneratedAt: IsoDateString.nullable().optional(),
   createdAt: IsoDateString,
   updatedAt: IsoDateString,
+  // Opening the detail is what clears `unread`; the detail carries the flag so
+  // the reader can tell a first open from a return visit. `proactiveKind` is
+  // a list concern (the sidebar row) and does not ride the detail.
+  origin: proactiveChatFields.origin,
+  unread: proactiveChatFields.unread,
 });
 
 /** Response for GET /api/chats/:id */

package/src/chat/types.ts

@@ -12,8 +12,10 @@ import {
   TitleSourceSchema,
   InvalidationReasonSchema,
   ChatChangedFieldSchema,
+  ChatOriginSchema,
   ChatSummarySchema,
   ChatSummaryExtendedSchema,
+  ProactiveChatResolutionSchema,
   TitleGenerationResponseSchema,
   ChatShareInfoSchema,
   SharedChatViewSchema,
@@ -132,10 +134,26 @@ export interface ChatListFilters {
 }
 
 /**
- * Extended chat summary with pin/title status.
+ * How a chat was born: `user` or `proactive` (the system spoke first).
+ */
+export type ChatOrigin = z.infer<typeof ChatOriginSchema>;
+
+/**
+ * Extended chat summary with pin/title status, plus the optional proactive
+ * wire fields (`origin`, `unread`, `proactiveKind`). Recognize `proactiveKind`
+ * once at the edge with `recognizeProactiveKind` — it is a bare string here.
  */
 export type ChatSummaryExtended = z.infer<typeof ChatSummaryExtendedSchema>;
 
+/**
+ * Resolving an occurrence id to the CURRENT reader's chat — one of the four
+ * bounded states `ready` (with `chatId`), `pending`, `unavailable`,
+ * `ineligible`. Never an open-ended "preparing".
+ */
+export type ProactiveChatResolution = z.infer<
+  typeof ProactiveChatResolutionSchema
+>;
+
 /**
  * Request to generate a title for a chat.
  */

package/src/index.ts

@@ -324,6 +324,49 @@ export type {
   UserNotificationKind,
 } from "./user-notifications/index";
 
+// Proactive delivery — how the system speaks first (ADR-CONTRACTS-142). A
+// COMPOSER above the three notification vocabularies, not a fourth peer: the
+// presentation class is a TOTAL FUNCTION from class to surfaces
+// (CLASS_SURFACES, checked in both directions by the compiler), and a kind
+// carries its class plus the IDS each surface needs — which banner, which chat
+// template, which inbox kind — never the surface booleans. The born-read rule
+// is stated once (bornRead) so the backend imports it rather than re-deriving
+// it per call site. Pushed-chat prose lives here too (PROACTIVE_CHAT_COMPOSERS,
+// total over the templates): the backend hands a composer facts and writes what
+// comes back, FROZEN into the transcript — so a composer may only interpolate
+// facts the recipient was entitled to at compose time. See src/proactive/README.md.
+export {
+  PROACTIVE_PRESENTATION_CLASSES,
+  CLASS_SURFACES,
+  bornRead,
+  ORG_SYSTEM_EVENT_TYPES,
+  PROACTIVE_CHAT_TEMPLATES,
+  PROACTIVE_EVENT_KIND_IDS,
+  PROACTIVE_RECIPIENT_REASONS,
+  PROACTIVE_PROJECTIONS,
+  PROACTIVE_EVENT_KINDS,
+  PROACTIVE_CHAT_MAX_REPLIES,
+  PROACTIVE_CHAT_COMPOSERS,
+} from "./proactive/index";
+
+export type {
+  ProactivePresentationClass,
+  BadgeCarrier,
+  ClassSurfacePlan,
+  OrgSystemEventType,
+  ProactiveChatTemplate,
+  ProactiveEventKind,
+  ProactiveEventId,
+  ProactiveRecipientReason,
+  ProactiveProjection,
+  ProactiveEventDefinition,
+  OrgBecameSharedFacts,
+  MorningBriefFacts,
+  ProactiveChatFacts,
+  ProactiveChatComposer,
+  ProactiveChatMessage,
+} from "./proactive/index";
+
 // Comment wire contract — where a thread hangs (the anchor union), what a
 // thread and its comments look like on the wire, and who a comment may name.
 // The anchor is the single most load-bearing shape in this package: the backend
@@ -481,11 +524,21 @@ export type {
   // Runtime profile types (PRD-00229)
   ChatRuntimeProfile,
   ChatRuntimeProfileInfo,
+  // Proactive chat wire vocabulary (ADR-CONTRACTS-142): how a chat was born,
+  // the occurrence-to-chat resolution states, and the recognized form of the
+  // wire-lenient `proactiveKind` string
+  ChatOrigin,
+  ProactiveChatResolution,
+  RecognizedProactiveKind,
 } from "./chat/index";
 
 export {
   CHAT_RUNTIME_PROFILES,
   DEFAULT_CHAT_RUNTIME_PROFILE,
+  // `proactiveKind` is a bare string on the wire so a new kind cannot make an
+  // older client reject the whole chat list; this is the ONE place it becomes
+  // a ProactiveEventKind. See src/chat/proactive-kind.ts.
+  recognizeProactiveKind,
 } from "./chat/index";
 
 // Organization domain types
@@ -961,6 +1014,11 @@ export type {
   InteractiveTaskData,
   InteractiveTaskPart,
   InteractiveTaskDataPart,
+  // Suggested replies surface types (non-governed chips, PRD-00958)
+  SuggestedReply,
+  SuggestedRepliesData,
+  SuggestedRepliesPart,
+  SuggestedRepliesDataPart,
   // Execution result types (Phase 5)
   ExecutionArtifactStatus,
   ExecutionResultSummary,

package/src/message-parts/README.md

@@ -14,6 +14,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - Confirmation is deterministic — no natural language inference ("yes" is invalid)
 - Execution results carry `state` resolved from ExecutionState (single authority, no redundant status)
 - Undo creates append-only audit rows — original execution is never mutated
+- `SuggestedRepliesPart` is a surface but NOT a governed one: a chip fires an ordinary user turn (no `executionId`, no `submitEndpoint`), is stateless (clicking never consumes it) and advisory (the composer stays enabled) — so it is outside the at-most-one-governed-surface-per-turn rule
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
@@ -65,6 +66,10 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `StatusPanelEntry` _(type)_ — Single entry in a status panel.
 - `StatusPanelPart` _(type)_ — Status panel surface part.
 - `StreamPhase` _(type)_ — Derived stream phase for UI state management.
+- `SuggestedRepliesData` _(type)_ — Suggested replies surface data payload.
+- `SuggestedRepliesDataPart` _(type)_ — Wire form, as persisted in `chat_messages.parts`.
+- `SuggestedRepliesPart` _(type)_ — Normalized form, as rendered.
+- `SuggestedReply` _(type)_ — Suggested follow-up chips beneath an assistant turn.
 - `SurfacePart` _(type)_ — Surface parts are rendered atomically (never streamed).
 - `TablePart` _(type)_ — Table surface part.
 - `TextPart` _(type)_ — Text content part.

package/src/message-parts/__tests__/suggested-replies.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { isSurfacePart, isTextPart } from "../types.js";
+import type { AssistantMessagePart, SurfacePart } from "../types.js";
+import { createPartBuilder, addSurface, addText } from "../builder.js";
+import type { SuggestedRepliesPart } from "../suggested-replies.js";
+
+// The semantic part is what the app renders after normalizing the wire part.
+// Typing the fixture as SuggestedRepliesPart and then assigning it to
+// SurfacePart is the compile-time proof that the union gained the member.
+const chips: SuggestedRepliesPart = {
+  type: "suggested-replies",
+  data: {
+    replies: [
+      { id: "r1", label: "What moved?" },
+      { id: "r2", label: "Undo", prompt: "Undo the last change" },
+    ],
+  },
+};
+
+describe("SuggestedRepliesPart in the SurfacePart union", () => {
+  it("is assignable to SurfacePart and AssistantMessagePart", () => {
+    const asSurface: SurfacePart = chips;
+    const asPart: AssistantMessagePart = chips;
+    expect(asSurface.type).toBe("suggested-replies");
+    expect(asPart.type).toBe("suggested-replies");
+  });
+
+  it("is classified as a surface part, not a text part", () => {
+    expect(isSurfacePart(chips)).toBe(true);
+    expect(isTextPart(chips)).toBe(false);
+  });
+
+  // The builder's narrative-before-surface state machine applies to chips like
+  // any other surface: they are emitted after the prose, never streamed.
+  it("is accepted by addSurface after narrative text", () => {
+    let state = createPartBuilder();
+    state = addText(state, "Five settings sections moved.").state;
+    const result = addSurface(state, chips);
+    expect(result.accepted).toBe(true);
+    expect(result.state.parts).toEqual([
+      { type: "text", text: "Five settings sections moved." },
+      chips,
+    ]);
+  });
+
+  it("does not consume: the same part can be added to two builders unchanged", () => {
+    const a = addSurface(createPartBuilder(), chips).state.parts[0];
+    const b = addSurface(createPartBuilder(), chips).state.parts[0];
+    expect(a).toEqual(b);
+    expect(a).toEqual(chips);
+  });
+});