@company-semantics/contracts 34.0.0 → 35.0.0

package/src/notifications/kinds/unit-owner-granted.ts

@@ -0,0 +1,95 @@
+/**
+ * Unit-owner-granted notification (added to a team's unit ownership).
+ *
+ * THREE ROLE STRINGS, DELIBERATELY DIFFERENT — do not unify them:
+ * - `roleWord` ("owner" / "delegate owner") — the title's short form. Derived
+ *   here because the payload does not carry it; this is `subjectData`'s only job
+ *   in `renderEmail` today, and it folds into `compose` with it.
+ * - `roleNoun` ("unit owner" / "delegate owner") — the body's prose form. Note it
+ *   disagrees with `roleWord` for a formal owner, on purpose: the title is terse,
+ *   the body is explanatory.
+ * - `titleCase(roleLabel)` ("Unit Owner" / "Delegate") — the Role row's display
+ *   form, which is the payload's own label.
+ */
+
+import type { ChatUnitItem, KeyValueRow } from "../content";
+import type { NotificationDefinition } from "../definition";
+
+import { formatExpiry, NOTICE, titleCase } from "../text";
+
+export const unitOwnerGrantedDefinition: NotificationDefinition<"org.unit_owner_granted"> =
+  {
+    kind: "org.unit_owner_granted",
+    compose: (payload, context) => {
+      const {
+        granterName,
+        recipientName,
+        orgName,
+        unitName,
+        roleLabel,
+        ctaUrl,
+        message,
+        expiresAt,
+      } = payload;
+
+      const roleWord = roleLabel === "Delegate" ? "delegate owner" : "owner";
+      const roleNoun =
+        roleLabel === "Delegate" ? "delegate owner" : "unit owner";
+
+      const items: ChatUnitItem[] = [
+        ...(message
+          ? [
+              {
+                type: "message" as const,
+                role: "user" as const,
+                text: message,
+                from: granterName,
+              },
+            ]
+          : []),
+        {
+          type: "message",
+          role: "assistant",
+          text: "Open the team to get started.",
+        },
+        { type: "callToAction", label: "MANAGE TEAM", href: ctaUrl },
+      ];
+
+      const rows: KeyValueRow[] = [
+        { label: "From", value: granterName },
+        { label: "Team", value: unitName },
+        { label: "Role", value: titleCase(roleLabel) },
+        ...(expiresAt != null
+          ? [{ label: "Expires", value: formatExpiry(expiresAt) }]
+          : []),
+      ];
+
+      return {
+        metadata: {
+          kind: "org.unit_owner_granted",
+          title: `You've been added as ${roleWord} to ${unitName} in ${orgName}`,
+        },
+        sections: [
+          {
+            elements: [
+              { type: "greeting", ...(recipientName ? { recipientName } : {}) },
+              {
+                type: "body",
+                text: `You are now a ${roleNoun} of ${unitName}. ${roleNoun[0].toUpperCase()}${roleNoun.slice(1)}s hold authority over the team: managing team membership, doc access, strategy, and execution against goals.`,
+              },
+              { type: "chatUnit", items },
+              { type: "keyValueTable", rows },
+              {
+                type: "notice",
+                lines: [
+                  `This notification was sent via ${context.brand.name}.`,
+                  NOTICE,
+                ],
+              },
+              { type: "signature" },
+            ],
+          },
+        ],
+      };
+    },
+  };

package/src/notifications/kinds.ts

