@company-semantics/contracts 58.1.0 → 58.3.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;

package/src/proactive/__tests__/vocabulary.test.ts

@@ -0,0 +1,279 @@
+/**
+ * The proactive vocabulary's invariants, as tests rather than prose
+ * (ADR-CONTRACTS-142).
+ *
+ * THE load-bearing test is `plan surfaces agree with the class table`. A kind
+ * carries ids and its surfaces come from its class, and nothing in the type
+ * system can check that the ids PRESENT on a plan match the surfaces its class
+ * DECLARES in `CLASS_SURFACES`. The union in `../plan` fixes that per member;
+ * this file checks the members against the table itself.
+ *
+ * The negative typecheck fixtures — the `@ts-expect-error` directives proving
+ * the four compile-error claims — live in `./compile-fixtures.ts`, a COMPILED
+ * module: `src/tsconfig.json` excludes `*.test.ts`, so a directive written here
+ * would never be checked, and an unused one would fail nothing. They are
+ * imported below so the runtime check is shown to reject exactly the plans the
+ * compiler rejects.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  CLASS_SURFACES,
+  PROACTIVE_PRESENTATION_CLASSES,
+  bornRead,
+} from "../classes";
+import type { ClassSurfacePlan, ProactivePresentationClass } from "../classes";
+import type { ProactiveChatMessage } from "../composer";
+import type { ProactiveChatFacts } from "../facts";
+import { PROACTIVE_EVENT_KIND_IDS } from "../kinds";
+import type { ProactiveEventDefinition } from "../plan";
+import { PROACTIVE_EVENT_KINDS } from "../registry";
+import { PROACTIVE_CHAT_TEMPLATES } from "../surfaces";
+import type { ProactiveChatTemplate } from "../surfaces";
+import { PROACTIVE_CHAT_COMPOSERS } from "../templates/index";
+import { USER_NOTIFICATION_KINDS } from "../../user-notifications/kinds";
+import {
+  PLAN_FIXTURES_THE_COMPILER_REJECTS,
+  REGISTRY_FIXTURES_THE_COMPILER_REJECTS,
+} from "./compile-fixtures";
+
+/**
+ * The registry, read as the union it satisfies rather than as its literal
+ * shape. Every member of `ProactiveEventDefinition` carries every id field
+ * (the absent ones as optional `never`), so a plan can be asked for an id it
+ * does not have and answer `undefined` — which is what the checks below need.
+ */
+const REGISTRY_ENTRIES: ReadonlyArray<
+  readonly [kind: string, plan: ProactiveEventDefinition]
+> = Object.entries(PROACTIVE_EVENT_KINDS);
+
+/**
+ * The ONE check the compiler cannot do, as a predicate: the ids present on a
+ * plan agree with the surfaces its class earns, and the inbox id is always
+ * there. Applied positively to the real registry and negatively to the plans
+ * the compiler rejects, so the two halves are shown to agree.
+ */
+function planAgreesWithClassTable(plan: ProactiveEventDefinition): boolean {
+  const surfaces: ClassSurfacePlan = CLASS_SURFACES[plan.class];
+  return (
+    (plan.bannerType !== undefined) === surfaces.banner &&
+    (plan.chatTemplate !== undefined) === surfaces.chat &&
+    plan.inboxKind !== undefined &&
+    surfaces.inbox
+  );
+}
+
+/**
+ * One facts factory per template, total over `ProactiveChatTemplate`. A
+ * FACTORY rather than a value so the purity test can hand a composer two
+ * structurally-equal but distinct objects — a composer that keyed anything on
+ * object identity would show up as a difference.
+ */
+const FRESH_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 fresh facts. The registry is a union of composers
+ * whose `compose` parameters differ per template, and TypeScript cannot
+ * correlate `PROACTIVE_CHAT_COMPOSERS[t]` with `FRESH_FACTS[t]` through a
+ * variable `t` — the cast is the one place the correlation is asserted, and
+ * the total factory record above is what keeps it honest.
+ */
+function composeFresh(template: ProactiveChatTemplate): ProactiveChatMessage {
+  const compose = PROACTIVE_CHAT_COMPOSERS[template].compose as (
+    facts: ProactiveChatFacts[ProactiveChatTemplate],
+  ) => ProactiveChatMessage;
+  return compose(FRESH_FACTS[template]());
+}
+
+describe("the class table", () => {
+  it("is total over PROACTIVE_PRESENTATION_CLASSES in practice", () => {
+    // `satisfies Record<...>` proves totality at compile time; this proves no
+    // entry is an accidental `undefined` and that no key is a non-class.
+    for (const cls of PROACTIVE_PRESENTATION_CLASSES) {
+      expect(CLASS_SURFACES[cls], cls).toBeDefined();
+    }
+    expect(Object.keys(CLASS_SURFACES).sort()).toEqual(
+      [...PROACTIVE_PRESENTATION_CLASSES].sort(),
+    );
+  });
+
+  it("every badge names a surface its class actually has", () => {
+    for (const cls of PROACTIVE_PRESENTATION_CLASSES) {
+      const surfaces: ClassSurfacePlan = CLASS_SURFACES[cls];
+      // Every class writes a durable row — `inbox` is literal true throughout.
+      expect(surfaces.inbox, `${cls} inbox`).toBe(true);
+      // The badge carrier must be a surface the class earns; the union makes
+      // the wrong pairing a compile error, and this is the same claim in
+      // practice.
+      expect(surfaces[surfaces.badge], `${cls} badge=${surfaces.badge}`).toBe(
+        true,
+      );
+    }
+  });
+
+  it("states the born-read rule once, and it matches the doctrine table", () => {
+    // The table in `../classes`: the badge carrier is the attention carrier,
+    // every other surface the class HAS is the paper trail. Pinned as the
+    // concrete rows the doctrine names rather than as a restatement of the
+    // helper's body, so a rewrite of `bornRead` that changed a row fails here.
+    // A surface the class does not earn has no row to be born into — `chat`
+    // is absent for `notice` — so it is not asked.
+    const expected: Record<
+      ProactivePresentationClass,
+      { readonly chat?: boolean; readonly inbox: boolean }
+    > = {
+      announcement: { chat: true, inbox: true },
+      explained: { chat: false, inbox: true },
+      briefing: { chat: false, inbox: true },
+      notice: { inbox: false },
+    };
+    for (const cls of PROACTIVE_PRESENTATION_CLASSES) {
+      const surfaces: ClassSurfacePlan = CLASS_SURFACES[cls];
+      const row = expected[cls];
+      expect(surfaces.chat, `${cls} has a chat`).toBe(row.chat !== undefined);
+      if (row.chat !== undefined) {
+        expect(bornRead(surfaces, "chat"), `${cls} chat`).toBe(row.chat);
+      }
+      expect(bornRead(surfaces, "inbox"), `${cls} inbox`).toBe(row.inbox);
+    }
+  });
+});
+
+describe("the kind registry", () => {
+  it("is total over PROACTIVE_EVENT_KIND_IDS in practice", () => {
+    for (const kind of PROACTIVE_EVENT_KIND_IDS) {
+      expect(PROACTIVE_EVENT_KINDS[kind], kind).toBeDefined();
+    }
+    expect(Object.keys(PROACTIVE_EVENT_KINDS).sort()).toEqual(
+      [...PROACTIVE_EVENT_KIND_IDS].sort(),
+    );
+  });
+
+  /**
+   * THE load-bearing test. A kind carries ids; its surfaces come from its
+   * class. Nothing in the type system can check that the ids present match the
+   * surfaces the class declares, so it is checked here.
+   */
+  it("plan surfaces agree with the class table", () => {
+    for (const [kind, plan] of REGISTRY_ENTRIES) {
+      const surfaces: ClassSurfacePlan = CLASS_SURFACES[plan.class];
+      expect(plan.bannerType !== undefined, `${kind} bannerType`).toBe(
+        surfaces.banner,
+      );
+      expect(plan.chatTemplate !== undefined, `${kind} chatTemplate`).toBe(
+        surfaces.chat,
+      );
+      expect(plan.inboxKind, `${kind} inboxKind`).toBeDefined();
+      expect(planAgreesWithClassTable(plan), kind).toBe(true);
+    }
+  });
+
+  it("every inbox kind is a real user notification kind", () => {
+    // Every class writes a durable row, so every plan names a row kind — and
+    // it must be one the inbox vocabulary actually has, or the backend writes
+    // a row no renderer owns.
+    for (const [kind, plan] of REGISTRY_ENTRIES) {
+      expect(USER_NOTIFICATION_KINDS, kind).toContain(plan.inboxKind);
+    }
+  });
+
+  it("names its inbox row in the proactive domain, never by the kind string", () => {
+    // Identical names across two unions is how one quietly becomes derived
+    // from the other (ADR-CONT-108). The producing domain is `proactive` —
+    // `src/proactive/` in the backend owns the renderer — matching the
+    // `companyMd.*` / `comment.*` convention.
+    for (const [kind, plan] of REGISTRY_ENTRIES) {
+      expect(plan.inboxKind, kind).not.toBe(kind);
+      expect(plan.inboxKind, kind).toMatch(/^proactive\./);
+    }
+  });
+
+  it("names kinds in {domain}.{type} form, matching the three unions", () => {
+    for (const kind of PROACTIVE_EVENT_KIND_IDS) {
+      expect(kind).toMatch(/^[a-z][a-zA-Z0-9]*\.[a-z][a-z0-9_]*$/);
+    }
+  });
+
+  it("every chat template has a composer", () => {
+    // The composer registry is total over PROACTIVE_CHAT_TEMPLATES at compile
+    // time; this proves the id a KIND names reaches a real composer whose
+    // `template` is that id, so the backend cannot write an empty message.
+    for (const [kind, plan] of REGISTRY_ENTRIES) {
+      if (plan.chatTemplate === undefined) continue;
+      const composer = PROACTIVE_CHAT_COMPOSERS[plan.chatTemplate];
+      expect(composer, kind).toBeDefined();
+      expect(composer.template, kind).toBe(plan.chatTemplate);
+    }
+  });
+
+  it("sets no emailKind in this wave", () => {
+    // notify/'s INV-1: every notification needs an explicit trigger; nothing
+    // sends autonomously. A kind that also emailed needs INV-PROACTIVE-TRIGGER
+    // reconciled with INV-1 in an ADR — lifting this assertion IS that ADR's
+    // job, not a tidy-up.
+    for (const [kind, plan] of REGISTRY_ENTRIES) {
+      expect(plan.emailKind, kind).toBeUndefined();
+    }
+  });
+});
+
+describe("the chat composers", () => {
+  it("composers are pure", () => {
+    // Same facts in, byte-identical message out — across two calls handed two
+    // distinct-but-equal facts objects. A clock, an env read, a counter or an
+    // identity-keyed cache would all surface as a difference here.
+    for (const template of PROACTIVE_CHAT_TEMPLATES) {
+      const first = composeFresh(template);
+      const second = composeFresh(template);
+      expect(JSON.stringify(first), template).toBe(JSON.stringify(second));
+      expect(first, template).toEqual(second);
+    }
+  });
+});
+
+describe("what the compiler rejects, the class-table check rejects too", () => {
+  it("rejects inconsistent plans at compile time", () => {
+    // The `@ts-expect-error` directives sit in ./compile-fixtures.ts, where
+    // `tsc -b` checks them. Here the same plans go through the runtime check:
+    // a notice naming a bannerType, an announcement omitting one, and an
+    // explained or a briefing naming one must all disagree with the class
+    // table.
+    const names = Object.keys(PLAN_FIXTURES_THE_COMPILER_REJECTS);
+    expect(names).toEqual([
+      "noticeNamingBanner",
+      "announcementOmittingBanner",
+      "explainedNamingBanner",
+      "briefingNamingBanner",
+    ]);
+    for (const [name, plan] of Object.entries(
+      PLAN_FIXTURES_THE_COMPILER_REJECTS,
+    )) {
+      expect(planAgreesWithClassTable(plan), name).toBe(false);
+    }
+  });
+
+  it("rejects a registry that is not total at compile time", () => {
+    // The fourth claim, both directions: a kind absent from the registry, and
+    // a plan for a string that is not a kind. The real registry passes the
+    // same two checks in `is total over PROACTIVE_EVENT_KIND_IDS in practice`.
+    const { registryMissingKind, registryNamingNonKind } =
+      REGISTRY_FIXTURES_THE_COMPILER_REJECTS;
+    const ids = new Set<string>(PROACTIVE_EVENT_KIND_IDS);
+    expect(
+      PROACTIVE_EVENT_KIND_IDS.some((kind) => !(kind in registryMissingKind)),
+    ).toBe(true);
+    expect(
+      Object.keys(registryNamingNonKind).some((key) => !ids.has(key)),
+    ).toBe(true);
+  });
+});

