@company-semantics/contracts 92.0.0 → 93.0.0

package/src/billing/refusals.ts

@@ -40,6 +40,11 @@
  */
 import { z } from "zod";
 
+import {
+  AffordanceSchema,
+  MAX_OFFERED_AFFORDANCES,
+} from "../affordances/affordance";
+
 import { type AiPauseReason } from "./vocabulary";
 
 /* -------------------------------------------------------------------------- */
@@ -216,5 +221,12 @@ export const BillingRefusalPartSchema = z
     orgId: z.string(),
     /** Whether retrying the same turn could succeed once the cause clears. */
     retryable: z.boolean(),
+    /**
+     * The catalog affordances that resolve the refusal for this viewer (control
+     * ADR affordance-system), e.g. billing.open. Present only when non-empty;
+     * the app renders them as controls beside the code's fact.
+     */
+    // prettier-ignore
+    affordances: z.array(AffordanceSchema).min(1).max(MAX_OFFERED_AFFORDANCES).optional(),
   })
   .strict();

package/src/message-parts/README.md

@@ -17,6 +17,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `SuggestedRepliesPart` is a surface but NOT a governed one: a chip fires an ordinary user turn (no `executionId`, no `submitEndpoint`), is stateless (clicking never consumes it) and advisory (the composer stays enabled) — so it is outside the at-most-one-governed-surface-per-turn rule
 - `WorkflowProgressPart` is the second non-governed surface: a two-field ANCHOR (`workflowId`, `workflowType`) to a durable background workflow. It presents no decision, carries no result snapshot (minted at t=0; parts are never rewritten) and no `startedAt` (operational state stays off immutable content), and names no domain vocabulary — live state is hydrated from the generic workflow projection read
 - `InputRequestPart` (`data-input-request` on the wire) is the GENERIC, GOVERNED anchor for a reviewed request: `{ requestType, requestId, stepCount, withheldCount }`, with every invariant of the structure-review anchor (anchor only — no cards, no endpoints, no staleness hashes; counts against the at-most-one-governed-surface-per-turn rule; emission is orchestration-driven). `isInputRequestDataPartShape` checks `requestType` as a non-empty string, NOT as a member of `INPUT_REQUEST_TYPES`: an unknown type renders nothing but never invalidates a persisted part
+- `AffordanceOfferPart` (`data-affordance-offer` on the wire) is the fourth non-governed surface: the next steps a pushed chat OFFERS, frozen with it as `OfferedAffordance` instances (control ADR `affordance-system`). Ids and args only — never labels, hrefs or a projected id (`review.open`), at most `MAX_OFFERED_AFFORDANCES`; written once with its message and never re-derived; the app renders each as a real control, re-gated per viewer. Built by `WireSurfaceBuilder.affordanceOffer`; emission is orchestration-driven (the proactive chat writer), never a model choice
 - `StructureReviewPart` (`data-structure-review`) is FROZEN, not retired: it stays in `SurfacePart` and parses forever because persisted transcripts carry it, and org-structure keeps emitting it
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
@@ -24,6 +25,9 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 ## Public API
 
 - `AddPartResult` _(type)_ — Result of adding a part to the builder.
+- `AffordanceOfferData` _(type)_ — Affordance offer data payload: the frozen, ordered offer.
+- `AffordanceOfferDataPart` _(type)_ — Affordance offer data part (wire format, as persisted in `chat_messages.parts`).
+- `AffordanceOfferPart` _(type)_ — Affordance offer message part (semantic type, as rendered).
 - `AssistantMessagePart` _(type)_ — All assistant message part types.
 - `CONFIRMATION_LABELS` — Human-readable confirmation dialog titles for each execution kind.
 - `CandidateSource` _(type)_ — How the frontend sources candidate values for an editable field. - `inline`: the options are shipped with the…
@@ -116,6 +120,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 
 **Internal domains:**
 
