@company-semantics/contracts 58.1.0 → 58.2.0

package/src/message-parts/__tests__/wire.test.ts

@@ -3,6 +3,7 @@ import { WireSurfaceBuilder } from "../wire.js";
 import type { MCPToolDescriptor } from "../../mcp/index.js";
 import type { ExecutionResultData } from "../execution.js";
 import type { UndoResultData } from "../execution.js";
+import type { SuggestedRepliesData } from "../suggested-replies.js";
 
 // Deliberately partial fixtures: toolList is a pure wrapper that passes `tools`
 // straight through, so these assert the wrapping, not descriptor validity. Cast
@@ -90,6 +91,53 @@ describe("WireSurfaceBuilder.undoResult", () => {
   });
 });
 
+describe("WireSurfaceBuilder.suggestedReplies", () => {
+  const data: SuggestedRepliesData = {
+    replies: [
+      { id: "r1", label: "Show me what moved" },
+      {
+        id: "r2",
+        label: "Why?",
+        prompt: "Why did these settings move out of My settings?",
+      },
+    ],
+  };
+
+  it("returns data part with type data-suggested-replies", () => {
+    const result = WireSurfaceBuilder.suggestedReplies(data);
+    expect(result.type).toBe("data-suggested-replies");
+  });
+
+  it("data matches input SuggestedRepliesData exactly", () => {
+    const result = WireSurfaceBuilder.suggestedReplies(data);
+    expect(result.data).toEqual(data);
+  });
+
+  // A chip is an ordinary user turn: the part carries nothing that would make
+  // it a governed surface. Pinning the key set catches an accidental
+  // executionId/submitEndpoint creeping onto the payload.
+  it("carries no governed-surface fields (no executionId, no submitEndpoint)", () => {
+    const result = WireSurfaceBuilder.suggestedReplies(data);
+    expect(Object.keys(result.data)).toEqual(["replies"]);
+    expect(result.data).not.toHaveProperty("executionId");
+    expect(result.data).not.toHaveProperty("submitEndpoint");
+  });
+
+  // Stateless: building twice from the same facts yields identical output, so
+  // a historical message re-rendered later cannot differ from the original.
+  it("is deterministic across repeated builds", () => {
+    expect(WireSurfaceBuilder.suggestedReplies(data)).toEqual(
+      WireSurfaceBuilder.suggestedReplies(data),
+    );
+  });
+
+  it("works with an empty replies array", () => {
+    const result = WireSurfaceBuilder.suggestedReplies({ replies: [] });
+    expect(result.type).toBe("data-suggested-replies");
+    expect(result.data.replies).toEqual([]);
+  });
+});
+
 describe("WireSurfaceBuilder.messageStart", () => {
   it("returns data part with type data-message-start", () => {
     const result = WireSurfaceBuilder.messageStart("msg-123");

package/src/message-parts/index.ts

@@ -56,6 +56,14 @@ export type {
   InteractiveTaskDataPart,
 } from "./interactive";
 
+// Suggested replies surface types (non-governed chips)
+export type {
+  SuggestedReply,
+  SuggestedRepliesData,
+  SuggestedRepliesPart,
+  SuggestedRepliesDataPart,
+} from "./suggested-replies";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

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

@@ -0,0 +1,48 @@
+/**
+ * Suggested follow-up chips beneath an assistant turn.
+ *
+ * INVARIANTS — these are what keep this OUT of the governed
+ * preview/confirmation/interactive triad:
+ *
+ * - A chip fires an ORDINARY USER TURN. No `executionId`, no `submitEndpoint`,
+ *   no side effect of its own. That is precisely why it is not a governed
+ *   surface and is not subject to the at-most-one-governed-surface-per-turn
+ *   rule.
+ * - STATELESS. Clicking does not consume it; the historical message renders
+ *   identically forever, because the turn it produced is already in the
+ *   transcript below it.
+ * - ADVISORY and non-exhaustive. The composer box stays enabled.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part
+ * types to null, so it drops the chips and still renders the prose.
+ *
+ * @see decisions/ADR-CONT-026.md for the message-parts design
+ * @see decisions/ADR-CONTRACTS-142-proactive-vocabulary-composes-the-three-notification-unions.md
+ */
+export interface SuggestedReply {
+  /** Stable within the part. Telemetry key and React key; never a server id. */
+  readonly id: string;
+  /** What the chip SAYS. */
+  readonly label: string;
+  /** What the chip SENDS, when it differs from the label. */
+  readonly prompt?: string;
+}
+
+/**
+ * Suggested replies surface data payload.
+ */
+export interface SuggestedRepliesData {
+  readonly replies: readonly SuggestedReply[];
+}
+
+/** Normalized form, as rendered. */
+export interface SuggestedRepliesPart {
+  type: "suggested-replies";
+  data: SuggestedRepliesData;
+}
+
+/** Wire form, as persisted in `chat_messages.parts`. */
+export interface SuggestedRepliesDataPart {
+  type: "data-suggested-replies";
+  data: SuggestedRepliesData;
+}

package/src/message-parts/types.ts

@@ -17,6 +17,7 @@ import type { ToolListMessagePart } from "../mcp/index";
 import type { PreviewPart } from "./preview";
 import type { ConfirmationPart } from "./confirmation";
 import type { InteractiveTaskPart } from "./interactive";
+import type { SuggestedRepliesPart } from "./suggested-replies";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -112,6 +113,10 @@ export interface TablePart {
 /**
  * Surface parts are rendered atomically (never streamed).
  * Extensible: add new surface types to this union.
+ *
+ * SuggestedRepliesPart is a surface part but NOT a governed one: a chip fires
+ * an ordinary user turn, so it is outside the preview/confirmation/interactive
+ * triad and its at-most-one-governed-surface-per-turn rule.
  */
 export type SurfacePart =
   | ToolListPart
@@ -120,7 +125,8 @@ export type SurfacePart =
   | TablePart
   | ConfirmationPart
   | PreviewPart
-  | InteractiveTaskPart;
+  | InteractiveTaskPart
+  | SuggestedRepliesPart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -17,6 +17,10 @@ import type {
   InteractiveTaskData,
   InteractiveTaskDataPart,
 } from "./interactive";
+import type {
+  SuggestedRepliesData,
+  SuggestedRepliesDataPart,
+} from "./suggested-replies";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -112,6 +116,28 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build a suggested-replies data part for streaming.
+   * Chips beneath an assistant turn that each fire an ORDINARY user turn.
+   *
+   * INVARIANTS:
+   * - Not a governed surface: no executionId, no submitEndpoint, no side
+   *   effect of its own — so it does not count against the
+   *   at-most-one-governed-surface-per-turn rule
+   * - Stateless: clicking does not consume it; the historical message renders
+   *   identically forever
+   * - Advisory and non-exhaustive: the composer box stays enabled
+   *
+   * @param data - Suggested replies data (the chip list)
+   * @returns Wire-format suggested replies part ready for stream
+   */
+  suggestedReplies(data: SuggestedRepliesData): SuggestedRepliesDataPart {
+    return {
+      type: "data-suggested-replies",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

package/src/proactive/README.md

@@ -0,0 +1,125 @@
+# proactive/
+
+## Purpose
+
+The vocabulary of **proactive delivery** — how the system speaks first. It
+encodes the doctrine in the control ADR with slug
+`proactive-delivery-occurrence-audience-projection` (ADR-CTRL-408) as a
+compile-checked vocabulary: a **presentation class** is a TOTAL FUNCTION from
+class to surfaces, and an **event kind** carries only the IDS each surface
+needs. See ADR-CONTRACTS-142.
+
+This vocabulary COMPOSES the three notification vocabularies beside it — it
+adds no member to `NotificationKind` or `ActionItemKind`, and it derives none of
+the three from another.
+
+## Invariants
+
+- **`CLASS_SURFACES` is total in both directions.** Checked by
+  `as const satisfies Record<ProactivePresentationClass, ClassSurfacePlan>`: a
+  class with no entry fails to compile, and an entry for a non-class fails too.
+- **Exactly one badge carrier per class.** `ClassSurfacePlan` is a UNION, not a
+  flat interface, so a badge naming a surface the class does not have is a
+  compile error.
+- **Every class writes a durable inbox row.** `inbox` is literal `true` in every
+  union member. What varies is whether the row is born read.
+- **The born-read rule is stated once.** `bornRead(surfaces, surface)` is the
+  only place "born read whenever a louder surface owns the badge" lives. A
+  backend that re-derives it per call site is how the two halves drift.
+- **Loudness, not severity.** `error|warning|info` exists in this package scoped
+  to org-transformation findings and is not overloaded here.
+- **Kinds carry ids, never surface booleans.** A kind names its `class` and the
+  identifiers each surface needs; the surfaces themselves are derived from the
+  class table. Restating them would leave the compiler having to prove two
+  declarations agree.
+- **`PROACTIVE_EVENT_KINDS` is total in both directions.** Same
+  `as const satisfies Record<ProactiveEventKind, ProactiveEventDefinition>`
+  idiom: a kind with no plan fails to compile, and a plan for a non-kind fails.
+- **The plan union types the ids a class lacks as `never`.** An `announcement`
+  MUST name a `bannerType` and a `chatTemplate`; `explained` and `briefing`
+  cannot name a banner; a `notice` can name neither. Every member requires an
+  `inboxKind`. The one consistency the compiler cannot express — a plan's ids
+  agreeing with `CLASS_SURFACES[plan.class]` — is pinned by the vocabulary
+  test.
+- **Email and action items are orthogonal axes.** `emailKind` is off-platform
+  delivery governed by notify/'s policy; `actionItemKind` is a work-state
+  projection, not a loudness tier. No kind sets `emailKind` in this wave.
+- **The kind string and the inbox kind string are distinct.**
+  `org.became_shared` names its row `proactive.org_became_shared` and
+  `brief.morning` names its row `proactive.brief_morning`; identical names
+  across two unions is how one quietly becomes derived from the other.
+- **A `briefing` needs no new machinery.** `brief.morning` is the proof: its
+  class already types `bannerType` as `never`, so it cannot name a banner, and
+  the plan/surface test covers it for free. ONE occurrence per org per
+  org-local day, with N recipients — personalisation lives in the per-recipient
+  `MorningBriefFacts`, never in occurrence identity, or the system would have
+  one event row per person per day and two shapes of occurrence to reason
+  about.
+- **`ORG_SYSTEM_EVENT_TYPES` mirrors the backend pgEnum value for value.**
+  `org.became_shared` names the EXISTING `first_member_joined` banner rather
+  than minting a third value — it fires at exactly the personal-to-shared flip.
+- **The occurrence vocabulary is closed.** `ProactiveEventId` is branded so a
+  raw string cannot stand in for an occurrence; `ProactiveRecipientReason` is a
+  closed enum because the recipients table is the frozen audit record of who
+  was addressed and why; `ProactiveProjection` is deliberately broader than the
+  three surfaces because an occurrence has zero or more PROJECTIONS.
+- **Pushed-chat copy lives here, not in the backend.** The precedent notify/'s
+  README states for outbound notifications — copy belongs to contracts'
+  `compose` — applied to the third surface. The backend hands a composer facts
+  and writes what comes back; it never owns a sentence.
+- **The composer is pure and content-only.** `(facts)` in, message out; no
+  clock, no env, no I/O; no markup, no channel names, no hrefs the app owns.
+  Members are arrow properties, never method shorthand, because the vocabulary
+  guard reads a method signature as behaviour.
+- **`PROACTIVE_CHAT_COMPOSERS` is total in both directions.** Same
+  `as const satisfies Record<ProactiveChatTemplate, ProactiveChatComposer>`
+  idiom: a template with no composer fails to compile. `ProactiveChatComposer`
+  is a DISTRIBUTIVE type so the bare name is a union of per-template composers
+  — an arrow `compose` is checked contravariantly, and a composer taking one
+  template's facts is not assignable to one taking the union of all facts.
+- **The pushed message is FROZEN AT WRITE TIME (INV-PROACTIVE-CONTENT).** It
+  is written once into `chat_messages.content` and never re-renders, so a
+  composer may only interpolate facts the recipient was entitled to at compose
+  time. The deliberate opposite of the durable-inbox rule, and both are
+  correct: a transcript that changed under the reader would be a lie about the
+  conversation.
+
+## Public API
+
+| Export                           | Description                                                                   |
+| -------------------------------- | ----------------------------------------------------------------------------- |
+| `PROACTIVE_PRESENTATION_CLASSES` | The closed class vocabulary (announcement, explained, briefing, notice)       |
+| `ProactivePresentationClass`     | Union derived from the array                                                  |
+| `BadgeCarrier`                   | `banner` \| `chat` \| `inbox` — exactly one per class                         |
+| `ClassSurfacePlan`               | Union of the surface sets a badge carrier presupposes                         |
+| `CLASS_SURFACES`                 | The total class → surfaces table                                              |
+| `bornRead`                       | Whether a class's `chat` or `inbox` row is born read                          |
+| `ORG_SYSTEM_EVENT_TYPES`         | Mirror of the backend `org_system_event_type` pgEnum — the banner ids         |
+| `OrgSystemEventType`             | Union derived from the array                                                  |
+| `PROACTIVE_CHAT_TEMPLATES`       | Which prose composes a kind's pushed chat (`orgBecameShared`, `morningBrief`) |
+| `ProactiveChatTemplate`          | Union derived from the array                                                  |
+| `PROACTIVE_EVENT_KIND_IDS`       | The closed kind vocabulary (`org.became_shared`, `brief.morning`)             |
+| `ProactiveEventKind`             | Union derived from the array                                                  |
+| `ProactiveEventId`               | Branded id of ONE occurrence — a raw string cannot be passed as one           |
+| `PROACTIVE_RECIPIENT_REASONS`    | Closed enum of WHY a recipient was addressed (the frozen audit record)        |
+| `ProactiveRecipientReason`       | Union derived from the array                                                  |
+| `PROACTIVE_PROJECTIONS`          | What was materialized for one recipient — broader than the three surfaces     |
+| `ProactiveProjection`            | Union derived from the array                                                  |
+| `ProactiveEventDefinition`       | A kind's plan: discriminated union on `class`, ids the class lacks as `never` |
+| `PROACTIVE_EVENT_KINDS`          | The total kind → plan registry                                                |
+| `ProactiveChatFacts`             | The facts each template composes from, keyed by template                      |
+| `OrgBecameSharedFacts`           | Facts for the personal-to-shared flip: `orgName`, `joinerDisplayName`         |
+| `MorningBriefFacts`              | Per-recipient facts for the morning brief — where personalisation lives       |
+| `ProactiveChatMessage`           | What a composer returns: `title`, `text`, and 0..4 `replies` chips            |
+| `ProactiveChatComposer`          | The composer port — `template` plus an arrow-property `compose(facts)`        |
+| `PROACTIVE_CHAT_MAX_REPLIES`     | At most this many chips (4); more is a menu, not a chip row                   |
+| `PROACTIVE_CHAT_COMPOSERS`       | The total template → composer registry (see `templates/README.md`)            |
+
+## Dependencies
+
+Type-only imports of `UserNotificationKind` (`../user-notifications`),
+`NotificationKind` (`../notifications`) and `ActionItemKind`
+(`../action-items`) — the three vocabularies this one composes — and of
+`SuggestedReply` (`../message-parts`), the chip shape a composer's `replies`
+reuse rather than redeclare. No `zod`, no runtime imports; pure vocabulary
+data and pure helpers.

package/src/proactive/__tests__/README.md

@@ -0,0 +1,56 @@
+# proactive/\_\_tests\_\_/
+
+## Purpose
+
+Locks the claims `../README.md` and ADR-CONTRACTS-142 make that the compiler
+cannot.
+
+- `vocabulary.test.ts` — the load-bearing one is
+  `plan surfaces agree with the class table`, the ONE consistency the type
+  system cannot express (the ids PRESENT on a kind's plan agree with the
+  surfaces `CLASS_SURFACES[plan.class]` DECLARES, and `inboxKind` is always
+  there). Also: `CLASS_SURFACES` is total
+  over `PROACTIVE_PRESENTATION_CLASSES` and every badge names a surface its
+  class has; `bornRead` matches the doctrine table row for row;
+  `PROACTIVE_EVENT_KINDS` is total over `PROACTIVE_EVENT_KIND_IDS`; every
+  `inboxKind` is a real `USER_NOTIFICATION_KINDS` member in the `proactive.`
+  domain and never the kind string itself; every `chatTemplate` a kind names
+  reaches a composer; no kind sets `emailKind`; and composers are pure (same
+  facts, byte-identical output across two calls).
+- `compile-fixtures.ts` — the negative typecheck fixtures. A COMPILED module,
+  not a `*.test.ts`: `src/tsconfig.json` excludes test files and vitest does
+  not typecheck, so a `@ts-expect-error` written in a test would never be
+  checked. Here `tsc -b` checks each directive, and an unused one (a claim that
+  stopped being true) fails `pnpm typecheck` with TS2578. The four claims: a
+  `notice` naming a `bannerType`, an `announcement` omitting one, an
+  `explained` (and, by the same union member, a `briefing`) naming one, and a
+  registry that is not total (a kind with no plan, and a plan for a non-kind). `vocabulary.test.ts` imports the fixtures
+  and shows the runtime class-table check rejects the same plans.
+- `chat-templates.test.ts` — the pushed-chat composer registry in practice:
+  every template in `PROACTIVE_CHAT_TEMPLATES` has a composer whose `template`
+  equals its key (the type proves totality; this proves no entry is an
+  accidental `undefined`), the org-became-shared prose NAMES THE RELOCATION and
+  every one of the five sections that leave My settings for Org settings, the
+  morning brief PERSONALISES THROUGH ITS FACTS (two recipients of one
+  occurrence get different prose from one composer), chips stay within
+  `PROACTIVE_CHAT_MAX_REPLIES`, and composers emit content — no markup, no
+  hrefs.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never behaviour. Anything needing a
+  database, a clock or an authority gate belongs in backend's
+  `src/proactive/__tests__/`.
+- Tests iterate the REAL exported arrays and registries rather than restating
+  them. A hand-copied list drifts and starts passing vacuously.
+- A composer is exercised through the registry (`PROACTIVE_CHAT_COMPOSERS`),
+  not by importing its module directly, so a template that is written but not
+  registered fails here rather than in the backend.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest` and the sibling modules under test.

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

@@ -0,0 +1,167 @@
+import { describe, it, expect } from "vitest";
+import { PROACTIVE_CHAT_MAX_REPLIES } from "../composer";
+import type { ProactiveChatMessage } from "../composer";
+import type { ProactiveChatFacts } from "../facts";
+import { PROACTIVE_CHAT_TEMPLATES } from "../surfaces";
+import type { ProactiveChatTemplate } from "../surfaces";
+import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+
+/**
+ * One representative facts fixture per template. Total over
+ * `ProactiveChatTemplate`, so a template added without a fixture fails to
+ * compile here — the registry-wide tests below then cover it for free.
+ */
+const FACTS: { readonly [T in ProactiveChatTemplate]: ProactiveChatFacts[T] } =
+  {
+    orgBecameShared: { orgName: "Acme", joinerDisplayName: "Ada" },
+    morningBrief: {
+      recipientDisplayName: "Ada",
+      orgName: "Acme",
+      orgLocalDateLabel: "Tuesday 25 August",
+      pendingActionItemCount: 2,
+      unreadNotificationCount: 5,
+    },
+  };
+
+/**
+ * Compose a template with its fixture. The registry is a union of composers
+ * whose `compose` parameters differ per template, and TypeScript cannot
+ * correlate `PROACTIVE_CHAT_COMPOSERS[t]` with `FACTS[t]` through a variable
+ * `t` — the cast is the one place the correlation is asserted, and the
+ * fixture record above is what keeps it honest.
+ */
+function composeFixture(template: ProactiveChatTemplate): ProactiveChatMessage {
+  const compose = PROACTIVE_CHAT_COMPOSERS[template].compose as (
+    facts: ProactiveChatFacts[ProactiveChatTemplate],
+  ) => ProactiveChatMessage;
+  return compose(FACTS[template]);
+}
+
+/**
+ * The pushed-chat templates: what the composer registry promises in practice
+ * and not just in type, and the one editorial claim the org-became-shared
+ * prose exists to make.
+ */
+describe("proactive chat templates", () => {
+  it("registry is total over PROACTIVE_CHAT_TEMPLATES in practice", () => {
+    // The type check proves totality at compile time; this proves no entry is
+    // an accidental `undefined` and that every registered composer names the
+    // key it sits under — the runtime half of "kind matches registry key".
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      const composer = PROACTIVE_CHAT_COMPOSERS[template];
+      expect(composer, template).toBeDefined();
+      expect(composer.template).toBe(template);
+    }
+    expect(Object.keys(PROACTIVE_CHAT_COMPOSERS).sort()).toEqual(
+      [...PROACTIVE_CHAT_TEMPLATES].sort(),
+    );
+  });
+
+  it("org became shared template names the relocation", () => {
+    const msg = PROACTIVE_CHAT_COMPOSERS.orgBecameShared.compose({
+      orgName: "Acme",
+      joinerDisplayName: "Ada",
+    });
+    expect(msg.text).toContain("Org settings");
+    expect(msg.text).toContain("relocation");
+    expect(msg.replies.length).toBeLessThanOrEqual(PROACTIVE_CHAT_MAX_REPLIES);
+  });
+
+  it("org became shared prose names every relocated section", () => {
+    // The five sections the app ADR `nav-posture-opens-on-invite-send` lists
+    // as leaving My settings. Naming some and not others is the "things going
+    // missing" reading this chat exists to prevent.
+    const msg = PROACTIVE_CHAT_COMPOSERS.orgBecameShared.compose({
+      orgName: "Acme",
+      joinerDisplayName: "Ada",
+    });
+    for (const section of [
+      "Integrations",
+      "Invite team members",
+      "AI Usage",
+      "Budget",
+      "Billing",
+      "My settings",
+    ]) {
+      expect(msg.text, section).toContain(section);
+    }
+  });
+
+  it("org became shared interpolates only the facts it was handed", () => {
+    const msg = PROACTIVE_CHAT_COMPOSERS.orgBecameShared.compose({
+      orgName: "Acme",
+      joinerDisplayName: "Ada",
+    });
+    expect(msg.title).toBe("Your workspace is now shared");
+    expect(msg.text).toContain("Ada accepted your invite");
+    expect(msg.text).toContain("Acme");
+  });
+
+  it("chips carry a label and, when they differ, a full prompt", () => {
+    const msg = PROACTIVE_CHAT_COMPOSERS.orgBecameShared.compose({
+      orgName: "Acme",
+      joinerDisplayName: "Ada",
+    });
+    const ids = msg.replies.map((reply) => reply.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    for (const reply of msg.replies) {
+      expect(reply.label.length).toBeGreaterThan(0);
+      if (reply.prompt !== undefined) {
+        expect(reply.prompt).not.toBe(reply.label);
+      }
+    }
+  });
+
+  it("morning brief personalises through the facts, not the occurrence", () => {
+    // Two people in one org on one morning share an occurrence and receive
+    // different prose because they were handed different facts. The composer
+    // knows nothing about who it is composing for — the difference is entirely
+    // in what it was given.
+    const shared = { orgName: "Acme", orgLocalDateLabel: "Tuesday 25 August" };
+    const ada = PROACTIVE_CHAT_COMPOSERS.morningBrief.compose({
+      ...shared,
+      recipientDisplayName: "Ada",
+      pendingActionItemCount: 1,
+      unreadNotificationCount: 3,
+    });
+    const grace = PROACTIVE_CHAT_COMPOSERS.morningBrief.compose({
+      ...shared,
+      recipientDisplayName: "Grace",
+      pendingActionItemCount: 0,
+      unreadNotificationCount: 0,
+    });
+    expect(ada.title).toBe(grace.title);
+    expect(ada.text).toContain("Good morning, Ada.");
+    expect(ada.text).toContain("1 decision waiting on you");
+    expect(ada.text).toContain("3 unread notifications");
+    expect(grace.text).toContain("Good morning, Grace.");
+    expect(grace.text).toContain("Nothing is waiting on you");
+    expect(grace.text).not.toContain("0 ");
+    expect(ada.text).not.toBe(grace.text);
+  });
+
+  it("composers emit content, never markup", () => {
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      const msg = composeFixture(template);
+      for (const value of [msg.title, msg.text]) {
+        expect(value, template).not.toMatch(/<[a-z!/]/i);
+        expect(value, template).not.toMatch(/https?:\/\//);
+      }
+      for (const reply of msg.replies) {
+        expect(reply.label, template).not.toMatch(/<[a-z!/]/i);
+        expect(reply.prompt ?? "", template).not.toMatch(/https?:\/\//);
+      }
+    }
+  });
+
+  it("every composer stays within the chip budget", () => {
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      const msg = composeFixture(template);
+      expect(msg.replies.length, template).toBeLessThanOrEqual(
+        PROACTIVE_CHAT_MAX_REPLIES,
+      );
+      expect(msg.title.length, template).toBeGreaterThan(0);
+      expect(msg.text.length, template).toBeGreaterThan(0);
+    }
+  });
+});

package/src/proactive/__tests__/compile-fixtures.ts

@@ -0,0 +1,110 @@
+/**
+ * Negative typecheck fixtures — the compile-error claims the proactive
+ * vocabulary makes (ADR-CONTRACTS-142), each pinned with `@ts-expect-error`.
+ *
+ * The directive is the proof. If a claim ever stops being true — say the plan
+ * union in `../plan` loosens `bannerType?: never` to a plain optional — the
+ * directive goes UNUSED and `pnpm typecheck` fails with TS2578. A claim that is
+ * only stated in a doc comment cannot fail that way.
+ *
+ * WHY A COMPILED MODULE AND NOT `vocabulary.test.ts`. `src/tsconfig.json`
+ * excludes every `*.test.ts` file and vitest does not typecheck, so a directive
+ * written inside a test file is never checked at all: an unused one would prove
+ * nothing and fail nothing. This file is not a `*.test.ts`, so `tsc -b`
+ * compiles it (the same placement as `../../notifications/__tests__/fixtures.ts`),
+ * and `vocabulary.test.ts` imports the fixtures to prove the RUNTIME half of
+ * each claim — that the class-table check rejects the same plans the compiler
+ * rejects.
+ *
+ * Each directive sits IMMEDIATELY above the line the compiler reports on: a
+ * wrongly-typed or excess property is reported at that property, a missing
+ * property at the initializer.
+ */
+
+import type { ProactiveEventKind } from "../kinds";
+import type { ProactiveEventDefinition } from "../plan";
+import { PROACTIVE_EVENT_KINDS } from "../registry";
+
+/** The registry's declared shape, so the totality fixtures fit on one line. */
+type ProactiveRegistry = Record<ProactiveEventKind, ProactiveEventDefinition>;
+
+// =============================================================================
+// Plans the class table forbids
+// =============================================================================
+
+/** CLAIM 1 — a `notice` has no banner, so naming a `bannerType` is an error. */
+const noticeNamingBanner: ProactiveEventDefinition = {
+  class: "notice",
+  inboxKind: "proactive.org_became_shared",
+  // @ts-expect-error a notice has no banner; its `bannerType` is typed `never`
+  bannerType: "first_member_joined",
+};
+
+/** CLAIM 2 — an `announcement` claims a banner, so omitting one is an error. */
+// @ts-expect-error an announcement MUST name the banner its class earns
+const announcementOmittingBanner: ProactiveEventDefinition = {
+  class: "announcement",
+  chatTemplate: "orgBecameShared",
+  inboxKind: "proactive.org_became_shared",
+};
+
+/** CLAIM 3 — `explained` has no banner either; naming one is an error. */
+const explainedNamingBanner: ProactiveEventDefinition = {
+  class: "explained",
+  chatTemplate: "orgBecameShared",
+  inboxKind: "proactive.org_became_shared",
+  // @ts-expect-error explained has no banner; its `bannerType` is typed `never`
+  bannerType: "first_member_joined",
+};
+
+/**
+ * CLAIM 3, for the class the second real kind uses — `briefing` shares the
+ * `explained` member, so `brief.morning` could not name a banner even if it
+ * tried. This is the compile-time proof that adding it needed no machinery.
+ */
+const briefingNamingBanner: ProactiveEventDefinition = {
+  class: "briefing",
+  chatTemplate: "morningBrief",
+  inboxKind: "proactive.brief_morning",
+  // @ts-expect-error a briefing has no banner; its `bannerType` is typed `never`
+  bannerType: "first_member_joined",
+};
+
+// =============================================================================
+// Registries that are not total
+// =============================================================================
+
+/** CLAIM 4 — a kind with no plan: the registry is not total, so it is an error. */
+// @ts-expect-error a registry missing a kind's plan does not satisfy the Record
+const registryMissingKind = {} as const satisfies ProactiveRegistry;
+
+/** CLAIM 4, other direction — a plan for a string that is not a kind. */
+const registryNamingNonKind = {
+  ...PROACTIVE_EVENT_KINDS,
+  // @ts-expect-error a plan for a non-kind is an excess property
+  "made.up": PROACTIVE_EVENT_KINDS["org.became_shared"],
+} as const satisfies ProactiveRegistry;
+
+// =============================================================================
+// Exports — the runtime half lives in vocabulary.test.ts
+// =============================================================================
+
+/**
+ * The plans above, typed as the union they failed to satisfy. At runtime they
+ * are ordinary objects, which is what lets the vocabulary test show that the
+ * class-table check rejects every one of them.
+ */
+export const PLAN_FIXTURES_THE_COMPILER_REJECTS: Readonly<
+  Record<string, ProactiveEventDefinition>
+> = {
+  noticeNamingBanner,
+  announcementOmittingBanner,
+  explainedNamingBanner,
+  briefingNamingBanner,
+};
+
+/** The two ways a registry stops being total. */
+export const REGISTRY_FIXTURES_THE_COMPILER_REJECTS = {
+  registryMissingKind,
+  registryNamingNonKind,
+} as const;