@company-semantics/contracts 32.0.0 → 33.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "32.0.0",
+  "version": "33.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -125,7 +125,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^22.20.1",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",
     "markdownlint-cli2": "^0.23.0",

package/src/content/schemas.ts

@@ -125,7 +125,24 @@ export const CompanyMdDocResponseSchema = z.object({
   ]),
   parentId: z.string().nullable(),
   owningUnitId: z.string().nullable(),
-  owner: CompanyMdPersonSchema.nullable(),
+  /**
+   * The doc's EFFECTIVE owners (ADR-CONTRACTS-084), resolved by the same
+   * authority as the share dialog's `owner_user_ids`: a stored personal owner,
+   * else the owning unit's live authority holders, else the org account owner.
+   *
+   * A list, not a scalar — co-ownership is first-class (ADR-CTRL-161) and every
+   * entry is owner-equivalent (ADR-BE-189), so a surface naming one owner reads
+   * `owners[0]` and derives any co-owner count from `owners.length` (e.g. "Ada
+   * +2 are owners"). Ordered deterministically so the named owner is stable
+   * across reads. Empty only when the org has no account owner
+   * (runtime-impossible) — replaces the nullable `owner` scalar and the
+   * `ownerCount` shadow field.
+   */
+  owners: z
+    .array(CompanyMdPersonSchema)
+    .refine((a) => new Set(a.map((p) => p.id)).size === a.length, {
+      message: "duplicate id in owners",
+    }),
   canEdit: z.boolean(),
   /**
    * UI capability signal (ADR-BE-382): whether the requesting actor holds

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

@@ -10,15 +10,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
   footer,
   greeting,
   keyValue,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type AuthOtpPayload = EmailPayloads["auth.otp"];

package/src/email/render/blocks.ts

@@ -7,6 +7,10 @@
  * UI is the components.** Editing a block restyles every email, HTML and plain
  * text, across the backend (real sends) and the app (Ladle preview).
  *
+ * This module holds the primitives — shells, paragraphs, and the CTA box. The
+ * chat unit builds on them from `./chat`; both are re-exported together from
+ * `./index`, which is the surface templates and consumers import.
+ *
  * INVARIANTS:
  * - Pure functions, no side effects — except `signature()`, which reads the
  *   current year (`new Date().getFullYear()`) for the copyright line.
@@ -17,11 +21,14 @@
 import { COMPANY_NAME, MONO_FONT_STACK } from "./constants";
 import { escapeHtml } from "./escape-html";
 
-const MONO = `font-family: ${MONO_FONT_STACK};`;
+/** Shared type styling. Exported for `./chat` only — not part of the package
+ * surface (`./index` does not re-export these), so components stay the one
+ * place styling is decided. */
+export 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";
+export const FONT_SIZE = "13px";
 
 // =============================================================================
 // Core types
