@company-semantics/contracts 34.0.0 → 35.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "34.0.0",
+  "version": "35.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -32,9 +32,9 @@
       "types": "./src/execution/index.ts",
       "default": "./src/execution/index.ts"
     },
-    "./email": {
-      "types": "./src/email/index.ts",
-      "default": "./src/email/index.ts"
+    "./notifications": {
+      "types": "./src/notifications/index.ts",
+      "default": "./src/notifications/index.ts"
     },
     "./ralph": {
       "types": "./src/ralph/index.ts",

package/src/index.ts

@@ -219,20 +219,26 @@ export type {
   WriteTierDisabledMeta,
 } from "./dispatch/index";
 
-// Email domain types
-// @see ADR-CONT-034 for design rationale
+// Notification domain types
+// Replaces the Email* vocabulary (ADR-CONT-034), which was deleted with
+// `@company-semantics/contracts/email` — email is now one channel, not the shape
+// of the layer. The render layer itself (content model, renderers,
+// renderToChannel) stays on the `/notifications` subpath; the root carries the
+// vocabulary, as it did for email.
+// @see ADR-CONTRACTS-086 for the multi-channel render layer
+// @see ADR-CONTRACTS-085 for the definition + registry
 export type {
-  EmailKind,
-  EmailPayloads,
-  SendEmailInput,
-  EmailKindDefinition,
-} from "./email/index";
+  NotificationKind,
+  NotificationPayloads,
+  NotificationDefinition,
+  NotificationDefinitions,
+} from "./notifications/index";
 
 export {
-  EMAIL_KINDS,
-  getEmailKindDefinition,
-  isValidEmailKind,
-} from "./email/index";
+  NOTIFICATION_DEFINITIONS,
+  getNotificationKindDefinition,
+  isValidNotificationKind,
+} from "./notifications/index";
 
 // Chat domain types
 // @see PRD-00142 for share chat design rationale

package/src/notifications/README.md

