@company-semantics/contracts 28.1.0 → 30.0.0

package/src/email/render/auth-otp.ts

@@ -33,13 +33,7 @@ export function renderAuthOtp(
 
   const blocks: Block[] = [
     paragraph("Copy/paste code in login form:"),
-    ctaBox({
-      label: otp,
-      padding: "20px 24px",
-      fontSize: "20px",
-      borderRadiusZero: true,
-      letterSpacing: "4px",
-    }),
+    ctaBox({ label: otp, variant: "code" }),
     keyValue("Status", "VALID"),
     keyValue(
       "Expires in",

package/src/email/render/blocks.ts

@@ -13,11 +13,15 @@
  *   for inline emphasis). No template hand-writes markup or raw strings.
  */
 
-import { COMPANY_NAME, MONO_FONT_STACK, SUPPORT_EMAIL } from "./constants";
+import { COMPANY_NAME, MONO_FONT_STACK } from "./constants";
 import { escapeHtml } from "./escape-html";
 
 const MONO = `font-family: ${MONO_FONT_STACK};`;
 
+/** The single font size for every email element (HTML). Plain text is monospace
+ * so it carries no size — this keeps one visual size across both surfaces. */
+const FONT_SIZE = "13px";
+
 // =============================================================================
 // Core types
 // =============================================================================
@@ -100,7 +104,7 @@ export function textShell(blocks: Block[]): string {
 // =============================================================================
 
 /**
- * Email paragraph — mono (matching the body shell), 14px, configurable spacing.
+ * Email paragraph — mono (matching the body shell), 13px, configurable spacing.
  * The single paragraph primitive: greeting / keyValue / footer / signature all
  * build on it, and templates use it directly for body lines.
  */
@@ -110,7 +114,7 @@ export function paragraph(
 ): Block {
   const { html, text } = renderInline(content);
   return {
-    html: `<p style="${MONO} font-size: 14px; margin: ${SPACING[spacing]};">${html}</p>`,
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
     text,
     spacing,
   };
@@ -141,20 +145,19 @@ export function footer(
     : escapeHtml(firstLine);
   const text = secondLine ? `${firstLine}\n${secondLine}` : firstLine;
   return {
-    html: `<p style="${MONO} font-size: 14px; margin: ${SPACING[spacing]};">${html}</p>`,
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
     text,
     spacing,
   };
 }
 
 /**
- * Trailing sign-off. Owns the full company sign-off in both surfaces: the
- * company (or custom `signer`) name and a "Questions? Contact <support>" line.
+ * Trailing sign-off — the company (or custom `signer`) name.
  */
 export function signature(signer: string = COMPANY_NAME): Block {
   return {
-    html: `<p style="${MONO} font-size: 14px; margin: ${SPACING.none};">${escapeHtml(signer)}<br><span style="color: #888;">Questions? Contact <a href="mailto:${SUPPORT_EMAIL}" style="color: #888;">${SUPPORT_EMAIL}</a></span></p>`,
-    text: `---\n${signer}\nQuestions? Contact ${SUPPORT_EMAIL}`,
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};">${escapeHtml(signer)}</p>`,
+    text: `---\n${signer}`,
     spacing: "none",
   };
 }
@@ -173,7 +176,7 @@ export const ACCESS_PHRASE: Record<"editor" | "commenter" | "viewer", string> =
 /** Centered continuation dots separator (chat-shared). */
 export function chatDots(): Block {
   return {
-    html: `<p style="${MONO} font-size: 20px; margin: 0 0 16px 0; max-width: 320px; text-align: center;">⋮</p>`,
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: 0 0 16px 0; max-width: 320px; text-align: center;">⋮</p>`,
     text: "                  ⋮",
     spacing: "normal",
   };
@@ -190,17 +193,36 @@ export interface CtaBoxOptions {
   /** When present, the label links to this URL (and the URL rides under the
    * plain-text box). */
   href?: string;
-  /** Inner-cell padding, e.g. `"16px 24px"`. */
+  /** Visual kind. `"action"` = link CTA (default); `"code"` = copy/paste code
+   * box (square corners, letter-spaced). */
+  variant?: "action" | "code";
+}
+
+/** Component-owned styling per CTA variant. Templates supply only `label`/`href`/
+ * `variant` — the only allowable UI is the component, so all CSS lives here,
+ * never at the call site. */
+interface CtaVariantStyle {
   padding: string;
-  /** Label font-size, e.g. `"16px"`. */
   fontSize: string;
-  /** Optional table `max-width`, e.g. `"220px"`. */
   maxWidth?: string;
-  /** Emit `border-radius: 0;` (OTP code box). */
-  borderRadiusZero?: boolean;
-  /** Optional `letter-spacing`, e.g. `"4px"` (OTP code box). */
+  square: boolean;
   letterSpacing?: string;
 }
+const CTA_VARIANTS: Record<"action" | "code", CtaVariantStyle> = {
+  action: {
+    padding: "16px 24px",
+    fontSize: FONT_SIZE,
+    maxWidth: "220px",
+    square: false,
+  },
+  code: {
+    padding: "16px 24px",
+    fontSize: FONT_SIZE,
+    maxWidth: "220px",
+    square: true,
+    letterSpacing: "4px",
+  },
+};
 
 /** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
 const CTA_BOX_PAD = 3;
@@ -216,19 +238,13 @@ function asciiCtaBox(label: string): string {
 /** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). When
  * `href` is given, HTML links the label and plain text prints the URL below. */
 export function ctaBox(opts: CtaBoxOptions): Block {
-  const {
-    label,
-    href,
-    padding,
-    fontSize,
-    maxWidth,
-    borderRadiusZero,
-    letterSpacing,
-  } = opts;
+  const { label, href, variant = "action" } = opts;
+  const { padding, fontSize, maxWidth, square, letterSpacing } =
+    CTA_VARIANTS[variant];
 
   const tableStyle =
     `border: 2px solid #1a1a1a;` +
-    (borderRadiusZero ? ` border-radius: 0;` : ``) +
+    (square ? ` border-radius: 0;` : ``) +
     ` margin: 0 0 20px 0;` +
     (maxWidth ? ` max-width: ${maxWidth};` : ``);
 
@@ -307,10 +323,10 @@ function clampMessage(text: string): string {
 }
 
 /**
- * Right-aligned user chat message. Truncated by clampMessage. The avatar rides
- * the bottom (bottom-aligned like a real chat). When `from` is given it renders
- * as an attribution below, right-aligned to the message's right edge (clear of
- * the face). Doubles as the "message from …" quote.
+ * Right-aligned user chat message. Truncated by clampMessage. In plain text the
+ * face sits beside the last message line. When `from` is given (the sender's
+ * name) it renders as an attribution below, right-aligned to the message's right
+ * edge.
  */
 export function chatUser(content: string, from?: string): Block {
   const clamped = clampMessage(content);
@@ -318,42 +334,47 @@ export function chatUser(content: string, from?: string): Block {
   const attributionRow = from
     ? `
   <tr>
-    <td style="${MONO} font-size: 11px; color: #888; text-align: right; padding-top: 4px;">${escapeHtml(from)}</td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; color: #888; text-align: right; padding-top: 4px;">${escapeHtml(from)}</td>
     <td></td>
   </tr>`
     : "";
   const html = `<table cellpadding="0" cellspacing="0" border="0" style="margin: 0 0 16px 0;">
   <tr>
-    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 0 12px; padding: 10px 14px; min-width: 280px; text-align: right; ${MONO} font-size: 13px; background: #f5f5f5;">${escapeHtml(clamped)}</td>
-    <td style="${MONO} font-size: 14px; padding-left: 8px; vertical-align: bottom;">(•̀_ರ╮)</td>
+    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 0 12px; padding: 10px 14px; min-width: 280px; text-align: right; ${MONO} font-size: ${FONT_SIZE}; background: #f5f5f5;">${escapeHtml(clamped)}</td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom;">(•̀_ರ╮)</td>
   </tr>${attributionRow}
 </table>`;
 
   const border = "─".repeat(MESSAGE_WIDTH + 1);
   const lines = wrapText(clamped, MESSAGE_WIDTH);
   const body = lines.map((line) => `│${line.padStart(MESSAGE_WIDTH)} │`);
-  const box = [`┌${border}┐`, ...body, `└${border}┘  (•̀_ರ╮)`];
+  // Face beside the last message line (one row up from the bottom border).
+  body[body.length - 1] += "  (•̀_ರ╮)";
+  const box = [`┌${border}┐`, ...body, `└${border}┘`];
   if (from) box.push(from.padStart(MESSAGE_WIDTH + 3));
 
   return { html, text: box.join("\n"), spacing: "normal" };
 }
 
-/** Left-aligned assistant chat message with `[c_S]` avatar (bottom-aligned). */
+/** Left-aligned assistant chat message with `[c_S]` avatar; in plain text the
+ * avatar sits beside the last message line (one row up from the bottom border). */
 export function chatAssistant(content: string): Block {
   const clamped = clampMessage(content);
 
   const html = `<table cellpadding="0" cellspacing="0" border="0" style="margin: 16px 0;">
   <tr>
-    <td style="${MONO} font-size: 14px; padding-right: 8px; vertical-align: bottom;">[c_S]</td>
-    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 12px 0; padding: 10px 14px; min-width: 280px; ${MONO} font-size: 13px; background: #f5f5f5;">${escapeHtml(clamped)}</td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom;">[c_S]</td>
+    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 12px 0; padding: 10px 14px; min-width: 280px; ${MONO} font-size: ${FONT_SIZE}; background: #f5f5f5;">${escapeHtml(clamped)}</td>
   </tr>
 </table>`;
 
   const lineWidth = 36;
   const lines = wrapText(clamped, lineWidth);
   const top = "       ┌──────────────────────────────────────┐";
-  const bot = "[c_S]  └──────────────────────────────────────┘";
+  const bot = "       └──────────────────────────────────────┘";
   const boxLines = lines.map((line) => `       │ ${line.padEnd(lineWidth)} │`);
+  // Avatar beside the last message line (one row up from the bottom border).
+  boxLines[boxLines.length - 1] = `[c_S]  ${boxLines[boxLines.length - 1].slice(7)}`;
 
   return { html, text: [top, ...boxLines, bot].join("\n"), spacing: "normal" };
 }

package/src/email/render/chat-shared.ts

@@ -31,13 +31,7 @@ export function renderChatShared(payload: ChatSharedPayload): Block[] {
 
   blocks.push(
     chatDots(),
-    ctaBox({
-      label: "SEE MORE",
-      href: shareUrl,
-      padding: "12px 20px",
-      fontSize: "14px",
-      maxWidth: "200px",
-    }),
+    ctaBox({ label: "SEE MORE", href: shareUrl }),
     footer(`This share was sent via ${COMPANY_NAME}.`),
     paragraph(NOTICE, "tight"),
     signature(),

package/src/email/render/company-md-access-approved.ts

@@ -30,13 +30,7 @@ export function renderAccessApproved(payload: AccessApprovedPayload): Block[] {
       bold(`"${docTitle}"`),
       ` — you ${ACCESS_PHRASE[accessLevel]}.`,
     ]),
-    ctaBox({
-      label: "OPEN",
-      href: docUrl,
-      padding: "16px 24px",
-      fontSize: "16px",
-      maxWidth: "220px",
-    }),
+    ctaBox({ label: "OPEN", href: docUrl }),
     footer(`This notification was sent via ${COMPANY_NAME}.`),
     signature(),
   ];

package/src/email/render/company-md-access-requested.ts

@@ -36,16 +36,10 @@ export function renderAccessRequested(
     ]),
   ];
 
-  if (message) blocks.push(chatUser(message, `Message from ${requesterName}`));
+  if (message) blocks.push(chatUser(message, requesterName));
 
   blocks.push(
-    ctaBox({
-      label: "REVIEW",
-      href: reviewUrl,
-      padding: "16px 24px",
-      fontSize: "16px",
-      maxWidth: "220px",
-    }),
+    ctaBox({ label: "REVIEW", href: reviewUrl }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, OWNER_NOTE),
     signature(),
   );

package/src/email/render/org-invite.ts

@@ -22,12 +22,7 @@ export function renderOrgInvite(payload: OrgInvitePayload): Block[] {
 
   return [
     paragraph("Workspace invitation."),
-    ctaBox({
-      label: "JOIN",
-      href: acceptUrl,
-      padding: "20px 24px",
-      fontSize: "16px",
-    }),
+    ctaBox({ label: "JOIN", href: acceptUrl }),
     keyValue("From", inviterName),
     keyValue("Workspace", orgName),
     keyValue("Role", role),

package/src/email/render/ownership-transfer.ts

@@ -30,16 +30,10 @@ export function renderOwnershipTransfer(
     ]),
   ];
 
-  if (note) blocks.push(chatUser(note, "Message from the current owner"));
+  if (note) blocks.push(chatUser(note, "the current owner"));
 
   blocks.push(
-    ctaBox({
-      label: "ACCEPT",
-      href: acceptUrl,
-      padding: "16px 24px",
-      fontSize: "16px",
-      maxWidth: "220px",
-    }),
+    ctaBox({ label: "ACCEPT", href: acceptUrl }),
     keyValue("Expires in", `${expiresInDays} days`, "normal"),
     footer(
       "If you did not expect this invitation, you can safely ignore this email.",

package/src/email/render/share-granted.ts

@@ -46,16 +46,10 @@ export function renderShareGranted(payload: ShareGrantedPayload): Block[] {
     ]),
   ];
 
-  if (message) blocks.push(chatUser(message, `Message from ${granterName}`));
+  if (message) blocks.push(chatUser(message, granterName));
 
   blocks.push(
-    ctaBox({
-      label: "OPEN",
-      href: ctaUrl,
-      padding: "16px 24px",
-      fontSize: "16px",
-      maxWidth: "220px",
-    }),
+    ctaBox({ label: "OPEN", href: ctaUrl }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
     signature(),
   );

package/src/email/render/unit-owner-granted.ts

@@ -37,16 +37,10 @@ export function renderUnitOwnerGranted(
     ]),
   ];
 
-  if (message) blocks.push(chatUser(message, `Message from ${granterName}`));
+  if (message) blocks.push(chatUser(message, granterName));
 
   blocks.push(
-    ctaBox({
-      label: "VIEW TEAM",
-      href: ctaUrl,
-      padding: "16px 24px",
-      fontSize: "16px",
-      maxWidth: "220px",
-    }),
+    ctaBox({ label: "VIEW TEAM", href: ctaUrl }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
     signature(),
   );

package/src/index.ts

@@ -352,15 +352,13 @@ export type {
   CompanyMdTreeNode,
   CompanyMdDoc,
   CompanyMdContextBankItem,
-  // Sharing and ACL types (PRD-00306)
+  // Sharing and ACL types (PRD-00306). Legacy AccessSource / AccessReason /
+  // EffectiveAccess / EvaluationStep / AccessExplanation removed with
+  // CompanyMdAccessEvaluator (ADR-BE-392); the ONE AccessSource is re-exported
+  // from ./permissions below.
   AccessLevel,
   SharePolicy,
   AclEntry,
-  AccessSource,
-  AccessReason,
-  EffectiveAccess,
-  EvaluationStep,
-  AccessExplanation,
   ShareState,
   PermissionAuditEntry,
 } from "./org/index";

package/src/org/README.md

@@ -17,10 +17,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 ## Public API
 
 - `AcceptInviteRequest` _(type)_ — Request payload for accepting an organization invite.
-- `AccessExplanation` _(type)_ — Full access explanation with evaluation trace.
 - `AccessLevel` _(type)_ — Document access level.
-- `AccessReason` _(type)_
-- `AccessSource` _(type)_ — Source of an access grant.
 - `AcknowledgeSystemEventResponse` _(type)_
 - `AcknowledgeSystemEventResponseSchema`
 - `AclEntry` _(type)_
@@ -93,8 +90,6 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `DomainResponseSchema`
 - `DomainStatus` _(type)_ — Status of a domain claim within an organization. - 'pending': Domain claimed but not yet verified -…
 - `DomainVerificationMethod` _(type)_ — Method used to verify domain ownership. - 'dnstxt': DNS TXT record verification (primary method) - 'email'…
-- `EffectiveAccess` _(type)_ — Effective access for a user on a document.
-- `EvaluationStep` _(type)_ — Single step in the access evaluation trace.
 - `ExecutionContext` _(type)_
 - `ExecutionContextSchema` — ExecutionContext — the RUN in which an intent was produced or applied.
 - `ExecutionScope` _(type)_ — Execution scope determines whose identity is used when executing actions. - 'self': Actions execute under the…

package/src/org/index.ts

@@ -227,16 +227,15 @@ export type {
   CompanyMdContextBankItem,
 } from "./company-md";
 
-// Sharing and ACL types (PRD-00306)
+// Sharing and ACL types (PRD-00306). The legacy AccessSource / AccessReason /
+// EffectiveAccess / EvaluationStep / AccessExplanation were removed with
+// CompanyMdAccessEvaluator (ADR-BE-392); ShareState.effectiveAccess now carries
+// the projection EffectiveAccessResponse, and the ONE AccessSource lives in
+// permissions/access-source.
 export type {
   AccessLevel,
   SharePolicy,
   AclEntry,
-  AccessSource,
-  AccessReason,
-  EffectiveAccess,
-  EvaluationStep,
-  AccessExplanation,
   ShareState,
   PermissionAuditEntry,
 } from "./sharing";

package/src/org/sharing.ts

@@ -1,3 +1,5 @@
+import type { EffectiveAccessResponse } from "../permissions/share-api.js";
+
 /**
  * Document access level.
  * Privilege order: editor > commenter > viewer.
@@ -23,81 +25,25 @@ export interface AclEntry {
   readonly grantedAt: string;
 }
 
-/**
- * Source of an access grant.
- * Used in EffectiveAccess.reasons and EvaluationStep.source.
- *
- * `unit_delegation` covers leadership/delegation grants on the doc's owning
- * unit via the authority projection (ADR-BE-169). Distinct from
- * `unit_baseline` (which is membership-role-based) — delegations live on the
- * `org_unit_authority_grants` table and carry an explicit scope set.
- *
- * `visibility` covers the general-access band (`private` | `unit` | `org` on
- * the entity's `visibility` column) — the "General access" tier in the share
- * dialog. `unit` grants viewer to everyone home-in or matrixed-into the owning
- * unit's subtree (members ∪ contributors, flowing down); at the org root `unit`
- * normalizes to org-wide. `org` grants viewer to every org member. This is a
- * first-class source so the deterministic evaluator, the in-memory open gate,
- * and the materialized grant-compiler all resolve the band identically. See
- * ADR-CONTRACTS-075 and backend ADR-BE-374.
- */
-export type AccessSource =
-  | "org_rbac"
-  | "sharing_policy"
-  | "visibility"
-  | "unit_baseline"
-  | "unit_delegation"
-  | "acl_grant"
-  | "doc_ownership";
-
-export interface AccessReason {
-  readonly source: AccessSource;
-  readonly detail: string;
-}
-
-/**
- * Effective access for a user on a document.
- *
- * INVARIANTS:
- * - canShare is granted ONLY by: doc ownership, ownership of the owning unit,
- *   or org-level org.manage_goals / org.manage_company_md.
- * - canShare is NEVER granted by ACL entries or sharing policy.
- * - org_edit via sharing policy does NOT imply canShare.
- * - Unit membership grants baseline access ONLY to resources owned by that unit.
- */
-export interface EffectiveAccess {
-  readonly level: "none" | AccessLevel;
-  readonly reasons: ReadonlyArray<AccessReason>;
-  readonly canShare: boolean;
-}
-
-/**
- * Single step in the access evaluation trace.
- * Enables full traceability for debugging, audit UI, and compliance.
- */
-export interface EvaluationStep {
-  readonly source: AccessSource;
-  readonly checked: boolean;
-  readonly granted: AccessLevel | null;
-  readonly detail: string;
-}
-
-/**
- * Full access explanation with evaluation trace.
- * Returned by GoalsAccessEvaluator.explain().
- */
-export interface AccessExplanation extends EffectiveAccess {
-  readonly evaluationTrace: ReadonlyArray<EvaluationStep>;
-}
-
 /**
  * Complete sharing state for a document.
- * Returned by GET /api/goals/docs/:slug/sharing.
+ * Returned by GET /api/company-md/docs/:id/sharing.
+ *
+ * `effectiveAccess` is the ONE effective-access authority's answer
+ * ({@link EffectiveAccessResponse}: a nullable `access_level` + the
+ * `source_chain` of provenance tokens from the single `access-source` vocabulary
+ * — `explicit` | `ownership` | `visibility` | `inheritance` | `authority` |
+ * `context_association` | `migration`). The legacy per-doc `EffectiveAccess` /
+ * `AccessExplanation` shapes (their own 7-token `AccessSource`, `reasons`,
+ * `evaluationTrace`) were removed when `CompanyMdAccessEvaluator` was deleted and
+ * the response was collapsed onto the single authority (ADR-BE-392). There is now
+ * ONE `AccessSource` in the package (the projection one, from
+ * `permissions/access-source`).
  */
 export interface ShareState {
   readonly sharingPolicy: SharePolicy;
   readonly acl: ReadonlyArray<AclEntry>;
-  readonly effectiveAccess: EffectiveAccess;
+  readonly effectiveAccess: EffectiveAccessResponse;
 }
 
 /**