@company-semantics/contracts 58.1.0 → 58.2.0

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?",
+      },
+    ],
+  }),
+};

package/src/proactive/templates/org-became-shared.ts

@@ -0,0 +1,54 @@
+/**
+ * The org-became-shared pushed chat — the first invited person accepted, so
+ * the owner's personal workspace is now a shared one (ADR-CONTRACTS-142).
+ *
+ * The prose NAMES THE RELOCATION, and that is its job. The app ADR with slug
+ * `nav-posture-opens-on-invite-send` established that conversion is a
+ * relocation, not an addition: five sections leave My settings (Integrations,
+ * Invite team members, AI Usage, Budget, Billing) and reappear under Org
+ * settings. Unannounced, that reads as things going missing — and a banner
+ * can say "something moved" but not walk the owner through what and why.
+ * This chat is where that explanation lives, and the chips let the owner ask
+ * the question the banner cannot answer.
+ *
+ * FROZEN AT WRITE TIME (INV-PROACTIVE-CONTENT). Both interpolated facts are
+ * things the owner was entitled to at compose time: they named the org, and
+ * they invited the person who accepted. Nothing here can be revoked later in
+ * a way the transcript would have to take back.
+ */
+
+import type { ProactiveChatComposer } from "../composer";
+
+export const orgBecameSharedComposer: ProactiveChatComposer<"orgBecameShared"> =
+  {
+    template: "orgBecameShared",
+    compose: (facts) => ({
+      title: "Your workspace is now shared",
+      text:
+        `${facts.joinerDisplayName} accepted your invite, so ${facts.orgName} ` +
+        `moved from a personal workspace to a shared one.\n\n` +
+        `This is a relocation, not an addition: Integrations, Invite team ` +
+        `members, AI Usage, Budget and Billing have moved out of My settings ` +
+        `and into Org settings. Nothing was removed — the five sections now ` +
+        `belong to the workspace rather than to you.`,
+      replies: [
+        {
+          id: "plain-english",
+          label: "Explain in plain English",
+          prompt:
+            "Explain in plain English what changed when my workspace became shared.",
+        },
+        {
+          id: "what-first",
+          label: "What should I set up first?",
+          prompt:
+            "Now that my workspace is shared, what should I set up first?",
+        },
+        {
+          id: "who-can-see",
+          label: "Who can see what now?",
+          prompt: "Who can see what in my workspace now that it is shared?",
+        },
+      ],
+    }),
+  };

package/src/resource-key-types.ts

@@ -150,6 +150,15 @@ export type ResourceKey =
   // every badge in the shell, and the two have different invalidation triggers
   // (a notification being READ changes the feed and not the bucket).
   | { type: "feed"; orgId: string }
+  /**
+   * Org system events (the banner strip).
+   *
+   * Lives HERE and not in the app's `AppOnlyKey` union, whose doc bar is "the
+   * server can never need to name this key" — here the server is the publisher.
+   * Once the banner is an asynchronous projection, an unsubscribed hook means a
+   * banner that only appears on next mount or reload.
+   */
+  | { type: "orgSystemEvents"; orgId: string }
   // User-scoped
   | { type: "dismissedBanners"; userId: string }
   | { type: "userOrgs"; userId: string }

package/src/resource-keys.ts

@@ -147,6 +147,7 @@ const ORG_SCOPED_TYPES = [
   "orgUnitOwners",
   "actionItems",
   "feed",
+  "orgSystemEvents",
 ] as const satisfies readonly OrgScopedType[];
 
 const USER_SCOPED_TYPES = [
@@ -285,6 +286,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "orgUnitOwners":
     case "actionItems":
     case "feed":
+    case "orgSystemEvents":
       return [key.type, key.orgId] as const;
 
     // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources

package/src/user-notifications/README.md

@@ -33,6 +33,16 @@ that renders them alongside action items at the top of `/me/work`.
 - **The cursor encodes `(createdAt, id)`.** The id breaks ties so two rows
   written in one transaction cannot straddle a page boundary and be served twice
   or skipped.
+- **A row can be BORN READ.** Every proactive kind writes a durable row here
+  as its paper trail, but only the class whose badge carrier is `inbox` writes
+  it unread; `proactive.org_became_shared` is an `announcement`, so the banner
+  holds the badge and the row arrives read, and `proactive.brief_morning` is a
+  `briefing`, so the pushed chat holds the badge and the row arrives read. That
+  rule is stated once, in `bornRead` (`../proactive/classes`), never re-derived
+  per call site (ADR-CONTRACTS-142). The kind strings are `proactive.*` — the
+  producing domain owns the renderer — and are deliberately not the
+  `ProactiveEventKind` strings `org.became_shared` / `brief.morning`, so
+  neither union can quietly become derived from the other.
 
 ## Public API
 

package/src/user-notifications/kinds.ts

@@ -76,6 +76,34 @@ export const USER_NOTIFICATION_KINDS = [
   "comment.mention",
   /** A thread you took part in got a new comment. Never emitted for an edit. */
   "comment.reply",
+  /**
+   * Your org stopped being personal — its first member joined
+   * (ADR-CONTRACTS-142). The durable row of the `org.became_shared` proactive
+   * kind.
+   *
+   * BORN READ: the banner holds the badge for an `announcement`, so this row
+   * is the paper trail and never the attention carrier (`bornRead` in
+   * `../proactive/classes` is the one place that rule is stated). The
+   * producing domain in the string is `proactive` — `src/proactive/` in the
+   * backend owns the renderer, matching the `companyMd.*` / `comment.*`
+   * convention. The string is deliberately DISTINCT from the proactive kind's
+   * `org.became_shared`: identical names across two unions is how one quietly
+   * becomes derived from the other, which ADR-CONT-108 forbids.
+   */
+  "proactive.org_became_shared",
+  /**
+   * Your morning brief was written (ADR-CONTRACTS-142). The durable row of
+   * the `brief.morning` proactive kind.
+   *
+   * BORN READ: the pushed chat holds the badge for a `briefing`, so this row
+   * is the paper trail and never the attention carrier (`bornRead` in
+   * `../proactive/classes` is the one place that rule is stated). One row per
+   * recipient per org-local day, pointing at that recipient's OWN chat — the
+   * occurrence is shared, the row and the chat are not. The string is
+   * deliberately DISTINCT from the proactive kind's `brief.morning`, for the
+   * reason stated on the member above.
+   */
+  "proactive.brief_morning",
 ] as const;
 
 export type UserNotificationKind = (typeof USER_NOTIFICATION_KINDS)[number];