@@ -235,8 +242,9 @@ function asciiCtaBox(label: string): string {
 }
 
 /** The bordered `>> LABEL <<` button (HTML table + ascii text), with `margin` on
- * the table. `ctaBox` wraps it as a standalone block; a chat unit embeds it. */
-function ctaButton(
+ * the table. `ctaBox` wraps it as a standalone block; a chat unit embeds it
+ * (hence the export — internal to the render layer, not re-exported by `./index`). */
+export function ctaButton(
   opts: CtaBoxOptions,
   margin: string,
 ): { html: string; text: string } {
@@ -271,297 +279,3 @@ export function ctaBox(opts: CtaBoxOptions): Block {
   const { html, text } = ctaButton(opts, "0 0 20px 0");
   return { html, text, spacing: "normal" };
 }
-
-// =============================================================================
-// Chat bubbles — one dual-output block per role
-// =============================================================================
-
-/** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
-function wrapText(text: string, width: number): string[] {
-  const lines: string[] = [];
-  let cur = "";
-  for (const word of text.split(/\s+/).filter(Boolean)) {
-    let w = word;
-    while (w.length > width) {
-      if (cur) {
-        lines.push(cur);
-        cur = "";
-      }
-      lines.push(w.slice(0, width));
-      w = w.slice(width);
-    }
-    if (!cur) cur = w;
-    else if (cur.length + 1 + w.length <= width) cur += ` ${w}`;
-    else {
-      lines.push(cur);
-      cur = w;
-    }
-  }
-  if (cur) lines.push(cur);
-  return lines.length ? lines : [""];
-}
-
-/** Chat message truncation budget: at most MAX_MESSAGE_LINES lines of MESSAGE_WIDTH chars. */
-const MAX_MESSAGE_LINES = 3;
-const MESSAGE_WIDTH = 36;
-/** Plain-text left gutter (7 cols) reserved for the avatar on both sides, so the
- * user box aligns with the assistant box. */
-const CHAT_INDENT = "       ";
-
-/** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
-function wrapClamped(text: string, width: number, maxLines: number): string[] {
-  const lines = wrapText(text, width);
-  if (lines.length <= maxLines) return lines;
-  const kept = lines.slice(0, maxLines);
-  const last = kept[maxLines - 1];
-  kept[maxLines - 1] =
-    (last.length > width - 3 ? last.slice(0, width - 3).trimEnd() : last) +
-    "...";
-  return kept;
-}
-
-/**
- * The one truncation authority: clamp a raw message to MAX_MESSAGE_LINES ×
- * MESSAGE_WIDTH, ellipsized. Both surfaces of a chat block run content through
- * this, so HTML and plain text truncate at exactly the same point.
- */
-function clampMessage(text: string): string {
-  return wrapClamped(text, MESSAGE_WIDTH, MAX_MESSAGE_LINES).join(" ");
-}
-
-/** One message in a chat unit. `chatUser`/`chatAssistant` build these; `chatUnit`
- * lays them out together. `from` is the user attribution (sender name). */
-export interface ChatMessage {
-  role: "user" | "assistant";
-  text: string;
-  from?: string;
-}
-
-/** A user (right-aligned) chat message with an optional `from` attribution. */
-export function chatUser(text: string, from?: string): ChatMessage {
-  return { role: "user", text, from };
-}
-
-/** An assistant (left-aligned) chat message. */
-export function chatAssistant(text: string): ChatMessage {
-  return { role: "assistant", text };
-}
-
-/** A CTA button placed inside a chat unit (below a message). */
-export interface ChatCta {
-  role: "cta";
-  cta: CtaBoxOptions;
-}
-
-/** Centered continuation dots inside a chat unit — a "conversation continues"
- * separator placed between a message bubble and a following CTA. */
-export interface ChatDots {
-  role: "dots";
-}
-
-/** An item in a chat unit: a message bubble, a CTA button, or continuation dots. */
-export type ChatItem = ChatMessage | ChatCta | ChatDots;
-
-/** A CTA button for a chat unit — pass it to `chatUnit` alongside messages. */
-export function chatCta(cta: CtaBoxOptions): ChatCta {
-  return { role: "cta", cta };
-}
-
-/** Continuation dots for a chat unit — pass it to `chatUnit` where the
- * conversation should read as continuing (e.g. between the preview and CTA). */
-export function chatDots(): ChatDots {
-  return { role: "dots" };
-}
-
-/** The `<hr>` bracketing a chat unit — 24px toward the bubbles, 12px on the
- * outer side. */
-function chatRuleHtml(position: "top" | "bottom"): string {
-  const margin = position === "top" ? "12px 0 24px 0" : "24px 0 12px 0";
-  return `<hr style="border: none; border-top: 1px solid #bbb; margin: ${margin};">`;
-}
-
-/**
- * Render one message to its HTML `<table>` and plain-text box lines. Both roles
- * share the 3-column skeleton: a fixed avatar column on each side (the visible
- * avatar plus the opposite avatar rendered `visibility: hidden` to reserve its
- * width, so bubbles stay bounded and aligned), a middle cell that right/left-
- * aligns the bubble, and — for a user `from` — an attribution row below.
- */
-function renderBubble(
-  msg: ChatMessage,
-  margin: string,
-): { html: string; text: string[] } {
-  const clamped = clampMessage(msg.text);
-  const isUser = msg.role === "user";
-
-  const radius = isUser ? "8px 8px 0 8px" : "8px 8px 8px 0";
-  const bubbleAlign = isUser ? " text-align: right;" : "";
-  const cellAlign = isUser ? "right" : "left";
-  const csHidden = isUser ? "visibility: hidden; " : "";
-  const kaomojiHidden = isUser ? "" : "visibility: hidden; ";
-
-  const attributionRow =
-    isUser && msg.from
-      ? `
-  <tr>
-    <td></td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">${escapeHtml(msg.from)}</td>
-    <td></td>
-  </tr>`
-      : "";
-
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: ${margin};">
-  <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; ${csHidden}white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: ${cellAlign};"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
-      <tr><td style="border-radius: ${radius}; padding: 10px 14px;${bubbleAlign} ${MONO} font-size: ${FONT_SIZE}; color: #ffffff; background: #666;">${escapeHtml(clamped)}</td></tr>
-    </table></td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; ${kaomojiHidden}white-space: nowrap;">(•̀_ರ╮)</td>
-  </tr>${attributionRow}
-</table>`;
-
-  const border = "─".repeat(MESSAGE_WIDTH + 2);
-  const lines = wrapText(clamped, MESSAGE_WIDTH);
-  const body = lines.map(
-    (line) =>
-      `${CHAT_INDENT}│ ${isUser ? line.padStart(MESSAGE_WIDTH) : line.padEnd(MESSAGE_WIDTH)} │`,
-  );
-  // Avatar beside the last message line (one row up from the bottom border).
-  const last = body.length - 1;
-  if (isUser) body[last] += "  (•̀_ರ╮)";
-  else body[last] = `[c_S]  ${body[last].slice(CHAT_INDENT.length)}`;
-
-  const box = [
-    `${CHAT_INDENT}┌${border}┐`,
-    ...body,
-    `${CHAT_INDENT}└${border}┘`,
-  ];
-  if (isUser && msg.from) {
-    box.push(msg.from.padStart(CHAT_INDENT.length + MESSAGE_WIDTH + 3));
-  }
-  return { html, text: box };
-}
-
-/** The right-edge column the plain-text CTA/dots align to under a user bubble. */
-const CHAT_RIGHT_EDGE = CHAT_INDENT.length + MESSAGE_WIDTH + 4;
-
-/** Centered "⋮" HTML, sized to sit above and centered over a CTA box (they share
- * the same inline-block, so the dots span exactly the button's width). */
-function dotsOverCtaHtml(): string {
-  return `<div style="${MONO} font-size: 20px; font-weight: bold; color: #666; text-align: center; margin: 0 0 16px 0;">⋮</div>`;
-}
-
-/**
- * A CTA button inside the chat stream — aligned to the side of the message it
- * follows (`right` under a user bubble, `left` otherwise). Hidden avatar mirrors
- * reserve both columns, so it sits in the message channel and never enters the
- * kaomoji column. The button carries no margin; the row's 24px matches the bubbles.
- * When `withDots`, continuation "⋮" render just above the button, centered over it.
- */
-function renderChatCta(
-  cta: CtaBoxOptions,
-  align: "left" | "right",
-  withDots: boolean,
-): { html: string; text: string[] } {
-  const { html: btnHtml, text: btnText } = ctaButton(cta, "0");
-  // Dots + button share one inline-block so the dots center over the button's
-  // exact width regardless of label length.
-  const stack = `<div style="display: inline-block; text-align: left;">${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
-  <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: ${align};">${stack}</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
-  </tr>
-</table>`;
-
-  // Right-align to the message box's right edge (under a user bubble); else the
-  // left avatar gutter.
-  const btnLines = btnText
-    .split("\n")
-    .map((l) =>
-      !l
-        ? l
-        : align === "right"
-          ? l.padStart(CHAT_RIGHT_EDGE)
-          : `${CHAT_INDENT}${l}`,
-    );
-  if (!withDots) return { html, text: btnLines };
-
-  // Center "⋮" over the ascii box (its first line spans the full box width).
-  const boxWidth = btnText.split("\n")[0].length;
-  const dotsCol =
-    align === "right"
-      ? CHAT_RIGHT_EDGE - Math.floor(boxWidth / 2)
-      : CHAT_INDENT.length + Math.ceil(boxWidth / 2);
-  return { html, text: ["⋮".padStart(dotsCol), "", ...btnLines] };
-}
-
-/**
- * Standalone continuation dots — centered in the message channel. Used only when
- * `chatDots()` is NOT immediately followed by a CTA (the common case folds the
- * dots into the CTA via `renderChatCta`, centered over the box).
- */
-function renderChatDots(): { html: string; text: string[] } {
-  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 16px 0;">
-  <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
-    <td style="width: 100%; text-align: center; ${MONO} font-size: 20px; font-weight: bold; color: #666;">⋮</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
-  </tr>
-</table>`;
-  // Center the "⋮" over the message box (avatar gutter + box width + borders).
-  const center = Math.round(CHAT_RIGHT_EDGE / 2);
-  return { html, text: ["⋮".padStart(center)] };
-}
-
-/**
- * Lay out one or more chat items — message bubbles and/or CTA buttons — as a
- * single block: a rule above and below (the real-chat "unit"), the items
- * between. The plain-text rule spans the widest line; a blank line follows the
- * top rule and the last item hugs the bottom rule. Continuation dots
- * (`chatDots`) sit above the CTA they precede, centered over the box.
- */
-export function chatUnit(...items: ChatItem[]): Block {
-  const parts: { html: string; text: string[] }[] = [];
-  items.forEach((item, i) => {
-    if (item.role === "dots") {
-      // Dots immediately before a CTA render with it (centered over the box);
-      // otherwise fall back to channel-centered standalone dots.
-      if (items[i + 1]?.role !== "cta") parts.push(renderChatDots());
-      return;
-    }
-    if (item.role === "cta") {
-      // Mirror the side of the nearest preceding message (skip any dots between),
-      // so the CTA sits under the bubble it belongs to — right under a user.
-      let j = i - 1;
-      while (j >= 0 && items[j].role === "dots") j--;
-      const align = items[j]?.role === "user" ? "right" : "left";
-      parts.push(renderChatCta(item.cta, align, items[i - 1]?.role === "dots"));
-      return;
-    }
-    // A bubble directly above a CTA or continuation dots gets a tighter 16px
-    // gap; else 24px.
-    const next = items[i + 1]?.role;
-    const margin =
-      next === "cta" || next === "dots" ? "0 0 16px 0" : "0 0 24px 0";
-    parts.push(renderBubble(item, margin));
-  });
-  const width = parts
-    .flatMap((b) => b.text)
-    .reduce((w, l) => Math.max(w, l.length), 0);
-  const rule = "_".repeat(width);
-
-  const html = [
-    chatRuleHtml("top"),
-    ...parts.map((b) => b.html),
-    chatRuleHtml("bottom"),
-  ].join("\n");
-
-  const text =
-    `${rule}\n\n` +
-    parts.map((b) => b.text.join("\n")).join("\n\n") +
-    `\n${rule}`;
-
-  return { html, text, spacing: "normal" };
-}

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

@@ -6,17 +6,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatCta,
-  chatDots,
-  chatUnit,
-  chatUser,
   footer,
   greeting,
   NOTICE,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatDots, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type ChatSharedPayload = EmailPayloads["chat.shared"];

package/src/email/render/chat.ts

@@ -0,0 +1,331 @@
+/**
+ * Chat unit — the dual-output chat transcript block.
+ *
+ * The one component with real layout of its own: message bubbles, an in-stream
+ * CTA, and continuation dots, laid out as a bracketed "unit". Same contract as
+ * every other component in `blocks.ts` (returns a `Block` = `{ html, text }`, so
+ * both surfaces derive from one source); it lives apart because bubble geometry
+ * — wrapping, truncation, avatar gutters, alignment — is a self-contained
+ * concern that the paragraph/CTA primitives next door do not share.
+ *
+ * INVARIANTS:
+ * - Pure functions, no side effects.
+ * - Components escape their own content; templates pass raw text.
+ * - HTML and plain text truncate at exactly the same point (`clampMessage` is
+ *   the single truncation authority).
+ */
+
+import {
+  type Block,
+  type CtaBoxOptions,
+  ctaButton,
+  FONT_SIZE,
+  MONO,
+} from "./blocks";
+import { escapeHtml } from "./escape-html";
+
+// =============================================================================
+// Text geometry
+// =============================================================================
+
+/** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
+function wrapText(text: string, width: number): string[] {
+  const lines: string[] = [];
+  let cur = "";
+  for (const word of text.split(/\s+/).filter(Boolean)) {
+    let w = word;
+    while (w.length > width) {
+      if (cur) {
+        lines.push(cur);
+        cur = "";
+      }
+      lines.push(w.slice(0, width));
+      w = w.slice(width);
+    }
+    if (!cur) cur = w;
+    else if (cur.length + 1 + w.length <= width) cur += ` ${w}`;
+    else {
+      lines.push(cur);
+      cur = w;
+    }
+  }
+  if (cur) lines.push(cur);
+  return lines.length ? lines : [""];
+}
+
+/** Chat message truncation budget: at most MAX_MESSAGE_LINES lines of MESSAGE_WIDTH chars. */
+const MAX_MESSAGE_LINES = 3;
+const MESSAGE_WIDTH = 36;
+/** Plain-text left gutter (7 cols) reserved for the avatar on both sides, so the
+ * user box aligns with the assistant box. */
+const CHAT_INDENT = "       ";
+
+/** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
+function wrapClamped(text: string, width: number, maxLines: number): string[] {
+  const lines = wrapText(text, width);
+  if (lines.length <= maxLines) return lines;
+  const kept = lines.slice(0, maxLines);
+  const last = kept[maxLines - 1];
+  kept[maxLines - 1] =
+    (last.length > width - 3 ? last.slice(0, width - 3).trimEnd() : last) +
+    "...";
+  return kept;
+}
+
+/**
+ * The one truncation authority: clamp a raw message to MAX_MESSAGE_LINES ×
+ * MESSAGE_WIDTH, ellipsized. Both surfaces of a chat block run content through
+ * this, so HTML and plain text truncate at exactly the same point.
+ */
+function clampMessage(text: string): string {
+  return wrapClamped(text, MESSAGE_WIDTH, MAX_MESSAGE_LINES).join(" ");
+}
+
+// =============================================================================
+// Chat items
+// =============================================================================
+
+/** One message in a chat unit. `chatUser`/`chatAssistant` build these; `chatUnit`
+ * lays them out together. `from` is the user attribution (sender name). */
+export interface ChatMessage {
+  role: "user" | "assistant";
+  text: string;
+  from?: string;
+}
+
+/** A user (right-aligned) chat message with an optional `from` attribution. */
+export function chatUser(text: string, from?: string): ChatMessage {
+  return { role: "user", text, from };
+}
+
+/** An assistant (left-aligned) chat message. */
+export function chatAssistant(text: string): ChatMessage {
+  return { role: "assistant", text };
+}
+
+/** A CTA button placed inside a chat unit (below a message). */
+export interface ChatCta {
+  role: "cta";
+  cta: CtaBoxOptions;
+}
+
+/** Centered continuation dots inside a chat unit — a "conversation continues"
+ * separator placed between a message bubble and a following CTA. */
+export interface ChatDots {
+  role: "dots";
+}
+
+/** An item in a chat unit: a message bubble, a CTA button, or continuation dots. */
+export type ChatItem = ChatMessage | ChatCta | ChatDots;
+
+/** A CTA button for a chat unit — pass it to `chatUnit` alongside messages. */
+export function chatCta(cta: CtaBoxOptions): ChatCta {
+  return { role: "cta", cta };
+}
+
+/** Continuation dots for a chat unit — pass it to `chatUnit` where the
+ * conversation should read as continuing (e.g. between the preview and CTA). */
+export function chatDots(): ChatDots {
+  return { role: "dots" };
+}
+
+// =============================================================================
+// Item rendering
+// =============================================================================
+
+/** The `<hr>` bracketing a chat unit — 24px toward the bubbles, 12px on the
+ * outer side. */
+function chatRuleHtml(position: "top" | "bottom"): string {
+  const margin = position === "top" ? "12px 0 24px 0" : "24px 0 12px 0";
+  return `<hr style="border: none; border-top: 1px solid #bbb; margin: ${margin};">`;
+}
+
+/**
+ * Render one message to its HTML `<table>` and plain-text box lines. Both roles
+ * share the 3-column skeleton: a fixed avatar column on each side (the visible
+ * avatar plus the opposite avatar rendered `visibility: hidden` to reserve its
+ * width, so bubbles stay bounded and aligned), a middle cell that right/left-
+ * aligns the bubble, and — for a user `from` — an attribution row below.
+ */
+function renderBubble(
+  msg: ChatMessage,
+  margin: string,
+): { html: string; text: string[] } {
+  const clamped = clampMessage(msg.text);
+  const isUser = msg.role === "user";
+
+  const radius = isUser ? "8px 8px 0 8px" : "8px 8px 8px 0";
+  const bubbleAlign = isUser ? " text-align: right;" : "";
+  const cellAlign = isUser ? "right" : "left";
+  const csHidden = isUser ? "visibility: hidden; " : "";
+  const kaomojiHidden = isUser ? "" : "visibility: hidden; ";
+
+  const attributionRow =
+    isUser && msg.from
+      ? `
+  <tr>
+    <td></td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; color: #666; text-align: right; padding-top: 6px; padding-right: 1ch;">${escapeHtml(msg.from)}</td>
+    <td></td>
+  </tr>`
+      : "";
+
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: ${margin};">
+  <tr>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; ${csHidden}white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: ${cellAlign};"><table cellpadding="0" cellspacing="0" border="0" style="display: inline-block; max-width: 100%; vertical-align: bottom;">
+      <tr><td style="border-radius: ${radius}; padding: 10px 14px;${bubbleAlign} ${MONO} font-size: ${FONT_SIZE}; color: #ffffff; background: #666;">${escapeHtml(clamped)}</td></tr>
+    </table></td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; ${kaomojiHidden}white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>${attributionRow}
+</table>`;
+
+  const border = "─".repeat(MESSAGE_WIDTH + 2);
+  const lines = wrapText(clamped, MESSAGE_WIDTH);
+  const body = lines.map(
+    (line) =>
+      `${CHAT_INDENT}│ ${isUser ? line.padStart(MESSAGE_WIDTH) : line.padEnd(MESSAGE_WIDTH)} │`,
+  );
+  // Avatar beside the last message line (one row up from the bottom border).
+  const last = body.length - 1;
+  if (isUser) body[last] += "  (•̀_ರ╮)";
+  else body[last] = `[c_S]  ${body[last].slice(CHAT_INDENT.length)}`;
+
+  const box = [
+    `${CHAT_INDENT}┌${border}┐`,
+    ...body,
+    `${CHAT_INDENT}└${border}┘`,
+  ];
+  if (isUser && msg.from) {
+    box.push(msg.from.padStart(CHAT_INDENT.length + MESSAGE_WIDTH + 3));
+  }
+  return { html, text: box };
+}
+
+/** The right-edge column the plain-text CTA/dots align to under a user bubble. */
+const CHAT_RIGHT_EDGE = CHAT_INDENT.length + MESSAGE_WIDTH + 4;
+
+/** Centered "⋮" HTML, sized to sit above and centered over a CTA box (they share
+ * the same inline-block, so the dots span exactly the button's width). */
+function dotsOverCtaHtml(): string {
+  return `<div style="${MONO} font-size: 20px; font-weight: bold; color: #666; text-align: center; margin: 0 0 16px 0;">⋮</div>`;
+}
+
+/**
+ * A CTA button inside the chat stream — aligned to the side of the message it
+ * follows (`right` under a user bubble, `left` otherwise). Hidden avatar mirrors
+ * reserve both columns, so it sits in the message channel and never enters the
+ * kaomoji column. The button carries no margin; the row's 24px matches the bubbles.
+ * When `withDots`, continuation "⋮" render just above the button, centered over it.
+ */
+function renderChatCta(
+  cta: CtaBoxOptions,
+  align: "left" | "right",
+  withDots: boolean,
+): { html: string; text: string[] } {
+  const { html: btnHtml, text: btnText } = ctaButton(cta, "0");
+  // Dots + button share one inline-block so the dots center over the button's
+  // exact width regardless of label length.
+  const stack = `<div style="display: inline-block; text-align: left;">${withDots ? dotsOverCtaHtml() : ""}${btnHtml}</div>`;
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 24px 0;">
+  <tr>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: ${align};">${stack}</td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>
+</table>`;
+
+  // Right-align to the message box's right edge (under a user bubble); else the
+  // left avatar gutter.
+  const btnLines = btnText
+    .split("\n")
+    .map((l) =>
+      !l
+        ? l
+        : align === "right"
+          ? l.padStart(CHAT_RIGHT_EDGE)
+          : `${CHAT_INDENT}${l}`,
+    );
+  if (!withDots) return { html, text: btnLines };
+
+  // Center "⋮" over the ascii box (its first line spans the full box width).
+  const boxWidth = btnText.split("\n")[0].length;
+  const dotsCol =
+    align === "right"
+      ? CHAT_RIGHT_EDGE - Math.floor(boxWidth / 2)
+      : CHAT_INDENT.length + Math.ceil(boxWidth / 2);
+  return { html, text: ["⋮".padStart(dotsCol), "", ...btnLines] };
+}
+
+/**
+ * Standalone continuation dots — centered in the message channel. Used only when
+ * `chatDots()` is NOT immediately followed by a CTA (the common case folds the
+ * dots into the CTA via `renderChatCta`, centered over the box).
+ */
+function renderChatDots(): { html: string; text: string[] } {
+  const html = `<table cellpadding="0" cellspacing="0" border="0" width="100%" style="margin: 0 0 16px 0;">
+  <tr>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: center; ${MONO} font-size: 20px; font-weight: bold; color: #666;">⋮</td>
+    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</td>
+  </tr>
+</table>`;
+  // Center the "⋮" over the message box (avatar gutter + box width + borders).
+  const center = Math.round(CHAT_RIGHT_EDGE / 2);
+  return { html, text: ["⋮".padStart(center)] };
+}
+
+// =============================================================================
+// Chat unit
+// =============================================================================
+
+/**
+ * Lay out one or more chat items — message bubbles and/or CTA buttons — as a
+ * single block: a rule above and below (the real-chat "unit"), the items
+ * between. The plain-text rule spans the widest line; a blank line follows the
+ * top rule and the last item hugs the bottom rule. Continuation dots
+ * (`chatDots`) sit above the CTA they precede, centered over the box.
+ */
+export function chatUnit(...items: ChatItem[]): Block {
+  const parts: { html: string; text: string[] }[] = [];
+  items.forEach((item, i) => {
+    if (item.role === "dots") {
+      // Dots immediately before a CTA render with it (centered over the box);
+      // otherwise fall back to channel-centered standalone dots.
+      if (items[i + 1]?.role !== "cta") parts.push(renderChatDots());
+      return;
+    }
+    if (item.role === "cta") {
+      // Mirror the side of the nearest preceding message (skip any dots between),
+      // so the CTA sits under the bubble it belongs to — right under a user.
+      let j = i - 1;
+      while (j >= 0 && items[j].role === "dots") j--;
+      const align = items[j]?.role === "user" ? "right" : "left";
+      parts.push(renderChatCta(item.cta, align, items[i - 1]?.role === "dots"));
+      return;
+    }
+    // A bubble directly above a CTA or continuation dots gets a tighter 16px
+    // gap; else 24px.
+    const next = items[i + 1]?.role;
+    const margin =
+      next === "cta" || next === "dots" ? "0 0 16px 0" : "0 0 24px 0";
+    parts.push(renderBubble(item, margin));
+  });
+  const width = parts
+    .flatMap((b) => b.text)
+    .reduce((w, l) => Math.max(w, l.length), 0);
+  const rule = "_".repeat(width);
+
+  const html = [
+    chatRuleHtml("top"),
+    ...parts.map((b) => b.html),
+    chatRuleHtml("bottom"),
+  ].join("\n");
+
+  const text =
+    `${rule}\n\n` +
+    parts.map((b) => b.text.join("\n")).join("\n\n") +
+    `\n${rule}`;
+
+  return { html, text, spacing: "normal" };
+}

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

@@ -7,15 +7,13 @@ import type { EmailPayloads } from "../types";
 import {
   ACCESS_PHRASE,
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
   footer,
   greeting,
   keyValue,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type AccessApprovedPayload =

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

@@ -6,14 +6,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatUnit,
-  chatUser,
   footer,
   greeting,
   keyValue,
   paragraph,
   signature,
 } from "./blocks";
+import { chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type AccessDeniedPayload =

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

@@ -6,16 +6,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
-  chatUser,
   footer,
   greeting,
   keyValue,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type AccessRequestedPayload =

package/src/email/render/index.ts

@@ -23,23 +23,27 @@ export {
   signature,
   NOTICE,
   ACCESS_PHRASE,
-  chatDots,
   ctaBox,
-  chatUser,
-  chatAssistant,
-  chatCta,
-  chatUnit,
   bold,
   type Block,
-  type ChatMessage,
-  type ChatCta,
-  type ChatItem,
   type Inline,
   type InlineContent,
   type Spacing,
   type CtaBoxOptions,
 } from "./blocks";
 
+// The chat unit — same `Block` contract, its own module (bubble geometry)
+export {
+  chatDots,
+  chatUser,
+  chatAssistant,
+  chatCta,
+  chatUnit,
+  type ChatMessage,
+  type ChatCta,
+  type ChatItem,
+} from "./chat";
+
 // Dispatcher
 export {
   renderEmail,

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

@@ -6,9 +6,6 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
   footer,
   formatExpiry,
   greeting,
@@ -18,6 +15,7 @@ import {
   signature,
   titleCase,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type OrgInvitePayload = EmailPayloads["org.invite"];

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

@@ -6,14 +6,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatUnit,
   footer,
   greeting,
   keyValue,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatUnit } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type OwnershipTransferCompletedPayload =

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

@@ -6,10 +6,6 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
-  chatUser,
   footer,
   formatExpiry,
   greeting,
@@ -18,6 +14,7 @@ import {
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type OwnershipTransferPayload = EmailPayloads["org.ownership_transfer"];

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

@@ -7,10 +7,6 @@ import type { EmailPayloads } from "../types";
 import {
   ACCESS_PHRASE,
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
-  chatUser,
   footer,
   greeting,
   keyValue,
@@ -18,6 +14,7 @@ import {
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type ShareGrantedPayload = EmailPayloads["share.granted"];

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

@@ -6,10 +6,6 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatCta,
-  chatUnit,
-  chatUser,
   footer,
   formatExpiry,
   greeting,
@@ -19,6 +15,7 @@ import {
   signature,
   titleCase,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];

package/src/org/company-md.ts

@@ -221,7 +221,21 @@ export interface CompanyMdDocCore extends CompanyMdNodeIdentity {
 }
 
 export interface CompanyMdDocCollaborators {
-  readonly owner: { readonly id: string; readonly name: string } | null;
+  /**
+   * The doc's EFFECTIVE owners (ADR-CONTRACTS-084) — hand-mirror of
+   * `CompanyMdDocResponseSchema.owners`; keep the two in lockstep.
+   *
+   * A list, not a scalar: ownership is resolved rather than stored (a personal
+   * owner, else the owning unit's live authority holders, else the org account
+   * owner), and co-ownership is first-class (ADR-CTRL-161) — every entry is
+   * owner-equivalent (ADR-BE-189). Name one owner with `owners[0]` and derive
+   * the co-owner count from `owners.length`. Empty only when the org has no
+   * account owner (runtime-impossible).
+   */
+  readonly owners: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+  }>;
   readonly canEdit: boolean;
   readonly members: ReadonlyArray<{
     readonly id: string;

package/src/permissions/share-api.ts

@@ -13,6 +13,15 @@ import { z } from "zod";
 import { AccessLevelSchema } from "./access-levels";
 import { AccessSourceSchema } from "./access-source";
 
+/**
+ * Contract-level invariant: an id set contains each id at most once. A duplicate
+ * is a serializer bug, not a presentation concern, so we fail Zod parse at the
+ * API boundary on both server and client (mirrors `uniqueByUserId` on
+ * OrgUnitOwnersResponseSchema).
+ */
+const uniqueValues = (arr: ReadonlyArray<string>): boolean =>
+  new Set(arr).size === arr.length;
+
 export const PrincipalTypeSchema = z.enum(["user", "unit", "org"]);
 export type PrincipalType = z.infer<typeof PrincipalTypeSchema>;
 
@@ -61,7 +70,19 @@ export type AclGrantResponse = z.infer<typeof AclGrantResponseSchema>;
 export const AclListResponseSchema = z.object({
   entity_type: z.string(),
   entity_id: z.string().uuid(),
-  owner_user_id: z.string().uuid().nullable(),
+  /**
+   * The entity's EFFECTIVE owners (ADR-CONTRACTS-084). Ownership is resolved,
+   * not stored: a personal doc yields its stored owner; a structural company.md
+   * doc yields its owning unit's live authority holders; the org account owner
+   * is the guaranteed fallback.
+   *
+   * A set, not a scalar — co-ownership is first-class (ADR-CTRL-161), so a unit
+   * with co-owners yields > 1 and EVERY entry is owner-equivalent (ADR-BE-189).
+   * Empty only when the org has no account owner (runtime-impossible).
+   */
+  owner_user_ids: z
+    .array(z.string().uuid())
+    .refine(uniqueValues, { message: "duplicate id in owner_user_ids" }),
   /** General-access scope: WHO is eligible (the discoverability axis). */
   visibility: EntityVisibilitySchema,
   /**