@@ -0,0 +1,142 @@
+# notifications/
+
+## Purpose
+
+Home of the multi-channel notification render layer (ADR-CONTRACTS-086) — the
+generalisation of the old email-only render layer (`src/email/`, now deleted)
+into `Definition → Payload → compose(payload, context) → Content → Renderer`.
+
+This is the package's SOLE notification surface. `@company-semantics/contracts/email`
+and every `Email*` symbol are gone, with no shim and no alias.
+
+The domain holds the **semantic model**: the channel-agnostic vocabulary an
+element names, and the renderers that decide what it looks like per channel.
+
+It used to hold an **output-parity baseline** too — a byte-exact capture of what
+the email layer rendered at 32.0.0, landed deliberately _before_ the abstraction
+it protected, so every step of the migration had a mechanical answer to "did any
+real email change?". That baseline did its job: the answer was "none", and it
+shipped in 35.0.0. ADR-CONTRACTS-087 retired it, because a proof that the
+migration changed nothing cannot also serve as permission to change something,
+and email design is not frozen. `__tests__/render-snapshot.test.ts` is the fence
+now; the retired bytes are readable in git at `v35.0.0`.
+
+- `content.ts` — `NotificationContent { metadata, sections }`, `Section`, and the
+  flat `NotificationElement` union (greeting, body, keyValueTable, callToAction,
+  list, divider, warning, metadata, notice, chatUnit, signature, heroImage). What
+  a notification SAYS, with no markup and no channel names.
+- `context.ts` — `RenderContext { brand: { name, copyrightYear } }`,
+  `COMPANY_NAME`, and `createRenderContext()`, whose defaults reproduce the brand
+  name + current year the email layer rendered.
+- `renderer.ts` — `Renderer<Out>`: a channel's `id`, its `supports(elementType)`
+  capability, and `render(content, context)` returning that channel's own type.
+
+And on top of THAT sits the **definition layer** (ADR-CONTRACTS-085) — the kinds
+themselves, moved out of the old email layer:
+
+- `kinds.ts` — the `NotificationKind` union. Eleven members: the kinds with
+  something to say.
+- `payloads.ts` — `NotificationPayloads`, the facts each kind carries.
+- `definition.ts` — `NotificationDefinition<K> { kind, defaults?, compose }`.
+- `kinds/` — one `compose` per kind. See its README for the block → element map.
+- `text.ts` — the stock wording (`NOTICE`, `ACCESS_PHRASE`) and value formats
+  (`titleCase`, `formatExpiry`) `compose` builds copy from. Channel-agnostic:
+  what a notification says is the same on every channel.
+- `registry.ts` — `NOTIFICATION_DEFINITIONS` plus
+  `getNotificationKindDefinition` / `isValidNotificationKind`.
+
+And on top of THAT sit the **channels** (ADR-CONTRACTS-086):
+
+- `renderers/email/` — `emailRenderer: Renderer<RenderedEmail>`, the old
+  `src/email/render` layer relocated behind the seam. Its own tests prove it
+  reproduces the golden from composed content.
+- `renderers/sms/` — `smsRenderer: Renderer<string>`, a non-functional
+  placeholder.
+- `renderers/slack/` — `slackRenderer: Renderer<SlackMessage>`, a non-functional
+  placeholder.
+
+The two placeholders are what make the seam's claims checkable. Email could
+satisfy `Renderer` by construction — the seam was drawn around it — so a layer
+with one channel in it proves only that the layer compiles. SMS (no markup, no
+images, one string) and Slack (a tree of typed blocks) were added without editing
+a single element, kind or definition, which is the property `renderers/README.md`
+says the seam exists for. They do not send and their copy is invented; their shape
+is not provisional.
+
+And on top of THAT sits the **entry point** (ADR-CONTRACTS-086):
+
+- `render.ts` — `renderToChannel(kind, payload, renderer, context?)`, the whole
+  pipeline in one call: look up the definition, `compose` the payload, hand the
+  content to a renderer. Plus `renderEmail(kind, payload, overrides?)`, the
+  convenience for the channel every caller has today.
+
+The pipeline is **closed**: every parity fixture renders through
+`renderToChannel` and lands on the golden byte-for-byte, so the whole
+generalisation is proven to have cost no email a single character. The snapshot
+suite moved here from the old `src/email/render` with the markup it documents —
+its `.snap` came across untouched, keys and all.
+
+The old `src/email/` is **deleted** — directory, `./email` subpath, and every
+`Email*` symbol, with no shim. `renderEmail` here is the replacement, same name
+and a different third argument (`RenderContextOverrides`, not
+`RenderEmailOptions`). Consumers migrate against the published major rather than
+against an alias: backend in PRD-00869, app in PRD-00870.
+
+Two things left the package with it and have no replacement here, both
+deliberately (ADR-CONTRACTS-086):
+
+- `auth.magic_link` — a subject reserved for a kind that never had a template.
+  It cannot be composed, so it is not a `NotificationKind`.
+- `SendEmailInput` — `to` / `idempotencyKey` are DELIVERY, and delivery is the
+  backend's (PRD-00869). Unlike `EmailKind` / `EmailPayloads`, it was never an
+  alias of anything here, so there was nothing to rename.
+
+## Invariants
+
+- `__tests__/render-snapshot.test.ts` locks what this layer renders. A diff there
+  means a real sent email changed: review it, then regenerate. It is a regression
+  fence, not a specification — but since ADR-CONTRACTS-087 retired the parity
+  golden that used to outrank it, reading the diff is the ONLY control left. A
+  snapshot refreshed on sight proves nothing.
+- Every kind in `NOTIFICATION_DEFINITIONS` needs at least one fixture in
+  `__tests__/fixtures.ts`, enforced by the tests. The registry is the source of
+  that list — it is total, so "every kind the entry point accepts" and "every
+  kind with a fixture" are the same claim.
+- Rendering MUST pin the year to `FIXTURE_CLOCK`'s — by passing
+  `copyrightYear` in the `RenderContext`, NOT by freezing the clock. `signature`
+  used to read `new Date().getFullYear()` mid-render, which is why the fixtures
+  once needed fake timers; the year is a value now, and no test in this domain
+  has an opinion about what day it is.
+- The captured year is **not** redacted or normalised. It is part of the output
+  surface the parity proof exists to protect.
+- Types and **pure** functions only — no classes, no side effects, no external
+  imports beyond `zod` (vocabulary-guard enforced), as in the old email layer.
+- `NotificationKind` has ELEVEN members where the old `EmailKind` had twelve. The
+  difference is `auth.magic_link`, a registered subject with no template that the
+  old `renderEmail` threw on. Excluding it is what makes
+  `NOTIFICATION_DEFINITIONS` total; adding it back "for symmetry" restores a
+  runtime hole. Give it a `compose` and it graduates.
+- This domain depends on NOTHING outside itself. The `notifications → email`
+  imports that existed while both layers did are gone with the directory, and
+  nothing may reintroduce one.
+- A kind IS its definition. Every `NotificationKind` has facts in `payloads.ts`
+  and a `compose` in `kinds/`, both compiler-enforced via `NotificationPayloads[K]`.
+- Capability belongs to the **renderer** (`Renderer.supports`), never to an
+  element or a kind. Elements carry no channel tags — the moment they do, every
+  new channel becomes a rewrite of the content.
+- `supports` and `render` MUST agree: an element `supports` declines is omitted,
+  not approximated and not thrown on.
+- `renderers/sms` and `renderers/slack` are PLACEHOLDERS: they do not send, and
+  their copy is invented rather than relocated from anything. Neither is reachable
+  from `renderEmail` and neither touches a parity fixture — a stub cannot change a
+  sent email, and must not acquire the ability to. Their SHAPE, however, is not
+  provisional: purity, total `supports`, and a natural `Out` are the seam's claims
+  and these modules are where two of them stop being test doubles.
+- `createRenderContext()` is the ONLY clock read in this domain, and only to
+  default `copyrightYear`. Renderers take the year from `RenderContext` — that is
+  what retires the hidden `new Date()` the old `signature()` did mid-render.
+- Channel-agnostic modules MUST NOT import from `renderers/`. `COMPANY_NAME`
+  lives in `context.ts` and `NOTICE` / `ACCESS_PHRASE` / `titleCase` /
+  `formatExpiry` in `text.ts` for exactly this reason: they are the same answer
+  on every channel, and sourcing a default from one channel is how the seam leaks
+  back. The arrow runs `kinds/` → `text.ts` / `context.ts`, never into a renderer.

