@company-semantics/contracts 58.1.0 → 58.3.0

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>;

package/src/proactive/surfaces.ts

@@ -0,0 +1,59 @@
+/**
+ * The IDS a surface needs — the vocabularies a proactive kind names INSTEAD of
+ * surface booleans (ADR-CONTRACTS-142).
+ *
+ * A kind never says `banner: true`; it says WHICH banner. This module holds
+ * the two id vocabularies the plan union in `./plan` draws on: the banner's
+ * `org_system_event_type` and the pushed-chat template. The durable inbox id
+ * is `UserNotificationKind` and lives in `../user-notifications`.
+ *
+ * INVARIANTS:
+ * - `ORG_SYSTEM_EVENT_TYPES` MIRRORS the backend `org_system_event_type`
+ *   pgEnum exactly. Contracts cannot import the schema, so the mirror is the
+ *   lock: a value here that the enum lacks is a banner nobody can write, and
+ *   a value the enum has that is absent here is a banner no kind can name.
+ *   Change both together.
+ * - A chat template earns membership by having a composer. The composer
+ *   registry (a later module) is total over this array, so adding a template
+ *   without prose is a compile error rather than an empty message.
+ */
+
+// =============================================================================
+// OrgSystemEventType
+// =============================================================================
+
+/**
+ * The banner types the org-level system-event table can record. Mirrors the
+ * backend `org_system_event_type` pgEnum value for value.
+ *
+ * `first_member_joined` is written AT MOST ONCE per org — a partial unique
+ * index makes the second write impossible — which is exactly why
+ * `org.became_shared` NAMES it rather than minting a third value. That kind
+ * fires at the personal-to-shared flip and nowhere else; a second value would
+ * put two banners on one transition.
+ */
+export const ORG_SYSTEM_EVENT_TYPES = [
+  /** Ownership of the org moved to a new owner. */
+  "ownership_transferred",
+  /** The first non-owner member joined — the org stopped being personal. */
+  "first_member_joined",
+] as const;
+export type OrgSystemEventType = (typeof ORG_SYSTEM_EVENT_TYPES)[number];
+
+// =============================================================================
+// ProactiveChatTemplate
+// =============================================================================
+
+/**
+ * Which prose composes a kind's pushed chat. Template ids are camelCase, unlike
+ * the dotted kind strings, because a template is a NAME FOR PROSE and not a
+ * `{domain}.{type}` fact — one kind names one template, but the template's
+ * facts are its own and are not the kind's payload.
+ */
+export const PROACTIVE_CHAT_TEMPLATES = [
+  /** "Your org just became shared — here is what moved and why." */
+  "orgBecameShared",
+  /** "Good morning — here is where things stand for you today." */
+  "morningBrief",
+] as const;
+export type ProactiveChatTemplate = (typeof PROACTIVE_CHAT_TEMPLATES)[number];

package/src/proactive/templates/README.md

@@ -0,0 +1,58 @@
+# proactive/templates/
+
+## Purpose
+
+One module per pushed-chat template (ADR-CONTRACTS-142). Each exports a single
+`ProactiveChatComposer<T>` whose `compose(facts)` says what that pushed chat
+says — its title, its prose and its chips — as content, never markup.
+
+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
+(no templates/ directory in the sending domain; copy belongs to contracts'
+`compose`), applied to the third surface.
+
+`index.ts` is the registry: `PROACTIVE_CHAT_COMPOSERS`, total over
+`PROACTIVE_CHAT_TEMPLATES` in both directions.
+
+## Invariants
+
+- `compose` is PURE and total: `(facts)` in, message out. No clock, no
+  environment, no I/O. The same facts produce a byte-identical message.
+- `compose` emits CONTENT — never markup, styling, hrefs the app owns or a
+  channel name.
+- **FROZEN AT WRITE TIME (INV-PROACTIVE-CONTENT).** The message is written once
+  into `chat_messages.content` and never re-renders, so a template may only
+  interpolate facts the recipient was entitled to at compose time. This is 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.
+- A template's `template` field equals its registry key. Enforced per entry by
+  the type and in practice by `../__tests__/chat-templates.test.ts`.
+- At most `PROACTIVE_CHAT_MAX_REPLIES` chips. More is a menu, not a chip row.
+- A file per template, named after it in kebab-case. Templates do not share a
+  module — the point is that a template is self-contained.
+- `org-became-shared.ts` NAMES THE RELOCATION: the five sections that leave My
+  settings for Org settings. Unannounced, that reads as things going missing
+  (the app ADR with slug `nav-posture-opens-on-invite-send`).
+- `morning-brief.ts` PERSONALISES THROUGH THE FACTS, never the occurrence. One
+  `brief.morning` occurrence per org per org-local day is shared by every
+  recipient; two people's briefs differ only because the `MorningBriefFacts`
+  they were handed differ. The composer does not know who it is composing for.
+  The org-local day arrives already rendered (`orgLocalDateLabel`) because
+  rendering it needs a locale and a time zone, and a pure composer reads
+  neither.
+
+## Public API
+
+| Export                     | Description                                                     |
+| -------------------------- | --------------------------------------------------------------- |
+| `PROACTIVE_CHAT_COMPOSERS` | The total template → composer registry                          |
+| `orgBecameSharedComposer`  | Prose for the personal-to-shared flip; names the relocation     |
+| `morningBriefComposer`     | Prose for one recipient's morning brief; personal via its facts |
+
+## Dependencies
+
+Type-only imports of `ProactiveChatComposer` (`../composer`),
+`ProactiveChatTemplate` (`../surfaces`) and the per-template facts
+(`../facts`). No `zod`, no runtime imports beyond the sibling template
+modules.