package/src/proactive/classes.ts

@@ -0,0 +1,125 @@
+/**
+ * Presentation classes — the TOTAL FUNCTION from "how loud is this" to "which
+ * surfaces does it earn" (control ADR slug
+ * `proactive-delivery-occurrence-audience-projection`, ADR-CONTRACTS-142).
+ *
+ * A proactive event kind carries its `class` plus the IDS each surface needs.
+ * It never restates the surface booleans; those are derived from this table.
+ * If a kind ever duplicated them, the compiler would be left having to prove
+ * two declarations agree — and it cannot, which is the guarantee this module
+ * exists to provide.
+ *
+ * INVARIANTS:
+ * - TOTAL in both directions. `as const satisfies Record<...>` means a class
+ *   with no entry fails to compile, and an entry for a non-class fails too.
+ * - EXACTLY ONE badge carrier per class. Never zero, never two — the badge is
+ *   the attention count, and a second carrier would double-count it.
+ * - EVERY class writes a durable inbox row. What varies is whether that row
+ *   is born read, and `bornRead` is the one place that rule is stated.
+ * - This is a LOUDNESS axis, not a severity axis. `error|warning|info` exists
+ *   in this package scoped to org-transformation findings and must not be
+ *   overloaded here.
+ */
+
+// =============================================================================
+// ProactivePresentationClass
+// =============================================================================
+
+/**
+ * The presentation class of a proactive occurrence — how LOUD it is and which
+ * surfaces it earns. Deliberately NOT a severity axis: `error|warning|info`
+ * exists in this package scoped to org-transformation findings and must not be
+ * overloaded.
+ *
+ * | class          | banner    | chat | inbox row | badge carrier |
+ * | -------------- | --------- | ---- | --------- | ------------- |
+ * | `announcement` | ack-gated | yes  | born read | banner        |
+ * | `explained`    | no        | yes  | born read | chat          |
+ * | `briefing`     | no        | yes  | born read | chat          |
+ * | `notice`       | no        | no   | unread    | inbox         |
+ */
+export const PROACTIVE_PRESENTATION_CLASSES = [
+  "announcement",
+  "explained",
+  "briefing",
+  "notice",
+] as const;
+export type ProactivePresentationClass =
+  (typeof PROACTIVE_PRESENTATION_CLASSES)[number];
+
+// =============================================================================
+// ClassSurfacePlan
+// =============================================================================
+
+/** Exactly one surface owns the unread badge. Never zero, never two. */
+export type BadgeCarrier = "banner" | "chat" | "inbox";
+
+/**
+ * A UNION, not a flat interface, so "the badge names a surface this class does
+ * not have" is a COMPILE error rather than a runtime surprise. Each member
+ * fixes the surfaces its badge carrier presupposes: a `banner` badge fixes
+ * `banner: true`; a `chat` badge fixes `banner: false, chat: true`; an `inbox`
+ * badge fixes both false.
+ *
+ * `inbox` is literal-true in every member: EVERY proactive event writes a
+ * durable row. What varies is whether that row is born read.
+ */
+export type ClassSurfacePlan =
+  | {
+      readonly badge: "banner";
+      readonly banner: true;
+      readonly chat: boolean;
+      readonly inbox: true;
+    }
+  | {
+      readonly badge: "chat";
+      readonly banner: false;
+      readonly chat: true;
+      readonly inbox: true;
+    }
+  | {
+      readonly badge: "inbox";
+      readonly banner: false;
+      readonly chat: false;
+      readonly inbox: true;
+    };
+
+// =============================================================================
+// CLASS_SURFACES
+// =============================================================================
+
+/**
+ * The class table. Totality is checked in BOTH directions by
+ * `satisfies Record<ProactivePresentationClass, ClassSurfacePlan>`: a new
+ * class with no entry fails, and an entry for a non-class fails. `as const`
+ * keeps each entry's literal shape, so `CLASS_SURFACES.notice.chat` is the
+ * type `false`, not `boolean`.
+ */
+export const CLASS_SURFACES = {
+  announcement: { banner: true, chat: true, inbox: true, badge: "banner" },
+  explained: { banner: false, chat: true, inbox: true, badge: "chat" },
+  briefing: { banner: false, chat: true, inbox: true, badge: "chat" },
+  notice: { banner: false, chat: false, inbox: true, badge: "inbox" },
+} as const satisfies Record<ProactivePresentationClass, ClassSurfacePlan>;
+
+// =============================================================================
+// bornRead
+// =============================================================================
+
+/**
+ * "Born read whenever a louder surface owns the badge" — stated ONCE.
+ *
+ * A backend that re-derives this per call site is how the two halves drift.
+ * The badge carrier is the attention carrier; every other surface is the paper
+ * trail (the rule generalised from the backend ADR slug
+ * `access-requested-inbox-born-read`).
+ *
+ * PURE: no clock, no env, no I/O. Only `chat` and `inbox` can be asked — the
+ * banner is ack-gated per recipient and has no read state to be born into.
+ */
+export function bornRead(
+  surfaces: ClassSurfacePlan,
+  surface: "chat" | "inbox",
+): boolean {
+  return surfaces.badge !== surface;
+}

