@company-semantics/contracts 31.0.0 → 33.0.0

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

@@ -64,6 +64,41 @@ function toEmail(subject: string, blocks: Block[]): RenderedEmail {
   return { subject, text: textShell(blocks), html: htmlShell(blocks) };
 }
 
+/**
+ * Fill `{field}` placeholders in a registry subject from the payload (e.g.
+ * `{orgName}` → the payload's orgName). Unmatched/absent placeholders are left
+ * verbatim, and a placeholder-free subject passes through untouched.
+ */
+function resolveSubject(template: string, payload: unknown): string {
+  if (!payload || typeof payload !== "object") return template;
+  const data = payload as Record<string, unknown>;
+  return template.replace(/\{(\w+)\}/g, (whole, key) =>
+    data[key] != null ? String(data[key]) : whole,
+  );
+}
+
+/**
+ * Per-kind subject data. Most kinds resolve directly against the payload; a few
+ * expose a derived token the payload doesn't carry. `org.unit_owner_granted`
+ * needs a short role word ("owner"/"delegate") for the subject, whereas the
+ * payload's `roleLabel` is the display form ("Unit owner"/"Delegate") used in
+ * the body's Role row — so it's derived here rather than mutating roleLabel.
+ */
+function subjectData(kind: EmailKind, payload: unknown): unknown {
+  if (
+    kind === "org.unit_owner_granted" &&
+    payload &&
+    typeof payload === "object"
+  ) {
+    const roleLabel = (payload as { roleLabel?: string }).roleLabel;
+    return {
+      ...payload,
+      roleWord: roleLabel === "Delegate" ? "delegate owner" : "owner",
+    };
+  }
+  return payload;
+}
+
 /**
  * Render an email by kind. Subject comes from `EMAIL_KINDS`; both surfaces
  * derive from one composed block list. Accepts the full `EmailKind` union so
@@ -77,7 +112,10 @@ export function renderEmail<K extends EmailKind>(
   payload: PayloadFor<K>,
   options?: RenderEmailOptions,
 ): RenderedEmail {
-  const subject = EMAIL_KINDS[kind].subject;
+  const subject = resolveSubject(
+    EMAIL_KINDS[kind].subject,
+    subjectData(kind, payload),
+  );
 
   switch (kind) {
     case "auth.otp":

package/src/email/render/security-alert.ts

@@ -1,11 +1,10 @@
 /**
- * Security alert email (plain text only). Signs off with a "Security" signer.
+ * Security alert email (plain text only).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { type Block, keyValue, paragraph, signature } from "./blocks";
-import { COMPANY_NAME } from "./constants";
+import { type Block, keyValue, paragraph, security, signature } from "./blocks";
 
 export type SecurityAlertPayload = EmailPayloads["security.alert"];
 export type SecurityAlertType = SecurityAlertPayload["alertType"];
@@ -18,19 +17,17 @@ export const SECURITY_ALERT_TYPES = [
 export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
   const { alertType, details, timestamp } = payload;
 
-  const blocks: Block[] = [];
+  const blocks: Block[] = [security()];
 
   switch (alertType) {
     case "excessive_otp_requests":
       blocks.push(
-        paragraph(
-          "We detected an unusual number of login code requests for your account.",
-        ),
+        paragraph("Unusual login-code activity detected."),
         keyValue("Details", details, "normal"),
         paragraph("If this was you, no action is needed.", "tight"),
         paragraph(
           "If you didn't request these codes, someone may be trying to access your account.",
-          "tight",
+          "normal",
         ),
         paragraph("We recommend reviewing your account security."),
       );
@@ -38,12 +35,14 @@ export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
 
     case "unusual_login_location":
       blocks.push(
-        paragraph("We detected a login attempt from an unusual location."),
+        paragraph("A login from an unusual location was detected."),
         keyValue("Details", details, "normal"),
         paragraph("If this was you, no action is needed.", "tight"),
         paragraph(
-          "If you didn't attempt to log in, please secure your account immediately.",
+          "If you didn't attempt to log in, someone may be trying to access your account.",
+          "normal",
         ),
+        paragraph("We recommend reviewing your account security."),
       );
       break;
 
@@ -54,8 +53,8 @@ export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
   }
 
   blocks.push(
-    keyValue("Time", new Date(timestamp).toUTCString(), "normal"),
-    signature(`${COMPANY_NAME} Security`),
+    keyValue("Time", new Date(timestamp).toUTCString(), "none"),
+    signature(),
   );
 
   return blocks;

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

@@ -7,16 +7,14 @@ import type { EmailPayloads } from "../types";
 import {
   ACCESS_PHRASE,
   type Block,
-  bold,
-  chatUser,
-  ctaBox,
   footer,
   greeting,
-  type Inline,
+  keyValue,
   NOTICE,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type ShareGrantedPayload = EmailPayloads["share.granted"];
@@ -32,25 +30,21 @@ export function renderShareGranted(payload: ShareGrantedPayload): Block[] {
     message,
   } = payload;
 
-  const entity: Array<string | Inline> = entityTitle
-    ? [`the ${entityLabel} `, bold(`"${entityTitle}"`)]
-    : [`a ${entityLabel}`];
-
   const blocks: Block[] = [
     greeting(recipientName),
-    paragraph([
-      bold(granterName),
-      " shared ",
-      ...entity,
-      ` with you — you ${ACCESS_PHRASE[accessLevel]}.`,
-    ]),
+    paragraph(`A ${entityLabel} was shared with you.`),
+    chatUnit(
+      message ? chatUser(message, granterName) : chatAssistant("Open to view."),
+      chatCta({ label: "OPEN", href: ctaUrl }),
+    ),
+    keyValue("From", granterName),
   ];
 
-  if (message) blocks.push(chatUser(message, granterName));
+  if (entityTitle) blocks.push(keyValue("Item", `"${entityTitle}"`));
 
   blocks.push(
-    ctaBox({ label: "OPEN", href: ctaUrl }),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
+    keyValue("Access", ACCESS_PHRASE[accessLevel], "normal"),
+    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
   );
 

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

@@ -6,15 +6,16 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  bold,
-  chatUser,
-  ctaBox,
   footer,
+  formatExpiry,
   greeting,
+  keyValue,
   NOTICE,
   paragraph,
   signature,
+  titleCase,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];
@@ -22,28 +23,38 @@ export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];
 export function renderUnitOwnerGranted(
   payload: UnitOwnerGrantedPayload,
 ): Block[] {
-  const { granterName, recipientName, unitName, roleLabel, ctaUrl, message } =
-    payload;
-
-  const blocks: Block[] = [
+  const {
+    granterName,
+    recipientName,
+    unitName,
+    roleLabel,
+    ctaUrl,
+    message,
+    expiresAt,
+  } = payload;
+  const roleNoun = roleLabel === "Delegate" ? "delegate owner" : "unit owner";
+
+  return [
     greeting(recipientName),
-    paragraph([
-      bold(granterName),
-      " added you as a ",
-      bold(roleLabel),
-      " of ",
-      bold(unitName),
-      ".",
-    ]),
-  ];
-
-  if (message) blocks.push(chatUser(message, granterName));
-
-  blocks.push(
-    ctaBox({ label: "VIEW TEAM", href: ctaUrl }),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
+    paragraph(
+      `You are now a ${roleNoun} of ${unitName}. ${roleNoun[0].toUpperCase()}${roleNoun.slice(1)}s hold authority over the team: managing team membership, doc access, strategy, and execution against goals.`,
+    ),
+    chatUnit(
+      ...(message ? [chatUser(message, granterName)] : []),
+      chatAssistant("Open the team to get started."),
+      chatCta({ label: "MANAGE TEAM", href: ctaUrl }),
+    ),
+    keyValue("From", granterName),
+    keyValue("Team", unitName),
+    keyValue(
+      "Role",
+      titleCase(roleLabel),
+      expiresAt != null ? "tight" : "normal",
+    ),
+    ...(expiresAt != null
+      ? [keyValue("Expires", formatExpiry(expiresAt), "normal")]
+      : []),
+    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
-  );
-
-  return blocks;
+  ];
 }

package/src/email/types.ts

@@ -63,13 +63,16 @@ export interface EmailPayloads {
     orgName: string;
     role: "admin" | "member";
     acceptUrl: string;
-    expiresInDays: number;
+    /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
+    expiresAt: string;
   };
   "org.unit_owner_granted": {
     /** Display name of the person who granted access */
     granterName: string;
     /** Display name of the recipient (optional; falls back to a neutral greeting) */
     recipientName?: string;
+    /** Name of the organization / workspace (rendered in the subject) */
+    orgName: string;
     /** Name of the org unit / team the access applies to */
     unitName: string;
     /** Human-readable role label the recipient was given */
@@ -78,16 +81,20 @@ export interface EmailPayloads {
     ctaUrl: string;
     /** Optional message from the granter, shown in the email and recorded with the grant */
     message?: string;
+    /** ISO timestamp when the grant expires. Absent = permanent (formal unit owners; delegations with no expiry). Rendered as the last key/value row ("Expires: Jun 13, 2026") when present. */
+    expiresAt?: string;
   };
   "org.ownership_transfer": {
     /** Name of the organization being transferred (subject is static; org name renders in the body) */
     orgName: string;
     /** Full URL to accept the transfer (token-bearing) */
     acceptUrl: string;
-    /** How long until the invitation expires */
-    expiresInDays: number;
+    /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
+    expiresAt: string;
     /** Optional message from the current owner */
     note?: string;
+    /** Display name of the workspace owner who initiated the transfer; attributes the note bubble. Omitted for admin-initiated transfers (no workspace-owner author). */
+    fromName?: string;
   };
   "org.ownership_transfer_completed": {
     /** Name of the organization that was transferred */

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,
   /**