package/src/notifications/__tests__/README.md

@@ -0,0 +1,49 @@
+# notifications/\_\_tests\_\_/
+
+## Purpose
+
+The shared fixture corpus for the multi-channel notification render layer
+(ADR-CONTRACTS-086), and the snapshot suite that documents the markup it renders
+to.
+
+- `fixtures.ts` — every implemented kind × representative payload, plus
+  `FIXTURE_CLOCK` and `fixtureKey`. Shared by every suite here and by
+  `../renderers/email/__tests__/render.test.ts`, so a kind added to the registry
+  is covered everywhere by being added once.
+- `render-snapshot.test.ts` + `__snapshots__/` — those fixtures rendered through
+  the email channel, as vitest snapshots. This is the fence: **a diff here means
+  a real sent email changed.**
+
+## The retired output-parity golden (ADR-CONTRACTS-087)
+
+`fixtures.ts` was `output-parity.golden.ts`, and it used to carry
+`OUTPUT_PARITY_GOLDEN` — the exact `{ subject, text, html }` the email layer
+emitted at 32.0.0, before any of this existed — asserted byte-for-byte by
+`output-parity.test.ts` at the entry point and by the email renderer's own suite
+at the renderer. Those two tests were the "no output change" contract for the
+generalisation: `src/email/` was deleted on that proof.
+
+**The proof passed and shipped in 35.0.0, which discharged it.** It was a claim
+about a migration, not a freeze on email design — and the moment email design is
+deliberately exercised, byte-equality to a deleted layer fails by construction
+and keeps failing.
+
+It was **retired rather than regenerated**, and the distinction is the point:
+rewriting those bytes to match a redesign would have made the file assert
+something false about a layer that no longer exists to contradict it. The bytes
+are readable in git at `v35.0.0`; nothing in the tree claims to be them.
+
+## Invariants
+
+- A snapshot diff means **a real sent email changed**. Review it, then
+  `vitest -u` — never the other way round. Regenerating on sight is the whole
+  hazard; the review is the control, and it is now the only one.
+- The year MUST be pinned via `FIXTURE_CLOCK` on the `RenderContext`, never by
+  freezing the clock. `signature` bakes it into every case, so an unpinned render
+  fails on the next New Year's Day for calendar reasons alone. Fake timers are
+  not needed anywhere here — that is the impurity ADR-CONTRACTS-086 retired, so
+  do not reintroduce them.
+- The pinned year is **not** redacted or normalised. It is part of the output
+  surface these suites exist to protect.
+- Every kind in `NOTIFICATION_DEFINITIONS` MUST have a fixture, enforced by
+  `./definition.test.ts` and `./registry.test.ts`.

