@company-semantics/contracts 35.0.0 → 36.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "35.0.0",
+  "version": "36.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -104,6 +104,7 @@
     "prepublishOnly": "echo 'ERROR: Publishing is CI-only via tag push. Use pnpm release instead.' && exit 1",
     "test": "vitest run",
     "test:run": "vitest run",
+    "color": "tsx scripts/color.ts",
     "generate:spec-hash": "tsx scripts/generate-spec-hash.ts",
     "generate:spec-hash:check": "tsx scripts/generate-spec-hash.ts --check",
     "generate:api": "pnpm generate:api-types && pnpm generate:spec-hash && pnpm generate:openapi-routes",
@@ -115,17 +116,21 @@
     "repo-map": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --write",
     "repo-map:check": "tsx ../company-semantics-ci/scripts/generate-repo-map.ts --roots src --name company-semantics-contracts --check",
     "readme-api": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --write --jsdoc",
-    "readme-api:check": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --check --jsdoc"
+    "readme-api:check": "tsx ../company-semantics-ci/scripts/generate-readme-api.ts --roots src --check --jsdoc",
+    "validate:amp": "tsx scripts/validate-amp.ts"
   },
   "packageManager": "pnpm@10.25.0",
   "engines": {
     "node": "22.x"
   },
   "dependencies": {
+    "@slack/types": "^3.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
+    "amphtml-validator": "^1.0.38",
+    "culori": "^4.0.2",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",
     "markdownlint-cli2": "^0.23.0",

package/src/notifications/README.md

@@ -9,15 +9,17 @@ into `Definition → Payload → compose(payload, context) → Content → Rende
 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.
+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,
@@ -91,16 +93,16 @@ deliberately (ADR-CONTRACTS-086):
 
 ## 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
+- `__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

package/src/notifications/__tests__/README.md

@@ -2,53 +2,48 @@
 
 ## 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.
+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
 
-- 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.
+- 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

@@ -13,6 +13,11 @@ 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.
 
@@ -20,13 +25,15 @@ file, so the `.snap` had to travel with it.
 
 - 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.
+- 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",
+}
+`;