@company-semantics/contracts 58.0.0 → 58.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "58.0.0",
+  "version": "58.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -142,7 +142,7 @@
     "@types/node": "^22.20.1",
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
-    "eslint": "^10.8.1",
+    "eslint": "^10.9.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
     "markdownlint-cli2": "^0.23.2",
@@ -151,8 +151,8 @@
     "tsx": "^4.23.12",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.67.0",
-    "vite": "^8.2.1",
-    "vitest": "^4.1.10",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11",
     "yaml": "^2.9.0"
   },
   "pnpm": {

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 = 'ffeb6e367b38' as const;
-export const SPEC_HASH_FULL = 'ffeb6e367b385ad32f7b46e4e74d276786d6cdf175352e57d0fc229dc8f506af' as const;
+export const SPEC_HASH = '49b741e4372d' as const;
+export const SPEC_HASH_FULL = '49b741e4372d56fb1a87312fe62f6e86ffd4987de590d03414ee833a4b6586b0' as const;

package/src/api/generated.ts

@@ -4834,6 +4834,10 @@ export interface components {
         };
         SendInviteBatchRequest: {
             expectedRevision: number;
+            message?: string;
+            roleByPersonId?: {
+                [key: string]: "admin" | "member";
+            };
         };
         InviteValidationResult: {
             valid: boolean;
@@ -5989,6 +5993,14 @@ export interface components {
                 /** @enum {string} */
                 relationshipType: "solid" | "dotted";
             }[];
+            unplaced: {
+                personId: string;
+                fullName: string;
+                /** @enum {string} */
+                state: "needs_review" | "excluded";
+                /** @enum {string} */
+                reason: "insufficient_evidence" | "conflicting_evidence" | "ambiguous_boundary" | "service_account" | "not_workforce" | "inactive";
+            }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
         IngestionOperationPollResponse: {

package/src/index.ts

@@ -798,20 +798,72 @@ export type {
 export {
   CanonicalPersonSchema,
   CanonicalOrgUnitSchema,
+  CanonicalPositionStatusSchema,
   CanonicalPositionSchema,
   CanonicalOccupancySchema,
   CanonicalReportingEdgeSchema,
+  CanonicalUnresolvedManagerResolutionSchema,
+  CanonicalUnresolvedManagerSchema,
   CanonicalFactsSchema,
 } from "./org/index";
 export type {
   CanonicalPerson,
   CanonicalOrgUnit,
+  CanonicalPositionStatus,
   CanonicalPosition,
   CanonicalOccupancy,
   CanonicalReportingEdge,
+  CanonicalUnresolvedManagerResolution,
+  CanonicalUnresolvedManager,
   CanonicalFacts,
 } from "./org/index";
 
+// Org-structure inference: a StructureInferenceSnapshot of the persisted graph
+// goes in, a StructureProposal — a proposed desired state, never database
+// commands — comes out. Typed evidence, targetUnitId for durable identity, and
+// exactly one PersonStructureOutcome per person in the snapshot. (PRD-00955)
+//
+// Acceptance attaches StructureProvenance — proposalOrigin, acceptedBy and
+// authority as three ORTHOGONAL axes, so accepting an AI proposal never rewrites
+// its origin as manual. mayOverrideAuthority is the single definition of
+// precedence, and it consults `authority` only. (PRD-00956)
+export {
+  StructureEvidenceSchema,
+  TOPOLOGY_ONLY_EVIDENCE_KINDS,
+  StructureUnitAuthoritySchema,
+  StructureProposalOriginSchema,
+  StructureAcceptedBySchema,
+  StructureAuthoritySchema,
+  StructureProvenanceSchema,
+  mayOverrideAuthority,
+  ProposedOrgUnitSchema,
+  PersonStructureOutcomeSchema,
+  StructureReviewItemSchema,
+  StructureProposalSchema,
+  StructurePersonFactSchema,
+  StructureReportingFactSchema,
+  ExistingUnitFactSchema,
+  ExistingPlacementFactSchema,
+  StructureInferenceSnapshotSchema,
+} from "./org/index";
+export type {
+  StructureEvidence,
+  StructureUnitAuthority,
+  StructureProposalOrigin,
+  StructureAcceptedBy,
+  StructureAuthority,
+  StructureProvenance,
+  ProposedOrgUnit,
+  PersonStructureOutcome,
+  StructureReviewItem,
+  StructureProposal,
+  StructurePersonFact,
+  StructureReportingFact,
+  ExistingUnitFact,
+  ExistingPlacementFact,
+  StructureInferenceSnapshot,
+} from "./org/index";
+
 // Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,

package/src/notifications/__tests__/__snapshots__/monospace-budget.test.ts.snap

@@ -11,6 +11,7 @@ exports[`monospace budget > overhangs only where content is atomic 1`] = `
   "https://app.companysemantics.ai/doc/handbook?thread=th_456",
   "https://app.companysemantics.ai/invite/abc123",
   "https://app.companysemantics.ai/invite/def456",
+  "https://app.companysemantics.ai/invite/ghi789",
   "https://app.companysemantics.ai/meeting/8842",
   "https://app.companysemantics.ai/org/unit/42",
   "https://app.companysemantics.ai/owner-transfer/accept/tok123",

package/src/notifications/__tests__/__snapshots__/registry.test.ts.snap

@@ -24,6 +24,7 @@ exports[`NOTIFICATION_DEFINITIONS > titles every kind 1`] = `
   "companyMd.access_requested · With message": "Someone requested access to a document",
   "org.invite · Admin": "You've been invited to join Acme Corp on Company Semantics",
   "org.invite · Member": "You've been invited to join Acme Corp on Company Semantics",
+  "org.invite · Member + note": "You've been invited to join Acme Corp on Company Semantics",
   "org.ownership_transfer · No note (admin)": "You've been invited to become a workspace owner",
   "org.ownership_transfer · With note + from": "You've been invited to become a workspace owner",
   "org.ownership_transfer_completed · Default": "Workspace ownership has been transferred",

package/src/notifications/__tests__/__snapshots__/render-snapshot.test.ts.snap

@@ -3481,6 +3481,213 @@ If you weren't expecting this, no action is
 required.
 
 
+/* EOM */
+ⓒ 2026 • Company Semantics
+https://companysemantics.ai
+",
+}
+`;
+
+exports[`email render > org.invite · Member + note 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">Acme Corp uses Company Semantics.</p>
+<hr class="cs-faint csr-chat-rule-top">
+<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"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
+      <tr><td class="cs-bubble csr-bubble-user">We start planning next quarter on Monday — glad you are joining.</td></tr>
+    </table></td>
+    <td class="csr-chat-avatar-right">(•̀_ರ╮)</td>
+  </tr>
+  <tr>
+    <td></td>
+    <td class="cs-meta csr-chat-attribution">Alex Rivera</td>
+    <td></td>
+  </tr>
+</table>
+<table cellpadding="0" cellspacing="0" border="0" width="100%" class="csr-chat-row-16">
+  <tr>
+    <td class="csr-chat-avatar-left">[c_S]</td>
+    <td class="csr-chat-channel-left"><table cellpadding="0" cellspacing="0" border="0" class="csr-chat-bubble-wrap">
+      <tr><td class="cs-bubble csr-bubble-assistant">Join to accept the invitation.</td></tr>
+    </table></td>
+    <td class="csr-chat-avatar-right-hidden">(•̀_ರ╮)</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-left"><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/invite/ghi789" class="cs-link csr-cta-anchor">&gt;&gt; <span class="csr-cta-label">JOIN</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">From: Alex Rivera</p>
+<p class="csr-p-tight">Workspace: Acme Corp</p>
+<p class="csr-p-tight">Role: Member</p>
+<p class="csr-p-normal">Expires: Jun 13, 2026</p>
+<p class="csr-p-none">This invitation was sent via Company Semantics.<br>If you weren&#39;t expecting this, no action is required.</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;">Acme Corp uses Company Semantics.</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 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;"><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;">We start planning next quarter on Monday — glad you are joining.</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;">Alex Rivera</td>
+    <td></td>
+  </tr>
+</table>
+<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; white-space: nowrap;">[c_S]</td>
+    <td style="width: 100%; text-align: left;"><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 8px 0; padding: 10px 14px; font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; color: #ffffff; background: #666;">Join to accept the invitation.</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; visibility: hidden; white-space: nowrap;">(•̀_ರ╮)</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: left;"><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/invite/ghi789" class="cs-link" style="display: block; padding: 16px 24px; color: #0047FF; text-decoration: none;">&gt;&gt; <span style="text-decoration: underline;">JOIN</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;">From: Alex Rivera</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Workspace: Acme Corp</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 4px 0;">Role: Member</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0 0 20px 0;">Expires: Jun 13, 2026</p>
+<p style="font-family: 'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace; font-size: 13px; margin: 0;">This invitation was sent via Company Semantics.<br>If you weren&#39;t expecting this, no action is required.</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": "You've been invited to join Acme Corp on Company Semantics",
+  "text": "Hi there,
+
+Acme Corp uses Company Semantics.
+
+────────────────────────────────────────────────
+
+       ┌──────────────────────────────┐
+       │       We start planning next │
+       │ quarter on Monday — glad you │
+       │                 are joining. │  (•̀_ರ╮)
+       └──────────────────────────────┘
+                           Alex Rivera
+
+       ┌──────────────────────────────┐
+       │ Join to accept the           │
+[c_S]  │ invitation.                  │
+       └──────────────────────────────┘
+
+       *----------------*
+       |   >> JOIN <<   |
+       *----------------*
+
+       https://app.companysemantics.ai/invite/ghi789
+────────────────────────────────────────────────
+
+From: Alex Rivera
+Workspace: Acme Corp
+Role: Member
+Expires: Jun 13, 2026
+
+This invitation was sent via Company Semantics.
+If you weren't expecting this, no action is
+required.
+
+
 /* EOM */
 ⓒ 2026 • Company Semantics
 https://companysemantics.ai

package/src/notifications/__tests__/fixtures.ts

@@ -86,6 +86,15 @@ add("org.invite", "Member", {
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
+add("org.invite", "Member + note", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/ghi789`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  message: "We start planning next quarter on Monday — glad you are joining.",
+});
+
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",
   recipientName: "Sam Chen",

package/src/notifications/__tests__/org-invite.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The invitation's optional note.
+ *
+ * An invite is often the first thing someone ever receives from a workspace, so
+ * the one line of human context on it does real work — and it has to arrive
+ * ATTRIBUTED. A note rendered as product copy reads as boilerplate, which is
+ * the one thing it is not.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { createRenderContext } from "../context";
+import type { ChatUnitItem, NotificationContent } from "../content";
+import { orgInviteDefinition } from "../kinds/org-invite";
+import type { NotificationPayloads } from "../payloads";
+
+const CONTEXT = createRenderContext();
+
+const payload = (
+  over: Partial<NotificationPayloads["org.invite"]> = {},
+): NotificationPayloads["org.invite"] => ({
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: "https://app.companysemantics.ai/invite/abc123",
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  ...over,
+});
+
+function chatItems(content: NotificationContent): ChatUnitItem[] {
+  const elements = content.sections.flatMap((s) => s.elements);
+  const unit = elements.find((e) => e.type === "chatUnit");
+  if (!unit || unit.type !== "chatUnit") throw new Error("no chat unit");
+  return [...unit.items];
+}
+
+describe("org.invite", () => {
+  it("carries the note as the inviter's own words, above the join prompt", () => {
+    const items = chatItems(
+      orgInviteDefinition.compose(
+        payload({ message: "Glad you are joining." }),
+        CONTEXT,
+      ),
+    );
+    expect(items[0]).toEqual({
+      type: "message",
+      role: "user",
+      text: "Glad you are joining.",
+      from: "Alex Rivera",
+    });
+    // The prompt survives the note: the message is WHY someone was invited, the
+    // prompt is what to do about it.
+    expect(items[1]).toMatchObject({
+      role: "assistant",
+      text: "Join to accept the invitation.",
+    });
+  });
+
+  it("renders no message block at all without one", () => {
+    const items = chatItems(orgInviteDefinition.compose(payload(), CONTEXT));
+    expect(items.some((i) => i.type === "message" && i.role === "user")).toBe(
+      false,
+    );
+    expect(items[0]).toMatchObject({ role: "assistant" });
+  });
+
+  it("keeps the call to action last either way", () => {
+    for (const message of [undefined, "Welcome."]) {
+      const items = chatItems(
+        orgInviteDefinition.compose(payload({ message }), CONTEXT),
+      );
+      expect(items[items.length - 1]).toMatchObject({ type: "callToAction" });
+    }
+  });
+});

package/src/notifications/__tests__/render-snapshot.test.ts

@@ -92,6 +92,14 @@ add("org.invite", "Member", {
   acceptUrl: `${APP}/invite/def456`,
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
+add("org.invite", "Member + note", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/ghi789`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  message: "We start planning next quarter on Monday — glad you are joining.",
+});
 
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",

package/src/notifications/kinds/org-invite.ts

@@ -7,6 +7,7 @@
  * nothing left to catch. See ADR-CONTRACTS-085.
  */
 
+import type { ChatUnitItem } from "../content";
 import type { NotificationDefinition } from "../definition";
 
 import { formatExpiry, NOTICE, titleCase } from "../text";
@@ -14,7 +15,31 @@ import { formatExpiry, NOTICE, titleCase } from "../text";
 export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
   kind: "org.invite",
   compose: (payload, context) => {
-    const { inviterName, orgName, role, acceptUrl, expiresAt } = payload;
+    const { inviterName, orgName, role, acceptUrl, expiresAt, message } =
+      payload;
+
+    // The inviter's own words come FIRST and keep their name on them, above the
+    // prompt to join — a note attributed to nobody reads as product copy, which
+    // is the one thing it is not. The join prompt stays either way: the message
+    // is why this person was invited, the prompt is what to do about it.
+    const items: ChatUnitItem[] = [
+      ...(message
+        ? [
+            {
+              type: "message" as const,
+              role: "user" as const,
+              text: message,
+              from: inviterName,
+            },
+          ]
+        : []),
+      {
+        type: "message",
+        role: "assistant",
+        text: "Join to accept the invitation.",
+      },
+      { type: "callToAction", label: "JOIN", href: acceptUrl },
+    ];
 
     return {
       metadata: {
@@ -26,17 +51,7 @@ export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
           elements: [
             { type: "greeting" },
             { type: "body", text: `${orgName} uses Company Semantics.` },
-            {
-              type: "chatUnit",
-              items: [
-                {
-                  type: "message",
-                  role: "assistant",
-                  text: "Join to accept the invitation.",
-                },
-                { type: "callToAction", label: "JOIN", href: acceptUrl },
-              ],
-            },
+            { type: "chatUnit", items },
             {
               type: "keyValueTable",
               rows: [

package/src/notifications/payloads.ts

@@ -51,6 +51,13 @@ export interface NotificationPayloads {
     acceptUrl: string;
     /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
     expiresAt: string;
+    /**
+     * Optional note from the inviter, shown above the join prompt and attributed
+     * to them — the same shape `share.granted` and `org.unit_owner_granted` give
+     * a granter's message. Absent means no message block at all, never an empty
+     * one.
+     */
+    message?: string;
   };
   "org.unit_owner_granted": {
     /** Display name of the person who granted access */

package/src/org/README.md

@@ -61,8 +61,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `CanonicalPersonSchema` — A person as reported by an external source, keyed by external identity.
 - `CanonicalPosition` _(type)_
 - `CanonicalPositionSchema` — A position (seat) as reported by an external source, placed in a unit by external reference…
+- `CanonicalPositionStatus` _(type)_
+- `CanonicalPositionStatusSchema` — Seat-existence as the SOURCE reported it.
 - `CanonicalReportingEdge` _(type)_
 - `CanonicalReportingEdgeSchema` — A reporting edge (a seat reports to a manager seat) as reported by an external source.
+- `CanonicalUnresolvedManager` _(type)_
+- `CanonicalUnresolvedManagerResolution` _(type)_
+- `CanonicalUnresolvedManagerResolutionSchema` — Why a supervisory reference could not be resolved to a seat in this batch.
+- `CanonicalUnresolvedManagerSchema` — A supervisory reference the source reported that we could NOT resolve to a seat in this batch.
 - `CapabilitiesResponse` _(type)_
 - `CapabilitiesResponseSchema` — The single validated capability surface the UI reads.
 - `ChangeMemberRoleRequest` _(type)_ — Request payload for changing a member's role.
@@ -129,6 +135,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `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…
+- `ExistingPlacementFact` _(type)_
+- `ExistingPlacementFactSchema` — Where a person already sits, and on whose authority they sit there.
+- `ExistingUnitFact` _(type)_
+- `ExistingUnitFactSchema` — An org unit that already exists, with the license the engine has over it.
 - `FACT_SOURCE_TIER_PRECEDENCE` — Truth hierarchy, highest precedence first.
 - `FactMutation` _(type)_
 - `FactMutationSchema` — A single atomic fact change the engine applies to the live org graph.
@@ -301,6 +311,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OwnershipTransferResponseSchema`
 - `OwnershipTransferStatus` _(type)_ — Status of pending ownership transfer for an organization.
 - `PermissionAuditEntry` _(type)_ — Single entry in the permission change audit log.
+- `PersonStructureOutcome` _(type)_
+- `PersonStructureOutcomeSchema` — EXACTLY ONE outcome per person in the snapshot. "Zero or one placement" would accept a proposal that simply…
 - `Phase3AuditAction` _(type)_ — Audit actions for Phase 3 workspace expansion features.
 - `Phase4AuditAction` _(type)_ — Audit actions for Phase 4 enterprise identity features.
 - `Position` _(type)_
@@ -311,6 +323,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `PositionSchema`
 - `PositionStatus` _(type)_
 - `PositionStatusSchema` — Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline.
+- `ProposedOrgUnit` _(type)_
+- `ProposedOrgUnitSchema` — A unit the proposal wants the org to have.
 - `Provenance` _(type)_
 - `ProvenanceSchema` — Provenance — WHO/WHAT generated an intent.
 - `ProviderStatus` _(type)_ — Provider-level configuration lifecycle.
@@ -351,10 +365,33 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SsoStepperStep` _(type)_ — Backend-authoritative stepper step.
 - `StagedPlacement` _(type)_ — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
 - `StagedPlacementSchema` — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
+- `StructureAcceptedBy` _(type)_
+- `StructureAcceptedBySchema` — WHO accepted the fact.
+- `StructureAuthority` _(type)_
+- `StructureAuthoritySchema` — The authority axis — the ONLY axis precedence runs on: `human_confirmed` `ai_inferred` `hris_source`.
+- `StructureEvidence` _(type)_
+- `StructureEvidenceSchema` — TYPED evidence.
+- `StructureInferenceSnapshot` _(type)_
+- `StructureInferenceSnapshotSchema` — The inference INPUT: a point-in-time view of the PERSISTED canonical graph.
+- `StructurePersonFact` _(type)_
+- `StructurePersonFactSchema` — A person as the inference engine sees them.
+- `StructureProposal` _(type)_
+- `StructureProposalOrigin` _(type)_
+- `StructureProposalOriginSchema` — How a structural fact came to be PROPOSED.
+- `StructureProposalSchema` — A proposed desired state for one org.
+- `StructureProvenance` _(type)_
+- `StructureProvenanceSchema` — The three axes together, as one accepted structural fact records them. - v1 — AI proposes, an admin clicks…
+- `StructureReportingFact` _(type)_
+- `StructureReportingFactSchema` — One reporting edge, at person granularity.
+- `StructureReviewItem` _(type)_
+- `StructureReviewItemSchema` — A question the engine is asking a human, with the competing signals attached.
+- `StructureUnitAuthority` _(type)_
+- `StructureUnitAuthoritySchema` — How much license the engine has over an EXISTING unit or placement.
 - `SubmitInteractiveTaskResponse` _(type)_
 - `SubmitInteractiveTaskResponseSchema` — Response for submitting a filled-in interactive chat task surface (e.g. the editable "change reporting…
 - `SyncRunSummary` _(type)_
 - `SyncRunSummarySchema`
+- `TOPOLOGY_ONLY_EVIDENCE_KINDS` — Evidence kinds that alone are NOT sufficient to justify a unit boundary.
 - `TRANSFER_RESPONSIBILITIES` — Responsibility checklist items shown on the acceptance page.
 - `TestSsoInitiation` _(type)_ — Initiation payload for a test SSO login attempt.
 - `TestSsoInitiationDto` _(type)_ — Initiation payload for a test SSO login attempt.
@@ -424,6 +461,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `WorkspaceSsoState` _(type)_ — Workspace SSO state derived from provider status + policy.
 - `WorkspaceSurface` _(type)_ — Discriminator for workspace surface routing. - 'info': Read-only surface, any member, org.view capabilities -…
 - `getViewScope` — Get the required scope for a view, or null if public.
+- `mayOverrideAuthority` — True when `incoming` may overwrite a fact currently held at `existing`.
 - `orderTreeNodes`
 
 <!-- END GENERATED: readme-public-api -->