package/src/proactive/composer.ts

@@ -0,0 +1,104 @@
+/**
+ * The pushed-chat composer port — what one chat template SAYS, given its facts
+ * (ADR-CONTRACTS-142).
+ *
+ * Copy lives here, in contracts, and not in the backend domain that writes the
+ * chat. That is the precedent notify/'s README states for outbound
+ * notifications — there is no templates/ directory in the sending domain;
+ * 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.
+ *
+ * Members are ARROW PROPERTIES, never method shorthand — the contracts
+ * vocabulary guard reads a method signature as behaviour smuggled into the
+ * vocabulary. Same rule, same reason, as `NotificationDefinition.compose`.
+ *
+ * INVARIANTS — three inherited from `NotificationDefinition`, one of its own:
+ *
+ * - PURE. `(facts)` in, message out. No clock, no environment, no I/O, no
+ *   ambient constant of its own. The same facts produce a byte-identical
+ *   message every time, which is what lets a test prove purity.
+ * - CONTENT ONLY. No markup, no styling, no channel names, no hrefs the app
+ *   owns. If a value is a formatting choice a renderer could reasonably make
+ *   differently, it is the renderer's.
+ * - TOTAL REGISTRY. `PROACTIVE_CHAT_COMPOSERS` in `./templates/index` is
+ *   checked in both directions over `PROACTIVE_CHAT_TEMPLATES`: a template
+ *   with no composer fails to compile, and a composer for a non-template
+ *   fails too.
+ * - FROZEN AT WRITE TIME (INV-PROACTIVE-CONTENT). The message is written ONCE
+ *   into `chat_messages.content` and never re-renders. It may therefore only
+ *   interpolate facts the recipient was entitled to at compose time. This is
+ *   the deliberate OPPOSITE of the durable-inbox rule — an inbox row holds
+ *   identifiers and is rendered at read time under the reader's CURRENT
+ *   authority — and both are correct: a transcript that changed under the
+ *   reader would be a lie about the conversation.
+ */
+
+import type { SuggestedReply } from "../message-parts/suggested-replies";
+import type { ProactiveChatFacts } from "./facts";
+import type { ProactiveChatTemplate } from "./surfaces";
+
+// =============================================================================
+// ProactiveChatMessage
+// =============================================================================
+
+/**
+ * At most this many chips under a pushed message. More than four is a menu,
+ * not a chip row.
+ */
+export const PROACTIVE_CHAT_MAX_REPLIES = 4;
+
+/**
+ * What a composer returns: the chat's title, the assistant turn's prose, and
+ * the chips beneath it.
+ *
+ * `replies` reuses the `SuggestedReply` vocabulary from `../message-parts`
+ * rather than redeclaring it — the backend writes these straight into a
+ * `suggested-replies` part, and one name for one shape keeps the two halves
+ * from drifting. A chip carries a `label` and an optional `prompt` because a
+ * short chip should be able to fire a full question.
+ */
+export interface ProactiveChatMessage {
+  /** The chat's `title` column. */
+  readonly title: string;
+  /** The assistant turn's prose — also `chat_messages.content`. */
+  readonly text: string;
+  /** 0..`PROACTIVE_CHAT_MAX_REPLIES` chips. */
+  readonly replies: readonly SuggestedReply[];
+}
+
+// =============================================================================
+// ProactiveChatComposer
+// =============================================================================
+
+/**
+ * One template's composer, parameterised by the template so `compose`
+ * receives that template's facts precisely rather than a union of every
+ * template's facts.
+ *
+ * A DISTRIBUTIVE conditional type rather than a generic object type with a
+ * union default, and the difference is load-bearing: `compose` is an arrow
+ * property, so it is checked contravariantly, and a composer that takes ONE
+ * template's facts is not assignable to one that takes the union of all facts.
+ * Distributing over `T` makes the bare `ProactiveChatComposer` a union of
+ * per-template composers, which is what `satisfies Record<ProactiveChatTemplate,
+ * ProactiveChatComposer>` in `./templates/index` needs to stay total once a
+ * second template with different facts joins the registry.
+ *
+ * `ProactiveChatFacts[T]` is the structural lock: a template without facts in
+ * `./facts` cannot be given a composer.
+ */
+export type ProactiveChatComposer<
+  T extends ProactiveChatTemplate = ProactiveChatTemplate,
+> = T extends unknown
+  ? {
+      /** The template this composes. MUST match its registry key. */
+      readonly template: T;
+      /**
+       * Say what this pushed chat says. Pure: `(facts)` in, message out —
+       * and frozen at write time, so only facts the recipient was entitled
+       * to at compose time (INV-PROACTIVE-CONTENT).
+       */
+      readonly compose: (facts: ProactiveChatFacts[T]) => ProactiveChatMessage;
+    }
+  : never;