@company-semantics/contracts 29.0.0 → 30.0.0

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",
   };
@@ -208,13 +211,14 @@ interface CtaVariantStyle {
 const CTA_VARIANTS: Record<"action" | "code", CtaVariantStyle> = {
   action: {
     padding: "16px 24px",
-    fontSize: "16px",
+    fontSize: FONT_SIZE,
     maxWidth: "220px",
     square: false,
   },
   code: {
-    padding: "20px 24px",
-    fontSize: "16px",
+    padding: "16px 24px",
+    fontSize: FONT_SIZE,
+    maxWidth: "220px",
     square: true,
     letterSpacing: "4px",
   },
@@ -319,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);
@@ -330,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/company-md-access-requested.ts

@@ -36,7 +36,7 @@ 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 }),

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

@@ -30,7 +30,7 @@ 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 }),

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

@@ -46,7 +46,7 @@ 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 }),

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

@@ -37,7 +37,7 @@ 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 }),

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;
 }
 
 /**