+- `affordances`
 - `chat`
 - `execution`
 - `input-requests`

package/src/message-parts/affordance-offer.ts

@@ -0,0 +1,44 @@
+/**
+ * Affordance Offer Part Types
+ *
+ * The next steps a message OFFERS, frozen with it (control ADR
+ * affordance-system). A pushed proactive chat carries its composer's
+ * `affordances` here so the app renders them as real controls — re-gated per
+ * viewer at render, live availability read separately, executed only by the
+ * server — instead of as chips that merely send a prompt.
+ *
+ * AFFORDANCE OFFER INVARIANTS:
+ * - OFFERED INSTANCES ONLY. Ids and their args, never labels or hrefs (the app
+ *   owns both), never a projected id (`review.open`), at most
+ *   MAX_OFFERED_AFFORDANCES.
+ * - WRITTEN ONCE, with the message it belongs to; never re-derived.
+ * - SHARE-SAFE. Ids and opaque target ids only.
+ * - NON-GOVERNED. It presents no decision and consumes no surface budget.
+ * - Emission is orchestration-driven (the proactive chat writer), never a model
+ *   choice.
+ *
+ * Purely additive: an app that predates this part normalizes unknown part
+ * types to null and drops it.
+ */
+
+import type { OfferedAffordance } from "../affordances/affordance";
+
+/** Affordance offer data payload: the frozen, ordered offer. */
+export interface AffordanceOfferData {
+  affordances: readonly OfferedAffordance[];
+}
+
+/** Affordance offer message part (semantic type, as rendered). */
+export interface AffordanceOfferPart {
+  type: "affordance-offer";
+  data: AffordanceOfferData;
+}
+
+/**
+ * Affordance offer data part (wire format, as persisted in
+ * `chat_messages.parts`). Uses AI SDK's data-{name} convention.
+ */
+export interface AffordanceOfferDataPart {
+  type: "data-affordance-offer";
+  data: AffordanceOfferData;
+}

package/src/message-parts/index.ts

@@ -97,6 +97,13 @@ export type {
   WorkflowOutcomeDataPart,
 } from "./workflow-outcome";
 
