@company-semantics/contracts 58.0.0 → 58.2.0

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;

package/src/proactive/facts.ts

@@ -0,0 +1,87 @@
+/**
+ * The FACTS each pushed-chat template composes from, keyed by template
+ * (ADR-CONTRACTS-142).
+ *
+ * Facts only — no copy, no formatted values. The composer in `./composer`
+ * turns these into prose; anything that is a phrasing choice belongs there,
+ * and anything that is a channel's formatting choice belongs in no vocabulary
+ * at all.
+ *
+ * Keyed by `ProactiveChatTemplate` for the same reason `NotificationPayloads`
+ * is keyed by `NotificationKind`: `ProactiveChatFacts[T]` is the structural
+ * lock between the two vocabularies. A template added to
+ * `PROACTIVE_CHAT_TEMPLATES` without facts here cannot be given a composer,
+ * and so cannot reach the registry.
+ *
+ * INVARIANTS:
+ * - Every fact is something the RECIPIENT was entitled to see at compose
+ *   time. The message is frozen into the transcript (INV-PROACTIVE-CONTENT in
+ *   `./composer`), so a fact that could later be revoked must not be
+ *   interpolated at all — there is no re-render to take it back.
+ * - Per-recipient personalisation lives HERE, in the facts, never in
+ *   occurrence identity. Two people in one org share an occurrence and
+ *   receive different prose because they were handed different facts.
+ */
+
+// =============================================================================
+// Per-template facts
+// =============================================================================
+
+/**
+ * The org just flipped from personal to shared: the first invited person
+ * accepted. Addressed to the owner who sent the invite.
+ */
+export interface OrgBecameSharedFacts {
+  /** The org's display name, as the owner knows it. */
+  readonly orgName: string;
+  /**
+   * Who accepted. A display name the owner already sees in the members list —
+   * the owner invited this person, so naming them discloses nothing new.
+   */
+  readonly joinerDisplayName: string;
+}
+
+/**
+ * The morning brief, for ONE recipient. This is where personalisation lives:
+ * two people in one org on one morning share an occurrence and are handed
+ * different facts, so they receive different prose.
+ *
+ * Every field is the recipient's own or the org's, as they see it — nothing
+ * here is a fact ABOUT another person. The counts are the recipient's own
+ * standing state and inbox, which they are entitled to at any moment; the
+ * message is frozen (INV-PROACTIVE-CONTENT), so a fact that could later be
+ * revoked would have no re-render to take it back, and none is included.
+ */
+export interface MorningBriefFacts {
+  /** The recipient's own display name, for the greeting. */
+  readonly recipientDisplayName: string;
+  /** The org's display name, as the recipient knows it. */
+  readonly orgName: string;
+  /**
+   * The org-local calendar day this brief is FOR, already rendered as the
+   * label the prose states ("Tuesday 25 August"). The ONE deliberate
+   * exception to "no formatted values": the day is an occurrence fact, but
+   * rendering it needs a locale and a time zone, and both are environment a
+   * pure composer must not read. The backend renders it once and hands it
+   * over as a fact.
+   */
+  readonly orgLocalDateLabel: string;
+  /** Decisions waiting on the recipient — THEIR action items, at compose time. */
+  readonly pendingActionItemCount: number;
+  /** Unread rows in the recipient's own inbox, at compose time. */
+  readonly unreadNotificationCount: number;
+}
+
+// =============================================================================
+// ProactiveChatFacts
+// =============================================================================
+
+/**
+ * Facts keyed by template. The index type `ProactiveChatFacts[T]` in
+ * `./composer` is what makes this total over `PROACTIVE_CHAT_TEMPLATES`: a
+ * template with no entry here fails at the composer's signature.
+ */
+export interface ProactiveChatFacts {
+  readonly orgBecameShared: OrgBecameSharedFacts;
+  readonly morningBrief: MorningBriefFacts;
+}

package/src/proactive/index.ts

