@company-semantics/contracts 56.0.0 → 57.0.0

package/package.json

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

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 = '6eb28e0d82f9' as const;
-export const SPEC_HASH_FULL = '6eb28e0d82f9d1d88e4fc954ece5377c85ddd6da30b6171c4d2aa75f347c09ed' as const;
+export const SPEC_HASH = 'ffeb6e367b38' as const;
+export const SPEC_HASH_FULL = 'ffeb6e367b385ad32f7b46e4e74d276786d6cdf175352e57d0fc229dc8f506af' as const;

package/src/api/generated.ts

@@ -926,6 +926,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/workspace/invites/batch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Invite many directory people at once */
+        post: operations["batchInvite"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/workspace/invites/{id}/reissue": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reissue an invite whose email was never delivered */
+        post: operations["reissueInvite"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/workspace/invites/accept": {
         parameters: {
             query?: never;
@@ -960,6 +994,92 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/workspace/invite-batches": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Draft a reviewable invite batch */
+        post: operations["createInviteBatch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/workspace/invite-batches/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Review an invite batch */
+        get: operations["getInviteBatch"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /** Change an invite batch selection or role */
+        patch: operations["updateInviteBatch"];
+        trace?: never;
+    };
+    "/api/workspace/invite-batches/{id}/prepare": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Evaluate eligibility and make a batch reviewable */
+        post: operations["prepareInviteBatch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/workspace/invite-batches/{id}/send": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Send a reviewed invite batch */
+        post: operations["sendInviteBatch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/workspace/invite-batches/{id}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Cancel the unsent remainder of an invite batch */
+        post: operations["cancelInviteBatch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/workspace/invites/validate": {
         parameters: {
             query?: never;
@@ -977,6 +1097,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/workspace/directory": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the org people directory */
+        get: operations["listOrgDirectory"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/workspace/domains": {
         parameters: {
             query?: never;
@@ -4577,6 +4714,32 @@ export interface components {
                 contributesTo: string[];
             };
         };
+        BatchInviteResponse: {
+            invited: string[];
+            skipped: {
+                /** Format: uuid */
+                personId: string;
+                /** @enum {string} */
+                reason: "already-member" | "invite-pending" | "no-email" | "send-failed";
+            }[];
+            failed: {
+                /** Format: uuid */
+                personId: string;
+                /** @enum {string} */
+                reason: "already-member" | "invite-pending" | "no-email" | "send-failed";
+            }[];
+        };
+        BatchInviteRequest: {
+            personIds: string[];
+            /** @enum {string} */
+            role: "admin" | "member";
+        };
+        ReissueInviteResponse: {
+            /** Format: uuid */
+            inviteId: string;
+            /** Format: uuid */
+            previousInviteId: string;
+        };
         InviteListResponse: {
             id: string;
             orgId: string;
@@ -4620,11 +4783,72 @@ export interface components {
         AcceptInviteRequest: {
             token: string;
         };
+        InviteBatchResponse: {
+            batch: {
+                /** Format: uuid */
+                id: string;
+                /** @enum {string} */
+                status: "draft" | "ready" | "sending" | "completed" | "cancelled";
+                source: string;
+                revision: number;
+                counts: {
+                    candidate: number;
+                    eligible: number;
+                    excluded: number;
+                    sent: number;
+                    failed: number;
+                    skipped: number;
+                };
+                /** Format: uuid */
+                createdByUserId: string;
+                confirmedByUserId: string | null;
+                confirmedAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+            };
+            items: {
+                /** Format: uuid */
+                personId: string;
+                displayName: string | null;
+                emailSnapshot: string | null;
+                /** @enum {string} */
+                role: "admin" | "member";
+                /** @enum {string} */
+                status: "eligible" | "excluded" | "sent" | "failed" | "skipped";
+                reason: ("already-member" | "invite-pending" | "no-email" | "invalid-email" | "removed-by-reviewer" | "address-changed" | "person-removed" | "send-failed" | "inactive-in-hris") | null;
+                inviteId: string | null;
+                emailOutsideVerifiedDomain: boolean;
+            }[];
+            verifiedDomains: string[];
+        };
+        CreateInviteBatchRequest: {
+            personIds: string[];
+            /** @enum {string} */
+            role: "admin" | "member";
+        };
+        UpdateInviteBatchRequest: {
+            deselectPersonIds?: string[];
+            reselectPersonIds?: string[];
+            /** @enum {string} */
+            role?: "admin" | "member";
+        };
+        SendInviteBatchRequest: {
+            expectedRevision: number;
+        };
         InviteValidationResult: {
             valid: boolean;
             status: string;
             orgName?: string;
         };
+        OrgDirectoryResponse: {
+            people: {
+                /** Format: uuid */
+                personId: string;
+                displayName: string;
+                primaryEmail: string | null;
+                userId: string | null;
+            }[];
+        };
         DomainListResponse: {
             id: string;
             orgId: string;
@@ -8230,6 +8454,52 @@ export interface operations {
             };
         };
     };
+    batchInvite: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BatchInviteRequest"];
+            };
+        };
+        responses: {
+            /** @description Per-person outcome; partial success is a normal result */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BatchInviteResponse"];
+                };
+            };
+        };
+    };
+    reissueInvite: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Prior invite revoked and a replacement sent */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReissueInviteResponse"];
+                };
+            };
+        };
+    };
     acceptInvite: {
         parameters: {
             query?: never;
@@ -8274,6 +8544,148 @@ export interface operations {
             };
         };
     };
+    createInviteBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateInviteBatchRequest"];
+            };
+        };
+        responses: {
+            /** @description Draft created; nothing has been sent */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InviteBatchResponse"];
+                };
+            };
+        };
+    };
+    getInviteBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Recipients, exclusions with reasons, and the org verified domains */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InviteBatchResponse"];
+                };
+            };
+        };
+    };
+    updateInviteBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateInviteBatchRequest"];
+            };
+        };
+        responses: {
+            /** @description Applied; revision bumped, invalidating any open review */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InviteBatchResponse"];
+                };
+            };
+        };
+    };
+    prepareInviteBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Eligibility evaluated; batch is ready to review */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InviteBatchResponse"];
+                };
+            };
+        };
+    };
+    sendInviteBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SendInviteBatchRequest"];
+            };
+        };
+        responses: {
+            /** @description Per-recipient outcome; partial success is a normal result */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InviteBatchResponse"];
+                };
+            };
+        };
+    };
+    cancelInviteBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Cancelled; invitations already sent are unaffected */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InviteBatchResponse"];
+                };
+            };
+        };
+    };
     validateInviteToken: {
         parameters: {
             query: {
@@ -8296,6 +8708,26 @@ export interface operations {
             };
         };
     };
+    listOrgDirectory: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Every person in the org directory */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgDirectoryResponse"];
+                };
+            };
+        };
+    };
     listDomains: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -185,14 +185,22 @@ export const openApiRoutes = {
   '/api/workspace/auth-policy/test-sso': ['POST'],
   '/api/workspace/auth-policy/test-sso/{attemptId}': ['GET'],
   '/api/workspace/auth-policy/validate-oidc': ['POST'],
+  '/api/workspace/directory': ['GET'],
   '/api/workspace/domains': ['GET', 'POST'],
   '/api/workspace/domains/{id}': ['DELETE'],
   '/api/workspace/domains/{id}/verify': ['POST'],
   '/api/workspace/handle': ['PATCH'],
+  '/api/workspace/invite-batches': ['POST'],
+  '/api/workspace/invite-batches/{id}': ['GET', 'PATCH'],
+  '/api/workspace/invite-batches/{id}/cancel': ['POST'],
+  '/api/workspace/invite-batches/{id}/prepare': ['POST'],
+  '/api/workspace/invite-batches/{id}/send': ['POST'],
   '/api/workspace/invites': ['GET', 'POST'],
   '/api/workspace/invites/accept': ['POST'],
+  '/api/workspace/invites/batch': ['POST'],
   '/api/workspace/invites/validate': ['GET'],
   '/api/workspace/invites/{id}': ['DELETE'],
+  '/api/workspace/invites/{id}/reissue': ['POST'],
   '/api/workspace/members': ['GET'],
   '/api/workspace/members/{id}': ['DELETE', 'GET'],
   '/api/workspace/members/{id}/role': ['PATCH'],

package/src/index.ts

@@ -620,6 +620,64 @@ export type {
   PositionReporting,
 } from "./org/index";
 
+// People directory: every `persons` row in the org, account-bearing or not.
+// Neither the member list (RBAC principals) nor the org chart (topology) — the
+// set an HRIS sync populates, and the only surface carrying a directory email.
+// Capability-gated, deliberately: the org-chart read is authenticated-only.
+export {
+  OrgDirectoryPersonSchema,
+  OrgDirectoryResponseSchema,
+} from "./org/index";
+export type { OrgDirectoryPerson, OrgDirectoryResponse } from "./org/index";
+
+// Bulk invite, keyed by personId so recipients are resolved server-side from the
+// caller's own directory rather than supplied by the caller.
+export {
+  BATCH_INVITE_PERSONS_MAX,
+  BATCH_INVITE_SKIP_REASONS,
+  BatchInviteSkipReasonSchema,
+  BatchInviteRequestSchema,
+  BatchInviteResponseSchema,
+} from "./org/index";
+export type {
+  BatchInviteSkipReason,
+  BatchInviteRequest,
+  BatchInviteResponse,
+} from "./org/index";
+
+// Invite batches: the persisted Prepare → Review → Send lifecycle that puts a
+// review boundary in front of bulk invite. The batch holds INTENT, never
+// credentials — there is no token field on a batch or an item, and there never
+// may be. Supersedes BatchInvite* above, which is removed in 58.0.0.
+export {
+  INVITE_BATCH_STATUSES,
+  INVITE_BATCH_ITEM_STATUSES,
+  INVITE_BATCH_ITEM_REASONS,
+  INVITE_BATCH_CHANGED,
+  InviteBatchStatusSchema,
+  InviteBatchItemStatusSchema,
+  InviteBatchItemReasonSchema,
+  InviteBatchItemSchema,
+  InviteBatchCountsSchema,
+  InviteBatchSchema,
+  InviteBatchResponseSchema,
+  CreateInviteBatchRequestSchema,
+  UpdateInviteBatchRequestSchema,
+  SendInviteBatchRequestSchema,
+} from "./org/index";
+export type {
+  InviteBatchStatus,
+  InviteBatchItemStatus,
+  InviteBatchItemReason,
+  InviteBatchItem,
+  InviteBatchCounts,
+  InviteBatch,
+  InviteBatchResponse,
+  CreateInviteBatchRequest,
+  UpdateInviteBatchRequest,
+  SendInviteBatchRequest,
+} from "./org/index";
+
 // Source authority: per-field ownership — who may WRITE a given entity field.
 // Orthogonal to provenance (who reported). (ADR-CONT-083 / ADR-CTRL-182)
 export { SourceAuthoritySchema } from "./org/index";

package/src/org/README.md

@@ -37,6 +37,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `AuthoritySource` _(type)_
 - `AuthoritySourceSchema` — Engine-internal authority source.
 - `AuthorizableView` _(type)_ — Type for views that can be checked against VIEWSCOPEMAP.
+- `BATCH_INVITE_PERSONS_MAX` — Cap on one batch.
+- `BATCH_INVITE_SKIP_REASONS` — Why one person in a batch did not receive an invite. - `already-member` — holds an account in this org…
+- `BatchInviteRequest` _(type)_
+- `BatchInviteRequestSchema`
+- `BatchInviteResponse` _(type)_
+- `BatchInviteResponseSchema`
+- `BatchInviteSkipReason` _(type)_
+- `BatchInviteSkipReasonSchema`
 - `COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES` — Cap on the MATERIALIZED document text, in UTF-8 bytes of the expanded result.
 - `COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS` — Cap on ONE presence position blob (`anchor` or `head`), in base64 chars.
 - `COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS` — Cap on ONE encoded update, measured on the base64 payload as it is sent.
@@ -101,6 +109,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `ConstraintViolationSchema` — One constraint the transformation engine evaluated and found violated.
 - `CreateDelegationRequest` _(type)_
 - `CreateDelegationRequestSchema`
+- `CreateInviteBatchRequest` _(type)_
+- `CreateInviteBatchRequestSchema`
 - `CreateInviteRequest` _(type)_ — Request payload for creating an organization invite.
 - `CreateInviteRequestPayload` _(type)_
 - `CreateInviteRequestSchema`
@@ -139,9 +149,27 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `HomeUnitRole` _(type)_
 - `HomeUnitRoleSchema` — Role the invitee takes in their home unit on acceptance.
 - `IDENTITY_TRUST_LEVEL_LABELS`
+- `INVITE_BATCH_CHANGED` — The error code a stale `send` (or a mutation of an already-claimed batch) returns, as `error` on the standard…
+- `INVITE_BATCH_ITEM_REASONS` — Why an item is not `sent`.
+- `INVITE_BATCH_ITEM_STATUSES` — Per-recipient outcome within a batch. - `eligible` — will be invited when the batch is sent. - `excluded` —…
+- `INVITE_BATCH_STATUSES` — Batch lifecycle. - `draft` — created, membership not yet evaluated.
 - `IdentityTrustLevel` _(type)_ — Identity Trust Level — org's identity posture
 - `IntegrationRequest` _(type)_ — Advisory integration request created by a member.
 - `IntegrationRequestStatus` _(type)_ — Status of an integration request from a member.
+- `InviteBatch` _(type)_
+- `InviteBatchCounts` _(type)_
+- `InviteBatchCountsSchema` — Denormalized counters, maintained by the batch's own writers in the same transaction as the items they…
+- `InviteBatchItem` _(type)_
+- `InviteBatchItemReason` _(type)_
+- `InviteBatchItemReasonSchema`
+- `InviteBatchItemSchema`
+- `InviteBatchItemStatus` _(type)_
+- `InviteBatchItemStatusSchema`
+- `InviteBatchResponse` _(type)_
+- `InviteBatchResponseSchema`
+- `InviteBatchSchema`
+- `InviteBatchStatus` _(type)_
+- `InviteBatchStatusSchema`
 - `InviteListResponse` _(type)_
 - `InviteListResponseSchema`
 - `InviteResponse` _(type)_
@@ -178,6 +206,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgBudgetConfigSchema`
 - `OrgDeletionStatus` _(type)_
 - `OrgDeletionStatusSchema`
+- `OrgDirectoryPerson` _(type)_
+- `OrgDirectoryPersonSchema`
+- `OrgDirectoryResponse` _(type)_
+- `OrgDirectoryResponseSchema`
 - `OrgDivergence` _(type)_
 - `OrgDivergenceResolution` _(type)_
 - `OrgDivergenceResolutionSchema` — What resolving a divergence means today.
@@ -299,6 +331,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `ScopeCheckResponseSchema`
 - `SelectionRationale` _(type)_
 - `SelectionRationaleSchema`
+- `SendInviteBatchRequest` _(type)_
+- `SendInviteBatchRequestSchema` — `expectedRevision` is REQUIRED and has no default.
 - `SetActiveOrgResponse` _(type)_
 - `SetActiveOrgResponseSchema`
 - `SetSeatManagerResponse` _(type)_
@@ -348,6 +382,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `UpdateAuthPolicyRequest` _(type)_ — Request payload for updating organization auth policy.
 - `UpdateDelegationRequest` _(type)_
 - `UpdateDelegationRequestSchema` — Change a delegation's expiry without revoking it: extend, shorten, or clear (set `expiresAt: null` to make it…
+- `UpdateInviteBatchRequest` _(type)_
+- `UpdateInviteBatchRequestSchema` — Change what a `draft` or `ready` batch will do.
 - `UpdateOpenRoleStatusRequest` _(type)_
 - `UpdateOpenRoleStatusRequestSchema` — Only the non-terminal client transitions are accepted; `fill` is its own endpoint and `open` is the seeded…
 - `UpdateOrgUnitRequest` _(type)_

package/src/org/index.ts

@@ -354,6 +354,29 @@ export {
   CreateInviteRequestSchema,
   InviteResponseSchema,
   InviteListResponseSchema,
+  // People directory + bulk invite (personId-keyed, capability-gated)
+  OrgDirectoryPersonSchema,
+  OrgDirectoryResponseSchema,
+  BATCH_INVITE_PERSONS_MAX,
+  BATCH_INVITE_SKIP_REASONS,
+  BatchInviteSkipReasonSchema,
+  BatchInviteRequestSchema,
+  BatchInviteResponseSchema,
+  // Invite batches — the persisted Prepare → Review → Send lifecycle
+  INVITE_BATCH_STATUSES,
+  INVITE_BATCH_ITEM_STATUSES,
+  INVITE_BATCH_ITEM_REASONS,
+  INVITE_BATCH_CHANGED,
+  InviteBatchStatusSchema,
+  InviteBatchItemStatusSchema,
+  InviteBatchItemReasonSchema,
+  InviteBatchItemSchema,
+  InviteBatchCountsSchema,
+  InviteBatchSchema,
+  InviteBatchResponseSchema,
+  CreateInviteBatchRequestSchema,
+  UpdateInviteBatchRequestSchema,
+  SendInviteBatchRequestSchema,
   DomainResponseSchema,
   DomainListResponseSchema,
   OrgBillingResponseSchema,
@@ -366,6 +389,21 @@ export type {
   CreateInviteRequestPayload,
   InviteResponse,
   InviteListResponse,
+  OrgDirectoryPerson,
+  OrgDirectoryResponse,
+  BatchInviteSkipReason,
+  BatchInviteRequest,
+  BatchInviteResponse,
+  InviteBatchStatus,
+  InviteBatchItemStatus,
+  InviteBatchItemReason,
+  InviteBatchItem,
+  InviteBatchCounts,
+  InviteBatch,
+  InviteBatchResponse,
+  CreateInviteBatchRequest,
+  UpdateInviteBatchRequest,
+  SendInviteBatchRequest,
   DomainResponse,
   DomainListResponse,
   OrgBillingResponse,

package/src/org/schemas.ts

@@ -781,6 +781,434 @@ export type CreateInviteRequestPayload = z.infer<
   typeof CreateInviteRequestSchema
 >;
 
+// ---------------------------------------------------------------------------
+// GET /api/workspace/directory
+//
+// The org's PEOPLE DIRECTORY — every `persons` row, account-bearing or not.
+// Distinct from the member list (`user_org_memberships`, RBAC principals) and
+// from the org chart (`positions` + occupancy, topology): this is the answer to
+// "who does this org know about", which after an HRIS sync is a much larger set
+// than either.
+//
+// It exists because inviting a synced person needs their address, and the org
+// chart cannot carry one: `GET /api/users/org-chart` is authenticated-only, so a
+// `primaryEmail` there would let any member enumerate the whole company's email
+// addresses. This surface is capability-gated instead.
+// ---------------------------------------------------------------------------
+
+export const OrgDirectoryPersonSchema = z.object({
+  personId: z.string().uuid(),
+  displayName: z.string(),
+  /**
+   * Nullable and NOT optional. A directory person with no address is a real,
+   * common state — an HRIS export with the email column unmapped produces a
+   * whole org of them — and it is the difference between "cannot be invited" and
+   * "not yet loaded". Callers must render the distinction rather than treat a
+   * missing address as absence of the person.
+   */
+  primaryEmail: z.string().nullable(),
+  /** The linked account, or null when this person has never signed up. */
+  userId: z.string().uuid().nullable(),
+});
+
+export type OrgDirectoryPerson = z.infer<typeof OrgDirectoryPersonSchema>;
+
+export const OrgDirectoryResponseSchema = z.object({
+  people: z.array(OrgDirectoryPersonSchema),
+});
+
+export type OrgDirectoryResponse = z.infer<typeof OrgDirectoryResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/invites/batch — DEPRECATED (removed in contracts 58.0.0)
+//
+// Superseded by the invite-batch lifecycle below. This route sends real email
+// the instant it is called: there is no moment at which a human sees the
+// addresses that are about to be written to, and no way to cancel. Everything it
+// does correctly — personId keying, per-person transactions, three honest result
+// buckets — is preserved by `POST /api/workspace/invite-batches/{id}/send`, with
+// a review boundary in front of it.
+//
+// Kept live for one major so consumers can migrate against a green cascade: a
+// single major that deleted these types while the app still imported them could
+// not land, because the release cascade gates on each consumer's full CI tier.
+// 57.0.0 adds the lifecycle; consumers move; 58.0.0 deletes everything below.
+//
+// Bulk invite, keyed by `personId` rather than by email. That is a security
+// property, not a convenience: the single-invite route takes a caller-supplied
+// address and can therefore reach any mailbox on the internet, which is why it
+// carries a strict per-minute limit. This route's recipients are resolved
+// server-side from the caller's own `persons` rows, so the reachable set is
+// bounded by the org's own directory and the arbitrary-recipient risk is gone.
+//
+// Consequence for callers: the client never needs to hold an email address to
+// send an invite, and an unknown or cross-org `personId` is silently omitted
+// from the response rather than reported — reporting it would make this a
+// membership oracle.
+// ---------------------------------------------------------------------------
+
+/**
+ * Cap on one batch. Bounds worst-case request latency, since the invite emails
+ * are sent before the response returns (the raw token exists only in memory and
+ * must not be parked in a queue).
+ */
+export const BATCH_INVITE_PERSONS_MAX = 100;
+
+/** @deprecated Use {@link CreateInviteBatchRequestSchema}. Removed in 58.0.0. */
+export const BatchInviteRequestSchema = z.object({
+  personIds: z.array(z.string().uuid()).min(1).max(BATCH_INVITE_PERSONS_MAX),
+  // Same restricted {admin, member} domain as a single invite.
+  role: z.enum(["admin", "member"]),
+});
+
+export type BatchInviteRequest = z.infer<typeof BatchInviteRequestSchema>;
+
+/**
+ * Why one person in a batch did not receive an invite.
+ *
+ * - `already-member`  — holds an account in this org already.
+ * - `invite-pending`  — an unexpired invite is already outstanding.
+ * - `no-email`        — the directory row carries no address to send to.
+ * - `send-failed`     — the invite row COMMITTED but the email did not leave.
+ *                       Recoverable by resending; never a reason to roll the
+ *                       invite back.
+ */
+export const BATCH_INVITE_SKIP_REASONS = [
+  "already-member",
+  "invite-pending",
+  "no-email",
+  "send-failed",
+] as const;
+
+/** @deprecated Use {@link InviteBatchItemReasonSchema}. Removed in 58.0.0. */
+export const BatchInviteSkipReasonSchema = z.enum(BATCH_INVITE_SKIP_REASONS);
+
+export type BatchInviteSkipReason = z.infer<typeof BatchInviteSkipReasonSchema>;
+
+const BatchInviteOutcomeSchema = z.object({
+  personId: z.string().uuid(),
+  reason: BatchInviteSkipReasonSchema,
+});
+
+/** @deprecated Use {@link InviteBatchResponseSchema}. Removed in 58.0.0. */
+export const BatchInviteResponseSchema = z.object({
+  /** Person ids that now hold a pending invite AND were emailed. */
+  invited: z.array(z.string().uuid()),
+  /** Never attempted — see {@link BatchInviteSkipReason}. */
+  skipped: z.array(BatchInviteOutcomeSchema),
+  /**
+   * Invite row exists, delivery did not. Separate from `skipped` because the
+   * remedy differs: a skip needs the underlying state to change, a failure needs
+   * a resend.
+   */
+  failed: z.array(BatchInviteOutcomeSchema),
+});
+
+export type BatchInviteResponse = z.infer<typeof BatchInviteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// Invite batches — the Prepare → Review → Send lifecycle
+//
+// POST   /api/workspace/invite-batches            create a draft
+// GET    /api/workspace/invite-batches/{id}       review it
+// PATCH  /api/workspace/invite-batches/{id}       change selection/role (bumps revision)
+// POST   /api/workspace/invite-batches/{id}/prepare  evaluate eligibility, draft → ready
+// POST   /api/workspace/invite-batches/{id}/send     send, gated on expectedRevision
+// POST   /api/workspace/invite-batches/{id}/cancel   cancel what has not been sent
+//
+// WHY A PERSISTED BATCH AT ALL. The one-shot bulk route (`POST
+// /api/workspace/invites/batch`, deprecated by this vocabulary) sends real email
+// the instant it is called — there is no moment at which a human can see the 88
+// addresses that are about to be written to. This lifecycle inserts exactly one:
+// `prepare` decides who is eligible, the review surface shows the recipients and
+// their addresses, and `send` acts on what was reviewed or refuses.
+//
+// THE BATCH HOLDS INTENT, NEVER CREDENTIALS. There is no token field on a batch
+// or an item, in any form, and there never may be. An invite token exists only
+// between generation and the send, in memory; only its SHA-256 is stored, on the
+// invite row. A batch that parked a live token at rest would undo that whole
+// property in exchange for nothing — the item carries `inviteId`, which is the
+// durable handle to the credential without being one.
+//
+// CONFIRMATION AUTHORIZES THE ADDRESSES SHOWN AT REVIEW TIME. `emailSnapshot` is
+// what the reviewer saw. At send, an item whose person now holds a different
+// address is `skipped` with `address-changed` — never mailed at the new one. The
+// same is true of someone who became a member, or gained an invite by another
+// route, between review and send. Approving a list is not approving whatever
+// that list becomes.
+// ---------------------------------------------------------------------------
+
+/**
+ * Batch lifecycle.
+ *
+ * - `draft`     — created, membership not yet evaluated. Sends nothing.
+ * - `ready`     — `prepare` ran; the item set and its exclusions are the review.
+ * - `sending`   — CLAIMED by a send. See {@link SendInviteBatchRequestSchema}.
+ * - `completed` — the send finished. Per-person outcomes live on the items.
+ * - `cancelled` — cancelled before or between sends; unsent items stay unsent.
+ *
+ * There is deliberately no `partially_completed`: it is `failedCount > 0` on a
+ * `completed` batch, and a second spelling of one fact is a second thing to keep
+ * true. There is deliberately no `expired` either — nothing sweeps batches, and
+ * a status no writer ever writes is a promise the API does not keep.
+ */
+export const INVITE_BATCH_STATUSES = [
+  "draft",
+  "ready",
+  "sending",
+  "completed",
+  "cancelled",
+] as const;
+
+export const InviteBatchStatusSchema = z.enum(INVITE_BATCH_STATUSES);
+
+export type InviteBatchStatus = z.infer<typeof InviteBatchStatusSchema>;
+
+/**
+ * Per-recipient outcome within a batch.
+ *
+ * - `eligible` — will be invited when the batch is sent.
+ * - `excluded` — will not, decided at PREPARE time. See {@link InviteBatchItemReason}.
+ * - `sent`     — an invite row exists AND the email left. Carries `inviteId`.
+ * - `failed`   — an invite row exists, the email did NOT leave. Also carries
+ *                `inviteId`: the remedy is a reissue, never a re-send, because
+ *                the credential in that row was already minted.
+ * - `skipped`  — eligible at review, refused at SEND because the world moved.
+ *
+ * `eligible` items on a batch stuck in `sending` are exactly the ones a crashed
+ * send never reached — which is why there is no separate `pending_send`.
+ */
+export const INVITE_BATCH_ITEM_STATUSES = [
+  "eligible",
+  "excluded",
+  "sent",
+  "failed",
+  "skipped",
+] as const;
+
+export const InviteBatchItemStatusSchema = z.enum(INVITE_BATCH_ITEM_STATUSES);
+
+export type InviteBatchItemStatus = z.infer<typeof InviteBatchItemStatusSchema>;
+
+/**
+ * Why an item is not `sent`. One vocabulary across `excluded` (decided at
+ * prepare) and `skipped` (decided at send) — the reader wants "why did this
+ * person not get an invitation", and splitting the answer by which stage
+ * noticed would make that two questions.
+ *
+ * - `already-member`      — holds an account in this org.
+ * - `invite-pending`      — an unexpired invite is already outstanding.
+ * - `no-email`            — the directory row carries no address.
+ * - `invalid-email`       — it carries one that is not a deliverable address.
+ *                           An HRIS export with a mangled column produces these;
+ *                           committing an invite row that can never be mailed is
+ *                           the failure this reason exists to prevent.
+ * - `removed-by-reviewer` — a human un-ticked them. Persisted rather than
+ *                           deleted so the choice is reversible AND legible:
+ *                           "who was deliberately left out" is a question the
+ *                           batch must be able to answer later.
+ * - `address-changed`     — SEND-time only. The person's address is no longer
+ *                           the one shown at review. Confirmation authorized the
+ *                           address, not the person.
+ * - `person-removed`      — SEND-time only. The directory row is gone.
+ * - `send-failed`         — pairs with `failed`, not with `excluded`/`skipped`.
+ * - `inactive-in-hris`    — RESERVED, and NOTHING WRITES IT TODAY. `persons`
+ *                           carries no employment-status column, the BambooHR
+ *                           client never reads one, and a "Sync now" full resync
+ *                           reports no departures at all — so a terminated
+ *                           employee is currently indistinguishable from a
+ *                           current one. The name is held here so the eventual
+ *                           implementation does not have to change the wire
+ *                           vocabulary; treating its ABSENCE as evidence that
+ *                           everyone listed is still employed would be wrong.
+ */
+export const INVITE_BATCH_ITEM_REASONS = [
+  "already-member",
+  "invite-pending",
+  "no-email",
+  "invalid-email",
+  "removed-by-reviewer",
+  "address-changed",
+  "person-removed",
+  "send-failed",
+  "inactive-in-hris",
+] as const;
+
+export const InviteBatchItemReasonSchema = z.enum(INVITE_BATCH_ITEM_REASONS);
+
+export type InviteBatchItemReason = z.infer<typeof InviteBatchItemReasonSchema>;
+
+export const InviteBatchItemSchema = z.object({
+  personId: z.string().uuid(),
+  /**
+   * Read live from the directory, NOT snapshotted. A name is for recognising the
+   * human; only the ADDRESS is the thing confirmation authorizes, so only the
+   * address is frozen. Null when the directory row has since been deleted.
+   */
+  displayName: z.string().nullable(),
+  /**
+   * The address as it stood when `prepare` ran — what the reviewer approved.
+   * Null only when the person had none. Compared against the live address at
+   * send; a mismatch is `address-changed`, never a send to the new one.
+   */
+  emailSnapshot: z.string().nullable(),
+  role: z.enum(["admin", "member"]),
+  status: InviteBatchItemStatusSchema,
+  /** Null exactly when `status` is `eligible` or `sent`. */
+  reason: InviteBatchItemReasonSchema.nullable(),
+  /**
+   * The invite row this item produced. Present for `sent` AND for `failed` — a
+   * failed item's credential was minted and committed before the send was
+   * attempted, so the row exists and reissue is the remedy.
+   */
+  inviteId: z.string().uuid().nullable(),
+  /**
+   * The snapshot address is not under a domain this org has VERIFIED. Computed
+   * at read time from `org_domains` (status `verified`), never stored: a domain
+   * verified after review must stop warning, and one revoked after review must
+   * start. Advisory — it does not exclude anyone. Sending outside your own
+   * domains is legitimate (contractors, personal addresses); doing it eighty-
+   * eight times without noticing is the accident worth surfacing.
+   */
+  emailOutsideVerifiedDomain: z.boolean(),
+});
+
+export type InviteBatchItem = z.infer<typeof InviteBatchItemSchema>;
+
+/**
+ * Denormalized counters, maintained by the batch's own writers in the same
+ * transaction as the items they describe.
+ *
+ * DELIBERATELY NOT DERIVED CLIENT-SIDE. The confirm control reads
+ * "Send {eligible} invitations", and that number must be the number the SERVER
+ * will act on. A count computed from a page of items can disagree with the set
+ * `send` iterates; a count the server wrote cannot.
+ */
+export const InviteBatchCountsSchema = z.object({
+  /** Every person the batch was created for. Never changes after create. */
+  candidate: z.number().int().nonnegative(),
+  eligible: z.number().int().nonnegative(),
+  excluded: z.number().int().nonnegative(),
+  sent: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+});
+
+export type InviteBatchCounts = z.infer<typeof InviteBatchCountsSchema>;
+
+export const InviteBatchSchema = z.object({
+  id: z.string().uuid(),
+  status: InviteBatchStatusSchema,
+  /**
+   * Where the candidate set came from. OPEN string, `directory` today — the org
+   * people directory. Not an enum: a future CSV or SCIM origin should not need a
+   * migration to be nameable.
+   */
+  source: z.string(),
+  /**
+   * Bumped by every mutation of the reviewable set (selection or role). `send`
+   * carries the revision the reviewer saw; a mismatch is
+   * {@link INVITE_BATCH_CHANGED} rather than a send of something else.
+   */
+  revision: z.number().int().nonnegative(),
+  counts: InviteBatchCountsSchema,
+  createdByUserId: z.string().uuid(),
+  /** Who ran `send`, and when they did. Null until then. */
+  confirmedByUserId: z.string().uuid().nullable(),
+  confirmedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type InviteBatch = z.infer<typeof InviteBatchSchema>;
+
+export const InviteBatchResponseSchema = z.object({
+  batch: InviteBatchSchema,
+  items: z.array(InviteBatchItemSchema),
+  /**
+   * The org's verified domains, so the review surface can NAME them in the
+   * out-of-domain warning rather than just flagging rows. Empty is the common
+   * case and means every address is out-of-domain by this definition — render
+   * the warning accordingly rather than as eighty-eight alarms.
+   */
+  verifiedDomains: z.array(z.string()),
+});
+
+export type InviteBatchResponse = z.infer<typeof InviteBatchResponseSchema>;
+
+export const CreateInviteBatchRequestSchema = z.object({
+  personIds: z.array(z.string().uuid()).min(1).max(BATCH_INVITE_PERSONS_MAX),
+  role: z.enum(["admin", "member"]),
+});
+
+export type CreateInviteBatchRequest = z.infer<
+  typeof CreateInviteBatchRequestSchema
+>;
+
+/**
+ * Change what a `draft` or `ready` batch will do. Every accepted call bumps
+ * `revision`, which is what invalidates a review already on someone's screen.
+ *
+ * Deselecting does NOT delete the item — it becomes `excluded` with
+ * `removed-by-reviewer`, so reselecting is a status flip rather than a
+ * re-preparation, and the batch can still answer who was deliberately omitted.
+ * Reselecting a person excluded by POLICY (already a member, no address) is
+ * refused: `reselect` reverses a human's decision, not the server's.
+ */
+export const UpdateInviteBatchRequestSchema = z
+  .object({
+    deselectPersonIds: z.array(z.string().uuid()).optional(),
+    reselectPersonIds: z.array(z.string().uuid()).optional(),
+    role: z.enum(["admin", "member"]).optional(),
+  })
+  .refine(
+    (v) =>
+      v.deselectPersonIds !== undefined ||
+      v.reselectPersonIds !== undefined ||
+      v.role !== undefined,
+    {
+      message:
+        "Provide at least one of deselectPersonIds, reselectPersonIds, role",
+    },
+  );
+
+export type UpdateInviteBatchRequest = z.infer<
+  typeof UpdateInviteBatchRequestSchema
+>;
+
+/**
+ * `expectedRevision` is REQUIRED and has no default. Sending is the only
+ * irreversible verb in this lifecycle — email cannot be recalled — so the one
+ * call that performs it must state what it believes it is sending.
+ *
+ * There is no `Idempotency-Key` here, deliberately. The send claim
+ * (`UPDATE ... SET status='sending' WHERE status='ready' AND revision = ?`) is
+ * an atomic compare-and-set: the first caller wins and every later one sees zero
+ * rows and gets {@link INVITE_BATCH_CHANGED}. That is exactly-once permanently
+ * and across every task in the cluster, where an idempotency key would be
+ * exactly-once for its retention window and only where the key store is shared.
+ * Routing this through a key ALSO means wrapping check + mutation + store in one
+ * transaction, which would roll back the record of mail that had already left.
+ */
+export const SendInviteBatchRequestSchema = z.object({
+  expectedRevision: z.number().int().nonnegative(),
+});
+
+export type SendInviteBatchRequest = z.infer<
+  typeof SendInviteBatchRequestSchema
+>;
+
+/**
+ * The error code a stale `send` (or a mutation of an already-claimed batch)
+ * returns, as `error` on the standard 409 envelope.
+ *
+ * It means: what you reviewed is not what is here now. The client's obligation
+ * is to re-fetch and put the CHANGES in front of the human again before the
+ * confirm control re-arms — not to retry with the new revision, which would
+ * authorize a list nobody read.
+ */
+export const INVITE_BATCH_CHANGED = "BATCH_CHANGED" as const;
+
 // ---------------------------------------------------------------------------
 // OrgDomain sub-schema
 // ---------------------------------------------------------------------------

package/src/resource-key-types.ts

@@ -20,6 +20,9 @@ export type ResourceKey =
   | { type: "teams"; orgId: string }
   | { type: "integrations"; orgId: string }
   | { type: "invites"; orgId: string }
+  // The people directory (`persons`) — every person the org knows about,
+  // account-bearing or not. Distinct from `members`, which is accounts only.
+  | { type: "orgDirectory"; orgId: string }
   | { type: "auditEvents"; orgId: string }
   | { type: "timeline"; orgId: string }
   // Identities (singular) — single entities

package/src/resource-keys.ts

@@ -129,6 +129,7 @@ const ORG_SCOPED_TYPES = [
   "teams",
   "integrations",
   "invites",
+  "orgDirectory",
   "auditEvents",
   "timeline",
   "workspace",
@@ -266,6 +267,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "teams":
     case "integrations":
     case "invites":
+    case "orgDirectory":
     case "auditEvents":
     case "timeline":
     case "workspace":