@company-semantics/contracts 40.0.0 → 42.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "40.0.0",
+  "version": "42.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -129,17 +129,17 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.20.1",
+    "@types/node": "^26.1.2",
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
     "husky": "^9.1.7",
-    "lint-staged": "^17.1.0",
-    "markdownlint-cli2": "^0.23.1",
+    "lint-staged": "^17.2.0",
+    "markdownlint-cli2": "^0.23.2",
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.6",
     "tsx": "^4.23.1",
     "typescript": "^5.8.3",
-    "vite": "^7.3.6",
+    "vite": "^8.2.0",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"
   },

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '402a9b3f7788' as const;
-export const SPEC_HASH_FULL = '402a9b3f77881eef9d41ee5ad49aa2b184a5b838ce948cc43ea4226e434f9b81' as const;
+export const SPEC_HASH = 'c0f32d11bf0f' as const;
+export const SPEC_HASH_FULL = 'c0f32d11bf0fdc59ee0a7bf84bee984f2f8109838d2659b6e66709e0198dcd4e' as const;

package/src/api/generated.ts

@@ -4603,6 +4603,11 @@ export interface components {
             /** @enum {string} */
             accessState?: "full" | "redacted_admin" | "locked_requestable";
             canRequestAccess?: boolean;
+            pendingAccessRequest?: {
+                id: string;
+                requestedAccessLevel: ("editor" | "commenter" | "viewer") | null;
+                createdAt: string;
+            } | null;
             /** @enum {string} */
             visibility: "private" | "unit" | "org";
             /** @enum {string} */
@@ -4726,9 +4731,12 @@ export interface components {
         ApproveAccessRequest: {
             /** @enum {string} */
             accessLevel: "editor" | "commenter" | "viewer";
+            notify?: boolean;
+            message?: string;
         };
         DenyAccessRequest: {
             reason?: string;
+            notify?: boolean;
         };
         /** @description Org-wide context-doc discovery hits the caller may view. */
         SearchContextDocsResponse: {

package/src/chat/README.md

@@ -42,7 +42,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatRuntimeProfile` _(type)_ — Chat runtime profile — user-selectable orchestration strategy.
 - `ChatRuntimeProfileInfo` _(type)_ — Runtime profile metadata for UI rendering.
 - `ChatShareInfo` _(type)_ — Chat share record with snapshot metadata.
-- `ChatShareInfoSchema`
+- `ChatShareInfoSchema` — A chat share, as returned by the share APIs.
 - `ChatSseEvent` _(type)_ — SSE event types for chat updates.
 - `ChatSseEventSchema`
 - `ChatSuccessResponse` _(type)_ — Generic mutation success confirmation.

package/src/chat/schemas.ts

@@ -58,12 +58,28 @@ export const SharedChatMessageSchema = z.object({
   parts: z.array(z.unknown()).optional(),
 });
 
+/**
+ * A chat share, as returned by the share APIs.
+ *
+ * SHOW-ONCE (ADR-BE-460). `token` and `shareUrl` are present ONLY on the
+ * response that creates the share. Share tokens are stored as a digest, so the
+ * server cannot redisplay one afterwards — listing or updating a share returns
+ * the record without them, and re-obtaining a link means revoke-and-reshare.
+ *
+ * This is the industry norm for capability links, and it is what removes the
+ * last reason to keep a recoverable copy of the token: a share list that can
+ * still show you the URL is a share list that can leak every live link at once.
+ * Consumers must treat both fields as optional and drive their copy-link
+ * affordance off creation, not off a fetched share.
+ */
 export const ChatShareInfoSchema = z.object({
   id: z.string(),
   chatId: z.string(),
-  token: z.string(),
+  /** Create-time only — never returned by list or update (show-once). */
+  token: z.string().optional(),
   visibility: ChatVisibilitySchema,
-  shareUrl: z.string(),
+  /** Create-time only — never returned by list or update (show-once). */
+  shareUrl: z.string().optional(),
   messageCountAtShare: z.number().int(),
   titleAtShare: z.string(),
   createdAt: IsoDateString,

package/src/content/schemas.ts

@@ -12,6 +12,7 @@
 import { z } from "zod";
 import { CursorPageSchema } from "../api/primitives";
 import { EffectiveAccessResponseSchema } from "../permissions/share-api";
+import { ViewerPendingAccessRequestSchema } from "../permissions/access-request";
 
 // ---------------------------------------------------------------------------
 // Company.md Sub-schemas
@@ -112,6 +113,15 @@ export const CompanyMdDocResponseSchema = z.object({
     .optional(),
   /** Whether the requesting actor may request access (ADR-BE-348 / ADR-BE-338). */
   canRequestAccess: z.boolean().optional(),
+  /**
+   * The requesting actor's own OPEN request on this node, if any
+   * (ADR-CONTRACTS-106). `canRequestAccess` answers "may you ask?" and is
+   * derived from discoverability + read-state alone, so it stays true after you
+   * have asked — this field is what distinguishes "you may ask" from "you
+   * already did", and it is the only thing standing between the locked view and
+   * an actor re-submitting a request they already filed.
+   */
+  pendingAccessRequest: ViewerPendingAccessRequestSchema.nullable().optional(),
   visibility: z.enum(["private", "unit", "org"]),
   // Governance + discovery projections (ADR-BE-348 / ADR-CTRL-194). Present on
   // the TS contract since the projection split; now promoted into the published

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

@@ -11,6 +11,7 @@ exports[`NOTIFICATION_DEFINITIONS > titles every kind 1`] = `
   "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 · Editor with message": "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",

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

@@ -1603,6 +1603,185 @@ This notification was sent via Company Semantics.
 Access is now active.
 
 
+/* EOM */
+ⓒ 2026 • Company Semantics
+https://companysemantics.ai
+",
+}
+`;
+
+exports[`email render > companyMd.access_request_approved · Editor with message 1`] = `
+{
+  "amp": "<!DOCTYPE html>
+<html amp4email data-css-strict lang="en">
+<head><meta charset="utf-8">
+<script async src="https://cdn.ampproject.org/v0.js"></script>
+<style amp4email-boilerplate>body{visibility:hidden}</style>
+<style amp-custom>.csr-body { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; color: #1a1a1a; background-color: #ffffff; margin: 0; padding: 0; }
+.csr-frame { max-width: 520px; margin: 0 auto; }
+.csr-p-normal { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0; }
+.csr-p-tight { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0; }
+.csr-p-none { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0; }
+.csr-eom { color: #bbb; }
+.csr-signature-link { color: #0047FF; text-decoration: none; }
+.csr-warning { color: #e7000b; }
+.csr-hr-normal { border: none; border-top: 1px solid #bbb; margin: 0 0 20px 0; }
+.csr-hr-tight { border: none; border-top: 1px solid #bbb; margin: 0 0 4px 0; }
+.csr-hr-none { border: none; border-top: 1px solid #bbb; margin: 0; }
+.csr-hero-normal { max-width: 100%; margin: 0 0 20px 0; }
+.csr-hero-tight { max-width: 100%; margin: 0 0 4px 0; }
+.csr-hero-none { max-width: 100%; margin: 0; }
+.csr-cta-box-normal { display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0 0 20px 0; max-width: 220px; }
+.csr-cta-box-tight { display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0 0 4px 0; max-width: 220px; }
+.csr-cta-box-none { display: inline-block; border: 1px solid #0047FF; border-radius: 2px; margin: 0; max-width: 220px; }
+.csr-cta-cell-linked { text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; }
+.csr-cta-cell-code { padding: 16px 24px; text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; }
+.csr-cta-label { text-decoration: underline; }
+.csr-cta-anchor { display: block; padding: 16px 24px; color: #0047FF; text-decoration: none; }
+.csr-cta-code { color: #0047FF; }
+.csr-chat-rule-top { border: none; border-top: 1px solid #bbb; margin: 12px 0 24px 0; }
+.csr-chat-rule-bottom { border: none; border-top: 1px solid #bbb; margin: 24px 0 12px 0; }
+.csr-chat-row-24 { margin: 0 0 24px 0; }
+.csr-chat-row-16 { margin: 0 0 16px 0; }
+.csr-chat-attribution { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch; }
+.csr-chat-avatar-left { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; white-space: nowrap; }
+.csr-chat-avatar-left-hidden { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap; }
+.csr-chat-avatar-right { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-left: 8px; vertical-align: bottom; white-space: nowrap; }
+.csr-chat-avatar-right-hidden { 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; }
+.csr-chat-channel-left { width: 100%; text-align: left; }
+.csr-chat-channel-right { width: 100%; text-align: right; }
+.csr-chat-bubble-wrap { display: inline-block; max-width: 100%; vertical-align: bottom; }
+.csr-bubble-user { border-radius: 8px 8px 0 8px; padding: 10px 14px; text-align: right; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666; }
+.csr-bubble-assistant { 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; }
+.csr-dots-over-cta { font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 20px; font-weight: bold; color: #666; text-align: center; margin: 0 0 16px 0; }
+.csr-dots-cell { width: 100%; text-align: center; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 20px; font-weight: bold; color: #666; }
+.csr-cta-stack { display: inline-block; text-align: left; }
+.cs-cta-hover:hover { background-color: #d1ffff; }</style></head>
+<body class="csr-body">
+<div class="csr-frame">
+<p class="csr-p-normal">Hi there,</p>
+<p class="csr-p-normal">Your access request was approved.</p>
+<hr class="cs-faint csr-chat-rule-top">
+<table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-16">
+  <tr>
+    <td class="csr-chat-avatar-left-hidden">[c_S]</td>
+    <td class="csr-chat-channel-right"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
+      <tr><td class="cs-bubble csr-bubble-user">Welcome aboard — start with the onboarding section.</td></tr>
+    </table></td>
+    <td class="csr-chat-avatar-right">(•̀_ರ╮)</td>
+  </tr>
+  <tr>
+    <td></td>
+    <td class="cs-meta csr-chat-attribution">Jordan Lee</td>
+    <td></td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-24">
+  <tr>
+    <td class="csr-chat-avatar-left-hidden">[c_S]</td>
+    <td class="csr-chat-channel-right"><div class="csr-cta-stack"><table cellpadding="0" cellspacing="0" border="0" class="cs-cta cs-cta-hover csr-cta-box-none">
+  <tr><td class="csr-cta-cell-linked">
+    <a href="https://app.companysemantics.ai/doc/handbook" class="cs-link csr-cta-anchor">&gt;&gt; <span class="csr-cta-label">OPEN</span> &lt;&lt;</a>
+  </td></tr>
+</table></div></td>
+    <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</td>
+  </tr>
+</table>
+<hr class="cs-faint csr-chat-rule-bottom">
+<p class="csr-p-tight">Document: &quot;Engineering Handbook&quot;</p>
+<p class="csr-p-tight">Access: can edit</p>
+<p class="csr-p-normal">Approved by: Jordan Lee</p>
+<p class="csr-p-none">This notification was sent via Company Semantics.<br>Access is now active.</p>
+<p class="csr-p-none"><br><br><span class="cs-faint csr-eom">/* EOM */</span><br>ⓒ 2026 • Company Semantics<br><a href="https://companysemantics.ai" target="_blank" rel="noopener noreferrer" class="cs-link csr-signature-link">https://companysemantics.ai</a></p>
+</div>
+</body>
+</html>",
+  "html": "<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8">
+<meta name="color-scheme" content="light dark">
+<meta name="supported-color-schemes" content="light dark">
+<style>.cs-cta-hover:hover { background-color: #d1ffff !important; }
+@media (prefers-color-scheme: dark) {
+body { background-color: #1a1a1a !important; color: #e8e8e8 !important; }
+.cs-faint { color: #666 !important; border-top-color: #666 !important; }
+.cs-meta { color: #8a8a8a !important; }
+.cs-cta { border-color: #00ffff !important; }
+.cs-cta-hover:hover { background-color: #154848 !important; }
+.cs-bubble { background: #154848 !important; color: #ffffff !important; }
+.cs-dots { color: #8a8a8a !important; }
+.cs-link { color: #00ffff !important; }
+.cs-destructive { color: #ff6b6b !important; }
+}</style>
+<!--[if mso]><style>.cs-cta td { padding: 16px 24px !important; }
+.cs-cta a { padding: 0 !important; }</style><![endif]--></head>
+<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; margin: 0 auto;">
+<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;">Your access request was approved.</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 16px 0;">
+  <tr>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: right;"><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 0 8px; padding: 10px 14px; text-align: right; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Welcome aboard — start with the onboarding section.</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; white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>
+  <tr>
+    <td></td>
+    <td class="cs-meta" style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">Jordan Lee</td>
+    <td></td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
+  <tr>
+    <td style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: right;"><div style="display: inline-block; text-align: left;"><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; 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/doc/handbook" class="cs-link" style="display: block; padding: 16px 24px; color: #0047FF; text-decoration: none;">&gt;&gt; <span style="text-decoration: underline;">OPEN</span> &lt;&lt;</a>
+  </td></tr>
+</table></div></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>
+</table>
+<hr class="cs-faint" style="border: none; border-top: 1px solid #bbb; margin: 24px 0 12px 0;">
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Document: &quot;Engineering Handbook&quot;</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Access: can edit</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Approved by: Jordan Lee</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0;">This notification was sent via Company Semantics.<br>Access is now active.</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0;"><br><br><span class="cs-faint" style="color: #bbb;">/* EOM */</span><br>ⓒ 2026 • Company Semantics<br><a href="https://companysemantics.ai" target="_blank" rel="noopener noreferrer" class="cs-link" style="color: #0047FF; text-decoration: none;">https://companysemantics.ai</a></p>
+</div>
+</body>
+</html>",
+  "subject": "Your access request was approved",
+  "text": "Hi there,
+
+Your access request was approved.
+
+________________________________________________________
+
+       ┌──────────────────────────────────────┐
+       │      Welcome aboard — start with the │
+       │                  onboarding section. │  (•̀_ರ╮)
+       └──────────────────────────────────────┘
+                                    Jordan Lee
+
+                             *----------------*
+                             |   >> OPEN <<   |
+                             *----------------*
+
+   https://app.companysemantics.ai/doc/handbook
+________________________________________________________
+
+Document: "Engineering Handbook"
+Access: can edit
+Approved by: Jordan Lee
+
+This notification was sent via Company Semantics.
+Access is now active.
+
+
 /* EOM */
 ⓒ 2026 • Company Semantics
 https://companysemantics.ai

package/src/notifications/__tests__/fixtures.ts

@@ -212,6 +212,15 @@ 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
+// 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`,
+  message: "Welcome aboard — start with the onboarding section.",
+});
 add("companyMd.access_request_approved", "Viewer", {
   approverName: "Jordan Lee",
   docTitle: "Engineering Handbook",

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

@@ -212,6 +212,15 @@ 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
+// on it — the branch this variant exists to pin, across every channel.
+add("companyMd.access_request_approved", "Editor with message", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "editor",
+  docUrl: `${APP}/doc/handbook`,
+  message: "Welcome aboard — start with the onboarding section.",
+});
 add("companyMd.access_request_approved", "Viewer", {
   approverName: "Jordan Lee",
   docTitle: "Engineering Handbook",

package/src/notifications/kinds/company-md-access-approved.ts

@@ -1,5 +1,12 @@
 /**
  * Company.md access-approved notification (sent to the requester).
+ *
+ * The chat unit carries EITHER the approver's own words or the bare "Open to
+ * view." prompt — never both. An approver who wrote a note has already said what
+ * the prompt would say, and stacking the two reads as a form letter with a
+ * comment bolted on. Same shape as `share.granted` (ADR-CONTRACTS-106); the call
+ * to action stays in place either way, since approval always resolves to a doc
+ * the requester can now open.
  */
 
 import type { NotificationDefinition } from "../definition";
@@ -10,7 +17,7 @@ export const accessApprovedDefinition: NotificationDefinition<"companyMd.access_
   {
     kind: "companyMd.access_request_approved",
     compose: (payload, context) => {
-      const { approverName, docTitle, accessLevel, docUrl } = payload;
+      const { approverName, docTitle, accessLevel, docUrl, message } = payload;
 
       return {
         metadata: {
@@ -25,11 +32,18 @@ export const accessApprovedDefinition: NotificationDefinition<"companyMd.access_
               {
                 type: "chatUnit",
                 items: [
-                  {
-                    type: "message",
-                    role: "assistant",
-                    text: "Open to view.",
-                  },
+                  message
+                    ? {
+                        type: "message",
+                        role: "user",
+                        text: message,
+                        from: approverName,
+                      }
+                    : {
+                        type: "message",
+                        role: "assistant",
+                        text: "Open to view.",
+                      },
                   { type: "callToAction", label: "OPEN", href: docUrl },
                 ],
               },

package/src/notifications/payloads.ts

@@ -151,6 +151,12 @@ export interface NotificationPayloads {
     accessLevel: "editor" | "commenter" | "viewer";
     /** Full URL to view the node */
     docUrl: string;
+    /**
+     * Optional note from the approver, included in the notification only (not
+     * persisted) — the approval counterpart of the deny kind's `reason`
+     * (ADR-CONTRACTS-106).
+     */
+    message?: string;
   };
   /** Sent to the requester when an owner denies (ADR-BE-338). */
   "companyMd.access_request_denied": {

package/src/org/company-md.ts

@@ -6,6 +6,8 @@
  * @see PRD-00173 for design rationale
  */
 
+import type { ViewerPendingAccessRequest } from "../permissions/access-request";
+
 /**
  * Visibility band for a Company.md document — the canonical AUTH
  * `entity_visibility` vocabulary (ADR-CONT-049, backend ADR-BE-178).
@@ -218,6 +220,13 @@ export interface CompanyMdDocCore extends CompanyMdNodeIdentity {
    * recipient to an `owners` node may still be allowed to request).
    */
   readonly canRequestAccess?: boolean;
+  /**
+   * The requesting actor's own OPEN request on this node (ADR-CONTRACTS-106).
+   * `canRequestAccess` is derived from discoverability + read-state and stays
+   * true once you have asked, so this is the field that separates "you may ask"
+   * from "you already did". Absent/`null` ⇒ nothing open.
+   */
+  readonly pendingAccessRequest?: ViewerPendingAccessRequest | null;
   /**
    * Whether this doc is served by the real-time collaboration protocol
    * (ADR-CONT-102). When `true` the client may open `/collab/sync` + the collab

package/src/permissions/access-request.ts

@@ -93,18 +93,89 @@ export const AccessRequestSchema = z.object({
 });
 export type AccessRequest = z.infer<typeof AccessRequestSchema>;
 
+/**
+ * The requesting actor's OWN open request on a node, surfaced on the single-doc
+ * read so a locked view can state that they already asked instead of offering
+ * the ask a second time (ADR-CONTRACTS-106).
+ *
+ * A deliberately NARROWER projection than the owner inbox's
+ * {@link AccessRequestSchema}: a requester is not authorized to learn who else
+ * asked or how anything was resolved, and needs only what they asked for and
+ * when. Absent/`null` ⇒ no open request, which is what an actor who never asked,
+ * and an actor whose request was already resolved, both see.
+ *
+ * Single-doc read ONLY — deliberately not on the tree node schema, where a
+ * per-node pending lookup would be an N+1 across the whole tree.
+ */
+export const ViewerPendingAccessRequestSchema = z.object({
+  id: z.string(),
+  /**
+   * The band they asked for. Null for requests filed before the field existed
+   * or by a client that named none.
+   */
+  requestedAccessLevel: GrantableAccessLevelSchema.nullable(),
+  createdAt: z.string(),
+});
+export type ViewerPendingAccessRequest = z.infer<
+  typeof ViewerPendingAccessRequestSchema
+>;
+
+/**
+ * Character cap on the approver's note to the requester.
+ *
+ * Deliberately the 2000 the deny `reason` already used, not the requester's 280:
+ * the requester writes a one-line ask into an owner's inbox row, the approver
+ * writes a reply that is read on its own in an email body.
+ */
+export const ACCESS_DECISION_MESSAGE_MAX_LENGTH = 2000;
+
+/**
+ * Whether the requester is told about the decision.
+ *
+ * ABSENT MEANS SEND (ADR-CONTRACTS-106). Approve/deny have always emailed the
+ * requester unconditionally, so a client that omits the field — an older app, a
+ * script — must keep getting that behavior. Only an explicit `false` suppresses
+ * the notification; a default of `false` here would silence every existing
+ * caller.
+ */
+const NotifySchema = z.boolean().optional();
+
 /**
  * POST body to approve a request. The owner chooses the granted level (default
  * `viewer` is applied server-side if the field is omitted by older clients).
  */
 export const ApproveAccessRequestSchema = z.object({
   accessLevel: GrantableAccessLevelSchema,
+  /** Whether to email the requester. Absent ⇒ send (see {@link NotifySchema}). */
+  notify: NotifySchema,
+  /**
+   * Optional note from the approver, quoted to the requester in the approval
+   * notification only — never persisted on the request or the minted grant.
+   * Ignored when `notify` is false: there is no other surface that would show
+   * it. Mirrors `share.granted`'s granter message.
+   */
+  message: z
+    .string()
+    .max(ACCESS_DECISION_MESSAGE_MAX_LENGTH)
+    .regex(PLAIN_TEXT, "Message must be plain text")
+    .optional(),
 });
 export type ApproveAccessRequest = z.infer<typeof ApproveAccessRequestSchema>;
 
 /** POST body to deny a request. */
 export const DenyAccessRequestSchema = z.object({
-  /** Optional reason, surfaced to the requester (email only). */
-  reason: z.string().max(2000).optional(),
+  /**
+   * Optional reason, surfaced to the requester (email only). This is the deny
+   * verb's message carrier — the approver's composer writes here rather than to
+   * a second `message` field, because the denied notification already quotes
+   * `reason` and a doc's denial has no other content.
+   */
+  reason: z
+    .string()
+    .max(ACCESS_DECISION_MESSAGE_MAX_LENGTH)
+    .regex(PLAIN_TEXT, "Reason must be plain text")
+    .optional(),
+  /** Whether to email the requester. Absent ⇒ send (see {@link NotifySchema}). */
+  notify: NotifySchema,
 });
 export type DenyAccessRequest = z.infer<typeof DenyAccessRequestSchema>;

package/src/security/token-policy.ts

@@ -64,8 +64,12 @@ export const AUTH_TOKEN_POLICY_REQUIREMENTS = {
     conformance: {
       status: "unmet",
       gap:
-        "Minted with randomUUID() (122 bits) and persisted verbatim: sessions.token " +
-        "holds the cookie value itself, and lookup is raw equality against it.",
+        "Issuance now conforms: minted by issueCapabilityToken at 256 bits and " +
+        "stored as a sha256:v1: digest (ADR-BE-460 deploy B). Still UNMET because " +
+        "the dual-read window is open — sessions.token retains the raw value so a " +
+        "rollback keeps working, and every lookup carries a plaintext fallback arm. " +
+        "Conformance is reached when migration C retires the column and deploy D " +
+        "removes the fallbacks.",
     },
   },
   ChatShareToken: {