@@ -0,0 +1,52 @@
+/**
+ * proactive/ — the vocabulary of proactive delivery: a presentation class that
+ * is a total function from class to surfaces, and kinds that carry ids, never
+ * surface booleans.
+ *
+ * See ./README.md for the domain, and ADR-CONTRACTS-142 for why this is a
+ * composer above the three notification vocabularies rather than a fourth peer.
+ */
+
+// The class table and the born-read rule
+export {
+  PROACTIVE_PRESENTATION_CLASSES,
+  CLASS_SURFACES,
+  bornRead,
+} from "./classes";
+export type {
+  ProactivePresentationClass,
+  BadgeCarrier,
+  ClassSurfacePlan,
+} from "./classes";
+
+// The ids a surface needs
+export { ORG_SYSTEM_EVENT_TYPES, PROACTIVE_CHAT_TEMPLATES } from "./surfaces";
+export type { OrgSystemEventType, ProactiveChatTemplate } from "./surfaces";
+
+// The kinds and the occurrence vocabulary
+export {
+  PROACTIVE_EVENT_KIND_IDS,
+  PROACTIVE_RECIPIENT_REASONS,
+  PROACTIVE_PROJECTIONS,
+} from "./kinds";
+export type {
+  ProactiveEventKind,
+  ProactiveEventId,
+  ProactiveRecipientReason,
+  ProactiveProjection,
+} from "./kinds";
+
+// The plan a kind carries, and the registry of every kind's plan
+export type { ProactiveEventDefinition } from "./plan";
+export { PROACTIVE_EVENT_KINDS } from "./registry";
+
+// The pushed-chat composer port, its facts, and the registry of every
+// template's prose
+export type {
+  OrgBecameSharedFacts,
+  MorningBriefFacts,
+  ProactiveChatFacts,
+} from "./facts";
+export { PROACTIVE_CHAT_MAX_REPLIES } from "./composer";
+export type { ProactiveChatComposer, ProactiveChatMessage } from "./composer";
+export { PROACTIVE_CHAT_COMPOSERS } from "./templates/index";

package/src/proactive/kinds.ts

@@ -0,0 +1,127 @@
+/**
+ * What kinds of proactive event exist, and the vocabulary of ONE OCCURRENCE:
+ * its id, why each recipient was addressed, and what was materialized for them
+ * (control ADR slug `proactive-delivery-occurrence-audience-projection`,
+ * ADR-CONTRACTS-142).
+ *
+ * A proactive event is the system speaking first. One OCCURRENCE is recorded
+ * with a frozen audience, and projected onto the surfaces its presentation
+ * class earns (`./classes`). The kind names the class and the ids; this module
+ * names the kinds and the occurrence vocabulary around them.
+ *
+ * INVARIANTS:
+ * - `{domain}.{type}` dot notation, matching the three notification unions.
+ *   These strings go on the wire (`proactiveKind` on a chat summary) and into
+ *   a database column. Renaming one is a migration, not a tidy-up.
+ * - A kind's string is DISTINCT from its inbox kind's string
+ *   (`org.became_shared` here, `proactive.org_became_shared` in
+ *   `../user-notifications`; `brief.morning` here, `proactive.brief_morning`
+ *   there). Identical names across two unions is how one
+ *   union quietly becomes derived from the other, which the ADR with slug
+ *   `user-notification-inbox-and-merged-feed` forbids.
+ * - Every kind has a plan in `./registry`. Enforced by the compiler, not by
+ *   this comment — the registry `satisfies Record<ProactiveEventKind, …>`.
+ */
+
+// =============================================================================
+// ProactiveEventKind
+// =============================================================================
+
+/**
+ * New kinds MUST be added to:
+ * 1. This array
+ * 2. `PROACTIVE_EVENT_KINDS` in `./registry`, with a plan whose class fixes
+ *    which ids the plan must and must not name
+ * 3. `USER_NOTIFICATION_KINDS`, because every class writes a durable row
+ *
+ * Step 2 is compiler-enforced; the array will not type-check without it.
+ */
+export const PROACTIVE_EVENT_KIND_IDS = [
+  /**
+   * The org stopped being personal: its first non-owner member joined. An
+   * `announcement` — it names the EXISTING `first_member_joined` banner, a
+   * pushed chat that explains the relocation of the settings sections, and a
+   * born-read inbox row.
+   */
+  "org.became_shared",
+  /**
+   * The morning brief. A `briefing` — a pushed chat that carries the badge
+   * and a born-read inbox row, and NO banner: the plan union in `./plan`
+   * types `bannerType` as `never` for this class, so the kind needs no new
+   * machinery to be kept out of the banner strip.
+   *
+   * ONE occurrence per org per org-local day, with N recipients. What differs
+   * between two people in the same org on the same morning is the FACTS each
+   * is handed (`MorningBriefFacts` in `./facts`), never the occurrence.
+   */
+  "brief.morning",
+] as const;
+export type ProactiveEventKind = (typeof PROACTIVE_EVENT_KIND_IDS)[number];
+
+// =============================================================================
+// ProactiveEventId
+// =============================================================================
+
+declare const ProactiveEventIdBrand: unique symbol;
+
+/**
+ * The id of ONE OCCURRENCE. Branded so a raw string cannot be passed where an
+ * occurrence id is required — the chat interaction key is derived from it, and
+ * a bare string there is how "one chat per kind per user forever" comes back.
+ *
+ * At runtime this is a plain string; the brand exists only in the type system
+ * (same idiom as `TraceId` in `../tracing`).
+ */
+export type ProactiveEventId = string & {
+  readonly [ProactiveEventIdBrand]: true;
+};
+
+// =============================================================================
+// ProactiveRecipientReason
+// =============================================================================
+
+/**
+ * WHY this occurrence was addressed to this person. A CLOSED set, not free
+ * text: `proactive_event_recipients` is relied on as the frozen audit record of
+ * the intended audience, and an unconstrained string would make that record
+ * unqueryable and let every new kind invent its own spelling.
+ */
+export const PROACTIVE_RECIPIENT_REASONS = [
+  /** Addressed because they own the org. */
+  "org_owner",
+  /** Addressed because they administer the org. */
+  "org_admin",
+  /** Addressed because they are a member of the org. */
+  "org_member",
+  /** Addressed because the occurrence is ABOUT them. */
+  "subject",
+  /** Addressed because they took part in the thing that happened. */
+  "participant",
+] as const;
+export type ProactiveRecipientReason =
+  (typeof PROACTIVE_RECIPIENT_REASONS)[number];
+
+// =============================================================================
+// ProactiveProjection
+// =============================================================================
+
+/**
+ * What was materialized for one recipient. Deliberately broader than the three
+ * presentation surfaces: an occurrence has zero or more PROJECTIONS, and the
+ * two orthogonal axes are projections too. For `notification_handoff` what is
+ * recorded is the successful handoff to notify/ and its correlation — email
+ * delivery itself remains notify/'s business.
+ */
+export const PROACTIVE_PROJECTIONS = [
+  /** An ack-gated banner row (an `org_system_event`). */
+  "banner",
+  /** A pushed chat, frozen into the transcript at write time. */
+  "chat",
+  /** A durable inbox row (a `user_notification`). */
+  "inbox",
+  /** Standing work state — a projection, NOT a loudness tier. */
+  "action_item",
+  /** The handoff to notify/ and its correlation id; not the delivery. */
+  "notification_handoff",
+] as const;
+export type ProactiveProjection = (typeof PROACTIVE_PROJECTIONS)[number];

