@company-semantics/contracts 35.0.0 → 35.1.0

package/src/notifications/__tests__/render-snapshot.test.ts

@@ -13,11 +13,15 @@
  * every snapshot key still resolves. That is the whole claim of the move: the
  * keys still match, so the bytes are still the bytes.
  *
- * Read this alongside `./output-parity.test.ts`, which is the load-bearing one.
- * A snapshot can be regenerated with a keystroke; the golden cannot. This file
- * exists to make the markup reviewable, not to be the proof.
+ * This file used to be the reviewable companion to `./output-parity.test.ts`,
+ * which was the load-bearing one: a snapshot can be regenerated with a
+ * keystroke, a committed golden cannot, so the golden was the proof and this was
+ * the documentation. ADR-CONTRACTS-087 retired that golden once its migration
+ * proof shipped in 35.0.0 — so this file is now BOTH. There is no longer a
+ * second oracle to catch a snapshot refreshed on autopilot; the diff you read
+ * before typing `vitest -u` is the control.
  *
- * The clock is pinned to `OUTPUT_PARITY_CLOCK`'s year rather than left to run.
+ * The clock is pinned to `FIXTURE_CLOCK`'s year rather than left to run.
  * These snapshots used to be captured under the wall clock — with the copyright
  * year baked into every one of them — so they were due to fail on the next New
  * Year's Day for calendar reasons alone. The year is a value in `RenderContext`
@@ -32,11 +36,11 @@ import type { NotificationPayloads } from "../payloads";
 import { renderEmail } from "../render";
 import { NOTIFICATION_DEFINITIONS } from "../registry";
 import type { RenderedEmail } from "../renderers/email";
