@company-semantics/contracts 87.0.0 → 88.0.1

package/src/org/invite-schemas.ts

@@ -0,0 +1,596 @@
+/**
+ * Invite Schemas
+ *
+ * Org invites, the people directory, the deprecated one-shot bulk invite, and the
+ * persisted invite-batch (Prepare → Review → Send) lifecycle.
+ *
+ * Split out of `./schemas.ts`, which re-exports this module unchanged — import
+ * from `./schemas` (or the `./org` entry), not from this file directly.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Invite sub-schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Role the invitee takes in their home unit on acceptance. `unit_owner` is a
+ * deferred unit-ownership grant applied at accept time. Source of truth
+ * for the hand-mirrored `OrgInvite`/`CreateInviteRequest` interface unions in
+ * `org/types.ts` (enforced by the `schema-type-mirror` guard).
+ */
+export const HomeUnitRoleSchema = z.enum(["member", "unit_owner"]);
+export type HomeUnitRole = z.infer<typeof HomeUnitRoleSchema>;
+
+/** Established title cap shared with org-unit/open-role titles. */
+const STAGED_PLACEMENT_TITLE_MAX = 255;
+/**
+ * Upper bound on the number of units an invitee can be staged into as owner or
+ * contributor. Bounds the replay cost of applying a staged placement at accept
+ * time (each entry is a deferred membership grant). A generous-but-finite cap.
+ */
+const STAGED_PLACEMENT_UNITS_MAX = 64;
+
+/**
+ * Staged member placement: the fuller org position an invitee is slotted into,
+ * applied as deferred grants when the invite is accepted. A superset of the
+ * legacy top-level `homeUnitId`/`homeUnitRole` fields, carrying the (optional)
+ * intended title, manager, and the units the invitee will own or contribute to.
+ *
+ * Every field is optional or defaulted so a placement can be partially
+ * specified at invite time. The array caps bound downstream replay cost.
+ */
+export const StagedPlacementSchema = z.object({
+  // Intended job/role title for the invitee. Trimmed; non-empty when present.
+  title: z.string().trim().min(1).max(STAGED_PLACEMENT_TITLE_MAX).optional(),
+  // The invitee's manager on acceptance (a `manages` designation).
+  managerUserId: z.string().uuid().optional(),
+  // Home unit the invitee is placed in (their `users.primary_unit_id`).
+  homeUnitId: z.string().uuid().optional(),
+  // Role the invitee takes in `homeUnitId` ('unit_owner' = deferred grant).
+  homeUnitRole: HomeUnitRoleSchema.optional(),
+  // Additional units the invitee becomes a unit owner of on acceptance.
+  unitOwnerOf: z
+    .array(z.string().uuid())
+    .max(STAGED_PLACEMENT_UNITS_MAX)
+    .default([]),
+  // Units the invitee contributes to (non-owner membership) on acceptance.
+  contributesTo: z
+    .array(z.string().uuid())
+    .max(STAGED_PLACEMENT_UNITS_MAX)
+    .default([]),
+});
+export type StagedPlacement = z.infer<typeof StagedPlacementSchema>;
+
+const OrgInviteSchema = z.object({
+  id: z.string(),
+  orgId: z.string(),
+  email: z.string(),
+  role: z.enum(["admin", "member"]),
+  invitedBy: z.object({ id: z.string(), name: z.string() }),
+  status: z.enum(["pending", "accepted", "expired", "revoked"]),
+  // Home unit the invitee is placed in on acceptance (users.primary_unit_id).
+  // Optional/nullable: legacy invites predate this field.
+  homeUnitId: z.string().uuid().optional(),
+  // Role the invitee takes in homeUnitId on acceptance ('unit_owner' is a
+  // deferred unit-ownership grant). Optional/'member' for legacy +
+  // unit-less invites.
+  homeUnitRole: HomeUnitRoleSchema.optional(),
+  // Fuller staged placement applied as deferred grants on acceptance. A
+  // superset of the top-level homeUnitId/homeUnitRole, kept additive/optional
+  // so legacy invites and unit-less invites parse unchanged.
+  stagedPlacement: StagedPlacementSchema.optional(),
+  createdAt: z.string(),
+  expiresAt: z.string(),
+  acceptedAt: z.string().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/invites
+// ---------------------------------------------------------------------------
+
+export const InviteResponseSchema = z.object({
+  invite: OrgInviteSchema,
+});
+
+export type InviteResponse = z.infer<typeof InviteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/invites
+// ---------------------------------------------------------------------------
+
+export const InviteListResponseSchema = z.array(OrgInviteSchema);
+
+export type InviteListResponse = z.infer<typeof InviteListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/invites — request body
+// Request schema colocated with the response schema (narrow deviation from
+// ADR-CONT-044, per the CreateOpenRoleRequestSchema precedent) because the
+// staged-placement shape is the published promise consumers must satisfy.
+// Mirrors the hand-written `CreateInviteRequest` interface in org/types.ts and
+// extends it with the optional `stagedPlacement` superset.
+// ---------------------------------------------------------------------------
+
+export const CreateInviteRequestSchema = z.object({
+  email: z.string().email(),
+  // Invites only grant the restricted {admin, member} domain.
+  role: z.enum(["admin", "member"]),
+  // Home unit the invitee is placed in on acceptance. Optional in the contract
+  // so the field can roll out without breaking older callers.
+  homeUnitId: z.string().uuid().optional(),
+  // Role the invitee takes in homeUnitId — only meaningful with a home unit.
+  homeUnitRole: HomeUnitRoleSchema.optional(),
+  // Fuller staged placement (title, manager, owned/contributed units) applied
+  // as deferred grants on acceptance. Optional/additive for back-compat.
+  stagedPlacement: StagedPlacementSchema.optional(),
+});
+
+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;
+
+/**
+ * How many days an invitation link stays redeemable.
+ *
+ * Shared vocabulary, not prose: the backend stamps `expires_at` from this when
+ * it mints an invite, and the review surface states the same window to the
+ * person about to send one. It lived in both places as a literal and drifted —
+ * the copy still promised seven days after the policy moved.
+ *
+ * A SECURITY parameter as much as a UX one: it bounds how long a leaked invite
+ * link stays usable, so widening it is a deliberate trust-model change rather
+ * than a copy edit.
+ */
+export const INVITE_EXPIRY_DAYS = 30;
+
+/** @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.
+ * - `canceled` — canceled 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",
+  "canceled",
+] 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 recognizing 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(),
+  /**
+   * The reviewer's optional note, carried into every invitation this send mails
+   * and attributed to the inviter (`NotificationPayloads['org.invite'].message`).
+   *
+   * It rides the SEND rather than the batch on purpose: it authorizes nothing,
+   * so it has no business bumping a revision that every open review reads as
+   * "read this again". Not persisted — the invitation is the only thing that
+   * ever carries it.
+   */
+  message: z.string().max(2000).optional(),
+  /**
+   * Per-person role overrides, keyed by `personId` — the reviewer set a role for
+   * ONE recipient rather than for the batch.
+   *
+   * The batch's own `role` remains what everyone else is invited as; a key here
+   * replaces it for that person only. A key naming somebody outside the batch,
+   * or somebody it is no longer sending to, is INERT rather than an error: the
+   * live directory re-check at send time already decides who is mailed, and a
+   * stale override describes a person nobody is inviting.
+   */
+  roleByPersonId: z
+    .record(z.string().uuid(), z.enum(["admin", "member"]))
+    .optional(),
+});
+
+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;