@@ -0,0 +1,68 @@
+/**
+ * What notifications exist (ADR-CONTRACTS-085).
+ *
+ * `NotificationKind` is the old `EmailKind` renamed and narrowed to the kinds
+ * that can actually be composed. `EmailKind` derived from this union while both
+ * layers existed; it was deleted with `src/email/` (ADR-CONTRACTS-086), so this
+ * is now the only union of its kind in the package.
+ *
+ * NOTE ON MODULE RESOLUTION: this file is `kinds.ts` and its neighbour is the
+ * `kinds/` directory. Under `moduleResolution: "bundler"` the specifier
+ * `./kinds` resolves to THIS FILE, never to `kinds/index.ts` — import the
+ * definition barrel explicitly as `./kinds/index`. The split is deliberate: this
+ * file is the vocabulary (which kinds exist), the directory is one definition
+ * per kind (what each one says).
+ *
+ * INVARIANTS:
+ * - Every member has a payload in `./payloads` and a definition in `./kinds/`.
+ *   Both are enforced structurally rather than by comment — see `./definition`
+ *   and `./registry`.
+ * - `{domain}.{type}` dot notation, matching the ids the email layer shipped on
+ *   the wire. These strings are persisted by consumers; renaming one is a
+ *   breaking change, not a tidy-up.
+ */
+
+// =============================================================================
+// NotificationKind Union
+// =============================================================================
+
+/**
+ * NotificationKind identifies the type of transactional notification.
+ *
+ * Naming convention: `{domain}.{type}`
+ * - domain: auth, org, security, chat, share, companyMd
+ * - type: specific notification variant
+ *
+ * This union is exactly the kinds with a `compose` implementation — the 11 the
+ * email layer could render, and deliberately NOT the 12 its `EmailKind` had.
+ * `auth.magic_link` was registered with a subject but never had a template, so
+ * the old `renderEmail("auth.magic_link", …)` type-checked and then threw at
+ * runtime. Excluding it closes that hole by construction: a kind IS its
+ * definition, `NOTIFICATION_DEFINITIONS` is total, and
+ * `getNotificationKindDefinition` cannot fail. A kind earns membership by having
+ * something to say, not by having a subject line reserved for it.
+ *
+ * That kind and its reserved subject left the package with `src/email/` and have
+ * no replacement here. Magic-link login is not a thing this layer can say; if it
+ * returns, it returns as a definition like any other.
+ *
+ * New kinds MUST be added to:
+ * 1. This union
+ * 2. `NotificationPayloads` in `./payloads`
+ * 3. A definition module under `./kinds/`, exported from `./kinds/index`
+ * 4. `NOTIFICATION_DEFINITIONS` in `./registry`
+ *
+ * Steps 2 and 4 are compiler-enforced; the union will not type-check without them.
+ */
+export type NotificationKind =
+  | "auth.otp"
+  | "org.invite"
+  | "org.unit_owner_granted"
+  | "org.ownership_transfer"
+  | "org.ownership_transfer_completed"
+  | "security.alert"
+  | "chat.shared"
+  | "share.granted"
+  | "companyMd.access_requested"
+  | "companyMd.access_request_approved"
+  | "companyMd.access_request_denied";

package/src/{email/types.ts → notifications/payloads.ts}

@@ -1,61 +1,47 @@
 /**
- * Email Domain Types
+ * The business facts each notification kind carries (ADR-CONTRACTS-085).
  *
- * Shared types for transactional email across Company Semantics codebases.
- * Types only - no runtime code, no business logic.
+ * This is the old `EmailPayloads` renamed, not redesigned: the same per-kind
+ * fields, in the same shapes, moved to the layer that actually owns them. A
+ * payload was never an email concept — "who invited you, to which workspace,
+ * until when" is true of the notification regardless of whether it arrives as an
+ * email, a chat message or a push. `EmailPayloads` aliased this type while both
+ * layers existed, and was deleted with `src/email/` (ADR-CONTRACTS-086).
  *
- * @see ADR-CONT-034 for design rationale
- */
-
-// =============================================================================
-// EmailKind Union
-// =============================================================================
-
-/**
- * EmailKind identifies the type of transactional email.
+ * A payload carries FACTS, never copy. "Jun 13, 2026" and "You've been added as
+ * owner" are `compose`'s output, not a caller's input — that split is what lets
+ * one payload render to every channel.
  *
- * Naming convention: `{domain}.{type}`
- * - domain: auth, org, security
- * - type: specific email variant
- *
- * New kinds MUST be added to:
- * 1. This union type
- * 2. EMAIL_KINDS registry in registry.ts
- * 3. EmailPayloads interface (if kind has payload)
+ * INVARIANTS:
+ * - Types only. No markup, no copy, no formatted values — an `expiresAt` is an
+ *   ISO timestamp here and becomes a date string in `compose`.
+ * - Keys are exactly `NotificationKind`. `../definition` enforces this
+ *   structurally: `NotificationPayloads[K]` fails to compile for a kind with no
+ *   entry here, so a kind cannot exist without its facts.
  */
