@company-semantics/contracts 34.0.0 → 35.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "34.0.0",
+  "version": "35.0.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,140 @@
+# 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 **output-parity baseline** — a committed, byte-exact
+capture of what the email layer rendered at 32.0.0, plus the test that proves
+this layer still renders exactly that. The baseline was deliberately landed
+_before_ the abstraction it protects, so that every later step in the migration
+had a mechanical answer to "did any real email change?". Now that the old layer
+is deleted, the golden is also the only surviving record of those bytes.
+
+On top of it sits the **semantic model**: the channel-agnostic vocabulary the
+migration is heading toward.
+
+- `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
+
+- The golden in `__tests__/output-parity.golden.ts` records what the email layer
+  rendered at **32.0.0**, and is now the only record of it — there is no longer a
+  layer to re-capture it from. It is a regression baseline, not a specification:
+  when it and this render layer disagree, the GOLDEN is right and the renderer
+  must be fixed, never the golden regenerated to match.
+- Every kind in `NOTIFICATION_DEFINITIONS` needs at least one parity fixture,
+  enforced by the test. 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 for parity MUST pin the year to `OUTPUT_PARITY_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,54 @@
+# notifications/\_\_tests\_\_/
+
+## Purpose
+
+The output-parity proof for the multi-channel notification render layer
+(ADR-CONTRACTS-086), and the snapshot suite that documents the markup.
+
+- `output-parity.golden.ts` — the fixtures (kind + payload) and
+  `OUTPUT_PARITY_GOLDEN`, the exact `{ subject, text, html }` each one rendered
+  to through the email layer **as it stood before any of this existed**.
+- `output-parity.test.ts` — renders every fixture through `renderToChannel`, the
+  new entry point, and asserts byte equality against that golden.
+- `render-snapshot.test.ts` + `__snapshots__/` — the same fixtures as vitest
+  snapshots, moved here from the old `src/email/render/__tests__/` with the
+  markup they document.
+
+The parity test used to pin the old `renderEmail` against itself, which was the
+point: the bytes were captured _before_ the layer they describe was touched. That
+baseline has now done its job — the same fixtures render through
+`compose → Content → Renderer` and produce the same bytes, so the generalisation
+is proven to have changed no email. `src/email/` was deleted on that proof.
+
+Prefer the golden when the two suites disagree. `vitest -u` can regenerate a
+snapshot in a keystroke, and a snapshot regenerated under refactor pressure is
+worth nothing; the golden is a committed module, so making it pass is a
+deliberate, reviewable act.
+
+## Invariants
+
+- The year MUST be pinned to `OUTPUT_PARITY_CLOCK`'s via the `RenderContext`, not
+  by freezing the clock. It is baked into every case by `signature`, so an
+  unpinned render fails on the next New Year's Day for calendar reasons alone.
+  Fake timers are no longer needed anywhere here, and that is the improvement
+  this layer was built to deliver — do not reintroduce them.
+- The captured year is **not** redacted or normalised. It is part of the output
+  surface this proof exists to protect.
+- A failure here means a **real sent email changed**. Review the diff before
+  regenerating; the golden is not a snapshot to refresh on sight. `src/email/` is
+  deleted, so these bytes cannot be re-captured — the golden is the only record
+  of what that layer emitted, and regenerating it destroys the proof rather than
+  updating it.
+- The golden and the fixtures MUST stay in exact correspondence — no missing and
+  no orphaned entries. The test enforces both directions.
+- Every kind in `NOTIFICATION_DEFINITIONS` MUST have a fixture, enforced by both
+  suites.
+- The golden's BYTES are frozen; its TYPES were re-anchored onto this domain when
+  the `Email*` originals were deleted. `OutputParityFixture.options` went with
+  them — it was declared as `RenderEmailOptions` and carried the old layer's
+  `includeRequestMetadata`, which `compose` replaced with "does the payload carry
+  request details?". It had been left in place as frozen evidence, but its type
+  no longer exists and no test ever read it; the one fixture that set it supplies
+  both request fields anyway, so the gate opens regardless. The byte equality is
+  what proves that — which is exactly why dropping the field was safe and
+  re-recording a byte would not be.

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

@@ -0,0 +1,32 @@
+# 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.
+
+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 **not** the migration's proof. That is
+  `../output-parity.golden.ts`, a committed module `vitest -u` cannot touch. When
+  the two disagree, the golden is right. Regenerating this file to make a
+  refactor pass is the exact failure ADR-CONTRACTS-086 exists to prevent, and it
+  is one keystroke away — which is why the golden is not a snapshot.
+- The copyright year is pinned to `OUTPUT_PARITY_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__/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 { OUTPUT_PARITY_CLOCK } from "./output-parity.golden";
+
+const FROZEN_YEAR = new Date(OUTPUT_PARITY_CLOCK).getUTCFullYear();
+
+beforeAll(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date(OUTPUT_PARITY_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(OUTPUT_PARITY_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(OUTPUT_PARITY_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());
+  });
+});