package/src/notifications/__tests__/__snapshots__/README.md

@@ -0,0 +1,39 @@
+# notifications/\_\_tests\_\_/\_\_snapshots\_\_/
+
+## Purpose
+
+Vitest snapshots for `../render-snapshot.test.ts` — the rendered subject / text /
+html of every notification kind × variant, as the email channel draws them.
+
+`render-snapshot.test.ts.snap` moved here verbatim from the old
+`src/email/render/__tests__/__snapshots__/` when the render layer was
+generalised behind the channel seam (ADR-CONTRACTS-086). Not one recorded byte
+changed: the suite's describe label stayed `email render` and its case labels
+stayed `{kind} · {name}`, so every snapshot key still resolves against the same
+file. That is the claim the move is making — the keys matched, so the bytes
+matched.
+
+The `security.alert` cases have since moved: the `warning` banner is drawn in the
+product's destructive colour (ADR-CONTRACTS-087). That is the first deliberate
+change to this markup since the move, and the reason the parity golden that used
+to guard it is gone.
+
+This directory exists because vitest resolves snapshots adjacent to the test
+file, so the `.snap` had to travel with it.
+
+## Invariants
+
+- This is **production-parity email markup**. A diff here means a real sent email
+  changed. Review it, then `vitest -u` — never the other way round.
+- These snapshots are now the **only** automated record of that markup. Until
+  ADR-CONTRACTS-087 the migration's proof sat beside them in
+  `../output-parity.golden.ts`, a committed module `vitest -u` could not touch,
+  and it was the tie-breaker when the two disagreed. That proof was discharged in
+  35.0.0 and retired, because it asserted byte-equality with a deleted layer and
+  email design is allowed to change. Nothing now catches a snapshot regenerated
+  under refactor pressure except reading the diff — so read it.
+- The copyright year is pinned to `FIXTURE_CLOCK`'s, never the wall clock. It is
+  baked into every case via `signature`, so an unpinned capture would fail on the
+  next New Year's Day for calendar reasons alone.
+- The year is **not** redacted or normalised. It is part of the output surface
+  these snapshots exist to protect.

package/src/notifications/__tests__/__snapshots__/registry.test.ts.snap