package/src/proactive/plan.ts

@@ -0,0 +1,79 @@
+/**
+ * The plan a proactive kind carries: its presentation class plus the IDS each
+ * surface needs — never the surface booleans (ADR-CONTRACTS-142).
+ *
+ * `ProactiveEventDefinition` is a discriminated union on `class`, and each
+ * member fixes what the class in `./classes` says it earns:
+ *
+ * | class                  | bannerType | chatTemplate | inboxKind |
+ * | ---------------------- | ---------- | ------------ | --------- |
+ * | `announcement`         | REQUIRED   | REQUIRED     | REQUIRED  |
+ * | `explained` `briefing` | `never`    | REQUIRED     | REQUIRED  |
+ * | `notice`               | `never`    | `never`      | REQUIRED  |
+ *
+ * `never` is load-bearing: naming a banner a class does not have is a COMPILE
+ * error, not a field the backend has to remember to ignore. Restating the
+ * booleans on the kind would leave the compiler having to prove two
+ * declarations agree — this shape is what makes that unnecessary.
+ *
+ * The ONE consistency the compiler cannot express — that this union's members
+ * agree with `CLASS_SURFACES` — is pinned by the vocabulary test.
+ *
+ * INVARIANTS:
+ * - `inboxKind` is ALWAYS present. Every class writes a durable row; what
+ *   varies is whether it is born read (`bornRead` in `./classes`).
+ * - `emailKind` and `actionItemKind` are ORTHOGONAL axes, orthogonal for
+ *   DIFFERENT reasons. Email is off-platform delivery governed by notify/'s
+ *   policy (its INV-1: an explicit trigger, never autonomous sending). An
+ *   action item is a work-state projection — standing state you can resolve —
+ *   and not a loudness tier. Neither is derived from the class.
+ * - No kind sets `emailKind` in this wave. A scheduled briefing that also
+ *   emailed would need `INV-PROACTIVE-TRIGGER` reconciled with notify/'s INV-1
+ *   in an ADR, not silently.
+ */
+
+import type { ActionItemKind } from "../action-items/kinds";
+import type { NotificationKind } from "../notifications/kinds";
+import type { UserNotificationKind } from "../user-notifications/kinds";
+import type { OrgSystemEventType, ProactiveChatTemplate } from "./surfaces";
+
+// =============================================================================
+// ProactiveEventDefinition
+// =============================================================================
+
+/** The fields every class carries, whatever its loudness. */
+interface ProactivePlanCommon {
+  /** ALWAYS present — every proactive event writes a durable inbox row. */
+  readonly inboxKind: UserNotificationKind;
+  /** ORTHOGONAL axis: off-platform delivery. Absent = no email. */
+  readonly emailKind?: NotificationKind;
+  /** ORTHOGONAL axis: standing work state, NOT a loudness tier. */
+  readonly actionItemKind?: ActionItemKind;
+}
+
+/**
+ * A kind's plan, discriminated on `class`. Each member names exactly the ids
+ * its class's surfaces need and types the rest as `never`.
+ */
+export type ProactiveEventDefinition =
+  | (ProactivePlanCommon & {
+      readonly class: "announcement";
+      /** REQUIRED — the class claims a banner, so it MUST name one. */
+      readonly bannerType: OrgSystemEventType;
+      /** REQUIRED — the class claims a chat, so it MUST name its prose. */
+      readonly chatTemplate: ProactiveChatTemplate;
+    })
+  | (ProactivePlanCommon & {
+      readonly class: "explained" | "briefing";
+      /** `never` — naming a banner a class does not have is a COMPILE error. */
+      readonly bannerType?: never;
+      /** REQUIRED — the chat is this class's badge carrier. */
+      readonly chatTemplate: ProactiveChatTemplate;
+    })
+  | (ProactivePlanCommon & {
+      readonly class: "notice";
+      /** `never` — a notice has no banner. */
+      readonly bannerType?: never;
+      /** `never` — a notice has no chat; the inbox row carries the badge. */
+      readonly chatTemplate?: never;
+    });

