@company-semantics/contracts 86.1.0 → 88.0.0

package/src/org/schemas.ts

@@ -4,22 +4,31 @@
  * Zod response schemas for workspace core endpoints.
  * Canonical location for runtime validation of workspace API responses.
  *
- * Covers:
- *  - workspace.ts (GET /api/workspace, /access, /members, /auth, /audit, etc.)
+ * Covers (defined here):
+ *  - workspace.ts (GET /api/workspace, /access, /members)
  *  - members.ts   (DELETE/PATCH /api/workspace/members)
  *  - user-orgs.ts (GET /api/user/orgs, POST /api/user/active-org, /leave)
  *  - scope-check.ts (GET /api/scope/check, POST /api/scope/check-batch)
+ *  - capabilities (GET /api/capabilities)
+ *
+ * The rest of the org schema corpus lives in sibling `*-schemas.ts` modules
+ * and is re-exported below, so `./schemas` stays the one import path for
+ * every org schema.
  */
 import { z } from "zod";
-import { CursorPageSchema, IsoDateTime } from "../api/primitives";
-import { AI_PAUSE_REASONS, MoneyMicrosSchema } from "../billing/vocabulary";
-import { AI_FEATURES } from "../usage/features";
+import { CursorPageSchema } from "../api/primitives";
+import { AI_PAUSE_REASONS } from "../billing/vocabulary";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
 import { PositionRefSchema } from "../identity/position-ref";
-import {
-  ORG_UNIT_ABSOLUTE_MAX_DEPTH,
-  UNIT_OWNER_MEMBERSHIP_ROLES,
-} from "./org-depth";
+import { AuthorityMutabilitySchema } from "./authority-schemas";
+
+// Sibling schema modules — re-exported whole; ./schemas is their only import path.
+export * from "./workspace-admin-schemas";
+export * from "./invite-schemas";
+export * from "./org-governance-schemas";
+export * from "./org-unit-schemas";
+export * from "./authority-schemas";
+export * from "./org-unit-api-schemas";
 
 // ---------------------------------------------------------------------------
 // Sub-schemas
@@ -50,17 +59,6 @@ export const OrgUnitDesignationSchema = z.enum([
 ]);
 export type OrgUnitDesignation = z.infer<typeof OrgUnitDesignationSchema>;
 
