@company-semantics/contracts 39.8.0 → 41.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "39.8.0",
+  "version": "41.0.0",
   "private": false,
   "repository": {
     "type": "git",

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 = 'e8cf36a33d43' as const;
-export const SPEC_HASH_FULL = 'e8cf36a33d43bec5e4383c8edbfbdccd37fe8d081a5ddd02e96c83cb5e7bd21a' as const;
+export const SPEC_HASH = 'c0f32d11bf0f' as const;
+export const SPEC_HASH_FULL = 'c0f32d11bf0fdc59ee0a7bf84bee984f2f8109838d2659b6e66709e0198dcd4e' as const;

package/src/api/generated.ts

@@ -1423,23 +1423,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{id}/content": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        /** Update a company.md document content */
-        put: operations["updateCompanyMdDocContent"];
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/api/company-md/docs/{id}/title": {
         parameters: {
             query?: never;
@@ -4620,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} */
@@ -4660,9 +4648,6 @@ export interface components {
             createdAt: string;
             updatedAt: string;
         };
-        UpdateCompanyMdContentRequest: {
-            content: string;
-        };
         UpdateCompanyMdTitleRequest: {
             title: string;
         };
@@ -4746,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: {
@@ -8224,30 +8212,6 @@ export interface operations {
             };
         };
     };
-    updateCompanyMdDocContent: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path: {
-                id: string;
-            };
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": components["schemas"]["UpdateCompanyMdContentRequest"];
-            };
-        };
-        responses: {
-            /** @description Content updated */
-            204: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-        };
-    };
     updateCompanyMdDocTitle: {
         parameters: {
             query?: never;

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/generated/openapi-routes.ts

@@ -34,7 +34,6 @@ export const openApiRoutes = {
   '/api/company-md/docs/{id}/collab/stream': ['GET'],
   '/api/company-md/docs/{id}/collab/sync': ['GET'],
   '/api/company-md/docs/{id}/collab/updates': ['POST'],
-  '/api/company-md/docs/{id}/content': ['PUT'],
   '/api/company-md/docs/{id}/context-bank': ['GET'],
   '/api/company-md/docs/{id}/context-bank/associate': ['POST'],
   '/api/company-md/docs/{id}/context-bank/retry': ['POST'],

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/kinds/company-md-access-requested.ts

@@ -28,8 +28,13 @@ export const accessRequestedDefinition: NotificationDefinition<"companyMd.access
   {
     kind: "companyMd.access_requested",
     compose: (payload, context) => {
-      const { requesterName, docTitle, message, requestedAccessLevel, reviewUrl } =
-        payload;
+      const {
+        requesterName,
+        docTitle,
+        message,
+        requestedAccessLevel,
+        reviewUrl,
+      } = payload;
 
       return {
         metadata: {

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

@@ -24,10 +24,38 @@ export const ACCESS_REQUEST_STATUSES = [
 export const AccessRequestStatusSchema = z.enum(ACCESS_REQUEST_STATUSES);
 export type AccessRequestStatus = z.infer<typeof AccessRequestStatusSchema>;
 
+/**
+ * Character cap on an access-request message.
+ *
+ * A note to an owner, not a document: 280 is enough to say why you want access
+ * and short enough to read in an inbox row. Exported so the request dialog's
+ * `maxLength` and its remaining-character counter read the SAME number the API
+ * rejects on — a UI that let you type past the server's limit would fail the
+ * send with no explanation.
+ *
+ * Enforced in three places, deliberately: the input caps typing, this schema
+ * rejects the request, and a CHECK constraint on
+ * `company_md_doc_access_requests.message` bounds anything that reaches the
+ * table by another path.
+ */
+export const ACCESS_REQUEST_MESSAGE_MAX_LENGTH = 280;
+
+/**
+ * Plain text only. Rejects C0/C1 control characters — a pasted binary blob or a
+ * terminal dump — while allowing the newlines and tabs a human types. The field
+ * is rendered as text, never as markup, so this is about what may be STORED,
+ * not about escaping at render time.
+ */
+const PLAIN_TEXT = /^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]*$/;
+
 /** POST body to create an access request. */
 export const AccessRequestCreateSchema = z.object({
   /** Optional context the requester sends to the owner(s). */
-  message: z.string().max(2000).optional(),
+  message: z
+    .string()
+    .max(ACCESS_REQUEST_MESSAGE_MAX_LENGTH)
+    .regex(PLAIN_TEXT, "Message must be plain text")
+    .optional(),
   /**
    * The band the requester is asking for (ADR-CONTRACTS-098 / ADR-BE-454):
    * `viewer` from the locked preview, `editor` from the view-only Editor tab
@@ -65,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>;