+// Affordance offer types (non-governed, the frozen offer on a pushed chat)
+export type {
+  AffordanceOfferData,
+  AffordanceOfferPart,
+  AffordanceOfferDataPart,
+} from "./affordance-offer";
+
 // Execution result types
 export type {
   ExecutionArtifactStatus,

package/src/message-parts/types.ts

@@ -22,6 +22,7 @@ import type { InputRequestPart } from "./input-request";
 import type { SuggestedRepliesPart } from "./suggested-replies";
 import type { WorkflowProgressPart } from "./workflow-progress";
 import type { WorkflowOutcomePart } from "./workflow-outcome";
+import type { AffordanceOfferPart } from "./affordance-offer";
 
 // =============================================================================
 // Narrative Parts (Streamable)
@@ -130,6 +131,10 @@ export interface TablePart {
  * workflow's execution epoch, carried on its settlement message. It presents no
  * decision; a review disposition is delivered as its own InputRequestPart.
  *
+ * AffordanceOfferPart is the fourth non-governed member: the next steps a pushed
+ * chat offers, frozen with it as affordance instances (control ADR
+ * affordance-system). It presents no decision and consumes no surface budget.
+ *
  * InputRequestPart is GOVERNED, like StructureReviewPart: it anchors a reviewed
  * request that asks the person to decide, so it counts against the
  * at-most-one-governed-surface-per-turn budget. It is the generic anchor;
@@ -148,7 +153,8 @@ export type SurfacePart =
   | InputRequestPart
   | SuggestedRepliesPart
   | WorkflowProgressPart
-  | WorkflowOutcomePart;
+  | WorkflowOutcomePart
+  | AffordanceOfferPart;
 
 /**
  * All assistant message part types.

package/src/message-parts/wire.ts

@@ -39,6 +39,10 @@ import type {
   WorkflowOutcomeData,
   WorkflowOutcomeDataPart,
 } from "./workflow-outcome";
+import type {
+  AffordanceOfferData,
+  AffordanceOfferDataPart,
+} from "./affordance-offer";
 import type {
   ExecutionResultData,
   ExecutionResultDataPart,
@@ -272,6 +276,20 @@ export const WireSurfaceBuilder = {
     };
   },
 
+  /**
+   * Build an affordance-offer data part: the frozen next steps a pushed chat
+   * offers (control ADR affordance-system). Non-governed; ids and args only.
+   *
+   * @param data - The offered affordance instances, in the producer's order
+   * @returns Wire-format affordance offer part
+   */
+  affordanceOffer(data: AffordanceOfferData): AffordanceOfferDataPart {
+    return {
+      type: "data-affordance-offer",
+      data,
+    };
+  },
+
   /**
    * Build an execution result data part for streaming.
    * Reports the outcome of an executed action.

package/src/notifications/README.md

@@ -131,9 +131,23 @@ deliberately (ADR-CONTRACTS-086):
   `chat.mention`: a kind is composable prose for a caller with an explicit
   trigger, and naming it on a plan would make the proactive pipeline send it
   autonomously — notify/'s INV-1 to grant, not this union's.
-- 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.
+- This domain depends on nothing outside itself except one **type-only** import:
+  `content.ts` reads `OfferedAffordance` from `../affordances/affordance` for
+  `CallToAction.affordance`. The `notifications → email` imports that existed
+  while both layers did are gone with the directory, and nothing may reintroduce
+  one.
+- `CallToAction.affordance` names the catalog affordance a link performs
+  (control ADR affordance-system; contracts ADR
+  affordance-catalog-wave-and-grounded-ctas). It is present exactly when the
+  link does what a catalog id names — the three `billing.*` kinds
+  (`billing.open`), `chat.shared` (`chat.open` with the payload's `chatId`),
+  `companyMd.access_request_approved` (`companyMd.openDoc` with `docId`) and
+  `org.unit_owner_granted` (`team.open` with `unitId`) — and the label line
+  carries `// cta-grounded: <id>`. It is absent for an OTP code (no `href`) and
+  for a link no catalog id names (an invite acceptance, a comment). Renderers
+  ignore it and draw the link as before. Body prose around a call to action
+  states facts and never tells the reader what to do; the `cta-prose-ratchet`
+  guard and `__tests__/grounded-ctas.test.ts` hold that line.
 - 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

package/src/notifications/__tests__/README.md

@@ -13,6 +13,10 @@ to.
 - `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.**
+- `grounded-ctas.test.ts` — a linked call to action whose link a catalog id
+  names carries that affordance, targeting the fixture payload's own id; a code
+  to copy never carries one; and no grounded or share notification body tells
+  the reader what to do (control ADR affordance-system).
 
 ## The retired output-parity golden (ADR-CONTRACTS-087)
 

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

@@ -552,7 +552,7 @@ exports[`email render > billing.auto_recharge_failed · Default 1`] = `
 <p class="csr-p-normal">Acme Corp tried to top up its AI balance automatically and the charge was not completed.</p>
 <p class="csr-p-tight">Workspace: Acme Corp</p>
 <p class="csr-p-normal">Status: Top-up failed</p>
-<p class="csr-p-normal">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits rather than running the same card again — so updating the payment method is what resolves this.</p>
+<p class="csr-p-normal">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits before charging the same card a second time — so updating the payment method is what resolves this.</p>
 <table cellpadding="0" cellspacing="0" border="0" class="cs-cta cs-cta-hover csr-cta-box-normal">
   <tr><td class="csr-cta-cell-linked">
     <a href="https://app.companysemantics.ai/org/billing" class="cs-link csr-cta-anchor">&gt;&gt; <span class="csr-cta-label">OPEN BILLING</span> &lt;&lt;</a>
@@ -588,7 +588,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Acme Corp tried to top up its AI balance automatically and the charge was not completed.</p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Workspace: Acme Corp</p>
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Status: Top-up failed</p>
-<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits rather than running the same card again — so updating the payment method is what resolves this.</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">AI work carries on until the remaining balance is spent, and then pauses. The next attempt is not immediate — the system waits before charging the same card a second time — so updating the payment method is what resolves this.</p>
 <table cellpadding="0" cellspacing="0" border="0" class="cs-cta cs-cta-hover" style="display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0 0 20px 0; max-width: 220px;">
   <tr><td style="text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px;">
     <a href="https://app.companysemantics.ai/org/billing" class="cs-link" style="display: block; padding: 16px 24px; color: #0047FF; text-decoration: none;">&gt;&gt; <span style="text-decoration: underline;">OPEN BILLING</span> &lt;&lt;</a>
@@ -610,8 +610,8 @@ Status: Top-up failed
 
 AI work carries on until the remaining balance
 is spent, and then pauses. The next attempt is
-not immediate — the system waits rather than
-running the same card again — so updating the
+not immediate — the system waits before charging
+the same card a second time — so updating the
 payment method is what resolves this.
 
 *------------------------*
@@ -1590,7 +1590,7 @@ exports[`email render > chat.shared · Long title 1`] = `
 <body class="csr-body">
 <div class="csr-frame">
 <p class="csr-p-normal">Hi there,</p>
-<p class="csr-p-normal">A chat was shared with you. You can take part in it.</p>
+<p class="csr-p-normal">A chat was shared with you, and you are a participant.</p>
 <hr class="cs-faint csr-chat-rule-top">
 <table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-24">
   <tr>
@@ -1654,7 +1654,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
 <body style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; color: #1a1a1a; background-color: #ffffff; margin: 0; padding: 0;">
 <div style="max-width: 520px;">
 <p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Hi there,</p>
-<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">A chat was shared with you. You can take part in it.</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">A chat was shared with you, and you are a participant.</p>
 <hr class="cs-faint" style="border: none; border-top: 1px solid #bbb; margin: 12px 0 24px 0;">
 <table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
   <tr>
@@ -1699,8 +1699,8 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   "subject": "A chat has been shared with you",
   "text": "Hi there,
 
-A chat was shared with you. You can take part in
-it.
+A chat was shared with you, and you are a
+participant.
 
 ────────────────────────────────────────────────
 
@@ -2909,7 +2909,7 @@ exports[`email render > companyMd.access_request_approved · Editor 1`] = `
   <tr>
     <td class="csr-chat-avatar-left">[c_S]</td>
     <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
-      <tr><td class="cs-bubble csr-bubble-assistant">Open to view.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">The document is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -2962,7 +2962,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <tr>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap;">[c_S]</td>
     <td style="width: 100%; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Open to view.</td></tr>
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">The document is ready for you.</td></tr>
     </table></td>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
   </tr>
@@ -2995,7 +2995,8 @@ Your access request was approved.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-[c_S]  │ Open to view.                │
+       │ The document is ready for    │
+[c_S]  │ you.                         │
        └──────────────────────────────┘
 
        *----------------*
@@ -3257,7 +3258,7 @@ exports[`email render > companyMd.access_request_approved · Viewer 1`] = `
   <tr>
     <td class="csr-chat-avatar-left">[c_S]</td>
     <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
-      <tr><td class="cs-bubble csr-bubble-assistant">Open to view.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">The document is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -3310,7 +3311,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <tr>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap;">[c_S]</td>
     <td style="width: 100%; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Open to view.</td></tr>
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">The document is ready for you.</td></tr>
     </table></td>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
   </tr>
@@ -3343,7 +3344,8 @@ Your access request was approved.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-[c_S]  │ Open to view.                │
+       │ The document is ready for    │
+[c_S]  │ you.                         │
        └──────────────────────────────┘
 
        *----------------*
@@ -5059,7 +5061,7 @@ exports[`email render > org.unit_owner_granted · Delegate with expiry 1`] = `
   <tr>
     <td class="csr-chat-avatar-left">[c_S]</td>
     <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
-      <tr><td class="cs-bubble csr-bubble-assistant">Open the team to get started.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">Platform Engineering is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -5113,7 +5115,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <tr>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap;">[c_S]</td>
     <td style="width: 100%; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Open the team to get started.</td></tr>
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Platform Engineering is ready for you.</td></tr>
     </table></td>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
   </tr>
@@ -5150,8 +5152,8 @@ strategy, and execution against goals.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-       │ Open the team to get         │
-[c_S]  │ started.                     │
+       │ Platform Engineering is      │
+[c_S]  │ ready for you.               │
        └──────────────────────────────┘
 
        *-----------------------*
@@ -5249,7 +5251,7 @@ exports[`email render > org.unit_owner_granted · Unit owner + message 1`] = `
   <tr>
     <td class="csr-chat-avatar-left">[c_S]</td>
     <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
-      <tr><td class="cs-bubble csr-bubble-assistant">Open the team to get started.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">Platform Engineering is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -5316,7 +5318,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <tr>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap;">[c_S]</td>
     <td style="width: 100%; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Open the team to get started.</td></tr>
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Platform Engineering is ready for you.</td></tr>
     </table></td>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
   </tr>
@@ -5358,8 +5360,8 @@ strategy, and execution against goals.
                             Jordan Lee
 
        ┌──────────────────────────────┐
-       │ Open the team to get         │
-[c_S]  │ started.                     │
+       │ Platform Engineering is      │
+[c_S]  │ ready for you.               │
        └──────────────────────────────┘
 
        *-----------------------*
@@ -5853,7 +5855,7 @@ exports[`email render > share.granted · Meeting · viewer · no title 1`] = `
   <tr>
     <td class="csr-chat-avatar-left">[c_S]</td>
     <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
-      <tr><td class="cs-bubble csr-bubble-assistant">Open to view.</td></tr>
+      <tr><td class="cs-bubble csr-bubble-assistant">It is ready for you.</td></tr>
     </table></td>
     <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
   </tr>
@@ -5905,7 +5907,7 @@ body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
   <tr>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap;">[c_S]</td>
     <td style="width: 100%; text-align: left;"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Open to view.</td></tr>
+      <tr><td class="cs-bubble" style="border-radius: 8px 8px 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">It is ready for you.</td></tr>
     </table></td>
     <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
   </tr>
@@ -5937,7 +5939,7 @@ A meeting was shared with you.
 ────────────────────────────────────────────────
 
        ┌──────────────────────────────┐
-[c_S]  │ Open to view.                │
+[c_S]  │ It is ready for you.         │
        └──────────────────────────────┘
 
        *----------------*

package/src/notifications/__tests__/fixtures.ts

@@ -102,6 +102,7 @@ add("org.unit_owner_granted", "Unit owner + message", {
   unitName: "Platform Engineering",
   roleLabel: "Unit owner",
   ctaUrl: `${APP}/org/unit/42`,
+  unitId: "unit_42",
   message: "Welcome aboard — glad to have you owning this team.",
 });
 add("org.unit_owner_granted", "Delegate with expiry", {
@@ -110,6 +111,7 @@ add("org.unit_owner_granted", "Delegate with expiry", {
   unitName: "Platform Engineering",
   roleLabel: "Delegate",
   ctaUrl: `${APP}/org/unit/42`,
+  unitId: "unit_42",
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
@@ -144,6 +146,7 @@ add("security.alert", "Unusual login location", {
 
 const CHAT_BASE = {
   sharedByName: "Alex Rivera",
+  chatId: "chat_7f3a",
   access: "read",
 } as const;
 add("chat.shared", "Default", {
@@ -220,14 +223,16 @@ add("companyMd.access_request_approved", "Editor", {
   docTitle: "Engineering Handbook",
   accessLevel: "editor",
   docUrl: `${APP}/doc/handbook`,
+  docId: "node_42",
 });
-// The approver's note replaces the "Open to view." prompt rather than stacking
+// The approver's note replaces the "The document is ready for you." line rather than stacking
 // on it — the branch this variant exists to pin.
 add("companyMd.access_request_approved", "Editor with message", {
   approverName: "Jordan Lee",
   docTitle: "Engineering Handbook",
   accessLevel: "editor",
   docUrl: `${APP}/doc/handbook`,
+  docId: "node_42",
   message: "Welcome aboard — start with the onboarding section.",
 });
 add("companyMd.access_request_approved", "Viewer", {
@@ -235,6 +240,7 @@ add("companyMd.access_request_approved", "Viewer", {
   docTitle: "Engineering Handbook",
   accessLevel: "viewer",
   docUrl: `${APP}/doc/handbook`,
+  docId: "node_42",
 });
 
 add("companyMd.access_request_denied", "With reason", {

package/src/notifications/__tests__/grounded-ctas.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+
+import type {
+  CallToAction,
+  NotificationContent,
+  NotificationElement,
+} from "../content";
+import { createRenderContext } from "../context";
+import type { NotificationKind } from "../kinds";
+import { NOTIFICATION_DEFINITIONS } from "../registry";
+import { NOTIFICATION_FIXTURES } from "./fixtures";
+
+/**
+ * A notification link that does what a catalog id names carries that
+ * affordance, and no notification prose tells the reader what to do
+ * (control ADR affordance-system; PRD-01137).
+ */
+const CALL_TO_ACTION =
+  /\byou can\b|\btry\b|\bagain\b|\bsettings\b|\breconnect\b|\badd funds\b|\bclick\b|\bgo to\b|\bopen\b/i;
+const CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
+
+function composeFixture(
+  kind: NotificationKind,
+  payload: unknown,
+): NotificationContent {
+  const compose = NOTIFICATION_DEFINITIONS[kind].compose as (
+    p: unknown,
+    c: typeof CONTEXT,
+  ) => NotificationContent;
+  return compose(payload, CONTEXT);
+}
+
+function elements(content: NotificationContent): NotificationElement[] {
+  const out: NotificationElement[] = [];
+  for (const section of content.sections) {
+    for (const element of section.elements) {
+      out.push(element);
+      if (element.type === "chatUnit")
+        out.push(...(element.items as unknown as NotificationElement[]));
+    }
+  }
+  return out;
+}
+
+const ctas = (content: NotificationContent) =>
+  elements(content).filter((e): e is CallToAction => e.type === "callToAction");
+
+const GROUNDED: Partial<
+  Record<NotificationKind, (payload: Record<string, unknown>) => unknown>
+> = {
+  "billing.auto_recharge_failed": () => ({ id: "billing.open" }),
+  "billing.payment_past_due": () => ({ id: "billing.open" }),
+  "billing.suspended": () => ({ id: "billing.open" }),
+  "chat.shared": (p) => ({ id: "chat.open", args: { chatId: p.chatId } }),
+  "companyMd.access_request_approved": (p) => ({
+    id: "companyMd.openDoc",
+    args: { docId: p.docId },
+  }),
+  "org.unit_owner_granted": (p) => ({
+    id: "team.open",
+    args: { unitId: p.unitId },
+  }),
+};
+
+describe("grounded notification calls to action", () => {
+  it("a linked call to action whose link a catalog id names carries that affordance, targeting the payload's own id", () => {
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      const expected = GROUNDED[fixture.kind];
+      if (!expected) continue;
+      const linked = ctas(composeFixture(fixture.kind, fixture.payload)).filter(
+        (c) => c.href !== undefined,
+      );
+      expect(linked, fixture.name).toHaveLength(1);
+      expect(
+        linked[0]?.affordance,
+        `${fixture.kind} · ${fixture.name}`,
+      ).toEqual(expected(fixture.payload as Record<string, unknown>));
+    }
+  });
+
+  it("a code to copy never carries an affordance", () => {
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      for (const cta of ctas(composeFixture(fixture.kind, fixture.payload))) {
+        if (cta.href === undefined)
+          expect(cta.affordance, fixture.name).toBeUndefined();
+      }
+    }
+  });
+
+  it("no grounded or share notification body tells the reader what to do", () => {
+    for (const fixture of NOTIFICATION_FIXTURES) {
+      if (!GROUNDED[fixture.kind] && fixture.kind !== "share.granted") continue;
+      for (const element of elements(
+        composeFixture(fixture.kind, fixture.payload),
+      )) {
+        if (element.type === "body")
+          expect(element.text, fixture.name).not.toMatch(CALL_TO_ACTION);
+        if (element.type === "message")
+          expect(element.text, fixture.name).not.toMatch(CALL_TO_ACTION);
+      }
+    }
+  });
+});

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