-/**
- * Whether the user can change this authority from this surface.
- *  - `derived`: change the upstream source instead (the org chart, RBAC roles).
- *  - `user_managed`: removable from this UI.
- *
- * Hoisted above {@link WorkspaceMemberUnitDesignationEntrySchema} so the
- * per-unit designation can carry it; also consumed by {@link OwnerAuthoritySchema}.
- */
-export const AuthorityMutabilitySchema = z.enum(["derived", "user_managed"]);
-export type AuthorityMutability = z.infer<typeof AuthorityMutabilitySchema>;
-
 export const WorkspaceMemberUnitDesignationEntrySchema = z.object({
   unitId: z.string(),
   unitName: z.string(),
@@ -295,236 +293,6 @@ export type WorkspaceMembersResponse = z.infer<
   typeof WorkspaceMembersResponseSchema
 >;
 
-// ---------------------------------------------------------------------------
-// GET /api/workspace/auth
-// ---------------------------------------------------------------------------
-
-const OidcValidationResultSchema = z.object({
-  valid: z.boolean(),
-  issuer: z.string().optional(),
-  authorizationEndpoint: z.string().optional(),
-  error: z.string().optional(),
-  errorCode: z
-    .enum(["UNREACHABLE", "INVALID_DOCUMENT", "MISSING_FIELDS", "SSRF_BLOCKED"])
-    .optional(),
-});
-
-const SsoDiscoveryConfigSchema = z.object({
-  redirectUri: z.string(),
-  requiredScopes: z.array(z.string()),
-  isOidcConfigured: z.boolean(),
-  oidcDiscoveryUrl: z.string().nullable(),
-});
-
-const SsoCredentialStatusSchema = z.object({
-  hasClientId: z.boolean(),
-  hasClientSecret: z.boolean(),
-});
-
-const ProviderStatusSchema = z.enum([
-  "NOT_CONFIGURED",
-  "CONFIG_SAVED",
-  "CONFIG_VALID",
-  "TEST_SUCCESS",
-  "ENABLED",
-]);
-
-const SsoStepperStepSchema = z.enum(["configure", "test", "enable", "enforce"]);
-
-const SsoOperationalStateSchema = z.object({
-  providerStatus: ProviderStatusSchema,
-  currentStep: SsoStepperStepSchema,
-  stepCompleted: z.boolean(),
-  activeProvider: z.string().nullable(),
-  oidcValidation: OidcValidationResultSchema.optional(),
-  credentialsSavedAt: z.string().optional(),
-  lastTestSuccessAt: z.string().optional(),
-  lastTestSuccessProvider: z.string().optional(),
-});
-
-const SsoSetupInfoSchema = SsoDiscoveryConfigSchema.merge(
-  SsoCredentialStatusSchema,
-).merge(SsoOperationalStateSchema);
-
-const SsoReadinessCheckSchema = z.object({
-  code: z.string(),
-  label: z.string(),
-  passed: z.boolean(),
-  message: z.string(),
-});
-
-const SsoReadinessSchema = z.object({
-  ready: z.boolean(),
-  checks: z.array(SsoReadinessCheckSchema),
-});
-
-const SsoEnforcementStatusSchema = z.object({
-  enforced: z.boolean(),
-  enforcedDomains: z.array(z.string()),
-  enforcedSince: z.string().nullable(),
-});
-
-const OwnerIdentityInfoSchema = z.object({
-  userId: z.string(),
-  name: z.string(),
-  email: z.string(),
-  hasSsoIdentity: z.boolean(),
-  linkedProvider: z.string().nullable(),
-  lastSsoLoginAt: z.string().nullable(),
-});
-
-const ProviderSuggestionSchema = z.object({
-  suggestedProvider: z.enum(["google", "microsoft"]).nullable(),
-  confidence: z.enum(["high", "low"]),
-  reason: z.string(),
-  detectedDomain: z.string().optional(),
-});
-
-const AuthMethodConfigSchema = z.object({
-  enabled: z.boolean(),
-  provider: z.string().optional(),
-});
-
-export const WorkspaceAuthConfigSchema = z.object({
-  emailOtp: AuthMethodConfigSchema,
-  googleSso: AuthMethodConfigSchema,
-  microsoftSso: AuthMethodConfigSchema,
-  okta: AuthMethodConfigSchema,
-  policy: z.object({
-    requireSSO: z.boolean(),
-    allowedProviders: z.array(z.string()),
-  }),
-  ssoSetup: SsoSetupInfoSchema.optional(),
-  ssoReadiness: SsoReadinessSchema.optional(),
-  ssoEnforcement: SsoEnforcementStatusSchema.optional(),
-  workspaceSsoState: z
-    .enum(["SSO_DISABLED", "SSO_ENABLED", "SSO_ENFORCED"])
-    .optional(),
-  ownerIdentities: z.array(OwnerIdentityInfoSchema).optional(),
-  providerSuggestion: ProviderSuggestionSchema.optional(),
-});
-
-export type WorkspaceAuthConfig = z.infer<typeof WorkspaceAuthConfigSchema>;
-
-// ---------------------------------------------------------------------------
-// GET /api/workspace/audit
-// ---------------------------------------------------------------------------
-
-export const WorkspaceAuditEventSchema = z.object({
-  id: z.string(),
-  timestamp: z.string(),
-  actor: z.object({
-    id: z.string(),
-    name: z.string(),
-    type: z.enum(["user", "system"]),
-  }),
-  action: z.string(),
-  summary: z.string(),
-});
-
-export const WorkspaceAuditResponseSchema = z.array(WorkspaceAuditEventSchema);
-
-export type WorkspaceAuditEvent = z.infer<typeof WorkspaceAuditEventSchema>;
-
-// ---------------------------------------------------------------------------
-// POST /api/workspace/resolve-path
-// ---------------------------------------------------------------------------
-
-const ResolvedDeptEntitySchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  slug: z.string(),
-  memberCount: z.number(),
-});
-
-export const WorkspaceResolvePathResponseSchema = z.object({
-  layers: z.array(
-    z.discriminatedUnion("type", [
-      z.object({ type: z.literal("dept"), entity: ResolvedDeptEntitySchema }),
-      z.object({ type: z.literal("team"), entity: ResolvedDeptEntitySchema }),
-      z.object({
-        type: z.literal("members"),
-        scope: z.enum(["org", "dept", "team"]),
-      }),
-    ]),
-  ),
-});
-
-export type WorkspaceResolvePathResponse = z.infer<
-  typeof WorkspaceResolvePathResponseSchema
->;
-
-// ---------------------------------------------------------------------------
-// PATCH /api/workspace/auth-policy
-// ---------------------------------------------------------------------------
-
-export const OrgAuthPolicySchema = z.object({
-  requireSSO: z.boolean(),
-  allowedProviders: z.array(z.string()),
-  selfRevoked: z.boolean().optional(),
-});
-
-export type OrgAuthPolicy = z.infer<typeof OrgAuthPolicySchema>;
-
-// ---------------------------------------------------------------------------
-// POST /api/workspace/auth-policy/validate-oidc
-// ---------------------------------------------------------------------------
-
-export { OidcValidationResultSchema };
-export type OidcValidationResult = z.infer<typeof OidcValidationResultSchema>;
-
-// ---------------------------------------------------------------------------
-// POST /api/workspace/resync-slack-logo
-// ---------------------------------------------------------------------------
-
-export const WorkspaceResyncSlackLogoResponseSchema = z.object({
-  success: z.literal(true),
-  logoUrl: z.string().nullable(),
-});
-
-export type WorkspaceResyncSlackLogoResponse = z.infer<
-  typeof WorkspaceResyncSlackLogoResponseSchema
->;
-
-// ---------------------------------------------------------------------------
-// POST /api/workspace/auth-policy/test-sso
-// ---------------------------------------------------------------------------
-
-export const TestSsoInitiationSchema = z.object({
-  authorizationUrl: z.string(),
-  attemptId: z.string(),
-});
-
-export type TestSsoInitiation = z.infer<typeof TestSsoInitiationSchema>;
-
-// ---------------------------------------------------------------------------
-// GET /api/workspace/auth-policy/test-sso/:attemptId
-// ---------------------------------------------------------------------------
-
-export const TestSsoResultSchema = z.object({
-  status: z.enum(["pending", "success", "failed", "expired"]),
-  claims: z
-    .object({
-      sub: z.string(),
-      email: z.string().optional(),
-      name: z.string().optional(),
-      issuer: z.string(),
-    })
-    .optional(),
-  identityLinked: z.boolean().optional(),
-  error: z.string().optional(),
-  errorCode: z
-    .enum([
-      "IDENTITY_CONFLICT",
-      "DOMAIN_MISMATCH",
-      "ISSUER_MISMATCH",
-      "CALLBACK_ERROR",
-    ])
-    .optional(),
-});
-
-export type TestSsoResult = z.infer<typeof TestSsoResultSchema>;
-
 // ---------------------------------------------------------------------------
 // DELETE /api/workspace/members/:id
 // ---------------------------------------------------------------------------