@@ -0,0 +1,31 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`NOTIFICATION_DEFINITIONS > titles every kind 1`] = `
+{
+  "auth.otp · Default": "Your login code for Company Semantics",
+  "auth.otp · Short expiry": "Your login code for Company Semantics",
+  "auth.otp · With request metadata": "Your login code for Company Semantics",
+  "chat.shared · Default": "A chat has been shared with you",
+  "chat.shared · Long preview": "A chat has been shared with you",
+  "chat.shared · Long title": "A chat has been shared with you",
+  "chat.shared · No preview": "A chat has been shared with you",
+  "chat.shared · Short": "A chat has been shared with you",
+  "companyMd.access_request_approved · Editor": "Your access request was approved",
+  "companyMd.access_request_approved · Viewer": "Your access request was approved",
+  "companyMd.access_request_denied · No reason": "Your access request was reviewed",
+  "companyMd.access_request_denied · With reason": "Your access request was reviewed",
+  "companyMd.access_requested · No message": "Someone requested access to a document",
+  "companyMd.access_requested · With message": "Someone requested access to a document",
+  "org.invite · Admin": "You've been invited to join Acme Corp on Company Semantics",
+  "org.invite · Member": "You've been invited to join Acme Corp on Company Semantics",
+  "org.ownership_transfer · No note (admin)": "You've been invited to become a workspace owner",
+  "org.ownership_transfer · With note + from": "You've been invited to become a workspace owner",
+  "org.ownership_transfer_completed · Default": "Workspace ownership has been transferred",
+  "org.unit_owner_granted · Delegate with expiry": "You've been added as delegate owner to Platform Engineering in Acme Corp",
+  "org.unit_owner_granted · Unit owner + message": "You've been added as owner to Platform Engineering in Acme Corp",
+  "security.alert · Excessive OTP requests": "Security alert for your account",
+  "security.alert · Unusual login location": "Security alert for your account",
+  "share.granted · Document · editor · message": "Something has been shared with you",
+  "share.granted · Meeting · viewer · no title": "Something has been shared with you",
+}
+`;

package/src/{email/render → notifications}/__tests__/__snapshots__/render-snapshot.test.ts.snap

@@ -1547,7 +1547,7 @@ exports[`email render > security.alert · Excessive OTP requests 1`] = `
 <head><meta charset="UTF-8"></head>
 <body style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; color: #1a1a1a; margin: 0; padding: 0;">
 <div style="max-width: 520px; margin: 0 auto;">
-<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">🆆🅰🆁🅽🅸🅽🅶</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;"><span style="color: #e7000b;">🆆🅰🆁🅽🅸🅽🅶</span></p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Unusual login-code activity detected.</p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Details: 12 login codes requested in 5 minutes</p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">If this was you, no action is needed.</p>
@@ -1587,7 +1587,7 @@ exports[`email render > security.alert · Unusual login location 1`] = `
 <head><meta charset="UTF-8"></head>
 <body style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; color: #1a1a1a; margin: 0; padding: 0;">
 <div style="max-width: 520px; margin: 0 auto;">
-<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">🆆🅰🆁🅽🅸🅽🅶</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;"><span style="color: #e7000b;">🆆🅰🆁🅽🅸🅽🅶</span></p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">A login from an unusual location was detected.</p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Details: Login from Berlin, DE</p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">If this was you, no action is needed.</p>