-export type EmailKind =
-  | "auth.otp"
-  | "auth.magic_link" // future
-  | "org.invite" // future
-  | "org.unit_owner_granted"
-  | "org.ownership_transfer"
-  | "org.ownership_transfer_completed"
-  | "security.alert" // future
-  | "chat.shared"
-  | "share.granted"
-  | "companyMd.access_requested"
-  | "companyMd.access_request_approved"
-  | "companyMd.access_request_denied";
 
 // =============================================================================
-// Email Payloads
+// Notification Payloads
 // =============================================================================
 
 /**
- * Type-safe payload mapping for each email kind.
+ * Type-safe payload mapping for each notification kind.
  *
- * Each key is an EmailKind, and the value is the required payload shape.
- * Kinds without entries here have empty payloads.
+ * Each key is a `NotificationKind`, and the value is the required payload shape.
  */
-export interface EmailPayloads {
+export interface NotificationPayloads {
   "auth.otp": {
     /** The 6-digit OTP code */
     otp: string;
     /** How long until the code expires */
     expiresInMinutes: number;
-    /** IP address of the request (for security context) */
+    /**
+     * IP address of the request (for security context). PII under GDPR: the
+     * caller decides whether to supply it at all, and `compose` shows request
+     * details only when it is present. See ADR-CONTRACTS-085.
+     */
     requestIp?: string;
-    /** User agent of the request (for security context) */
+    /** User agent of the request (for security context). PII-gated upstream, as `requestIp`. */
     userAgent?: string;
   };
   "org.invite": {
@@ -71,7 +57,7 @@ export interface EmailPayloads {
     granterName: string;
     /** Display name of the recipient (optional; falls back to a neutral greeting) */
     recipientName?: string;
-    /** Name of the organization / workspace (rendered in the subject) */
+    /** Name of the organization / workspace (rendered in the title) */
     orgName: string;
     /** Name of the org unit / team the access applies to */
     unitName: string;
@@ -79,13 +65,13 @@ export interface EmailPayloads {
     roleLabel: "Unit owner" | "Delegate";
     /** Full URL to view the org unit in the app */
     ctaUrl: string;
-    /** Optional message from the granter, shown in the email and recorded with the grant */
+    /** Optional message from the granter, shown in the notification and recorded with the grant */
     message?: string;
     /** ISO timestamp when the grant expires. Absent = permanent (formal unit owners; delegations with no expiry). Rendered as the last key/value row ("Expires: Jun 13, 2026") when present. */
     expiresAt?: string;
   };
   "org.ownership_transfer": {
-    /** Name of the organization being transferred (subject is static; org name renders in the body) */
+    /** Name of the organization being transferred (title is static; org name renders in the body) */
     orgName: string;
     /** Full URL to accept the transfer (token-bearing) */
     acceptUrl: string;
@@ -119,7 +105,7 @@ export interface EmailPayloads {
     shareUrl: string;
     /** Share visibility mode */
     visibility: "private" | "public";
-    /** First ~200 chars of chat content for email preview. Generated server-side from snapshot. */
+    /** First ~200 chars of chat content for preview. Generated server-side from snapshot. */
     previewText?: string;
   };
   "share.granted": {
@@ -135,7 +121,7 @@ export interface EmailPayloads {
     accessLevel: "editor" | "commenter" | "viewer";
     /** Full URL to view the shared entity in the app */
     ctaUrl: string;
-    /** Optional message from the granter, included in the email only (not persisted) */
+    /** Optional message from the granter, included in the notification only (not persisted) */
     message?: string;
   };
   /** Sent to the doc owner(s) when an actor requests access (ADR-BE-338). */
@@ -144,7 +130,7 @@ export interface EmailPayloads {
     requesterName: string;
     /** Title of the company.md node access is requested for */
     docTitle: string;
-    /** Optional message from the requester (email only) */
+    /** Optional message from the requester (notification only) */
     message?: string;
     /** Deep-link that opens the doc's ShareDialog scrolled to the pending request */
     reviewUrl: string;
@@ -166,28 +152,7 @@ export interface EmailPayloads {
     approverName: string;
     /** Title of the company.md node */
     docTitle: string;
-    /** Optional reason from the owner (email only) */
+    /** Optional reason from the owner (notification only) */
     reason?: string;
   };
 }
-
-// =============================================================================
-// Send Email Input
-// =============================================================================
-
-/**
- * Type-safe input for sending emails.
- *
- * The payload type is inferred from the kind.
- * If the kind is in EmailPayloads, that payload is required.
- */
-export interface SendEmailInput<K extends EmailKind> {
-  /** The type of email to send */
-  kind: K;
-  /** Recipient email address (will be normalized) */
-  to: string;
-  /** Type-safe payload for this email kind */
-  payload: K extends keyof EmailPayloads ? EmailPayloads[K] : never;
-  /** Idempotency key to prevent duplicate sends */
-  idempotencyKey: string;
-}

package/src/notifications/registry.ts

@@ -0,0 +1,107 @@
+/**
+ * The notification definition registry (ADR-CONTRACTS-085).
+ *
+ * `NOTIFICATION_DEFINITIONS` is the single source of truth for what each kind
+ * says, and replaced `EMAIL_KINDS` as the place a caller starts from. What it
+ * does not hold is as important as what it does: no subject (that is
+ * `compose`'s `metadata.title`), and no `plainTextRequired` / `htmlSupported`
+ * (that is `Renderer.supports`). What remains is the kind and how to say it.
+ *
+ * INVARIANTS:
+ * - Exhaustive over `NotificationKind`, by construction — `NotificationDefinitions`
+ *   is a mapped type, so a kind with no entry is a compile error rather than an
+ *   `undefined` at runtime.
+ * - Registry keys MUST match `definition.kind`. Enforced by the mapped type: the
+ *   value at key `K` is a `NotificationDefinition<K>`, whose `kind` is `K`.
+ * - Total: `getNotificationKindDefinition` cannot fail for a `NotificationKind`.
+ *   This is the improvement on `EMAIL_KINDS`, where `auth.magic_link` type-checked
+ *   and then threw — see `./kinds` for why the union excludes it.
+ */
+
+import type { NotificationDefinition } from "./definition";
+import type { NotificationKind } from "./kinds";
+
+import {
+  accessApprovedDefinition,
+  accessDeniedDefinition,
+  accessRequestedDefinition,
+  authOtpDefinition,
+  chatSharedDefinition,
+  orgInviteDefinition,
+  ownershipTransferCompletedDefinition,
+  ownershipTransferDefinition,
+  securityAlertDefinition,
+  shareGrantedDefinition,
+  unitOwnerGrantedDefinition,
+} from "./kinds/index";
+
+// =============================================================================
+// Registry
+// =============================================================================
+
+/**
+ * The registry's shape: `Record<NotificationKind, NotificationDefinition>` made
+ * per-kind precise.
+ *
+ * A plain `Record` would widen every `compose` to accept a union of all eleven
+ * payloads, and — since `compose` is an arrow property, checked contravariantly
+ * — no real definition would be assignable to it. The mapped type keeps each
+ * kind bound to its own payload, which is what a caller wants anyway.
+ */
+export type NotificationDefinitions = {
+  [K in NotificationKind]: NotificationDefinition<K>;
+};
+
+/**
+ * Every notification kind and its definition.
+ *
+ * To add a kind:
+ * 1. Add it to `NotificationKind` in `./kinds`
+ * 2. Add its facts to `NotificationPayloads` in `./payloads`
+ * 3. Write `./kinds/{kind}.ts` and export it from `./kinds/index`
+ * 4. Add it here
+ *
+ * Steps 2–4 are compiler-enforced; step 1 alone will not type-check.
+ */
+export const NOTIFICATION_DEFINITIONS: NotificationDefinitions = {
+  "auth.otp": authOtpDefinition,
+  "org.invite": orgInviteDefinition,
+  "org.unit_owner_granted": unitOwnerGrantedDefinition,
+  "org.ownership_transfer": ownershipTransferDefinition,
+  "org.ownership_transfer_completed": ownershipTransferCompletedDefinition,
+  "security.alert": securityAlertDefinition,
+  "chat.shared": chatSharedDefinition,
+  "share.granted": shareGrantedDefinition,
+  "companyMd.access_requested": accessRequestedDefinition,
+  "companyMd.access_request_approved": accessApprovedDefinition,
+  "companyMd.access_request_denied": accessDeniedDefinition,
+};
+
+// =============================================================================
+// Registry Helpers
+// =============================================================================
+
+/**
+ * Type-safe registry lookup. Generic in `K` so a caller with a literal kind gets
+ * that kind's definition — and so its `compose` takes that kind's payload —
+ * rather than a union it would have to narrow again.
+ */
+export function getNotificationKindDefinition<K extends NotificationKind>(
+  kind: K,
+): NotificationDefinitions[K] {
+  return NOTIFICATION_DEFINITIONS[kind];
+}
+
+/**
+ * Check if a string is a valid `NotificationKind`.
+ * Use at API boundaries to reject unknown kinds.
+ *
+ * `Object.hasOwn`, not `in`: this is fed untrusted strings by definition, and
+ * `in` walks the prototype chain — the old `isValidEmailKind("toString")`
+ * returned true. The registry's OWN keys are the vocabulary; `Object`'s are not.
+ */
+export function isValidNotificationKind(
+  kind: string,
+): kind is NotificationKind {
+  return Object.hasOwn(NOTIFICATION_DEFINITIONS, kind);
+}

package/src/notifications/render.ts

@@ -0,0 +1,106 @@
+/**
+ * The entry point (ADR-CONTRACTS-086).
+ *
+ * `renderToChannel` is the whole pipeline in one call: look the kind up in
+ * `NOTIFICATION_DEFINITIONS`, `compose` its payload into channel-agnostic
+ * `NotificationContent`, hand that to a `Renderer`. Every piece already existed
+ * and is already proven byte-for-byte against the output-parity golden — this
+ * module is the wiring, not a rendering change.
+ *
+ * What it deliberately does NOT do is dispatch. The old `renderEmail` was a
+ * twelve-arm `switch` that threw on the one arm it did not have; here the
+ * registry is a mapped type over `NotificationKind`, so the lookup cannot miss
+ * and there is no `default:` to fall into. Adding a channel adds a `Renderer`
+ * and touches nothing here; adding a kind adds a definition and touches nothing
+ * here. That is the point of the seam.
+ *
+ * `renderEmail` is a convenience over it, kept because email is the channel
+ * every caller has today and `renderToChannel(kind, payload, emailRenderer,
+ * createRenderContext())` is a lot of ceremony for "send this email". It REPLACES
+ * the old `email/render/render-email`, which was deleted along with the `./email`
+ * subpath (ADR-CONTRACTS-086) — same name, different third argument: a
+ * render-context concern rather than `RenderEmailOptions`.
+ * `includeRequestMetadata` has no equivalent and needs none — `auth.otp`'s
+ * `compose` gates request details on whether the payload carries them, so the
+ * decision stays with the caller that holds the policy instead of being handed
+ * PII and told to ignore it.
+ *
+ * INVARIANTS:
+ * - `renderToChannel` is PURE when given a `RenderContext`. It reads the clock
+ *   only to build one when the caller supplies none, and only via
+ *   `createRenderContext` — the single sanctioned clock read in this domain.
+ *   Pass a context to get reproducible bytes.
+ * - Output MUST equal what the old email layer emitted, byte for byte, for every
+ *   fixture in `__tests__/output-parity.golden.ts`. That is what
+ *   `__tests__/output-parity.test.ts` asserts, and it is the only reason this
+ *   rewiring is safe. The golden is now the sole record of those bytes.
+ * - A kind's `defaults` layer UNDER the caller's wishes, never over them. A full
+ *   `RenderContext` has no gaps left to fill, so it wins outright; partial
+ *   overrides are filled from `defaults` first and the package default last.
+ * - Depends only on this domain. The cycle back into `../email` that this layer
+ *   existed to unwind is gone with the directory; nothing may reintroduce one.
+ */
+
+import type { RenderContext, RenderContextOverrides } from "./context";
+import { createRenderContext } from "./context";
+import type { NotificationKind } from "./kinds";
+import type { NotificationPayloads } from "./payloads";
+import { NOTIFICATION_DEFINITIONS } from "./registry";
+import type { Renderer } from "./renderer";
+import type { RenderedEmail } from "./renderers/email";
+import { emailRenderer } from "./renderers/email";
+
+/**
+ * Layer a kind's `defaults` under a caller's overrides, field by field.
+ *
+ * Shallow-merging `brand` rather than replacing it is the difference between
+ * "the caller pinned the year" and "the caller pinned the year and silently lost
+ * the kind's signer".
+ */
+function layerOverrides(
+  defaults: RenderContextOverrides | undefined,
+  overrides: RenderContextOverrides | undefined,
+): RenderContextOverrides {
+  return { brand: { ...defaults?.brand, ...overrides?.brand } };
+}
+
+/**
+ * Render a notification to one channel: compose the kind's content, then let the
+ * renderer say it.
+ *
+ * Generic in `K` so a caller with a literal kind is held to that kind's payload,
+ * and in `Out` so the renderer's natural type comes back — `RenderedEmail` for
+ * email, whatever the next channel returns for the next channel. Forcing a
+ * common output shape would recreate the fusion this layer unpicks.
+ *
+ * @param context Pin it for reproducible bytes. Omitted, it is built from the
+ * kind's `defaults` and today's date — the one clock read.
+ */
+export function renderToChannel<K extends NotificationKind, Out>(
+  kind: K,
+  payload: NotificationPayloads[K],
+  renderer: Renderer<Out>,
+  context?: RenderContext,
+): Out {
+  const definition = NOTIFICATION_DEFINITIONS[kind];
+  const resolved = context ?? createRenderContext(definition.defaults);
+  return renderer.render(definition.compose(payload, resolved), resolved);
+}
+
+/**
+ * Render a notification as an email.
+ *
+ * The third argument is `RenderContextOverrides`, not options: there is nothing
+ * left to opt into. The subject is `compose`'s `metadata.title`, and request
+ * metadata is decided by what the payload carries.
+ */
+export function renderEmail<K extends NotificationKind>(
+  kind: K,
+  payload: NotificationPayloads[K],
+  overrides?: RenderContextOverrides,
+): RenderedEmail {
+  const context = createRenderContext(
+    layerOverrides(NOTIFICATION_DEFINITIONS[kind].defaults, overrides),
+  );
+  return renderToChannel(kind, payload, emailRenderer, context);
+}

package/src/notifications/renderer.ts

@@ -0,0 +1,50 @@
+/**
+ * The channel seam (ADR-CONTRACTS-086).
+ *
+ * A `Renderer` turns channel-agnostic `NotificationContent` into one channel's
+ * bytes. Email becomes one renderer rather than the shape of the whole layer.
+ *
+ * Two things are deliberate here.
+ *
+ * **Capability lives on the renderer, not the content.** `supports` asks a
+ * renderer what it can depict. The alternative — tagging elements with the
+ * channels they apply to — makes every new channel a rewrite of the content, and
+ * puts knowledge of the channel back inside the thing that is supposed to be
+ * channel-agnostic. This also superseded the `plainTextRequired` /
+ * `htmlSupported` flags on the old `EmailKindDefinition`, which put capability on
+ * the kind: the kind is not what can or cannot draw an image.
+ *
+ * **Each renderer returns its natural type.** `Out` is `{ subject, text, html }`
+ * for email and something else entirely for the next channel. Forcing a common
+ * output shape would recreate the fusion this layer unpicked — the old `Block`,
+ * which carried `html` and `text` together and would have carried a third
+ * surface bolted on.
+ *
+ * Delivery and policy stay OUT of contracts: a renderer renders, it does not
+ * send, and nothing here decides whether to.
+ *
+ * INVARIANTS:
+ * - Pure — `render` is a function of `(content, context)` and nothing else. No
+ *   clock, no environment, no I/O. Ambient state arrives via `RenderContext`.
+ * - `supports` is total over `NotificationElementType` and must agree with
+ *   `render`: if it answers `false`, `render` MUST omit that element rather than
+ *   throw or approximate it.
+ */
+
+import type { NotificationContent, NotificationElementType } from "./content";
+import type { RenderContext } from "./context";
+
+/**
+ * A channel's renderer. `Out` is whatever that channel's bytes look like.
+ *
+ * Members are arrow properties, not method shorthand: the vocabulary-guard reads
+ * method signatures as behaviour smuggled into the vocabulary.
+ */
+export interface Renderer<Out> {
+  /** Stable channel identity, e.g. "email". */
+  id: string;
+  /** Whether this channel can depict the given element. Must be total. */
+  supports: (elementType: NotificationElementType) => boolean;
+  /** Render the whole notification. Pure. */
+  render: (content: NotificationContent, context: RenderContext) => Out;
+}

package/src/notifications/renderers/README.md

@@ -0,0 +1,50 @@
+# notifications/renderers/
+
+## Purpose
+
+One directory per channel (ADR-CONTRACTS-086). A renderer turns
+channel-agnostic `NotificationContent` into one channel's bytes, and is the
+only place in this package that knows what a sentence looks like.
+
+- `email/` — `Renderer<RenderedEmail>`, the first and richest channel. It is the
+  old `src/email/render` layer relocated behind the seam, and — now that the
+  original is deleted — what replaced it: email demoted from "the shape of the
+  whole layer" to one channel among several.
+- `sms/` — `Renderer<string>`, a non-functional placeholder. The poorest channel
+  the vocabulary will meet: no markup, no images, no layout.
+- `slack/` — `Renderer<SlackMessage>`, a non-functional placeholder. A minimal
+  Block Kit tree.
+
+A channel is added by writing a directory here — not by editing `../content.ts`,
+`../definition.ts` or any kind. That is the property the seam exists for, and the
+measure of whether it holds.
+
+`sms/` and `slack/` are that measure, cashed. Email could satisfy `Renderer` by
+construction — the seam was drawn around it, so it proves nothing on its own.
+Adding two channels that are nothing like it, and adding them **without touching a
+single element, kind or definition**, is what turns the claim above from an
+intention into a fact. They are placeholders on purpose: they do not send, and
+their copy is invented rather than relocated. Their SHAPE is not provisional.
+
+Three channels now answer `supports` differently over one content that carries no
+channel tags — email declines nothing, slack declines `chatUnit`, sms also
+declines `heroImage` and `divider` — and `Out` is a record, then a string, then a
+different record. Those are this layer's two design claims, stated by real modules
+rather than by test doubles.
+
+## Invariants
+
+- `render` is PURE — a function of `(content, context)`. No clock (the year comes
+  from `RenderContext`), no environment, no I/O. `../context.ts` owns the only
+  clock read in the domain.
+- `supports` is total over `NotificationElementType` and MUST agree with
+  `render`: an element it declines is OMITTED, never approximated and never
+  thrown on.
+- Each renderer returns its NATURAL type. There is no `ChannelOutput` supertype —
+  forcing a common shape would recreate the `html`+`text` fusion this layer is
+  unpicking, with a third surface bolted on.
+- A renderer renders. It does not send, and it does not decide whether to —
+  delivery and policy are the backend's.
+- Markup, styling and spacing live HERE and nowhere else. If a renderer needs a
+  fact the content does not carry, the fix is upstream in `compose`; the moment a
+  renderer starts special-casing a `metadata.kind`, the model has lost.