@company-semantics/contracts 56.1.0 → 58.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "56.1.0",
+  "version": "58.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 = '373ff35b2847' as const;
-export const SPEC_HASH_FULL = '373ff35b284714e9030fd0c611b3d4c1be255cd12df7f6adec2b6f7e6ba9179f' as const;
+export const SPEC_HASH = 'ffeb6e367b38' as const;
+export const SPEC_HASH_FULL = 'ffeb6e367b385ad32f7b46e4e74d276786d6cdf175352e57d0fc229dc8f506af' as const;

package/src/api/generated.ts

@@ -943,6 +943,23 @@ export interface paths {
         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;
@@ -977,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;
@@ -4631,6 +4734,12 @@ export interface components {
             /** @enum {string} */
             role: "admin" | "member";
         };
+        ReissueInviteResponse: {
+            /** Format: uuid */
+            inviteId: string;
+            /** Format: uuid */
+            previousInviteId: string;
+        };
         InviteListResponse: {
             id: string;
             orgId: string;
@@ -4674,6 +4783,58 @@ 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;
@@ -8317,6 +8478,28 @@ export interface operations {
             };
         };
     };
+    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;
@@ -8361,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: {

package/src/generated/openapi-routes.ts

@@ -190,11 +190,17 @@ export const openApiRoutes = {
   '/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

@@ -645,6 +645,39 @@ export type {
   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/integrations/README.md

@@ -16,6 +16,10 @@ alongside `Meetings`, `Comms`, and `Docs`.
 
 - `HrConnectionStatusSchema` is a read projection: count and sync fields are
   `null` until the first successful sync (a connected, never-synced integration).
+- `revokedReason` is non-null only when `credentialState` is `'unusable'`, and
+  its enum mirrors the backend's `ConnectionRevokedReason` exactly — the app
+  `parse`s this projection, so a value missing from the enum throws rather than
+  degrades (ADR-CONTRACTS-138).
 - `HrConnectInputSchema` carries only the customer's provider `subdomain`; no
   secrets or provider credentials live in contracts.
 - Pure vocabulary — `zod` is the only runtime import (vocabulary-guard).

package/src/integrations/schemas.ts

@@ -83,6 +83,32 @@ export const HrConnectionStatusSchema = z
       description:
         "Health of the most recent sync; null when no sync has run yet.",
     }),
+    revokedReason: z
+      .enum([
+        "token_refresh_failed",
+        "missing_refresh_token",
+        "member_removed",
+        "app_uninstalled",
+        "tokens_revoked",
+      ])
+      .nullable()
+      .meta({
+        description:
+          "Why the credential died, when `credentialState` is 'unusable'. " +
+          "'token_refresh_failed' — the provider rejected the refresh grant, " +
+          "which is a sign-in that simply aged out and is fixed by " +
+          "reconnecting. 'missing_refresh_token' — there is nothing left to " +
+          "refresh with, so reconnecting is the ONLY repair. " +
+          "'member_removed' — the person whose account backed this " +
+          "connection left the org, so someone else must reconnect it. " +
+          "'app_uninstalled' / 'tokens_revoked' — the grant was withdrawn on " +
+          "the provider's side, and reconnecting will fail again until it is " +
+          "restored there. The distinction matters because the four cases " +
+          "ask different things of the reader: three are 'click Reconnect' " +
+          "and one is 'go fix it in the provider first'. Null whenever " +
+          "`credentialState` is not 'unusable', and null on a connection " +
+          "revoked before this field existed.",
+      }),
   })
   .meta({
     description: "Connection-status projection for an HR integration.",

package/src/org/README.md

@@ -109,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`
@@ -147,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)_
@@ -311,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)_
@@ -360,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

@@ -362,6 +362,21 @@ export {
   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,
@@ -379,6 +394,16 @@ export type {
   BatchInviteSkipReason,
   BatchInviteRequest,
   BatchInviteResponse,
+  InviteBatchStatus,
+  InviteBatchItemStatus,
+  InviteBatchItemReason,
+  InviteBatchItem,
+  InviteBatchCounts,
+  InviteBatch,
+  InviteBatchResponse,
+  CreateInviteBatchRequest,
+  UpdateInviteBatchRequest,
+  SendInviteBatchRequest,
   DomainResponse,
   DomainListResponse,
   OrgBillingResponse,

package/src/org/schemas.ts

@@ -820,7 +820,19 @@ export const OrgDirectoryResponseSchema = z.object({
 export type OrgDirectoryResponse = z.infer<typeof OrgDirectoryResponseSchema>;
 
 // ---------------------------------------------------------------------------
-// POST /api/workspace/invites/batch
+// 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
@@ -842,6 +854,7 @@ export type OrgDirectoryResponse = z.infer<typeof OrgDirectoryResponseSchema>;
  */
 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.
@@ -867,6 +880,7 @@ export const BATCH_INVITE_SKIP_REASONS = [
   "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>;
@@ -876,6 +890,7 @@ const BatchInviteOutcomeSchema = z.object({
   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()),
@@ -891,6 +906,309 @@ export const BatchInviteResponseSchema = z.object({
 
 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
 // ---------------------------------------------------------------------------