package/src/notifications/__tests__/content.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The semantic model is types-only, so these tests do two jobs a type alone
+ * cannot (ADR-CONTRACTS-086).
+ *
+ * They pin the MEMBERSHIP of the element union: `ALL_ELEMENT_TYPES` is typed
+ * `Record<NotificationElementType, true>`, so adding an element without listing
+ * it here fails to compile, and the runtime assertion below fails if one is
+ * renamed or dropped. The union is the contract every renderer's `supports` is
+ * total over — it should not move by accident.
+ *
+ * And they pin that the union is REACHABLE as content: the fixture composes one
+ * element of every kind through `NotificationContent`, which is the check that
+ * the model can actually express a notification rather than merely type-check.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  NotificationContent,
+  NotificationElement,
+  NotificationElementType,
+} from "../content";
+
+/**
+ * Every element type, exhaustively. The `Record` type is the lock: a new union
+ * member is a compile error until it is named here.
+ */
+const ALL_ELEMENT_TYPES: Record<NotificationElementType, true> = {
+  greeting: true,
+  body: true,
+  keyValueTable: true,
+  callToAction: true,
+  list: true,
+  divider: true,
+  warning: true,
+  metadata: true,
+  notice: true,
+  chatUnit: true,
+  signature: true,
+  heroImage: true,
+};
+
+/** One element of every kind, in a plausible notification order. */
+const EVERY_ELEMENT: NotificationElement[] = [
+  { type: "heroImage", src: "https://example.test/hero.png", alt: "Acme" },
+  { type: "greeting", recipientName: "Ada" },
+  { type: "warning" },
+  { type: "body", text: "Acme uses Company Semantics." },
+  {
+    type: "chatUnit",
+    items: [
+      { type: "message", role: "user", text: "Can I join?", from: "Ada" },
+      { type: "continuation" },
+      { type: "message", role: "assistant", text: "Join to accept." },
+      { type: "callToAction", label: "JOIN", href: "https://example.test/j" },
+    ],
+  },
+  { type: "callToAction", label: "123456" },
+  { type: "divider" },
+  {
+    type: "keyValueTable",
+    rows: [
+      { label: "From", value: "Grace" },
+      { label: "Role", value: "Admin" },
+    ],
+  },
+  { type: "list", items: ["Read", "Comment"], ordered: false },
+  {
+    type: "metadata",
+    label: "Request details",
+    rows: [{ label: "IP address", value: "203.0.113.4" }],
+  },
+  {
+    type: "notice",
+    lines: ["Sent via Company Semantics.", "No action needed."],
+  },
+  { type: "signature" },
+];
+
+describe("NotificationElement", () => {
+  it("has exactly the twelve element types the renderers switch over", () => {
+    expect(Object.keys(ALL_ELEMENT_TYPES).sort()).toEqual([
+      "body",
+      "callToAction",
+      "chatUnit",
+      "divider",
+      "greeting",
+      "heroImage",
+      "keyValueTable",
+      "list",
+      "metadata",
+      "notice",
+      "signature",
+      "warning",
+    ]);
+  });
+
+  it("covers every element type in the fixture", () => {
+    const covered = new Set(EVERY_ELEMENT.map((e) => e.type));
+    expect([...covered].sort()).toEqual(Object.keys(ALL_ELEMENT_TYPES).sort());
+  });
+
+  it("discriminates exhaustively on `type`", () => {
+    // The `never` guard is the idiom every renderer will rely on: if a member is
+    // added to the union, this stops compiling rather than silently falling
+    // through to a default.
+    const describeElement = (element: NotificationElement): string => {
+      switch (element.type) {
+        case "greeting":
+          return element.recipientName ?? "anonymous";
+        case "body":
+          return element.text;
+        case "keyValueTable":
+          return element.rows.map((r) => r.label).join(",");
+        case "callToAction":
+          return element.href ?? element.label;
+        case "list":
+          return element.items.join(",");
+        case "divider":
+          return "divider";
+        case "warning":
+          return "warning";
+        case "metadata":
+          return element.label ?? "metadata";
+        case "notice":
+          return element.lines.join(" ");
+        case "chatUnit":
+          return element.items.map((i) => i.type).join(",");
+        case "signature":
+          return element.signer ?? "brand";
+        case "heroImage":
+          return element.alt;
+        default: {
+          const _exhaustive: never = element;
+          throw new Error(`Unhandled element: ${JSON.stringify(_exhaustive)}`);
+        }
+      }
+    };
+
+    expect(EVERY_ELEMENT.map(describeElement)).toHaveLength(
+      EVERY_ELEMENT.length,
+    );
+  });
+
+  it("reuses CallToAction inside a chat unit rather than mirroring it", () => {
+    // A CTA in a conversation is the same intent as a standalone one. If these
+    // ever diverge, a renderer would need two code paths for one concept.
+    const cta: NotificationElement = { type: "callToAction", label: "OPEN" };
+    const unit: NotificationElement = { type: "chatUnit", items: [cta] };
+    expect(unit).toEqual({
+      type: "chatUnit",
+      items: [{ type: "callToAction", label: "OPEN" }],
+    });
+  });
+});
+
+describe("NotificationContent", () => {
+  it("carries the headline in metadata, not in a channel registry", () => {
+    // The subject moving out of EMAIL_KINDS and into Content is the fusion
+    // ADR-CONTRACTS-086 splits — it is what lets a second renderer attach
+    // without restating the copy.
+    const content: NotificationContent = {
+      metadata: { kind: "org.invite", title: "Join Acme on Company Semantics" },
+      sections: [{ elements: EVERY_ELEMENT }],
+    };
+
+    expect(content.metadata.title).toBe("Join Acme on Company Semantics");
+    expect(content.metadata.kind).toBe("org.invite");
+    expect(content.sections[0].elements).toHaveLength(EVERY_ELEMENT.length);
+  });
+
+  it("groups elements into sections a channel may split on", () => {
+    const content: NotificationContent = {
+      metadata: { kind: "auth.otp", title: "Your login code" },
+      sections: [
+        { elements: [{ type: "greeting" }] },
+        { elements: [{ type: "callToAction", label: "123456" }] },
+      ],
+    };
+
+    expect(content.sections).toHaveLength(2);
+    expect(
+      content.sections.flatMap((s) => s.elements).map((e) => e.type),
+    ).toEqual(["greeting", "callToAction"]);
+  });
+});

