@company-semantics/contracts 101.1.0 → 102.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "101.1.0",
+  "version": "102.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/__tests__/leader-access.test.ts

@@ -0,0 +1,51 @@
+/**
+ * ACL leader access (AclListResponse.leader_access)
+ *
+ * INVARIANTS TESTED:
+ * - LEADER_ACCESS_BASES is exactly ancestor_lead, ancestor_delegate, account_owner
+ * - leader_access is REQUIRED on every ACL list response (no default)
+ * - leader_access names each person at most once
+ */
+import { describe, expect, it } from "vitest";
+import {
+  AclListResponseSchema,
+  LEADER_ACCESS_BASES,
+} from "../permissions/index";
+
+const base = {
+  entity_type: "company_md",
+  entity_id: "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
+  owner_user_ids: ["11111111-1111-4111-8111-111111111111"],
+  visibility: "private",
+  general_access_role: "viewer",
+  grants: [],
+};
+
+describe("ACL leader access", () => {
+  it("names exactly the three leader-access bases", () => {
+    expect([...LEADER_ACCESS_BASES]).toEqual([
+      "ancestor_lead",
+      "ancestor_delegate",
+      "account_owner",
+    ]);
+  });
+
+  it("requires leader_access on every ACL list response", () => {
+    expect(() => AclListResponseSchema.parse(base)).toThrow();
+    expect(
+      AclListResponseSchema.parse({ ...base, leader_access: [] }).leader_access,
+    ).toEqual([]);
+  });
+
+  it("refuses a duplicate person in leader_access", () => {
+    const row = {
+      user_id: "22222222-2222-4222-8222-222222222222",
+      basis: "ancestor_lead",
+      via_unit_id: "33333333-3333-4333-8333-333333333333",
+      via_unit_name: "Finance",
+    };
+    expect(() =>
+      AclListResponseSchema.parse({ ...base, leader_access: [row, row] }),
+    ).toThrow();
+  });
+});

package/src/action-items/README.md

@@ -67,14 +67,15 @@ absent from the next read. There is no clearing code to forget to write.
 
 ## Kinds
 
-| Kind                               | Derived from                                            | Resolved at                                  |
-| ---------------------------------- | ------------------------------------------------------- | -------------------------------------------- |
-| `companyMd.access_request_pending` | A pending access request on a company.md document       | The document's share dialog                  |
-| `execution.confirmation_pending`   | A chat execution in `pending_confirmation`              | Its confirm / reject routes                  |
-| `structure.owner_grant_pending`    | A lead → owner grant the bridge could not mint          | The unit's owners dialog                     |
-| `structure.finding_review_pending` | An open row of `structure_findings`                     | The finding sheet in Settings → Integrations |
-| `sourceSync.approval_pending`      | A draft candidate set whose scope approvals are pending | The Drive settings panel that reviews it     |
-| `sourceSync.proposal_pending`      | A validated synthesis batch with a document `proposed`  | The synthesis review                         |
+| Kind                                     | Derived from                                              | Resolved at                                  |
+| ---------------------------------------- | --------------------------------------------------------- | -------------------------------------------- |
+| `companyMd.access_request_pending`       | A pending access request on a company.md document         | The document's share dialog                  |
+| `execution.confirmation_pending`         | A chat execution in `pending_confirmation`                | Its confirm / reject routes                  |
+| `structure.owner_grant_pending`          | A lead → owner grant the bridge could not mint            | The unit's owners dialog                     |
+| `structure.finding_review_pending`       | An open row of `structure_findings`                       | The finding sheet in Settings → Integrations |
+| `sourceSync.approval_pending`            | A draft candidate set whose scope approvals are pending   | The Drive settings panel that reviews it     |
+| `sourceSync.proposal_pending`            | A validated synthesis batch with a document `proposed`    | The synthesis review                         |
+| `sourceSync.approver_assignment_pending` | A Source Sync scope with waiting work and nobody assigned | The unit's settings page (owners dialog)     |
 
 ## Public API
 

package/src/action-items/__tests__/approver-needed-kind.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Approver-needed vocabulary
+ *
+ * INVARIANTS TESTED:
+ * - sourceSync.approver_assignment_pending is appended LAST to ACTION_ITEM_KINDS
+ * - an approver-needed item anchored on a unit parses as an ActionItem
+ * - scope_assignee is appended LAST to PROACTIVE_RECIPIENT_REASONS
+ */
+import { describe, expect, it } from "vitest";
+import { ACTION_ITEM_KINDS } from "../kinds.js";
+import { ActionItemSchema } from "../schemas.js";
+import { PROACTIVE_RECIPIENT_REASONS } from "../../proactive/kinds.js";
+
+describe("approver-needed vocabulary", () => {
+  it("appends sourceSync.approver_assignment_pending as the last action item kind", () => {
+    expect(ACTION_ITEM_KINDS[ACTION_ITEM_KINDS.length - 1]).toBe(
+      "sourceSync.approver_assignment_pending",
+    );
+  });
+
+  it("parses an approver-needed item anchored on a unit", () => {
+    const item = ActionItemSchema.parse({
+      id: "sourceSync.approver_assignment_pending:unit:7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
+      kind: "sourceSync.approver_assignment_pending",
+      target: { type: "org_unit", id: "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" },
+      unitPath: "root.sales",
+      title: "Sales needs an approver",
+      detail: "3 files are waiting. Assign a lead or add a delegate.",
+      contextLabel: "Sales",
+      provider: "google_drive",
+      href: "/@acme/team/sales/settings",
+      createdAt: "2026-10-12T00:00:00.000Z",
+    });
+    expect(item.kind).toBe("sourceSync.approver_assignment_pending");
+  });
+
+  it("appends scope_assignee as the last proactive recipient reason", () => {
+    expect(
+      PROACTIVE_RECIPIENT_REASONS[PROACTIVE_RECIPIENT_REASONS.length - 1],
+    ).toBe("scope_assignee");
+  });
+});

