@company-semantics/contracts 35.0.0 → 36.0.0

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

@@ -12,13 +12,13 @@
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 
 import { COMPANY_NAME, createRenderContext } from "../context";
-import { OUTPUT_PARITY_CLOCK } from "./output-parity.golden";
+import { FIXTURE_CLOCK } from "./fixtures";
 
-const FROZEN_YEAR = new Date(OUTPUT_PARITY_CLOCK).getUTCFullYear();
+const FROZEN_YEAR = new Date(FIXTURE_CLOCK).getUTCFullYear();
 
 beforeAll(() => {
   vi.useFakeTimers();
-  vi.setSystemTime(new Date(OUTPUT_PARITY_CLOCK));
+  vi.setSystemTime(new Date(FIXTURE_CLOCK));
 });
 
 afterAll(() => {
@@ -38,7 +38,7 @@ describe("createRenderContext", () => {
   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));
+    vi.setSystemTime(new Date(FIXTURE_CLOCK));
   });
 
   it("overrides each brand field independently", () => {
@@ -55,7 +55,7 @@ describe("createRenderContext", () => {
     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));
+    vi.setSystemTime(new Date(FIXTURE_CLOCK));
   });
 
   it("returns a fresh context per call — callers cannot alias each other", () => {

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

@@ -31,7 +31,7 @@ import type { NotificationContent, NotificationElement } from "../content";
 import { createRenderContext } from "../context";
 import type { NotificationKind } from "../kinds";
 import { NOTIFICATION_DEFINITIONS } from "../registry";
-import { OUTPUT_PARITY_FIXTURES } from "./output-parity.golden";
+import { NOTIFICATION_FIXTURES } from "./fixtures";
 
 const CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
 
@@ -40,7 +40,7 @@ function compose(
   kind: NotificationKind,
   context = CONTEXT,
 ): NotificationContent {
-  const fixture = OUTPUT_PARITY_FIXTURES.find((f) => f.kind === kind);
+  const fixture = NOTIFICATION_FIXTURES.find((f) => f.kind === kind);
   if (!fixture) throw new Error(`No parity fixture for kind: ${kind}`);
   const fn = NOTIFICATION_DEFINITIONS[kind].compose as (
     p: unknown,

package/src/notifications/__tests__/fixtures.ts

@@ -0,0 +1,226 @@
+/**
+ * The notification fixture corpus: every implemented kind × representative
+ * payload. Shared by `./render-snapshot.test.ts`, `./definition.test.ts`,
+ * `./registry.test.ts` and `../renderers/email/__tests__/render.test.ts`, so a
+ * kind added to the registry is covered everywhere by being added once here.
+ *
+ * WAS `output-parity.golden.ts` (ADR-CONTRACTS-087). These same inputs used to
+ * carry a frozen `OUTPUT_PARITY_GOLDEN` of the `{ subject, text, html }` the
+ * email layer emitted at 32.0.0, asserted byte-for-byte to prove the
+ * multi-channel generalisation (ADR-CONTRACTS-086) changed no output. That proof
+ * passed and shipped in 35.0.0, which discharged it: it was a claim about a
+ * migration, not a freeze on email design. The bytes were retired rather than
+ * rewritten — editing them to match a deliberate redesign would have made the
+ * file assert something false about a layer that no longer exists. They remain
+ * readable in git at `v35.0.0`.
+ *
+ * `./render-snapshot.test.ts` is now the fence: it locks the same fixtures'
+ * rendered output, and unlike the golden it is regenerable on purpose, because
+ * changing how email looks is now an ordinary reviewed diff.
+ *
+ * Capture-time options are not recorded. The old `renderEmail` took a
+ * `RenderEmailOptions`, and one fixture set `includeRequestMetadata: true`; the
+ * entry point has no equivalent because `auth.otp`'s `compose` gates request
+ * details on whether the payload carries them — and that fixture's payload
+ * carries both, so the gate opens anyway.
+ */
+
+import type { NotificationKind } from "../kinds";
+import type { NotificationPayloads } from "../payloads";
+
+/**
+ * The instant every fixture renders under.
+ *
+ * A pinned year, not a frozen clock. The copyright year is a value on
+ * `RenderContext`, so a test states this instant instead of stubbing time —
+ * which is the impurity ADR-CONTRACTS-086 retired. Pinned rather than left to
+ * the wall clock so no snapshot is due to fail on New Year's Day.
+ */
+export const FIXTURE_CLOCK = "2026-07-15T00:00:00.000Z";
+
+/** One case: a kind rendered with a representative payload. */
+export interface NotificationFixture {
+  readonly kind: NotificationKind;
+  /** Variant label, unique within a kind. */
+  readonly name: string;
+  readonly payload: NotificationPayloads[NotificationKind];
+}
+
+/** Stable label for a fixture — also its snapshot key. */
+export function fixtureKey(kind: NotificationKind, name: string): string {
+  return `${kind} · ${name}`;
+}
+
+const fixtures: NotificationFixture[] = [];
+function add<K extends NotificationKind>(
+  kind: K,
+  name: string,
+  payload: NotificationPayloads[K],
+): void {
+  fixtures.push({ kind, name, payload });
+}
+
+const APP = "https://app.companysemantics.ai";
+
+add("auth.otp", "Default", { otp: "123456", expiresInMinutes: 10 });
+add("auth.otp", "Short expiry", { otp: "902413", expiresInMinutes: 1 });
+add("auth.otp", "With request metadata", {
+  otp: "246810",
+  expiresInMinutes: 5,
+  requestIp: "203.0.113.4",
+  userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+});
+
+add("org.invite", "Admin", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "admin",
+  acceptUrl: `${APP}/invite/abc123`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+add("org.invite", "Member", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/def456`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+
+add("org.unit_owner_granted", "Unit owner + message", {
+  granterName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  orgName: "Acme Corp",
+  unitName: "Platform Engineering",
+  roleLabel: "Unit owner",
+  ctaUrl: `${APP}/org/unit/42`,
+  message: "Welcome aboard — glad to have you owning this team.",
+});
+add("org.unit_owner_granted", "Delegate with expiry", {
+  granterName: "Jordan Lee",
+  orgName: "Acme Corp",
+  unitName: "Platform Engineering",
+  roleLabel: "Delegate",
+  ctaUrl: `${APP}/org/unit/42`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+
+add("org.ownership_transfer", "With note + from", {
+  orgName: "Acme Corp",
+  acceptUrl: `${APP}/owner-transfer/accept/tok123`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  note: "Handing this over as I move to an advisory role.",
+  fromName: "Jordan Lee",
+});
+add("org.ownership_transfer", "No note (admin)", {
+  orgName: "Acme Corp",
+  acceptUrl: `${APP}/owner-transfer/accept/tok456`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+
+add("org.ownership_transfer_completed", "Default", {
+  orgName: "Acme Corp",
+  newOwnerEmail: "new.owner@acme.com",
+});
+
+add("security.alert", "Excessive OTP requests", {
+  alertType: "excessive_otp_requests",
+  details: "12 login codes requested in 5 minutes",
+  timestamp: "2026-07-12T14:30:00Z",
+});
+add("security.alert", "Unusual login location", {
+  alertType: "unusual_login_location",
+  details: "Login from Berlin, DE",
+  timestamp: "2026-07-12T14:30:00Z",
+});
+
+const CHAT_BASE = {
+  sharedByName: "Alex Rivera",
+  visibility: "private",
+} as const;
+add("chat.shared", "Default", {
+  ...CHAT_BASE,
+  chatTitle: "API design discussion",
+  shareUrl: `${APP}/share/abc123`,
+  previewText:
+    "Here are my thoughts on the REST API design for the new authentication endpoints.",
+});
+add("chat.shared", "No preview", {
+  ...CHAT_BASE,
+  chatTitle: "Quick sync notes",
+  shareUrl: `${APP}/share/xyz789`,
+});
+add("chat.shared", "Long title", {
+  ...CHAT_BASE,
+  visibility: "public",
+  chatTitle:
+    "This is a very long chat title that should be truncated to fit the layout properly",
+  shareUrl: `${APP}/share/long456`,
+  previewText: "The assistant response preview text.",
+});
+add("chat.shared", "Long preview", {
+  ...CHAT_BASE,
+  chatTitle: "Code review feedback",
+  shareUrl: `${APP}/share/preview789`,
+  previewText:
+    "I reviewed the pull request and found several areas that need improvement. The authentication logic needs better error handling, and the database queries could be optimized.",
+});
+add("chat.shared", "Short", {
+  ...CHAT_BASE,
+  chatTitle: "Hi",
+  shareUrl: `${APP}/share/short123`,
+  previewText: "Hello!",
+});
+
+add("share.granted", "Document · editor · message", {
+  granterName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  entityLabel: "document",
+  entityTitle: "Q3 Roadmap",
+  accessLevel: "editor",
+  ctaUrl: `${APP}/doc/roadmap`,
+  message: "Take a look before Thursday's planning.",
+});
+add("share.granted", "Meeting · viewer · no title", {
+  granterName: "Jordan Lee",
+  entityLabel: "meeting",
+  accessLevel: "viewer",
+  ctaUrl: `${APP}/meeting/8842`,
+});
+
+add("companyMd.access_requested", "With message", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  message: "I'd like to contribute the onboarding section.",
+  reviewUrl: `${APP}/doc/handbook?request=req_123`,
+});
+add("companyMd.access_requested", "No message", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  reviewUrl: `${APP}/doc/handbook?request=req_456`,
+});
+
+add("companyMd.access_request_approved", "Editor", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "editor",
+  docUrl: `${APP}/doc/handbook`,
+});
+add("companyMd.access_request_approved", "Viewer", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "viewer",
+  docUrl: `${APP}/doc/handbook`,
+});
+
+add("companyMd.access_request_denied", "With reason", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  reason: "This doc is limited to the platform team for now.",
+});
+add("companyMd.access_request_denied", "No reason", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+});
+
+/** The corpus — every implemented kind × representative variants. */
+export const NOTIFICATION_FIXTURES: readonly NotificationFixture[] = fixtures;

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

@@ -17,9 +17,8 @@
  *   union member is added without being named here;
  * - the frozen list in the first test, which fails at runtime if one is removed;
  * - `./registry.test.ts`, which pins a definition for every member;
- * - `./output-parity.test.ts`, which pins golden bytes — captured from the old
- *   layer — for every member. That is what now carries "these are exactly the
- *   kinds email could render": every kind here has bytes that layer produced.
+ * - `./render-snapshot.test.ts`, which pins rendered output for every member.
+ *   That is what carries "these are exactly the kinds email can render".
  *
  * The DIVERGENCE is the easiest thing in this change to mistake for an omission,
  * so it keeps a test of its own. `auth.magic_link` was a registered subject with

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

@@ -28,11 +28,7 @@ import {
   isValidNotificationKind,
   NOTIFICATION_DEFINITIONS,
 } from "../registry";
-import {
-  fixtureKey,
-  OUTPUT_PARITY_FIXTURES,
-  OUTPUT_PARITY_GOLDEN,
-} from "./output-parity.golden";
+import { fixtureKey, NOTIFICATION_FIXTURES } from "./fixtures";
 
 const KINDS = Object.keys(NOTIFICATION_DEFINITIONS) as NotificationKind[];
 
@@ -45,7 +41,7 @@ const CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
  * so a second set of inputs would be a second thing to keep true.
  */
 function payloadFor(kind: NotificationKind): unknown {
-  const fixture = OUTPUT_PARITY_FIXTURES.find((f) => f.kind === kind);
+  const fixture = NOTIFICATION_FIXTURES.find((f) => f.kind === kind);
   if (!fixture) throw new Error(`No parity fixture for kind: ${kind}`);
   return fixture.payload;
 }
@@ -112,28 +108,32 @@ describe("NOTIFICATION_DEFINITIONS", () => {
     }
   });
 
-  it("titles every kind exactly as email subjected it at 32.0.0", () => {
-    // The subject MOVED from EMAIL_KINDS into compose — it was not rewritten.
-    // Asserted against the frozen golden's subjects, across every parity
-    // fixture, so the interpolation the old `resolveSubject`/`subjectData` did
-    // (the `{orgName}` fill, and unit_owner_granted's derived `roleWord`) is
-    // proven to survive as a template literal rather than assumed to.
+  it("titles every kind", () => {
+    // The title is what the email channel turns into a subject, and the
+    // interpolation `compose` does (the `{orgName}` fill, and
+    // unit_owner_granted's derived `roleWord`) is easy to break silently — a
+    // template literal that stops filling yields a plausible-looking title with
+    // a hole in it. Snapshotting every fixture's title makes that a reviewable
+    // diff, and isolates the claim at COMPOSE: `./render-snapshot.test.ts`
+    // covers the same titles once the renderer has had them.
     //
-    // The oracle used to be the old `renderEmail`'s own output. The golden is
-    // what replaced it when that layer was deleted, and it is the stronger of
-    // the two: it is the bytes 32.0.0 actually shipped, not live code that could
-    // have drifted alongside this registry. This isolates the claim at COMPOSE —
-    // `./output-parity.test.ts` proves the same subjects survive the renderer.
-    for (const fixture of OUTPUT_PARITY_FIXTURES) {
-      const compose = NOTIFICATION_DEFINITIONS[fixture.kind].compose as (
-        p: unknown,
-        c: typeof CONTEXT,
-      ) => { metadata: { title: string } };
-
-      expect(compose(fixture.payload, CONTEXT).metadata.title).toBe(
-        OUTPUT_PARITY_GOLDEN[fixtureKey(fixture.kind, fixture.name)].subject,
-      );
-    }
+    // These titles were asserted against the frozen 32.0.0 golden's subjects
+    // until ADR-CONTRACTS-087 retired it — the values below are those subjects,
+    // recaptured here as an ordinary snapshot. The migration proof they served
+    // was discharged in 35.0.0.
+    const titles = Object.fromEntries(
+      NOTIFICATION_FIXTURES.map((fixture) => {
+        const compose = NOTIFICATION_DEFINITIONS[fixture.kind].compose as (
+          p: unknown,
+          c: typeof CONTEXT,
+        ) => { metadata: { title: string } };
+        return [
+          fixtureKey(fixture.kind, fixture.name),
+          compose(fixture.payload, CONTEXT).metadata.title,
+        ];
+      }),
+    );
+    expect(titles).toMatchSnapshot();
   });
 });
 

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/content.ts

@@ -138,11 +138,23 @@ export interface Signature {
   signer?: string;
 }
 
-/** A leading image. `alt` is required — a text-only channel has nothing else. */
+/**
+ * A leading image. `alt` is required — a text-only channel has nothing else.
+ *
+ * `width`/`height` are the image's intrinsic pixel dimensions. They are optional
+ * because a channel that can measure an image itself does not need to be told, and
+ * requiring them would put a rendering constraint into channel-agnostic content.
+ * But a channel MAY be unable to draw one without them: AMP's `<amp-img>` requires
+ * explicit dimensions to reserve layout before the image loads, so the email
+ * channel's AMP surface degrades to the `alt` text when they are absent
+ * (ADR-CONTRACTS-089). Supplying them is what makes the image drawable everywhere.
+ */
 export interface HeroImage {
   type: "heroImage";
   src: string;
   alt: string;
+  width?: number;
+  height?: number;
 }
 
 // =============================================================================

package/src/notifications/index.ts

@@ -58,17 +58,23 @@ export type { RenderedEmail } from "./renderers/email";
 
 export { emailRenderer } from "./renderers/email";
 
+// The `Slack*` block types this barrel used to export were a hand-written subset
+// of Block Kit and are GONE (ADR-CONTRACTS-090). Slack's own `@slack/types` is
+// the vocabulary now, re-exported here so a consumer need not depend on it
+// directly: `SlackBlock` -> `KnownBlock`, `SlackSectionBlock` -> `SectionBlock`,
+// `SlackMrkdwnText` -> `MrkdwnElement`, `SlackPlainText` -> `PlainTextElement`.
 export type {
-  SlackActionsBlock,
-  SlackBlock,
-  SlackButtonElement,
-  SlackContextBlock,
-  SlackDividerBlock,
-  SlackImageBlock,
+  ActionsBlock,
+  ContextBlock,
+  DividerBlock,
+  HeaderBlock,
+  ImageBlock,
+  KnownBlock,
+  MrkdwnElement,
+  PlainTextElement,
+  RichTextBlock,
+  SectionBlock,
   SlackMessage,
-  SlackMrkdwnText,
-  SlackPlainText,
-  SlackSectionBlock,
 } from "./renderers/slack";
 
 export { slackRenderer } from "./renderers/slack";

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.