package/src/proactive/templates/index.ts

@@ -0,0 +1,32 @@
+/**
+ * The pushed-chat composer registry — every template and its prose
+ * (ADR-CONTRACTS-142).
+ *
+ * INVARIANTS:
+ * - TOTAL in both directions over `PROACTIVE_CHAT_TEMPLATES`. `as const
+ *   satisfies Record<...>` means a template with no composer fails to compile,
+ *   and a composer for a non-template fails too. A kind can therefore name a
+ *   `chatTemplate` in `../registry` and be sure prose exists for it.
+ * - Each composer's `template` equals the key it sits under. The type says so
+ *   per entry; the chat-templates test pins it in practice.
+ * - `as const` keeps each entry's literal shape, so
+ *   `PROACTIVE_CHAT_COMPOSERS.orgBecameShared.compose` takes exactly
+ *   `OrgBecameSharedFacts` rather than a union of every template's facts.
+ *
+ * To add a template:
+ * 1. Add it to `PROACTIVE_CHAT_TEMPLATES` in `../surfaces`
+ * 2. Add its facts to `ProactiveChatFacts` in `../facts`
+ * 3. Add a `<template>Composer` module beside this one, and register it here
+ *
+ * Step 1 alone will not type-check; that is the point.
+ */
+
+import type { ProactiveChatComposer } from "../composer";
+import type { ProactiveChatTemplate } from "../surfaces";
+import { morningBriefComposer } from "./morning-brief";
+import { orgBecameSharedComposer } from "./org-became-shared";
+
+export const PROACTIVE_CHAT_COMPOSERS = {
+  orgBecameShared: orgBecameSharedComposer,
+  morningBrief: morningBriefComposer,
+} as const satisfies Record<ProactiveChatTemplate, ProactiveChatComposer>;

package/src/proactive/templates/morning-brief.ts

@@ -0,0 +1,77 @@
+/**
+ * The morning-brief pushed chat — where things stand for ONE recipient on one
+ * org-local morning (ADR-CONTRACTS-142).
+ *
+ * The prose is PERSONAL and the occurrence is not: one `brief.morning`
+ * occurrence per org per day is shared by every recipient, and what makes two
+ * people's briefs differ is the `MorningBriefFacts` each was handed. Nothing
+ * in this module knows or cares which recipient it is composing for — that is
+ * exactly what keeps it pure.
+ *
+ * PURE. `(facts)` in, message out — no clock, no locale, no environment. The
+ * org-local day arrives already rendered (`orgLocalDateLabel`) for that reason.
+ *
+ * FROZEN AT WRITE TIME (INV-PROACTIVE-CONTENT). This prose is written once
+ * into the transcript and NEVER re-renders, so it may only interpolate facts
+ * the recipient was entitled to at compose time. Every fact it uses is the
+ * recipient's own — their name, their org's name, their counts — so there is
+ * nothing here a later revocation would have to take back.
+ */
+
+import type { ProactiveChatComposer } from "../composer";
+import type { MorningBriefFacts } from "../facts";
+
+/** "1 decision" / "3 decisions" — the one pluralisation the brief needs. */
+function counted(n: number, singular: string, plural: string): string {
+  return `${n} ${n === 1 ? singular : plural}`;
+}
+
+/**
+ * The sentence about what is waiting on the recipient. Only the non-zero
+ * counts are mentioned; a brief that says "0 decisions" is reading a table
+ * aloud, not briefing anyone.
+ */
+function standingLine(facts: MorningBriefFacts): string {
+  const parts: string[] = [];
+  if (facts.pendingActionItemCount > 0) {
+    parts.push(
+      `${counted(facts.pendingActionItemCount, "decision", "decisions")} waiting on you`,
+    );
+  }
+  if (facts.unreadNotificationCount > 0) {
+    parts.push(
+      counted(
+        facts.unreadNotificationCount,
+        "unread notification",
+        "unread notifications",
+      ),
+    );
+  }
+  if (parts.length === 0) {
+    return "Nothing is waiting on you, and your inbox is clear.";
+  }
+  return `You have ${parts.join(" and ")}.`;
+}
+
+export const morningBriefComposer: ProactiveChatComposer<"morningBrief"> = {
+  template: "morningBrief",
+  compose: (facts) => ({
+    title: `Your ${facts.orgLocalDateLabel} brief`,
+    text:
+      `Good morning, ${facts.recipientDisplayName}. Here is where ` +
+      `${facts.orgName} stands on ${facts.orgLocalDateLabel}.\n\n` +
+      standingLine(facts),
+    replies: [
+      {
+        id: "whats-changed",
+        label: "What changed since yesterday?",
+        prompt: "What changed in my workspace since yesterday?",
+      },
+      {
+        id: "needs-me",
+        label: "What needs me today?",
+        prompt: "What needs a decision from me today?",
+      },
+    ],
+  }),
+};