@@ -681,1414 +449,6 @@ export type ScopeCheckBatchResponse = z.infer<
   typeof ScopeCheckBatchResponseSchema
 >;
 
-// ---------------------------------------------------------------------------
-// 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;
-
-// ---------------------------------------------------------------------------
-// OrgDomain sub-schema
-// ---------------------------------------------------------------------------
-
-const OrgDomainSchema = z.object({
-  id: z.string(),
-  orgId: z.string(),
-  domain: z.string(),
-  status: z.enum(["pending", "verified"]),
-  verificationMethod: z.enum(["dns_txt", "email", "idp"]),
-  verificationToken: z.string().optional(),
-  verifiedAt: z.string().nullable(),
-  createdAt: z.string(),
-  verifiedBy: z
-    .object({ id: z.string(), name: z.string(), email: z.string() })
-    .optional(),
-});
-
-// ---------------------------------------------------------------------------
-// GET /api/workspace/domains/:id/verify (single domain)
-// POST /api/workspace/domains/:id/verify (returns verified OrgDomain)
-// ---------------------------------------------------------------------------
-
-export const DomainResponseSchema = OrgDomainSchema;
-
-export type DomainResponse = z.infer<typeof DomainResponseSchema>;
-
-// ---------------------------------------------------------------------------
-// GET /api/workspace/domains
-// ---------------------------------------------------------------------------
-
-export const DomainListResponseSchema = z.array(OrgDomainSchema);
-
-export type DomainListResponse = z.infer<typeof DomainListResponseSchema>;
-
-// ---------------------------------------------------------------------------
-// GET /api/org/deletion-eligibility
-// ---------------------------------------------------------------------------
-
-const MemberClassificationSchema = z.object({
-  userId: z.string(),
-  email: z.string(),
-  suggestedFate: z.enum(["REMOVE_FROM_ORG", "DELETE_ACCOUNT", "BLOCKED"]),
-  reason: z.string(),
-});
-
-export const OrgDeletionStatusSchema = z.object({
-  orgId: z.string(),
-  eligible: z.boolean(),
-  isPersonalOrg: z.boolean(),
-  ownerStatus: z.string().optional(),
-  deletionRequestedAt: z.string().optional(),
-  classifications: z.array(MemberClassificationSchema),
-});
-
-export type OrgDeletionStatus = z.infer<typeof OrgDeletionStatusSchema>;
-
-// ---------------------------------------------------------------------------
-// POST /api/org/transfer-ownership (initiate)
-// ---------------------------------------------------------------------------
-
-export const OwnershipTransferResponseSchema = z.object({
-  transferId: z.string(),
-  expiresAt: z.string(),
-  message: z.string(),
-});
-
-export type OwnershipTransferResponse = z.infer<
-  typeof OwnershipTransferResponseSchema
->;
-
-// ---------------------------------------------------------------------------
-// POST /api/org/transfer-ownership/preview
-// ---------------------------------------------------------------------------
-
-export const OwnershipTransferPreviewSchema = z.object({
-  workspaceName: z.string(),
-  initiatorName: z.string(),
-  initiatorEmail: z.string(),
-  note: z.string().optional(),
-  expiresAt: z.string(),
-  token: z.string(),
-});
-
-export type OwnershipTransferPreview = z.infer<
-  typeof OwnershipTransferPreviewSchema
->;
-
-// ---------------------------------------------------------------------------
-// GET /api/org/system-events
-// ---------------------------------------------------------------------------
-
-const OrgSystemEventSchema = z.object({
-  id: z.string(),
-  type: z.string(),
-  payload: z.unknown(),
-  createdAt: z.string(),
-});
-
-export const OrgSystemEventsListSchema = z.object({
-  events: z.array(OrgSystemEventSchema),
-});
-
-export type OrgSystemEventsList = z.infer<typeof OrgSystemEventsListSchema>;
-
-// ---------------------------------------------------------------------------
-// POST /api/org/system-events/:id/acknowledge
-// ---------------------------------------------------------------------------
-
-export const AcknowledgeSystemEventResponseSchema = z.object({
-  success: z.literal(true),
-});
-
-export type AcknowledgeSystemEventResponse = z.infer<
-  typeof AcknowledgeSystemEventResponseSchema
->;
-
-// ---------------------------------------------------------------------------
-// GET /api/orgs/:orgId/ai-usage
-//
-// INV-USAGE-LEDGER: every request, token and dollar here is read from the
-// settled billing ledger (`billing_usage_events`) — one row per billed provider
-// call, whatever feature made it. A `request` is one settled billable provider
-// invocation (retries and fallbacks are separate requests), every amount is
-// the customer charge in integer micro-USD, and `tokens` is input + output +
-// cache read + cache write (reasoning is a subset of output, never added).
-// `chatRuns` alone comes from runtime telemetry: duration and failure
-// diagnostics for chat turns, carrying no money.
-// ---------------------------------------------------------------------------
-
-const OrgAiUsageTotalsSchema = z.object({
-  requests: z.number().int().min(0),
-  tokens: z.number().int().min(0),
-  customerChargeMicros: MoneyMicrosSchema,
-});
-
-const OrgChatRunProfileSchema = z.object({
-  profile: z.string(),
-  executions: z.number().int().min(0),
-  percentOfTotal: z.number(),
-  avgDurationMs: z.number(),
-  failureRate: z.number(),
-});
-
-export const OrgUsageResponseSchema = z.object({
-  /** The org's billing window: `start`/`end` in UTC, days bucketed in `timezone`. */
-  period: z.object({
-    start: IsoDateTime,
-    end: IsoDateTime,
-    timezone: z.string(),
-  }),
-  summary: OrgAiUsageTotalsSchema,
-  daily: z.array(
-    z.object({
-      date: z.string(),
-      requests: z.number().int().min(0),
-      customerChargeMicros: MoneyMicrosSchema,
-    }),
-  ),
-  byFeature: z.array(
-    OrgAiUsageTotalsSchema.extend({ feature: z.enum(AI_FEATURES) }),
-  ),
-  byModel: z.array(
-    OrgAiUsageTotalsSchema.extend({
-      provider: z.string(),
-      modelId: z.string(),
-    }),
-  ),
-  /** Attributed usage only: system work (no user) counts in the totals, not here. */
-  byUser: z.array(
-    OrgAiUsageTotalsSchema.extend({
-      userId: z.string(),
-      email: z.string().nullable(),
-    }),
-  ),
-  chatRuns: z.object({
-    executions: z.number().int().min(0),
-    avgDurationMs: z.number(),
-    failureRate: z.number(),
-    byProfile: z.array(OrgChatRunProfileSchema),
-  }),
-});
-
-export type OrgUsageResponse = z.infer<typeof OrgUsageResponseSchema>;
-
-// ---------------------------------------------------------------------------
-// OrgUnit canonical model (ADR-BE-120)
-// ---------------------------------------------------------------------------
-
-export const OrgUnitClassificationSchema = z.enum([
-  "execution_unit",
-  "org_container",
-  "leadership",
-  "custom",
-]);
-
-export const OrgUnitSyncModeSchema = z.enum([
-  "manual_only",
-  "synced_readonly",
-  "synced_with_overrides",
-]);
-
-export const OrgUnitVisibilitySchema = z.enum([
-  "public",
-  "private",
-  "restricted",
-]);
-
-export const OrgUnitRelationshipTypeSchema = z.enum([
-  "collaborates_with",
-  "reports_to",
-  "depends_on",
-  "custom",
-]);
-
-export const OrgUnitRelationshipRoleSchema = z.enum([
-  "owner",
-  "participant",
-  "supporting",
-]);
-
-/**
- * Positional slot a member holds in the org-unit tree. ORTHOGONAL to the
- * `OrgChartRole` policy vocabulary (this is an INPUT to authority resolution,
- * not the derived policy role). Level is encoded in the value (l1…l20, one
- * per depth up to `ORG_UNIT_ABSOLUTE_MAX_DEPTH`).
- */
-export const UnitMembershipRoleSchema = z.enum([
-  "member",
-  ...UNIT_OWNER_MEMBERSHIP_ROLES,
-]);
-
-export type UnitMembershipRole = z.infer<typeof UnitMembershipRoleSchema>;
-
-export const OrgUnitMembershipStatusSchema = z.enum([
-  "active",
-  "pending",
-  "removed",
-]);
-
-export const OrgUnitMembershipSourceSchema = z.enum([
-  "manual",
-  "google_groups",
-  "scim",
-  "hris",
-]);
-
-/**
- * Hiring lifecycle of an open role. See `OpenRoleStatus` in `./org-units` for
- * the transition rules. Only `open` and `hiring` are "active" (render a card
- * and count toward `openRoleCount`); `filled`/`closed` are terminal.
- */
-export const OpenRoleStatusSchema = z.enum([
-  "open",
-  "hiring",
-  "filled",
-  "closed",
-]);
-
-export const OrgUnitErrorCodeSchema = z.enum([
-  "CYCLE_BLOCKED",
-  "DEPTH_EXCEEDED",
-  "TARGET_ARCHIVED",
-  "ROOT_HAS_NO_PARENT",
-  "PARENT_ARCHIVED",
-  "SLUG_TAKEN",
-  "CROSS_ORG_REPARENT",
-  "ORDERKEY_CONFLICT",
-  "SIBLING_NOT_FOUND",
-  "SIBLINGS_DIFFERENT_PARENT",
-]);
-
-export const OrgUnitSchema = z.object({
-  id: z.string().uuid(),
-  orgId: z.string().uuid(),
-  parentId: z.string().uuid().nullable(),
-  slug: z.string().min(1),
-  name: z.string().min(1),
-  description: z.string().nullable(),
-  typeTag: z.string().min(1),
-  classification: OrgUnitClassificationSchema.nullable(),
-  orderKey: z.string().min(1),
-  path: z.string().min(1),
-  syncMode: OrgUnitSyncModeSchema,
-  visibilityDefault: OrgUnitVisibilitySchema.nullable(),
-  metadata: z.record(z.string(), z.unknown()),
-  archivedAt: z.string().nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-
-/**
- * Active users home directly at this unit who have no level-(depth+1) home
- * assignment within its subtree. The settings UI surfaces this as a
- * synthetic "[child level label] assignment missing" row above the
- * children list at every level. `null` for leaf-level units (no children
- * configured below them) where the concept is meaningless.
- */
-export const MissingAtNextLevelSchema = z.object({
-  count: z.number().int().min(0),
-  userIds: z.array(z.string().uuid()),
-});
-
-export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
-  depth: z.number().int().min(1).max(ORG_UNIT_ABSOLUTE_MAX_DEPTH),
-  hasChildren: z.boolean(),
-  /**
-   * WHAT it counts is the `.describe()` below — the single field-level
-   * description, which reaches `openapi/backend.yaml` and the generated API
-   * types. This comment carries only WHY, so the two cannot drift into
-   * disagreeing.
-   *
-   * Why accounts: it is the right population for anything that needs an account
-   * to act on — the share dialog's fanout, the unit-scoped members table. It is
-   * backed by `home_assignments`, whose `user_id` is NOT NULL, so an accountless
-   * person structurally cannot appear in it. Deliberately NOT redefined and NOT
-   * deprecated; {@link placedPeopleCount} answers the headcount question, and the
-   * two legitimately disagree (ADR-CONTRACTS-150, ADR-BE-657).
-   */
-  memberCount: z
-    .number()
-    .int()
-    .min(0)
-    .describe(
-      "Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount.",
-    ),
-  /** Drives the "(N + M open)" count split in the people surfaces. */
-  openRoleCount: z
-    .number()
-    .int()
-    .min(0)
-    .describe(
-      "Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount.",
-    ),
-  /**
-   * Predicate: `placement_role='canonical'`, `status <> 'ended'`, keyed by
-   * `positions.unit_id`. Placement and home are independent graphs
-   * (ADR-CTRL-159), so a person seated here may be homed elsewhere and vice
-   * versa. The `positions.status` non-filter stated in the `.describe()` below
-   * is deliberate and load-bearing — the backend pins it with a test whose name
-   * says so (ADR-BE-657).
-   */
-  placedPeopleCount: z
-    .number()
-    .int()
-    .min(0)
-    .describe(
-      "Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it.",
-    ),
-  missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
-});
-
-export const OrgUnitMembershipSchema = z.object({
-  id: z.string().uuid(),
-  orgId: z.string().uuid(),
-  unitId: z.string().uuid(),
-  userId: z.string().uuid(),
-  membershipRole: UnitMembershipRoleSchema,
-  status: OrgUnitMembershipStatusSchema,
-  source: OrgUnitMembershipSourceSchema,
-  sourceRef: z.string().nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-
-/**
- * An open role — a persisted placeholder for the person who will sit in a unit.
- * Carries unit membership (a seat) but never authority. `title` and
- * `targetStartDate` are optional planning attributes. On `fill`, `filledByUserId`
- * points at the seated user and a real `org_unit_membership` is created; the row
- * is kept as staffing history. `targetStartDate` is an ISO date (YYYY-MM-DD).
- */
-export const OpenRoleSchema = z.object({
-  id: z.string().uuid(),
-  orgId: z.string().uuid(),
-  unitId: z.string().uuid(),
-  title: z.string().nullable(),
-  targetStartDate: z.string().nullable(),
-  status: OpenRoleStatusSchema,
-  filledByUserId: z.string().uuid().nullable(),
-  // The open role's own reporting edge (ADR-BE-291): defaults to its creator's
-  // seat, editable/clearable. Drives chart placement now that the unit-head
-  // anchor is retired (ADR-BE-292). Null → unmanaged (Unassigned bucket).
-  //
-  // The manager POSITION, not a user (ADR-CONTRACTS-131). The retired
-  // user-keyed flattening was a lie in two directions: an open-role manager
-  // already surfaced as null because it had no user to collapse to, and
-  // post-HRIS every open role reporting to an imported (accountless) manager
-  // would read null too.
-  reportsToPositionId: z.string().uuid().nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-
-// ---------------------------------------------------------------------------
-// Authority & Delegation vocabulary
-//
-// The API expresses authority as orthogonal axes (mechanism × locality ×
-// mutability) instead of a single overloaded `source` enum, so future
-// combinations like inherited-delegated or hris-delegated compose by
-// construction rather than forcing each consumer to add a new switch case.
-// The engine's internal AuthoritySource enum stays narrower than the wire
-// shape — it's debug/audit vocabulary, not API vocabulary.
-// ---------------------------------------------------------------------------
-
-/**
- * Engine-internal authority source. Used by the projection storage layer for
- * debugging and drift records; not part of the public API response shape.
- * `manual_membership` was removed when the legacy `l{N}_unit_owner` track was
- * canonicalized onto delegations.
- */
-export const AuthoritySourceSchema = z.enum([
-  "structural",
-  "delegated",
-  "org_admin",
-]);
-export type AuthoritySource = z.infer<typeof AuthoritySourceSchema>;
-
-export const AuthorityOriginSchema = z.enum([
-  "topology",
-  "delegation",
-  "administrative_override",
-]);
-export type AuthorityOrigin = z.infer<typeof AuthorityOriginSchema>;
-
-export const AuthorityConfidenceSchema = z.enum(["authoritative", "inferred"]);
-export type AuthorityConfidence = z.infer<typeof AuthorityConfidenceSchema>;
-
-/** How the authority arose. */
-export const AuthorityMechanismSchema = z.enum([
-  "structural",
-  "delegated",
-  "rbac",
-]);
-export type AuthorityMechanism = z.infer<typeof AuthorityMechanismSchema>;
-
-/** Whether the grant lives on the target unit or is inherited from an ancestor. */
-export const AuthorityLocalitySchema = z.enum(["local", "inherited"]);
-export type AuthorityLocality = z.infer<typeof AuthorityLocalitySchema>;
-
-// AuthorityMutabilitySchema is defined above (hoisted next to
-// WorkspaceMemberUnitDesignationEntrySchema, which also carries it).
-
-export const OwnerAuthoritySchema = z.object({
-  mechanism: AuthorityMechanismSchema,
-  locality: AuthorityLocalitySchema,
-  mutability: AuthorityMutabilitySchema,
-  derivedFromUnitId: z.string().uuid(),
-  derivedFromUnitName: z.string().min(1).optional(),
-  /**
-   * True when this authority derives from the org ROOT unit — i.e. the holder
-   * is a CEO (a unit owner of the org root, observed locally on the root
-   * or as inherited authority on a descendant). Lets consumers classify CEO
-   * without a separate org-tree lookup, the same way `mechanism === 'rbac'`
-   * identifies an org admin. Omitted (falsy) for non-root derivations.
-   */
-  derivedFromRoot: z.boolean().optional(),
-  derivedFromUserId: z.string().uuid().nullable().optional(),
-  /**
-   * Human-readable reason this authority applies, built at serialize time from
-   * the strategy's derivation metadata. Foundation for trust UI, debugging,
-   * AI explainability, governance reports, and audits.
-   */
-  explanation: z.string(),
-  /**
-   * Strategy-specific structured metadata, preserved verbatim for tooling that
-   * needs more than the explanation string (drift detection, audits).
-   */
-  derivationMetadata: z.record(z.string(), z.unknown()).optional(),
-  /**
-   * `org_unit_delegations.id` when `mechanism === 'delegated'`. Surfaced
-   * separately so the UI doesn't need to inspect derivationMetadata to render
-   * the revoke action.
-   */
-  delegationId: z.string().uuid().optional(),
-  /**
-   * Delegation expiry as an ISO-8601 timestamp when `mechanism === 'delegated'`
-   * and the delegation is time-boxed; `null` for a permanent delegation; omitted
-   * for non-delegated mechanisms. Expired delegations never reach this surface —
-   * the projection read filters `expires_at > now()` — so a present value is
-   * always in the future.
-   */
-  expiresAt: IsoDateTime.nullable().optional(),
-});
-export type OwnerAuthority = z.infer<typeof OwnerAuthoritySchema>;
-
-export const OrgUnitOwnerSchema = z.object({
-  userId: z.string().uuid(),
-  fullName: z.string().min(1),
-  jobTitle: z.string().nullable(),
-  avatarUrl: z.string().nullable(),
-  /** All authority grants this user holds for the unit. At least one entry. */
-  authorities: z.array(OwnerAuthoritySchema).min(1),
-});
-export type OrgUnitOwner = z.infer<typeof OrgUnitOwnerSchema>;
-
-/**
- * A lead the structure review chose who is NOT YET an owner, because they have
- * no account to grant to. Mirrors one `staged` row of the backend's lead → owner
- * bridge ledger (ADR-BE-734): the grant is minted the moment the person links an
- * account, attributed to the reviewer who decided it. Person-keyed on purpose —
- * an owner is user-keyed and this person has no user.
- *
- * DISPLAY ONLY. Never an authorization input: a pending owner holds nothing
- * until the grant exists, and consumers must not derive a capability from it.
- */
-export const PendingUnitOwnerSchema = z.object({
-  personId: z.string().uuid(),
-  fullName: z.string().min(1),
-  jobTitle: z.string().nullable(),
-  /** When the reviewer decided it — the answer's time, not the row's. */
-  decidedAt: IsoDateTime,
-  /** Why it is pending. One reason today; a closed enum so a second is a decision. */
-  reason: z.enum(["no_account"]),
-});
-export type PendingUnitOwner = z.infer<typeof PendingUnitOwnerSchema>;
-
-/**
- * "No lead for now" (ADR-BE-733): the latest `unit_head` review answer for the
- * unit was an explicit clear, and no later answer superseded it. Distinct from
- * "never had one" — an absence a person recorded, not a default. Display only.
- */
-export const UnitLeadClearedSchema = z.object({
-  decidedAt: IsoDateTime,
-});
-export type UnitLeadCleared = z.infer<typeof UnitLeadClearedSchema>;
-
-/**
- * Contract-level invariant: each owner list contains each userId at most once.
- * Duplicate userIds are a serializer bug, not a presentation concern, so we
- * fail Zod parse at the API boundary on both server and client.
- */
-const uniqueByUserId = (arr: ReadonlyArray<{ userId: string }>): boolean =>
-  new Set(arr.map((o) => o.userId)).size === arr.length;
-const uniqueByPersonId = (arr: ReadonlyArray<{ personId: string }>): boolean =>
-  new Set(arr.map((o) => o.personId)).size === arr.length;
-
-export const OrgUnitOwnersResponseSchema = z.object({
-  owners: z
-    .array(OrgUnitOwnerSchema)
-    .refine(uniqueByUserId, { message: "duplicate userId in owners" }),
-  inherited: z
-    .array(OrgUnitOwnerSchema)
-    .refine(uniqueByUserId, { message: "duplicate userId in inherited" })
-    .optional(),
-  /**
-   * Leads chosen in the structure review who become owners once they have an
-   * account. Always present (`[]` when none) — the server knows, so the client
-   * never has to guess between "none" and "not asked".
-   */
-  pending: z
-    .array(PendingUnitOwnerSchema)
-    .refine(uniqueByPersonId, { message: "duplicate personId in pending" }),
-  /** The recorded "no lead for now", or null when no such answer stands. */
-  leadCleared: UnitLeadClearedSchema.nullable(),
-});
-export type OrgUnitOwnersResponse = z.infer<typeof OrgUnitOwnersResponseSchema>;
-
-export const DelegationSchema = z.object({
-  id: z.string().uuid(),
-  orgId: z.string().uuid(),
-  unitId: z.string().uuid(),
-  userId: z.string().uuid(),
-  grantedBy: z.string().uuid().nullable(),
-  grantedAt: z.string(),
-  revokedAt: z.string().nullable(),
-  status: z.enum(["active", "revoked"]),
-  note: z.string().nullable(),
-  /**
-   * ISO-8601 timestamp at which the delegation stops conferring authority, or
-   * `null` for a permanent delegation. Enforcement is read-time (the projection
-   * read filters `expires_at > now()`); the row itself stays `status='active'`
-   * until explicitly revoked.
-   */
-  expiresAt: z.string().nullable(),
-});
-export type Delegation = z.infer<typeof DelegationSchema>;
-
-export const CreateDelegationRequestSchema = z.object({
-  userId: z.string().uuid(),
-  note: z.string().max(2000).optional(),
-  /**
-   * Optional ISO-8601 expiry. Omitted or `null` ⇒ a permanent delegation. The
-   * UI captures a date and sends end-of-day in the user's timezone.
-   */
-  expiresAt: IsoDateTime.nullable().optional(),
-  /**
-   * When true, the granted user is emailed a notification (carrying `note` as
-   * the message). Not persisted — it only gates the side-effect email. Omitted
-   * is treated as false; left without a default so the inferred request type
-   * keeps `notify` optional rather than forcing every caller to pass it.
-   */
-  notify: z.boolean().optional(),
-});
-export type CreateDelegationRequest = z.infer<
-  typeof CreateDelegationRequestSchema
->;
-
-/**
- * Change a delegation's expiry without revoking it: extend, shorten, or clear
- * (set `expiresAt: null` to make it permanent). Used by the inline expiry edit
- * on an existing delegate row.
- */
-export const UpdateDelegationRequestSchema = z.object({
-  expiresAt: IsoDateTime.nullable(),
-});
-export type UpdateDelegationRequest = z.infer<
-  typeof UpdateDelegationRequestSchema
->;
-
-export const DelegationListResponseSchema = z.object({
-  delegations: z.array(DelegationSchema),
-});
-export type DelegationListResponse = z.infer<
-  typeof DelegationListResponseSchema
->;
-
-export const OrgUnitRelationshipSchema = z.object({
-  id: z.string().uuid(),
-  orgId: z.string().uuid(),
-  fromUnit: z.string().uuid(),
-  toUnit: z.string().uuid(),
-  type: OrgUnitRelationshipTypeSchema,
-  role: OrgUnitRelationshipRoleSchema,
-  contextKey: z.string().nullable(),
-  metadata: z.record(z.string(), z.unknown()),
-  createdAt: z.string(),
-});
-
-export const OrgLevelIconSchema = z.enum([
-  "city",
-  "buildings",
-  "users-four",
-  "users-three",
-  "users",
-]);
-
-export const OrgLevelConfigSchema = z.object({
-  orgId: z.string().uuid(),
-  depth: z.number().int().min(1).max(ORG_UNIT_ABSOLUTE_MAX_DEPTH),
-  label: z.string().min(1).nullable(),
-  labelPlural: z.string().min(1).nullable(),
-  icon: OrgLevelIconSchema.nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-
-// --- Response schemas (request schemas live in backend per ADR-CONT-044) ---
-
-export const OrgUnitResponseSchema = z.object({ unit: OrgUnitSchema });
-
-export const OrgUnitTreeResponseSchema = z.object({
-  nodes: z.array(OrgUnitTreeNodeSchema),
-  levelConfig: z.array(OrgLevelConfigSchema),
-});
-
-export const OrgUnitChildrenResponseSchema = z.object({
-  parentId: z.string().uuid(),
-  children: z.array(OrgUnitTreeNodeSchema),
-});
-
-export const OrgUnitAncestorsResponseSchema = z.object({
-  unitId: z.string().uuid(),
-  ancestors: z.array(OrgUnitSchema),
-});
-
-export const OrgUnitDescendantsResponseSchema = z.object({
-  rootId: z.string().uuid(),
-  descendants: z.array(OrgUnitSchema),
-});
-
-export const OrgUnitRelationshipsResponseSchema = z.object({
-  unitId: z.string().uuid(),
-  incoming: z.array(OrgUnitRelationshipSchema),
-  outgoing: z.array(OrgUnitRelationshipSchema),
-});
-
-export const OrgLevelConfigResponseSchema = z.object({
-  entries: z.array(OrgLevelConfigSchema),
-});
-
-export const OrgUnitMembershipResponseSchema = z.object({
-  membership: OrgUnitMembershipSchema,
-});
-
-export const OrgUnitMembershipListResponseSchema = z.object({
-  unitId: z.string().uuid(),
-  memberships: z.array(OrgUnitMembershipSchema),
-});
-
-// ---------------------------------------------------------------------------
-// Open roles (PRD open-roles)
-// Request schemas are colocated here (a narrow deviation from ADR-CONT-044, as
-// with UpdateOrgUnitRequest) so the app's add-role form and the backend
-// validate against one published shape.
-// ---------------------------------------------------------------------------
-
-export const OpenRoleResponseSchema = z.object({ openRole: OpenRoleSchema });
-
-export const OpenRoleListResponseSchema = z.object({
-  unitId: z.string().uuid(),
-  openRoles: z.array(OpenRoleSchema),
-});
-
-/** ISO calendar date (YYYY-MM-DD) — version-agnostic vs `z.string().date()`. */
-const IsoDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
-  message: "must be an ISO date (YYYY-MM-DD)",
-});
-
-export const CreateOpenRoleRequestSchema = z.object({
-  title: z.string().min(1).max(255).nullable().optional(),
-  targetStartDate: IsoDateSchema.nullable().optional(),
-});
-
-/** Only the non-terminal client transitions are accepted; `fill` is its own
- * endpoint and `open` is the seeded initial state, never set by the client. */
-export const UpdateOpenRoleStatusRequestSchema = z.object({
-  status: z.enum(["hiring", "closed"]),
-});
-
-/**
- * Fill an open role by seating an existing org member (`userId`) or inviting a
- * new person by email. Exactly one branch — a discriminated union keyed on `mode`.
- */
-export const FillOpenRoleRequestSchema = z.discriminatedUnion("mode", [
-  z.object({ mode: z.literal("existing"), userId: z.string().uuid() }),
-  z.object({
-    mode: z.literal("invite"),
-    email: z.string().email(),
-    role: z.enum(["admin", "member"]),
-  }),
-]);
-
-/**
- * Effective manager of an org unit — a user whose membership (direct or
- * inherited from an ancestor) grants the `orgUnit.{id}.manage` capability.
- *
- * Direct grants have `inheritedFromUnitId === unitId`. For inherited grants,
- * `inheritedFromUnitId` identifies the ancestor whose membership propagates
- * authority down the subtree (ltree `path @>` containment).
- */
-export const OrgUnitPermissionsEntrySchema = z.object({
-  userId: z.string().uuid(),
-  membershipRole: UnitMembershipRoleSchema,
-  inheritedFromUnitId: z.string().uuid(),
-  inheritedFromUnitName: z.string().min(1),
-});
-
-export const ListOrgUnitPermissionsResponseSchema = z.object({
-  unitId: z.string().uuid(),
-  entries: z.array(OrgUnitPermissionsEntrySchema),
-});
-
-// ---------------------------------------------------------------------------
-// PATCH /api/org-units/:unitId (PRD-00526)
-// Request schema colocated with the response schema so the app can import
-// the same shape backend validates against. This is a narrow deviation from
-// ADR-CONT-044 (request schemas normally live in backend) because the
-// partial-update + at-least-one-field refinement is the published promise
-// consumers must satisfy.
-// ---------------------------------------------------------------------------
-
-export const UpdateOrgUnitRequestSchema = z
-  .object({
-    name: z.string().min(1).max(255).optional(),
-    description: z.string().max(2000).nullable().optional(),
-  })
-  .refine((v) => v.name !== undefined || v.description !== undefined, {
-    message: "at least one of name or description must be provided",
-  });
-
-export const UpdateOrgUnitResponseSchema = z.object({ unit: OrgUnitSchema });
-
-// --- Inferred types ---
-
-export type OrgUnit = z.infer<typeof OrgUnitSchema>;
-export type OrgUnitTreeNode = z.infer<typeof OrgUnitTreeNodeSchema>;
-export type OrgUnitMembership = z.infer<typeof OrgUnitMembershipSchema>;
-export type OrgUnitRelationship = z.infer<typeof OrgUnitRelationshipSchema>;
-export type OrgLevelConfig = z.infer<typeof OrgLevelConfigSchema>;
-export type OrgLevelIcon = z.infer<typeof OrgLevelIconSchema>;
-export type OrgUnitResponse = z.infer<typeof OrgUnitResponseSchema>;
-export type OrgUnitTreeResponse = z.infer<typeof OrgUnitTreeResponseSchema>;
-export type MissingAtNextLevel = z.infer<typeof MissingAtNextLevelSchema>;
-export type OrgUnitChildrenResponse = z.infer<
-  typeof OrgUnitChildrenResponseSchema
->;
-export type OrgUnitAncestorsResponse = z.infer<
-  typeof OrgUnitAncestorsResponseSchema
->;
-export type OrgUnitDescendantsResponse = z.infer<
-  typeof OrgUnitDescendantsResponseSchema
->;
-export type OrgUnitRelationshipsResponse = z.infer<
-  typeof OrgUnitRelationshipsResponseSchema
->;
-export type OrgLevelConfigResponse = z.infer<
-  typeof OrgLevelConfigResponseSchema
->;
-export type OrgUnitMembershipResponse = z.infer<
-  typeof OrgUnitMembershipResponseSchema
->;
-export type OrgUnitMembershipListResponse = z.infer<
-  typeof OrgUnitMembershipListResponseSchema
->;
-export type OpenRole = z.infer<typeof OpenRoleSchema>;
-export type OpenRoleResponse = z.infer<typeof OpenRoleResponseSchema>;
-export type OpenRoleListResponse = z.infer<typeof OpenRoleListResponseSchema>;
-export type CreateOpenRoleRequest = z.infer<typeof CreateOpenRoleRequestSchema>;
-export type UpdateOpenRoleStatusRequest = z.infer<
-  typeof UpdateOpenRoleStatusRequestSchema
->;
-export type FillOpenRoleRequest = z.infer<typeof FillOpenRoleRequestSchema>;
-export type OrgUnitPermissionsEntry = z.infer<
-  typeof OrgUnitPermissionsEntrySchema
->;
-export type ListOrgUnitPermissionsResponse = z.infer<
-  typeof ListOrgUnitPermissionsResponseSchema
->;
-export type UpdateOrgUnitRequest = z.infer<typeof UpdateOrgUnitRequestSchema>;
-export type UpdateOrgUnitResponse = z.infer<typeof UpdateOrgUnitResponseSchema>;
-
 // =============================================================================
 // Mutation Capabilities (GET /api/capabilities) — ADR-BE-241 / PRD-00707 F4
 // =============================================================================