@company-semantics/contracts 58.0.0 → 58.2.0

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;

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);
+  });
+});