@@ -220,7 +220,7 @@ add("companyMd.access_request_approved", "Editor", {
   accessLevel: "editor",
   docUrl: `${APP}/doc/handbook`,
 });
-// The approver's note replaces the "Open to view." prompt rather than stacking
+// The approver's note replaces the "The document is ready for you." line rather than stacking
 // on it — the branch this variant exists to pin, across every channel.
 add("companyMd.access_request_approved", "Editor with message", {
   approverName: "Jordan Lee",

package/src/notifications/content.ts

@@ -23,6 +23,8 @@
  *   security notice", not "render a red box".
  */
 
+import type { OfferedAffordance } from "../affordances/affordance";
+
 // =============================================================================
 // Shared value types
 // =============================================================================
@@ -73,11 +75,18 @@ export interface KeyValueTable {
  * The one action the notification is asking for. `href` absent means the label
  * IS the payload (an OTP code), not a link — the renderer must not fabricate a
  * destination for it.
+ *
+ * `affordance` names the catalog affordance the link performs (control ADR
+ * affordance-system): present exactly when the link does what a catalog id
+ * names, so the label is that affordance's label (`// cta-grounded: <id>` at
+ * the composer). Absent for an OTP code and for a link no catalog id names (an
+ * invite acceptance, a comment). Renderers draw the link as before.
  */
 export interface CallToAction {
   type: "callToAction";
   label: string;
   href?: string;
+  affordance?: OfferedAffordance;
 }
 
 /** A sequence of items. `ordered` when the sequence itself carries meaning. */

package/src/notifications/kinds/billing-auto-recharge-failed.ts

@@ -52,13 +52,15 @@ export const billingAutoRechargeFailedDefinition: NotificationDefinition<"billin
                 text:
                   "AI work carries on until the remaining balance is spent, " +
                   "and then pauses. The next attempt is not immediate — the " +
-                  "system waits rather than running the same card again — so " +
-                  "updating the payment method is what resolves this.",
+                  "system waits before charging the same card a second time — " +
+                  "so updating the payment method is what resolves this.",
               },
               {
                 type: "callToAction",
+                // cta-grounded: billing.open
                 label: "OPEN BILLING",
                 href: billingUrl,
+                affordance: { id: "billing.open" },
               },
               {
                 type: "notice",

package/src/notifications/kinds/billing-payment-past-due.ts

@@ -59,8 +59,10 @@ export const billingPaymentPastDueDefinition: NotificationDefinition<"billing.pa
               },
               {
                 type: "callToAction",
+                // cta-grounded: billing.open
                 label: "OPEN BILLING",
                 href: billingUrl,
+                affordance: { id: "billing.open" },
               },
               {
                 type: "notice",