package/src/proactive/registry.ts

@@ -0,0 +1,71 @@
+/**
+ * The proactive kind registry — every kind and its plan (ADR-CONTRACTS-142).
+ *
+ * A kind carries `class` plus the IDS each surface needs. It NEVER restates the
+ * surface booleans — those are derived from `CLASS_SURFACES` in `./classes`.
+ * Duplicating them would leave the compiler having to prove two declarations
+ * agree, which is the guarantee this shape exists to provide.
+ *
+ * INVARIANTS:
+ * - TOTAL in both directions. `as const satisfies Record<...>` means a kind
+ *   with no plan fails to compile, and a plan for a non-kind fails too.
+ * - `as const` keeps each plan's literal shape, so
+ *   `PROACTIVE_EVENT_KINDS["org.became_shared"].class` is the type
+ *   `"announcement"` and a consumer can index `CLASS_SURFACES` with it
+ *   precisely.
+ * - Each plan's ids agree with its class's surfaces. The union in `./plan`
+ *   enforces that per member; the vocabulary test pins the cross-check
+ *   against `CLASS_SURFACES` the compiler cannot see.
+ */
+
+import type { ProactiveEventKind } from "./kinds";
+import type { ProactiveEventDefinition } from "./plan";
+
+// =============================================================================
+// PROACTIVE_EVENT_KINDS
+// =============================================================================
+
+/**
+ * Every proactive kind and its plan.
+ *
+ * `org.became_shared` names the EXISTING `first_member_joined` banner type. It
+ * fires at exactly the personal-to-shared flip, so minting a second
+ * `org_system_event_type` would put two banners on one transition. Its inbox
+ * row is `proactive.org_became_shared` — a DISTINCT string from the kind, so
+ * neither union can be read as derived from the other — and it is born read,
+ * because the banner holds the badge.
+ *
+ * To add a kind:
+ * 1. Add it to `PROACTIVE_EVENT_KIND_IDS` in `./kinds`
+ * 2. Add its inbox kind to `USER_NOTIFICATION_KINDS`
+ * 3. Add its plan here; the class decides which ids it must and must not name
+ *
+ * Step 3 is compiler-enforced; step 1 alone will not type-check.
+ */
+export const PROACTIVE_EVENT_KINDS = {
+  "org.became_shared": {
+    class: "announcement",
+    bannerType: "first_member_joined",
+    chatTemplate: "orgBecameShared",
+    inboxKind: "proactive.org_became_shared",
+  },
+  /**
+   * The morning brief.
+   *
+   * class `briefing` => a chat (which carries the badge) + a BORN-READ inbox
+   * row, and NO banner. The plan union already types `bannerType` as `never`
+   * for this class, which is the compile-time proof the class table is doing
+   * its job: adding this kind needed no new machinery at all.
+   *
+   * ONE ORG OCCURRENCE PER ORG-LOCAL DAY, with N recipients. Personalisation
+   * lives in the per-recipient FACTS (`MorningBriefFacts`), never in
+   * occurrence identity — modelling it per user would mint one event row per
+   * person per day and give the system two shapes of occurrence to reason
+   * about.
+   */
+  "brief.morning": {
+    class: "briefing",
+    chatTemplate: "morningBrief",
+    inboxKind: "proactive.brief_morning",
+  },
+} as const satisfies Record<ProactiveEventKind, ProactiveEventDefinition>;