package/src/notifications/__tests__/context.test.ts

@@ -0,0 +1,72 @@
+/**
+ * `createRenderContext` is the one place in the notifications domain allowed to
+ * read the clock (ADR-CONTRACTS-086). These tests pin both halves of that deal:
+ * the defaults reproduce today's values exactly (so hoisting the year out of
+ * `signature()` changes no bytes), and an override makes the context fully
+ * deterministic (so nothing downstream needs a fake timer).
+ *
+ * The clock is frozen here for the same reason the parity suite freezes it: the
+ * default year assertion would otherwise be a New Year's Day time bomb.
+ */
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { COMPANY_NAME, createRenderContext } from "../context";
+import { FIXTURE_CLOCK } from "./fixtures";
+
+const FROZEN_YEAR = new Date(FIXTURE_CLOCK).getUTCFullYear();
+
+beforeAll(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date(FIXTURE_CLOCK));
+});
+
+afterAll(() => {
+  vi.useRealTimers();
+});
+
+describe("createRenderContext", () => {
+  it("defaults to the values the email layer rendered", () => {
+    // The no-op case must reproduce `signature()`'s inputs exactly: COMPANY_NAME
+    // and the current year. If this drifts, hoisting the clock read out of the
+    // render path silently changes a real sent email.
+    expect(createRenderContext()).toEqual({
+      brand: { name: COMPANY_NAME, copyrightYear: FROZEN_YEAR },
+    });
+  });
+
+  it("defaults the year from the clock", () => {
+    vi.setSystemTime(new Date("2030-03-04T05:06:07.000Z"));
+    expect(createRenderContext().brand.copyrightYear).toBe(2030);
+    vi.setSystemTime(new Date(FIXTURE_CLOCK));
+  });
+
+  it("overrides each brand field independently", () => {
+    expect(createRenderContext({ brand: { name: "Acme" } })).toEqual({
+      brand: { name: "Acme", copyrightYear: FROZEN_YEAR },
+    });
+    expect(createRenderContext({ brand: { copyrightYear: 1999 } })).toEqual({
+      brand: { name: COMPANY_NAME, copyrightYear: 1999 },
+    });
+  });
+
+  it("is deterministic — a pinned year ignores the clock entirely", () => {
+    const pinned = { brand: { copyrightYear: 2020 } };
+    const before = createRenderContext(pinned);
+    vi.setSystemTime(new Date("2031-01-01T00:00:00.000Z"));
+    expect(createRenderContext(pinned)).toEqual(before);
+    vi.setSystemTime(new Date(FIXTURE_CLOCK));
+  });
+
+  it("returns a fresh context per call — callers cannot alias each other", () => {
+    const a = createRenderContext();
+    const b = createRenderContext();
+    expect(a).not.toBe(b);
+    expect(a.brand).not.toBe(b.brand);
+  });
+
+  it("treats an empty override object as no override", () => {
+    expect(createRenderContext({})).toEqual(createRenderContext());
+    expect(createRenderContext({ brand: {} })).toEqual(createRenderContext());
+  });
+});