@company-semantics/contracts 58.0.0 → 58.2.0

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