-import { OUTPUT_PARITY_CLOCK } from "./output-parity.golden";
+import { FIXTURE_CLOCK } from "./fixtures";
 
 /** Pinned so no wall-clock year can reach a snapshot. */
 const CONTEXT: RenderContextOverrides = {
-  brand: { copyrightYear: new Date(OUTPUT_PARITY_CLOCK).getUTCFullYear() },
+  brand: { copyrightYear: new Date(FIXTURE_CLOCK).getUTCFullYear() },
 };
 
 interface Fixture {

package/src/notifications/kinds/README.md

@@ -50,8 +50,8 @@ template literal the compiler checks.
 - Definitions take `formatExpiry`, `titleCase`, `NOTICE` and `ACCESS_PHRASE` from
   `../text` — never from a renderer. They are content (phrasing and display
   format), not markup, so they sit beside the kinds rather than inside the
-  channel that used to own them. The output-parity golden asserts these strings
-  byte-for-byte; a second copy of one is the exact failure this migration exists
+  channel that used to own them. `../__tests__/render-snapshot.test.ts` locks
+  these strings; a second copy of one is the exact failure this migration exists
   to prevent.
 - A file per kind, named after its old `email/render` counterpart. Kinds do not
   share a module — the point is that a kind is self-contained.

package/src/notifications/render.ts

@@ -4,8 +4,7 @@
  * `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.
+ * when this was written — the 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
@@ -30,10 +29,11 @@
  *   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.
+ * - Output is locked by `__tests__/render-snapshot.test.ts`, across every fixture
+ *   in `__tests__/fixtures.ts`. A diff there means a real sent email changed:
+ *   review it, then regenerate. This rewiring was originally proven safe by
+ *   byte-equality with the old email layer; that proof shipped in 35.0.0 and was
+ *   retired with the golden (ADR-CONTRACTS-087).
  * - 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.

package/src/notifications/renderers/email/README.md

@@ -48,12 +48,16 @@ expect to style it properly rather than trust the placeholder.
 
 ## Invariants
 
-- Output is byte-identical to what the old `src/email/render` emitted. This is
-  the whole constraint of the migration. `__tests__/render.test.ts` proves it by
-  composing every fixture in the frozen output-parity golden and rendering it
-  through this channel — a diff there means a real sent email changed. The golden
-  is the only record of those bytes now, so it is the authority: fix the
-  renderer, never the golden.
+- Output is locked by `../../__tests__/render-snapshot.test.ts`, across every
+  fixture in `../../__tests__/fixtures.ts` — a diff there means a real sent email
+  changed, so review it before regenerating. Byte-identity with the old
+  `src/email/render` was the whole constraint of the migration; it held, shipped
+  in 35.0.0, and ADR-CONTRACTS-087 retired the golden that proved it, because
+  that proof could not double as permission to change the design.
+- `__tests__/render.test.ts` asserts the rules that outlive any redesign — every
+  element type supported, subject from the content's title, year and signer from
+  context, the `:` restored, user content escaped. Markup belongs in the
+  snapshot, not there.
 - PURE. `render` is a function of `(content, context)`: no clock, no environment,
   no I/O. The copyright year comes from `context.brand.copyrightYear`, which is
   what retires the `new Date().getFullYear()` hidden inside the old

package/src/notifications/renderers/email/__tests__/README.md

@@ -4,26 +4,29 @@
 
 Tests for the email channel (ADR-CONTRACTS-086).
 
-`render.test.ts` holds the renderer's one load-bearing proof: every fixture in
-`../../../__tests__/output-parity.golden.ts`, composed through
-`NOTIFICATION_DEFINITIONS` and rendered through `emailRenderer`, byte-for-byte.
-The rest of the file pins the properties the golden cannot see — that `supports`
-is total, that the year comes from `RenderContext`, that the `:` separator the
-content model drops is put back, and that user-controlled fields are escaped.
+`render.test.ts` pins the renderer's behavioural rules — the claims that hold no
+matter how the email is styled: that `supports` is total, that the subject comes
+from the content's title, that the year and signer come from `RenderContext`
+rather than a clock, that the `:` separator the content model drops is put back,
+and that user-controlled fields are escaped. It also renders every fixture in
+`../../../__tests__/fixtures.ts` through `NOTIFICATION_DEFINITIONS`, which proves
+each kind composes and renders on both surfaces at all.
+
+The MARKUP is not here. `../../../__tests__/render-snapshot.test.ts` locks that.
 
 ## Invariants
 
-- The golden is the ORACLE, not this renderer's output. When the two disagree,
-  the renderer is wrong: the golden records what the old `src/email/render`
-  emitted at 32.0.0, and "no rendered email changed" is the migration's whole
-  promise. It is never regenerated to make this file pass — and since that layer
-  is now deleted, the golden is the only record of those bytes, so regenerating
-  it destroys the evidence rather than updating it.
+- Rules here, markup there. A test in this file that asserts what the HTML looks
+  like is in the wrong file: it belongs in the snapshot, where a redesign shows
+  up as a reviewable diff instead of a wall of broken assertions.
 - NO fake timers. The old layer's `signature()` read the wall clock, which is why
   every render test had to freeze it; here the year is a field on
   `RenderContext`, and keeping this file clock-free is the improvement being
   locked in.
-- Parity is asserted at two levels against one golden: here through the RENDERER
-  (composed content → bytes), and in `../../../__tests__/output-parity.test.ts`
-  through the ENTRY POINT (`renderToChannel`, the whole pipeline). Either one
-  drifting from the golden is a failure.
+- This file used to assert every fixture byte-for-byte against a frozen golden of
+  what `src/email/render` emitted at 32.0.0 — the migration's "no rendered email
+  changed" promise, checked here at the RENDERER and in a companion suite at the
+  ENTRY POINT (`renderToChannel`). The promise held and shipped in 35.0.0;
+  ADR-CONTRACTS-087 retired both, because byte-equality with a deleted layer
+  cannot survive email design being deliberately changed. The bytes are in git at
+  `v35.0.0`.

package/src/notifications/renderers/email/__tests__/render.test.ts

@@ -1,20 +1,19 @@
 /**
- * The email renderer's correctness proof (ADR-CONTRACTS-086).
+ * The email renderer's behavioural rules (ADR-CONTRACTS-086) — the claims that
+ * hold no matter how the email is styled: it supports every element type, takes
+ * the subject from the content's title, takes the year and signer from context
+ * rather than a clock, restores the `:` the content model does not carry, and
+ * escapes user-controlled text.
  *
- * The renderer has exactly one hard requirement: compose a kind, render it
- * through this channel, and get the bytes the old `src/email/render` produced.
- * So that is what this asserts — every fixture in the frozen output-parity
- * golden, composed via `NOTIFICATION_DEFINITIONS` and rendered through
- * `emailRenderer`, character-for-character.
- *
- * This does NOT replace `../../../__tests__/output-parity.test.ts`. That one
- * pins the ENTRY POINT (`renderToChannel`, the whole pipeline) against the same
- * golden; this pins the RENDERER alone, so a failure here says the markup moved
- * rather than that the wiring did. Two levels, one golden: either drifting is a
- * failure.
+ * The MARKUP is not asserted here. `../../../__tests__/render-snapshot.test.ts`
+ * locks that, as a reviewable regenerable diff. Until ADR-CONTRACTS-087 this
+ * file also asserted every fixture byte-for-byte against the 32.0.0 golden, to
+ * prove the multi-channel generalisation moved no bytes; that proof shipped in
+ * 35.0.0 and was retired with the golden, because email design is now allowed to
+ * change and byte-equality to a deleted layer cannot survive it being exercised.
  *
  * There is no fake timer here, and that is the improvement being locked in: the
- * year comes from `RenderContext`, so the golden's clock is just a number.
+ * year comes from `RenderContext`, so the fixtures' clock is just a number.
  */
 
 import { describe, expect, it } from "vitest";
@@ -26,23 +25,21 @@ import type {
 import type { RenderContext } from "../../../context";
 import { NOTIFICATION_DEFINITIONS } from "../../../registry";
 import {
-  OUTPUT_PARITY_CLOCK,
-  OUTPUT_PARITY_FIXTURES,
-  OUTPUT_PARITY_GOLDEN,
+  FIXTURE_CLOCK,
+  NOTIFICATION_FIXTURES,
   fixtureKey,
-} from "../../../__tests__/output-parity.golden";
+} from "../../../__tests__/fixtures";
 import { emailRenderer } from "../index";
 
 /**
- * The golden's context, stated rather than ticked. The old layer reached for
+ * The fixtures' context, stated rather than ticked. The old layer reached for
  * `new Date().getFullYear()` mid-render, which is why every render test had to
- * freeze the clock; here the year the golden was captured under is simply a
- * value.
+ * freeze the clock; here the year is simply a value.
  */
-const GOLDEN_CONTEXT: RenderContext = {
+const FIXTURE_CONTEXT: RenderContext = {
   brand: {
     name: "Company Semantics",
-    copyrightYear: new Date(OUTPUT_PARITY_CLOCK).getUTCFullYear(),
+    copyrightYear: new Date(FIXTURE_CLOCK).getUTCFullYear(),
   },
 };
 
@@ -77,7 +74,7 @@ describe("emailRenderer", () => {
       metadata: { kind: "org.invite", title: "Join Acme" },
       sections: [{ elements: [{ type: "body", text: "Hello." }] }],
     };
-    expect(emailRenderer.render(content, GOLDEN_CONTEXT).subject).toBe(
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT).subject).toBe(
       "Join Acme",
     );
   });
@@ -100,7 +97,7 @@ describe("emailRenderer", () => {
       metadata: { kind: "org.invite", title: "t" },
       sections: [{ elements: [{ type: "signature", signer: "Grace" }] }],
     };
-    expect(emailRenderer.render(content, GOLDEN_CONTEXT).text).toContain(
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT).text).toContain(
       "• Grace",
     );
   });
@@ -126,7 +123,7 @@ describe("emailRenderer", () => {
         },
       ],
     };
-    const { text } = emailRenderer.render(content, GOLDEN_CONTEXT);
+    const { text } = emailRenderer.render(content, FIXTURE_CONTEXT);
     expect(text).toContain("Status: Valid");
     expect(text).toContain("Request details:");
     expect(text).toContain("IP address: 203.0.113.1");
@@ -141,7 +138,7 @@ describe("emailRenderer", () => {
         },
       ],
     };
-    const { html } = emailRenderer.render(content, GOLDEN_CONTEXT);
+    const { html } = emailRenderer.render(content, FIXTURE_CONTEXT);
     expect(html).toContain("<script>");
     expect(html).not.toContain("<script>");
   });
@@ -153,27 +150,38 @@ describe("emailRenderer", () => {
         details: "5 codes in 2 minutes",
         timestamp: "2026-07-15T00:00:00.000Z",
       },
-      GOLDEN_CONTEXT,
+      FIXTURE_CONTEXT,
     );
-    expect(emailRenderer.render(content, GOLDEN_CONTEXT)).toEqual(
-      emailRenderer.render(content, GOLDEN_CONTEXT),
+    expect(emailRenderer.render(content, FIXTURE_CONTEXT)).toEqual(
+      emailRenderer.render(content, FIXTURE_CONTEXT),
     );
   });
 
-  describe("output parity with the email layer at 32.0.0", () => {
-    for (const fixture of OUTPUT_PARITY_FIXTURES) {
+  describe("renders every fixture", () => {
+    // Was a byte-for-byte assertion against the 32.0.0 golden until
+    // ADR-CONTRACTS-087 retired it. The markup itself is locked by
+    // `../../../__tests__/render-snapshot.test.ts`; what is worth proving HERE
+    // is narrower and survives a redesign — that every kind in the registry
+    // composes and renders through this channel at all, on both surfaces. A kind
+    // whose `compose` reaches for a field its payload lacks fails here, at the
+    // renderer, rather than in whichever consumer sends it first.
+    for (const fixture of NOTIFICATION_FIXTURES) {
       const key = fixtureKey(fixture.kind, fixture.name);
-      it(`${key} renders byte-for-byte`, () => {
+      it(`${key}`, () => {
         const definition = NOTIFICATION_DEFINITIONS[fixture.kind];
         // `payload as never`: the fixture call sites are type-checked in the
-        // golden module; this only bridges compose's per-kind payload.
+        // fixtures module; this only bridges compose's per-kind payload.
         const content = definition.compose(
           fixture.payload as never,
-          GOLDEN_CONTEXT,
+          FIXTURE_CONTEXT,
         );
-        expect(emailRenderer.render(content, GOLDEN_CONTEXT)).toEqual(
-          OUTPUT_PARITY_GOLDEN[key],
+        const { subject, text, html } = emailRenderer.render(
+          content,
+          FIXTURE_CONTEXT,
         );
+        expect(subject).toBeTruthy();
+        expect(text).toBeTruthy();
+        expect(html).toContain("<!DOCTYPE html>");
       });
     }
   });

package/src/notifications/renderers/email/chat.ts

@@ -8,8 +8,9 @@
  * the "⋮" dots.
  *
  * INVARIANTS:
- * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits. The
- *   box art is real output: the output-parity golden asserts every column of it.
+ * - Pure. The box art is real output, and every column of it is locked by
+ *   `../../__tests__/render-snapshot.test.ts` — a stray space is a visibly
+ *   broken email, not a whitespace nit.
  * - Both surfaces truncate at the same point — `clampMessage` is the one
  *   truncation authority, and HTML and plain text both run content through it.
  */

package/src/notifications/renderers/email/constants.ts

@@ -33,6 +33,23 @@ export const MONO = `font-family: ${MONO_FONT_STACK};`;
  */
 export const FONT_SIZE = "13px";
 
+/**
+ * The colour for a `warning` — the product's destructive token, resolved.
+ *
+ * This is `--destructive` from the app's `globals.css` `:root`
+ * (`oklch(0.577 0.245 27.325)`) converted to sRGB hex. It is COPIED, not
+ * imported, and it has to be: contracts sits ABOVE the app in the dependency
+ * flow, so this package cannot read the app's stylesheet — and email cannot read
+ * one either. There is no CSS to cascade from and no custom properties to
+ * resolve, so every colour in this channel is a literal in an inline `style`.
+ * If the token moves, this does not follow it; that divergence is the cost of
+ * the arrow pointing one way.
+ *
+ * The `:root` value rather than `.dark`'s, because this channel is light-only by
+ * construction — `./shells.ts` states `color: #1a1a1a` on the body.
+ */
+export const DESTRUCTIVE = "#e7000b";
+
 /**
  * The gap AFTER a rendered line: `"normal"` is a blank line in plain text,
  * anything else is none.

package/src/notifications/renderers/email/index.ts

@@ -11,10 +11,10 @@
  * - Pure. `render` is a function of `(content, context)` — no clock, no
  *   environment, no I/O. The copyright year comes from
  *   `context.brand.copyrightYear`.
- * - Output is byte-identical to what the old `src/email/render` emitted. That is
- *   the whole constraint of this migration, and `__tests__/render.test.ts`
- *   proves it against the frozen output-parity golden — which, now that the old
- *   layer is deleted, is the only surviving record of those bytes.
+ * - Output is locked by `../../__tests__/render-snapshot.test.ts`. Byte-identity
+ *   with the old `src/email/render` was the whole constraint of the migration
+ *   and it held; ADR-CONTRACTS-087 discharged that proof once it shipped, so
+ *   this channel's markup is now free to change — reviewably, via the snapshot.
  * - `supports` answers true for every element type: email is the rich channel,
  *   and there is nothing in the content model it cannot depict.
  */

package/src/notifications/renderers/email/render.ts

@@ -5,7 +5,9 @@
  * module offered templates a component per intent (`greeting()`, `keyValue()`,
  * `footer()`) and each template chose which to call; here the CONTENT names the
  * intent and this module is the only thing that knows the markup. The strings
- * are the same strings — the output-parity golden asserts them byte-for-byte.
+ * started as the same strings, byte-for-byte; they are free to diverge now
+ * (ADR-CONTRACTS-087) and `../../__tests__/render-snapshot.test.ts` is what
+ * makes each divergence a reviewed one.
  *
  * **Spacing is derived, because the content model does not carry it.** The old
  * layer passed a `Spacing` per block, and `../../kinds` deliberately dropped it:
@@ -45,6 +47,7 @@ import type { RenderContext } from "../../context";
 
 import {
   COMPANY_URL,
+  DESTRUCTIVE,
   FONT_SIZE,
   MONO,
   SPACING,
@@ -151,8 +154,18 @@ export function renderElement(
     case "warning": {
       // Fieldless by design — the banner IS the content, and its wording is the
       // renderer's (see `../../content.ts`).
+      //
+      // The colour is this channel's answer to "this is a security notice", and
+      // only the HTML surface can give it: plain text has no colour, so there
+      // the banner's own glyphs carry the whole signal.
       const text = "🆆🅰🆁🅽🅸🅽🅶";
-      return [paragraph(escapeHtml(text), text, trailing)];
+      return [
+        paragraph(
+          `<span style="color: ${DESTRUCTIVE};">${escapeHtml(text)}</span>`,
+          text,
+          trailing,
+        ),
+      ];
     }
 
     case "notice":

package/src/notifications/renderers/email/shells.ts

@@ -8,8 +8,9 @@
  *
  * INVARIANTS:
  * - Pure functions of their input lines. No clock, no environment, no I/O.
- * - Byte-identical to what that module emitted. These strings are the email's
- *   actual markup; the output-parity golden asserts them character-for-character.
+ * - These strings are the email's actual markup, and
+ *   `../../__tests__/render-snapshot.test.ts` asserts them
+ *   character-for-character.
  */
 
 import { MONO, type Spacing } from "./constants";

package/src/notifications/text.ts

@@ -14,8 +14,8 @@
  *   returns a tag, the seam ADR-CONTRACTS-086 draws is back where it started.
  * - Pure. `formatExpiry` builds a `Date` from its ARGUMENT, which is not a clock
  *   read; nothing here may add one.
- * - These strings are output. The output-parity golden asserts them
- *   byte-for-byte, so a wording change here changes a real sent email.
+ * - These strings are output. `__tests__/render-snapshot.test.ts` locks them, so
+ *   a wording change here changes a real sent email.
  */
 
 /** The standard "no action required" reassurance line. */