package/src/action-items/kinds.ts

@@ -115,6 +115,19 @@
  * `sourceSync.review_ready` proactive kind: that kind announces the review
  * ONCE; this item stays until the review is done. The backend provider is
  * PRD-01029's.
+ *
+ * `sourceSync.approver_assignment_pending` passes them too. A Source Sync scope with work
+ * waiting (an open scope of a draft candidate set, a proposed scope of a
+ * validated synthesis batch, or a suspended standing order) whose assignment is
+ * `unassigned` is waiting on somebody to make a responsible person exist: assign
+ * the unit a lead or add a delegate. That is administration, not approval, so it
+ * is owed by the people who manage the org (an org admin or an account owner),
+ * who gain NO access to the work by resolving it. A provider can derive it from
+ * the same rows the two other Source Sync kinds read plus the live assignment; the
+ * `href` is the unit's own settings page, where the owners dialog assigns a lead
+ * or adds a delegate, and a scope that becomes assigned (or whose work is done) is
+ * absent from the next read. The item names the unit and a count only: never a
+ * document title, a file name or a source.
  */
 export const ACTION_ITEM_KINDS = [
   "companyMd.access_request_pending",
@@ -123,6 +136,7 @@ export const ACTION_ITEM_KINDS = [
   "structure.finding_review_pending",
   "sourceSync.approval_pending",
   "sourceSync.proposal_pending",
+  "sourceSync.approver_assignment_pending",
 ] as const;
 
 export type ActionItemKind = (typeof ACTION_ITEM_KINDS)[number];

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 = '2a364932e5ca' as const;
-export const SPEC_HASH_FULL = '2a364932e5ca5fb988423a06d4c58a57c255317be05c842237ce045260d2dd93' as const;
+export const SPEC_HASH = '1edc559559e5' as const;
+export const SPEC_HASH_FULL = '1edc559559e5cd64ba5b3d4d3c7a61822aa00f0d63ae30d297c970f3cdf5103e' as const;

package/src/api/generated.ts

@@ -5280,7 +5280,7 @@ export interface paths {
         };
         /**
          * List the org’s source sync standing orders
-         * @description Every standing order — active, suspended with the reason it stopped acting, and revoked — with the grantor’s display name when the grantor is still a member.
+         * @description Every standing order — active, suspended with the reason it stopped acting, and revoked — with the grantor’s display name when the grantor is still a member — and the caller’s grantability (SourceSyncStandingOrderGrantability) for the company scope and each active or suspended order’s scope, at most 10: whether the caller could grant that scope’s order and, when not, why (needs_approval_authority before needs_doc_access). A scope not listed is undecided; the grant decides.
          */
         get: operations["listSourceSyncStandingOrders"];
         put?: never;
@@ -9023,7 +9023,7 @@ export interface components {
             items: {
                 id: string;
                 /** @enum {string} */
-                kind: "companyMd.access_request_pending" | "execution.confirmation_pending" | "structure.owner_grant_pending" | "structure.finding_review_pending" | "sourceSync.approval_pending" | "sourceSync.proposal_pending";
+                kind: "companyMd.access_request_pending" | "execution.confirmation_pending" | "structure.owner_grant_pending" | "structure.finding_review_pending" | "sourceSync.approval_pending" | "sourceSync.proposal_pending" | "sourceSync.approver_assignment_pending";
                 target: {
                     /** @enum {string} */
                     type: "company_md" | "org_unit" | "org" | "execution";
@@ -9157,7 +9157,7 @@ export interface components {
                 item: {
                     id: string;
                     /** @enum {string} */
-                    kind: "companyMd.access_request_pending" | "execution.confirmation_pending" | "structure.owner_grant_pending" | "structure.finding_review_pending" | "sourceSync.approval_pending" | "sourceSync.proposal_pending";
+                    kind: "companyMd.access_request_pending" | "execution.confirmation_pending" | "structure.owner_grant_pending" | "structure.finding_review_pending" | "sourceSync.approval_pending" | "sourceSync.proposal_pending" | "sourceSync.approver_assignment_pending";
                     target: {
                         /** @enum {string} */
                         type: "company_md" | "org_unit" | "org" | "execution";
@@ -10840,13 +10840,21 @@ export interface components {
                 scopeKey: string;
                 /** @enum {string} */
                 state: "pending" | "approved" | "rejected";
-                /** @enum {string} */
-                requiredApproverKind: "org_admin" | "unit_head";
-                assignedTo: {
-                    label: string;
-                    isCaller: boolean;
-                } | null;
-                vacantHead: boolean;
+                assignment: {
+                    /** @constant */
+                    status: "assigned";
+                    assignees: {
+                        label: string;
+                        isCaller: boolean;
+                        /** @enum {string} */
+                        basis: "lead" | "delegate";
+                    }[];
+                } | {
+                    /** @constant */
+                    status: "unassigned";
+                    /** @enum {string} */
+                    reason: "no_responsible_person" | "no_eligible_approver";
+                };
                 approvedBy: {
                     label: string;
                 } | null;
@@ -10906,13 +10914,21 @@ export interface components {
                 scopeKey: string;
                 /** @enum {string} */
                 state: "pending" | "approved" | "rejected";
-                /** @enum {string} */
-                requiredApproverKind: "org_admin" | "unit_head";
-                assignedTo: {
-                    label: string;
-                    isCaller: boolean;
-                } | null;
-                vacantHead: boolean;
+                assignment: {
+                    /** @constant */
+                    status: "assigned";
+                    assignees: {
+                        label: string;
+                        isCaller: boolean;
+                        /** @enum {string} */
+                        basis: "lead" | "delegate";
+                    }[];
+                } | {
+                    /** @constant */
+                    status: "unassigned";
+                    /** @enum {string} */
+                    reason: "no_responsible_person" | "no_eligible_approver";
+                };
                 approvedBy: {
                     label: string;
                 } | null;
@@ -11035,13 +11051,21 @@ export interface components {
                 scopeKey: string;
                 /** @enum {string} */
                 state: "pending" | "approved" | "rejected";
-                /** @enum {string} */
-                requiredApproverKind: "org_admin" | "unit_head";
-                assignedTo: {
-                    label: string;
-                    isCaller: boolean;
-                } | null;
-                vacantHead: boolean;
+                assignment: {
+                    /** @constant */
+                    status: "assigned";
+                    assignees: {
+                        label: string;
+                        isCaller: boolean;
+                        /** @enum {string} */
+                        basis: "lead" | "delegate";
+                    }[];
+                } | {
+                    /** @constant */
+                    status: "unassigned";
+                    /** @enum {string} */
+                    reason: "no_responsible_person" | "no_eligible_approver";
+                };
                 approvedBy: {
                     label: string;
                 } | null;
@@ -11096,13 +11120,21 @@ export interface components {
                 scopeKey: string;
                 /** @enum {string} */
                 state: "pending" | "approved" | "rejected";
-                /** @enum {string} */
-                requiredApproverKind: "org_admin" | "unit_head";
-                assignedTo: {
-                    label: string;
-                    isCaller: boolean;
-                } | null;
-                vacantHead: boolean;
+                assignment: {
+                    /** @constant */
+                    status: "assigned";
+                    assignees: {
+                        label: string;
+                        isCaller: boolean;
+                        /** @enum {string} */
+                        basis: "lead" | "delegate";
+                    }[];
+                } | {
+                    /** @constant */
+                    status: "unassigned";
+                    /** @enum {string} */
+                    reason: "no_responsible_person" | "no_eligible_approver";
+                };
                 approvedBy: {
                     label: string;
                 } | null;
@@ -21863,7 +21895,7 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description The caller does not hold the authority the order would exercise */
+            /** @description The caller does not hold the authority the order would exercise, or cannot act on the scope’s document (SOURCE_SYNC_SCOPE_DOC_ACCESS_DENIED) */
             403: {
                 headers: {
                     [name: string]: unknown;

package/src/permissions/share-api.ts

@@ -82,6 +82,32 @@ export const AclGrantResponseSchema = z.object({
 });
 export type AclGrantResponse = z.infer<typeof AclGrantResponseSchema>;
 
+/**
+ * Why a person who is NOT an owner and holds no grant on this document can
+ * still reach it. Structural, never a grant row: inherited unit authority
+ * (an ancestor unit's lead or delegate holds the `unit_editor` band on every
+ * descendant document) and account ownership. Document sharing CANNOT remove
+ * these: there are no deny rows, so a "private" company.md document is still
+ * readable and editable by them. The share dialog lists them so it never implies
+ * otherwise.
+ */
+export const LEADER_ACCESS_BASES = [
+  "ancestor_lead",
+  "ancestor_delegate",
+  "account_owner",
+] as const;
+export type LeaderAccessBasis = (typeof LEADER_ACCESS_BASES)[number];
+
+export const LeaderAccessSchema = z.object({
+  user_id: z.string().uuid(),
+  basis: z.enum(LEADER_ACCESS_BASES),
+  /** The ancestor unit the authority comes from; null for `account_owner`. */
+  via_unit_id: z.string().uuid().nullable(),
+  /** That unit's name, for "Leads Finance"; null for `account_owner`. */
+  via_unit_name: z.string().min(1).nullable(),
+});
+export type LeaderAccess = z.infer<typeof LeaderAccessSchema>;
+
 export const AclListResponseSchema = z.object({
   entity_type: z.string(),
   entity_id: z.string().uuid(),
@@ -98,6 +124,19 @@ export const AclListResponseSchema = z.object({
   owner_user_ids: z
     .array(z.string().uuid())
     .refine(uniqueValues, { message: "duplicate id in owner_user_ids" }),
+  /**
+   * Everyone who reaches this entity through structure rather than ownership or a
+   * grant, one entry per person, never someone already in `owner_user_ids`.
+   * company_md only; every other entity type sends `[]`.
+   */
+  leader_access: z
+    .array(LeaderAccessSchema)
+    .refine(
+      (rows) => new Set(rows.map((r) => r.user_id)).size === rows.length,
+      {
+        message: "duplicate user_id in leader_access",
+      },
+    ),
   /**
    * General-access scope: WHO may read. NOT discoverability — see
    * `discoverability`.

package/src/proactive/kinds.ts

@@ -373,6 +373,13 @@ export const PROACTIVE_RECIPIENT_REASONS = [
   "subject",
   /** Addressed because they took part in the thing that happened. */
   "participant",
+  /**
+   * Addressed because a Source Sync scope's approval is ASSIGNED to them: a
+   * local lead or active delegate of the scope's unit (the root unit for the
+   * company scope). Assignment, not authority: an account owner or an inherited
+   * leader who may also approve is not addressed for it.
+   */
+  "scope_assignee",
 ] as const;
 export type ProactiveRecipientReason =
   (typeof PROACTIVE_RECIPIENT_REASONS)[number];

package/src/source-sync/README.md

@@ -50,8 +50,16 @@ way. This directory holds that shared spelling.
 - **A caller sees only their scopes' states.** Every checkpoint response (the
   candidate set, approve, the synthesis, apply) carries `scopes`: one
   `SourceSyncScopeApprovalProjection` per scope the caller may see, naming
-  people by label only, and nothing about any other scope. `vacantHead` says a
-  unit has no head (still `unit_head`, no assignee: admins approve it).
+  people by label only, and nothing about any other scope.
+- **A scope is assigned, not routed.** `assignment` is either `assigned` to the
+  scope unit's local leads and active delegates who can act on the document
+  (the root unit for the company scope), or `unassigned` with a typed reason
+  (`no_responsible_person`, `no_eligible_approver`). Nobody is assigned by
+  virtue of an org role: a vacancy is a coordination task, never a reason to
+  widen who decides. Assignment is not eligibility: the caller's own
+  `approvable` / `blockedReason` say whether they may approve. A pending scope
+  reports its assignment as of now; an approved one the assignment its
+  approval recorded.
 - **A withheld source says so.** A candidate item, a change's source and a
   decision evidence row carry a required `withheld`; a withheld source is named
   by its class and has no link or owner. A client reads the flag, never the copy.
@@ -279,8 +287,11 @@ in `attention-evidence.ts`.
   to a proposed document change.
 - `SOURCE_SYNC_SCOPE_APPROVAL_STATES` / `SourceSyncScopeApprovalState` —
   `pending`, `approved` or `rejected` (no verb writes `rejected` yet).
-- `SOURCE_SYNC_SCOPE_APPROVER_KINDS` / `SourceSyncScopeApproverKind` —
-  `org_admin` or `unit_head`.
+- `SOURCE_SYNC_SCOPE_ASSIGNEE_BASES` / `SourceSyncScopeAssigneeBasis` — why a
+  person is assigned a scope: `lead` (a local lead of the scope's unit) or
+  `delegate` (an active delegate of it).
+- `SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS` / `SourceSyncScopeUnassignedReason` —
+  why nobody is assigned: `no_responsible_person` or `no_eligible_approver`.
 - `SOURCE_SYNC_SCOPE_BLOCKED_REASONS` / `SourceSyncScopeBlockedReason` — why
   the caller may not approve a scope or grant its standing order:
   `needs_approval_authority` (checked first) or `needs_doc_access`.
@@ -339,8 +350,13 @@ in `attention-evidence.ts`.
 - `SourceSyncScopeApprovalSchema` / `SourceSyncScopeApproval` — one approval
   row: one scope bound to its own `candidateSetHash`.
 - `SourceSyncScopeApprovalProjectionSchema` / `SourceSyncScopeApprovalProjection`
-  — one scope's approval as the caller may see it: state, approver kind,
-  assignee (`isCaller`), `vacantHead`, approver and time.
+  — one scope's approval as the caller may see it: state, `assignment`,
+  approver and time, and whether the caller may approve it.
+- `SourceSyncScopeAssigneeSchema` / `SourceSyncScopeAssignee` — one assignee:
+  label, `isCaller` and `basis`.
+- `SourceSyncScopeAssignmentSchema` / `SourceSyncScopeAssignment` — whom a
+  scope is assigned to: `assigned` (1..50 assignees) or `unassigned` with a
+  reason, discriminated on `status`.
 - `SourceSyncApproveResponseSchema` / `SourceSyncApproveResponse` — the
   approval as recorded, one row per scope approved in the call, every visible
   scope's state, and the synthesis workflow started.

package/src/source-sync/__tests__/scope-assignment.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Source Sync scope assignment wire tests.
+ *
+ * INVARIANTS TESTED:
+ * - Assignees are named by basis `lead` or `delegate` only; there is no admin basis
+ * - An unassigned scope carries a typed reason, never an admin fallback
+ * - An assigned scope names at least one assignee
+ * - The retired routing fields (requiredApproverKind, vacantHead) are not part of
+ *   the projection
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  SOURCE_SYNC_SCOPE_ASSIGNEE_BASES,
+  SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS,
+  SourceSyncScopeApprovalProjectionSchema,
+  SourceSyncScopeAssignmentSchema,
+} from "../index";
+
+const pending = (assignment: unknown) => ({
+  scopeKey: "unit:7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
+  state: "pending",
+  assignment,
+  approvedBy: null,
+  approvedAt: null,
+  approvable: true,
+  blockedReason: null,
+});
+
+describe("scope assignment wire", () => {
+  it("names exactly the assignee bases lead and delegate", () => {
+    expect([...SOURCE_SYNC_SCOPE_ASSIGNEE_BASES]).toEqual(["lead", "delegate"]);
+  });
+
+  it("names exactly the unassigned reasons", () => {
+    expect([...SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS]).toEqual([
+      "no_responsible_person",
+      "no_eligible_approver",
+    ]);
+  });
+
+  it("accepts an assigned scope with a lead and a delegate", () => {
+    const parsed = SourceSyncScopeApprovalProjectionSchema.parse(
+      pending({
+        status: "assigned",
+        assignees: [
+          { label: "Maya Chen", isCaller: false, basis: "lead" },
+          { label: "Sam Lee", isCaller: true, basis: "delegate" },
+        ],
+      }),
+    );
+    expect(parsed.assignment.status).toBe("assigned");
+  });
+
+  it("refuses an assigned scope with no assignees", () => {
+    expect(() =>
+      SourceSyncScopeAssignmentSchema.parse({
+        status: "assigned",
+        assignees: [],
+      }),
+    ).toThrow();
+  });
+
+  it("accepts an unassigned scope with a typed reason and refuses an untyped one", () => {
+    expect(
+      SourceSyncScopeAssignmentSchema.parse({
+        status: "unassigned",
+        reason: "no_responsible_person",
+      }).status,
+    ).toBe("unassigned");
+    expect(() =>
+      SourceSyncScopeAssignmentSchema.parse({
+        status: "unassigned",
+        reason: "org_admins",
+      }),
+    ).toThrow();
+  });
+
+  it("refuses the retired routing fields", () => {
+    const legacy = {
+      ...pending({ status: "unassigned", reason: "no_responsible_person" }),
+      requiredApproverKind: "org_admin",
+      vacantHead: true,
+    };
+    const strict = SourceSyncScopeApprovalProjectionSchema.strict();
+    expect(() => strict.parse(legacy)).toThrow();
+    const declared = Object.keys(SourceSyncScopeApprovalProjectionSchema.shape);
+    for (const retired of [
+      "requiredApproverKind",
+      "assignedTo",
+      "vacantHead",
+    ]) {
+      expect(declared).not.toContain(retired);
+    }
+  });
+});

package/src/source-sync/__tests__/scope-projection.test.ts

@@ -2,9 +2,11 @@
  * Source Sync per-scope approval projection and withheld-source marker tests.
  *
  * INVARIANTS TESTED:
- * - A scope projection names people by LABEL only; its states and approver kinds
- *   are the closed stored vocabularies
- * - A vacant unit scope is a `unit_head` scope with no assignee and `vacantHead: true`
+ * - A scope projection names people by LABEL only; its states, assignee bases and
+ *   unassigned reasons are closed vocabularies
+ * - A scope with no local lead or active delegate is `unassigned` with a typed
+ *   reason; nothing on the wire names an admin to fall back to
+ * - `assignment` is REQUIRED on every projection
  * - Every read and write response of the checkpoint carries `scopes` (required)
  * - `withheld` is REQUIRED on a candidate item, a change's source and an evidence
  *   row: a producer that forgets it fails to parse, never defaults to shown
@@ -29,9 +31,10 @@ function scope(overrides: Record<string, unknown> = {}) {
   return {
     scopeKey: UNIT_SCOPE,
     state: "pending",
-    requiredApproverKind: "unit_head",
-    assignedTo: { label: "Maya Chen", isCaller: false },
-    vacantHead: false,
+    assignment: {
+      status: "assigned",
+      assignees: [{ label: "Maya Chen", isCaller: false, basis: "lead" }],
+    },
     approvedBy: null,
     approvedAt: null,
     approvable: true,
@@ -41,25 +44,42 @@ function scope(overrides: Record<string, unknown> = {}) {
 }
 
 describe("SourceSyncScopeApprovalProjectionSchema", () => {
-  it("accepts a pending unit scope routed to its head", () => {
+  it("accepts a pending unit scope assigned to its lead", () => {
     expect(
       SourceSyncScopeApprovalProjectionSchema.safeParse(scope()).success,
     ).toBe(true);
   });
 
-  it("accepts a vacant unit scope: unit_head, no assignee, vacantHead", () => {
+  it("accepts a unit scope with no lead or delegate: unassigned, no_responsible_person", () => {
     const parsed = SourceSyncScopeApprovalProjectionSchema.safeParse(
-      scope({ assignedTo: null, vacantHead: true }),
+      scope({
+        assignment: { status: "unassigned", reason: "no_responsible_person" },
+      }),
     );
     expect(parsed.success).toBe(true);
   });
 
-  it("accepts the company scope routed to the org's admins", () => {
+  it("accepts the company scope assigned to the root unit's leads and delegates", () => {
     const parsed = SourceSyncScopeApprovalProjectionSchema.safeParse(
       scope({
         scopeKey: "company",
-        requiredApproverKind: "org_admin",
-        assignedTo: null,
+        assignment: {
+          status: "assigned",
+          assignees: [
+            { label: "Maya Chen", isCaller: false, basis: "lead" },
+            { label: "Sam Lee", isCaller: true, basis: "delegate" },
+          ],
+        },
+      }),
+    );
+    expect(parsed.success).toBe(true);
+  });
+
+  it("accepts the company scope unassigned when no root lead can act on the document", () => {
+    const parsed = SourceSyncScopeApprovalProjectionSchema.safeParse(
+      scope({
+        scopeKey: "company",
+        assignment: { status: "unassigned", reason: "no_eligible_approver" },
       }),
     );
     expect(parsed.success).toBe(true);
@@ -76,7 +96,7 @@ describe("SourceSyncScopeApprovalProjectionSchema", () => {
     expect(parsed.success).toBe(true);
   });
 
-  it("refuses a state or approver kind outside the stored vocabulary", () => {
+  it("refuses a state, assignee basis or unassigned reason outside the vocabulary", () => {
     expect(
       SourceSyncScopeApprovalProjectionSchema.safeParse(
         scope({ state: "waiting" }),
@@ -84,20 +104,38 @@ describe("SourceSyncScopeApprovalProjectionSchema", () => {
     ).toBe(false);
     expect(
       SourceSyncScopeApprovalProjectionSchema.safeParse(
-        scope({ requiredApproverKind: "member" }),
+        scope({
+          assignment: {
+            status: "assigned",
+            assignees: [
+              { label: "Maya Chen", isCaller: false, basis: "admin" },
+            ],
+          },
+        }),
+      ).success,
+    ).toBe(false);
+    expect(
+      SourceSyncScopeApprovalProjectionSchema.safeParse(
+        scope({ assignment: { status: "unassigned", reason: "vacant_head" } }),
       ).success,
     ).toBe(false);
   });
 
-  it("refuses an empty label and a missing vacantHead", () => {
+  it("refuses an empty assignee label and a missing assignment", () => {
     expect(
       SourceSyncScopeApprovalProjectionSchema.safeParse(
-        scope({ assignedTo: { label: "", isCaller: true } }),
+        scope({
+          assignment: {
+            status: "assigned",
+            assignees: [{ label: "", isCaller: true, basis: "lead" }],
+          },
+        }),
       ).success,
     ).toBe(false);
-    const { vacantHead: _omit, ...withoutVacant } = scope();
+    const { assignment: _omit, ...withoutAssignment } = scope();
     expect(
-      SourceSyncScopeApprovalProjectionSchema.safeParse(withoutVacant).success,
+      SourceSyncScopeApprovalProjectionSchema.safeParse(withoutAssignment)
+        .success,
     ).toBe(false);
   });
 });

package/src/source-sync/__tests__/vocabulary.test.ts

@@ -6,7 +6,7 @@
  * order.
  *
  * INVARIANTS TESTED:
- * - Each of the twenty-five closed sets (eleven Source Sync, thirteen discovery
+ * - Each of the twenty-six closed sets (twelve Source Sync, thirteen discovery
  *   relevance, one attention evidence) has exactly the members this release
  *   fixes
  * - `decoy` is a source class; `unknown` is a sharing breadth
@@ -58,7 +58,8 @@ import {
   SOURCE_SYNC_DOC_RISKS,
   SOURCE_SYNC_EDIT_RISKS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
-  SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_ASSIGNEE_BASES,
+  SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS,
   SOURCE_USES,
 } from "../vocabulary";
 
@@ -136,9 +137,14 @@ const VOCABULARIES = [
     members: ["pending", "approved", "rejected"],
   },
   {
-    name: "SOURCE_SYNC_SCOPE_APPROVER_KINDS",
-    tuple: SOURCE_SYNC_SCOPE_APPROVER_KINDS,
-    members: ["org_admin", "unit_head"],
+    name: "SOURCE_SYNC_SCOPE_ASSIGNEE_BASES",
+    tuple: SOURCE_SYNC_SCOPE_ASSIGNEE_BASES,
+    members: ["lead", "delegate"],
+  },
+  {
+    name: "SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS",
+    tuple: SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS,
+    members: ["no_responsible_person", "no_eligible_approver"],
   },
   {
     name: "OPERATING_KNOWLEDGE_FAMILIES",

package/src/source-sync/index.ts

@@ -30,7 +30,8 @@ export type {
   SourceSyncDocRisk,
   SourceSyncDocDisposition,
   SourceSyncScopeApprovalState,
-  SourceSyncScopeApproverKind,
+  SourceSyncScopeAssigneeBasis,
+  SourceSyncScopeUnassignedReason,
   SourceSyncScopeBlockedReason,
   DocumentType,
   KnownDocumentType,
@@ -47,7 +48,8 @@ export {
   SOURCE_SYNC_DOC_RISKS,
   SOURCE_SYNC_DOC_DISPOSITIONS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
-  SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_ASSIGNEE_BASES,
+  SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS,
   SOURCE_SYNC_SCOPE_BLOCKED_REASONS,
   DOCUMENT_TYPES,
   OPERATING_KNOWLEDGE_FAMILIES,
@@ -139,6 +141,8 @@ export type {
   SourceSyncAddCandidateRequest,
   SourceSyncApproveRequest,
   SourceSyncScopeApproval,
+  SourceSyncScopeAssignee,
+  SourceSyncScopeAssignment,
   SourceSyncScopeApprovalProjection,
   SourceSyncApproveResponse,
   SourceSyncRiskReason,
@@ -159,6 +163,8 @@ export {
   SourceSyncAddCandidateRequestSchema,
   SourceSyncApproveRequestSchema,
   SourceSyncScopeApprovalSchema,
+  SourceSyncScopeAssigneeSchema,
+  SourceSyncScopeAssignmentSchema,
   SourceSyncScopeApprovalProjectionSchema,
   SourceSyncApproveResponseSchema,
   SourceSyncDocChangeSchema,

package/src/source-sync/schemas.ts

@@ -25,8 +25,9 @@ import {
   SOURCE_SYNC_DOC_DISPOSITIONS,
   SOURCE_SYNC_DOC_RISKS,
   SOURCE_SYNC_SCOPE_APPROVAL_STATES,
-  SOURCE_SYNC_SCOPE_APPROVER_KINDS,
+  SOURCE_SYNC_SCOPE_ASSIGNEE_BASES,
   SOURCE_SYNC_SCOPE_BLOCKED_REASONS,
+  SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS,
 } from "./vocabulary";
 import { CandidateDiscoverySummarySchema } from "./relevance";
 import { SourceSyncCandidateItemSchema } from "./candidate-item";
@@ -34,18 +35,45 @@ import { SourceSyncCandidateItemSchema } from "./candidate-item";
 /** A person as the review names them: a display label, never an id or an address. */
 const PersonLabel = z.string().min(1).max(255);
 
+/** One person a scope's approval is assigned to, by label only. */
+export const SourceSyncScopeAssigneeSchema = z.object({
+  label: PersonLabel,
+  /** True when this assignee is the caller. */
+  isCaller: z.boolean(),
+  basis: z.enum(SOURCE_SYNC_SCOPE_ASSIGNEE_BASES),
+});
+
+/**
+ * Whom a scope's approval is ASSIGNED to. Assignment is not eligibility: the
+ * caller's own `approvable` says whether THEY may approve; an account owner or an
+ * inherited leader may approve a scope assigned to someone else, or an
+ * unassigned one.
+ *
+ * - `assigned`: every eligible local lead and active delegate of the scope's unit
+ *   (the root unit for the company scope), at least one, in the server's order.
+ * - `unassigned`: nobody, with the typed reason. There is no admin fallback.
+ *
+ * A pending scope reports its assignment as derived NOW. An approved scope reports
+ * the assignment its approval RECORDED; a later lead change never rewrites it.
+ */
+export const SourceSyncScopeAssignmentSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("assigned"),
+    assignees: z.array(SourceSyncScopeAssigneeSchema).min(1).max(50),
+  }),
+  z.object({
+    status: z.literal("unassigned"),
+    reason: z.enum(SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS),
+  }),
+]);
+
 /**
  * ONE scope's approval as THE CALLER may see it. A response carries one per scope
  * the caller may see, and nothing about any other scope: not its key, not a count.
  *
- * - `requiredApproverKind` is who the scope needs: `org_admin` for the company
- *   scope, `unit_head` for a unit's.
- * - `assignedTo` is the ONE person the scope is routed to, or null when it is
- *   routed to the org's admins. Routing is not authority: any admin may approve.
- * - `vacantHead` is true exactly for a unit scope whose unit has no head. It is
- *   still a `unit_head` scope, `assignedTo` is null, and the org's admins approve it.
- * - An approved scope reports the routing its approval RECORDED; a later head
- *   change does not rewrite it. A pending scope reports its routing as of now.
+ * - `assignment` is whom the scope is assigned to (see
+ *   SourceSyncScopeAssignmentSchema): the scope unit's local leads and active
+ *   delegates, or nobody with a typed reason.
  * - `approvable` is whether THE CALLER may approve this pending scope now. A scope
  *   can be visible but not approvable: approving needs approval authority on the
  *   scope AND the caller's own upload and edit access on the scope's document,
@@ -61,15 +89,7 @@ export const SourceSyncScopeApprovalProjectionSchema = z.object({
   /** 'company' or 'unit:<uuid>'. */
   scopeKey: z.string().min(1).max(64),
   state: z.enum(SOURCE_SYNC_SCOPE_APPROVAL_STATES),
-  requiredApproverKind: z.enum(SOURCE_SYNC_SCOPE_APPROVER_KINDS),
-  assignedTo: z
-    .object({
-      label: PersonLabel,
-      /** True when the scope is routed to the caller. */
-      isCaller: z.boolean(),
-    })
-    .nullable(),
-  vacantHead: z.boolean(),
+  assignment: SourceSyncScopeAssignmentSchema,
   /** Non-null exactly when a person's approval is recorded. */
   approvedBy: z.object({ label: PersonLabel }).nullable(),
   approvedAt: IsoDateTime.nullable(),
@@ -343,6 +363,12 @@ export type SourceSyncApproveRequest = z.infer<
 export type SourceSyncScopeApproval = z.infer<
   typeof SourceSyncScopeApprovalSchema
 >;
+export type SourceSyncScopeAssignee = z.infer<
+  typeof SourceSyncScopeAssigneeSchema
+>;
+export type SourceSyncScopeAssignment = z.infer<
+  typeof SourceSyncScopeAssignmentSchema
+>;
 export type SourceSyncScopeApprovalProjection = z.infer<
   typeof SourceSyncScopeApprovalProjectionSchema
 >;

package/src/source-sync/vocabulary.ts

@@ -101,15 +101,40 @@ export type SourceSyncScopeApprovalState =
   (typeof SOURCE_SYNC_SCOPE_APPROVAL_STATES)[number];
 
 /**
- * Who must approve a scope: the org's admins (the company scope) or the unit's
- * head (a unit scope). Mirrors the `required_approver_kind` CHECK.
+ * Why a person is ASSIGNED a scope's approval. Assignment is not authority: it
+ * names the people asked to decide, nothing more (control principle: authority to
+ * act is not assigned work).
+ *
+ * - `lead`: a LOCAL structural lead of the scope's unit. The company scope's unit
+ *   is the org's root unit, so its leads are the root unit's local leads.
+ * - `delegate`: an ACTIVE (unexpired, unrevoked) delegate of that unit.
+ *
+ * Only local holders are ever assigned. A leader who holds authority over the
+ * unit by inheritance (an ancestor unit's lead) and an account owner may approve
+ * but are never assigned, so inherited authority never fans work out to every
+ * descendant team. Org admins are never assigned.
+ */
+export const SOURCE_SYNC_SCOPE_ASSIGNEE_BASES = ["lead", "delegate"] as const;
+export type SourceSyncScopeAssigneeBasis =
+  (typeof SOURCE_SYNC_SCOPE_ASSIGNEE_BASES)[number];
+
+/**
+ * Why a scope has NOBODY assigned. Never a reason to fall back to the org's
+ * admins or the account owner: a vacancy grants no one anything, and an org
+ * admin resolves it by assigning a lead or a delegate (the backend's
+ * `sourceSync.approver_assignment_pending` action item).
+ *
+ * - `no_responsible_person`: the scope's unit has no local lead and no active
+ *   delegate, or the unit no longer exists.
+ * - `no_eligible_approver`: it has local leads or delegates, but none of them can
+ *   upload to and edit the scope's document (`needs_doc_access` for each).
  */
-export const SOURCE_SYNC_SCOPE_APPROVER_KINDS = [
-  "org_admin",
-  "unit_head",
+export const SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS = [
+  "no_responsible_person",
+  "no_eligible_approver",
 ] as const;
-export type SourceSyncScopeApproverKind =
-  (typeof SOURCE_SYNC_SCOPE_APPROVER_KINDS)[number];
+export type SourceSyncScopeUnassignedReason =
+  (typeof SOURCE_SYNC_SCOPE_UNASSIGNED_REASONS)[number];
 
 /**
  * Why the CALLER may not approve a scope they can see, or grant its standing