@company-semantics/contracts 9.0.0 → 9.2.0

package/src/org/schemas.ts

@@ -10,9 +10,9 @@
  *  - 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)
  */
-import { z } from 'zod';
-import { CursorPageSchema } from '../api/primitives';
-import { OrgChartRoleSchema } from '../permissions/orgchart-roles';
+import { z } from "zod";
+import { CursorPageSchema } from "../api/primitives";
+import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
 
 // ---------------------------------------------------------------------------
 // Sub-schemas
@@ -22,7 +22,7 @@ const WorkspaceMemberUnitSummarySchema = z.object({
   unitId: z.string(),
   unitName: z.string(),
   unitPath: z.string(),
-  role: z.enum(['owner', 'manager', 'member']),
+  role: z.enum(["owner", "manager", "member"]),
 });
 
 /**
@@ -35,11 +35,11 @@ const WorkspaceMemberUnitSummarySchema = z.object({
  * the orthogonal membership/delegation axes, not this enum).
  */
 export const OrgUnitDesignationSchema = z.enum([
-  'whole_org',
-  'admin',
-  'leader',
-  'delegate',
-  'member',
+  "whole_org",
+  "admin",
+  "leader",
+  "delegate",
+  "member",
 ]);
 export type OrgUnitDesignation = z.infer<typeof OrgUnitDesignationSchema>;
 
@@ -48,7 +48,9 @@ export const WorkspaceMemberManagesEntrySchema = z.object({
   unitName: z.string(),
   designation: OrgUnitDesignationSchema,
 });
-export type WorkspaceMemberManagesEntry = z.infer<typeof WorkspaceMemberManagesEntrySchema>;
+export type WorkspaceMemberManagesEntry = z.infer<
+  typeof WorkspaceMemberManagesEntrySchema
+>;
 
 const WorkspaceMemberSchema = z.object({
   id: z.string(),
@@ -93,7 +95,7 @@ const WorkspaceMemberSchema = z.object({
   /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
   unitMembershipsTruncated: z.boolean(),
   /** Invite lifecycle status. `null` for members without an invite record. */
-  inviteStatus: z.enum(['active', 'pending', 'expired']).nullable(),
+  inviteStatus: z.enum(["active", "pending", "expired"]).nullable(),
 });
 
 const MemberRecentActionSchema = z.object({
@@ -123,7 +125,7 @@ export type WorkspaceMemberDetail = z.infer<typeof WorkspaceMemberDetailSchema>;
 
 export const RoleCatalogEntrySchema = z.object({
   name: z.string(),
-  type: z.enum(['system', 'custom']),
+  type: z.enum(["system", "custom"]),
   description: z.string(),
   scopes: z.array(z.string()),
   memberCount: z.number().int().nonnegative(),
@@ -147,7 +149,9 @@ export const WorkspaceAccessResponseSchema = z.object({
   hasAccess: z.boolean(),
 });
 
-export type WorkspaceAccessResponse = z.infer<typeof WorkspaceAccessResponseSchema>;
+export type WorkspaceAccessResponse = z.infer<
+  typeof WorkspaceAccessResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // GET /api/workspace
@@ -158,7 +162,7 @@ export const WorkspaceOverviewSchema = z.object({
   id: z.string(),
   name: z.string(),
   slug: z.string(),
-  type: z.enum(['personal', 'shared']),
+  type: z.enum(["personal", "shared"]),
   logoUrl: z.string().nullable(),
   owner: WorkspaceOwnerSchema,
   createdAt: z.string(),
@@ -172,9 +176,13 @@ export type WorkspaceOverview = z.infer<typeof WorkspaceOverviewSchema>;
 // GET /api/workspace/members
 // ---------------------------------------------------------------------------
 
-export const WorkspaceMembersResponseSchema = CursorPageSchema(WorkspaceMemberSchema);
+export const WorkspaceMembersResponseSchema = CursorPageSchema(
+  WorkspaceMemberSchema,
+);
 
-export type WorkspaceMembersResponse = z.infer<typeof WorkspaceMembersResponseSchema>;
+export type WorkspaceMembersResponse = z.infer<
+  typeof WorkspaceMembersResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // GET /api/workspace/auth
@@ -185,7 +193,9 @@ const OidcValidationResultSchema = z.object({
   issuer: z.string().optional(),
   authorizationEndpoint: z.string().optional(),
   error: z.string().optional(),
-  errorCode: z.enum(['UNREACHABLE', 'INVALID_DOCUMENT', 'MISSING_FIELDS', 'SSRF_BLOCKED']).optional(),
+  errorCode: z
+    .enum(["UNREACHABLE", "INVALID_DOCUMENT", "MISSING_FIELDS", "SSRF_BLOCKED"])
+    .optional(),
 });
 
 const SsoDiscoveryConfigSchema = z.object({
@@ -201,14 +211,14 @@ const SsoCredentialStatusSchema = z.object({
 });
 
 const ProviderStatusSchema = z.enum([
-  'NOT_CONFIGURED',
-  'CONFIG_SAVED',
-  'CONFIG_VALID',
-  'TEST_SUCCESS',
-  'ENABLED',
+  "NOT_CONFIGURED",
+  "CONFIG_SAVED",
+  "CONFIG_VALID",
+  "TEST_SUCCESS",
+  "ENABLED",
 ]);
 
-const SsoStepperStepSchema = z.enum(['configure', 'test', 'enable', 'enforce']);
+const SsoStepperStepSchema = z.enum(["configure", "test", "enable", "enforce"]);
 
 const SsoOperationalStateSchema = z.object({
   providerStatus: ProviderStatusSchema,
@@ -221,9 +231,9 @@ const SsoOperationalStateSchema = z.object({
   lastTestSuccessProvider: z.string().optional(),
 });
 
-const SsoSetupInfoSchema = SsoDiscoveryConfigSchema.merge(SsoCredentialStatusSchema).merge(
-  SsoOperationalStateSchema
-);
+const SsoSetupInfoSchema = SsoDiscoveryConfigSchema.merge(
+  SsoCredentialStatusSchema,
+).merge(SsoOperationalStateSchema);
 
 const SsoReadinessCheckSchema = z.object({
   code: z.string(),
@@ -253,8 +263,8 @@ const OwnerIdentityInfoSchema = z.object({
 });
 
 const ProviderSuggestionSchema = z.object({
-  suggestedProvider: z.enum(['google', 'microsoft']).nullable(),
-  confidence: z.enum(['high', 'low']),
+  suggestedProvider: z.enum(["google", "microsoft"]).nullable(),
+  confidence: z.enum(["high", "low"]),
   reason: z.string(),
   detectedDomain: z.string().optional(),
 });
@@ -276,7 +286,9 @@ export const WorkspaceAuthConfigSchema = z.object({
   ssoSetup: SsoSetupInfoSchema.optional(),
   ssoReadiness: SsoReadinessSchema.optional(),
   ssoEnforcement: SsoEnforcementStatusSchema.optional(),
-  workspaceSsoState: z.enum(['SSO_DISABLED', 'SSO_ENABLED', 'SSO_ENFORCED']).optional(),
+  workspaceSsoState: z
+    .enum(["SSO_DISABLED", "SSO_ENABLED", "SSO_ENFORCED"])
+    .optional(),
   ownerIdentities: z.array(OwnerIdentityInfoSchema).optional(),
   providerSuggestion: ProviderSuggestionSchema.optional(),
 });
@@ -293,7 +305,7 @@ export const WorkspaceAuditEventSchema = z.object({
   actor: z.object({
     id: z.string(),
     name: z.string(),
-    type: z.enum(['user', 'system']),
+    type: z.enum(["user", "system"]),
   }),
   action: z.string(),
   summary: z.string(),
@@ -316,15 +328,20 @@ const ResolvedDeptEntitySchema = z.object({
 
 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']) }),
-    ])
+    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>;
+export type WorkspaceResolvePathResponse = z.infer<
+  typeof WorkspaceResolvePathResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // PATCH /api/workspace/auth-policy
@@ -354,7 +371,9 @@ export const WorkspaceResyncSlackLogoResponseSchema = z.object({
   logoUrl: z.string().nullable(),
 });
 
-export type WorkspaceResyncSlackLogoResponse = z.infer<typeof WorkspaceResyncSlackLogoResponseSchema>;
+export type WorkspaceResyncSlackLogoResponse = z.infer<
+  typeof WorkspaceResyncSlackLogoResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // POST /api/workspace/auth-policy/test-sso
@@ -372,7 +391,7 @@ export type TestSsoInitiation = z.infer<typeof TestSsoInitiationSchema>;
 // ---------------------------------------------------------------------------
 
 export const TestSsoResultSchema = z.object({
-  status: z.enum(['pending', 'success', 'failed', 'expired']),
+  status: z.enum(["pending", "success", "failed", "expired"]),
   claims: z
     .object({
       sub: z.string(),
@@ -384,7 +403,12 @@ export const TestSsoResultSchema = z.object({
   identityLinked: z.boolean().optional(),
   error: z.string().optional(),
   errorCode: z
-    .enum(['IDENTITY_CONFLICT', 'DOMAIN_MISMATCH', 'ISSUER_MISMATCH', 'CALLBACK_ERROR'])
+    .enum([
+      "IDENTITY_CONFLICT",
+      "DOMAIN_MISMATCH",
+      "ISSUER_MISMATCH",
+      "CALLBACK_ERROR",
+    ])
     .optional(),
 });
 
@@ -416,7 +440,9 @@ export const ChangeMemberRoleResponseSchema = z.object({
   message: z.string(),
 });
 
-export type ChangeMemberRoleResponse = z.infer<typeof ChangeMemberRoleResponseSchema>;
+export type ChangeMemberRoleResponse = z.infer<
+  typeof ChangeMemberRoleResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // GET /api/user/orgs
@@ -430,7 +456,7 @@ const UserOrgMembershipSchema = z.object({
   role: OrgChartRoleSchema.nullable(),
   joinedAt: z.string(),
   isActive: z.boolean(),
-  orgType: z.enum(['personal', 'shared']),
+  orgType: z.enum(["personal", "shared"]),
 });
 
 export const UserOrgsResponseSchema = z.object({
@@ -479,7 +505,9 @@ export const ScopeCheckBatchResponseSchema = z.object({
   results: z.record(z.string(), z.object({ hasAccess: z.boolean() })),
 });
 
-export type ScopeCheckBatchResponse = z.infer<typeof ScopeCheckBatchResponseSchema>;
+export type ScopeCheckBatchResponse = z.infer<
+  typeof ScopeCheckBatchResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // Invite sub-schema
@@ -489,9 +517,9 @@ const OrgInviteSchema = z.object({
   id: z.string(),
   orgId: z.string(),
   email: z.string(),
-  role: z.enum(['admin', 'member']),
+  role: z.enum(["admin", "member"]),
   invitedBy: z.object({ id: z.string(), name: z.string() }),
-  status: z.enum(['pending', 'accepted', 'expired', 'revoked']),
+  status: z.enum(["pending", "accepted", "expired", "revoked"]),
   createdAt: z.string(),
   expiresAt: z.string(),
   acceptedAt: z.string().optional(),
@@ -523,12 +551,14 @@ 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']),
+  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(),
+  verifiedBy: z
+    .object({ id: z.string(), name: z.string(), email: z.string() })
+    .optional(),
 });
 
 // ---------------------------------------------------------------------------
@@ -554,7 +584,7 @@ export type DomainListResponse = z.infer<typeof DomainListResponseSchema>;
 
 export const OrgBillingResponseSchema = z.object({
   planName: z.string(),
-  planStatus: z.enum(['active', 'trialing', 'past_due', 'canceled']),
+  planStatus: z.enum(["active", "trialing", "past_due", "canceled"]),
   billingCadence: z.string(),
   seatCount: z.number(),
   seatLimit: z.number(),
@@ -570,7 +600,7 @@ export type OrgBillingResponse = z.infer<typeof OrgBillingResponseSchema>;
 const MemberClassificationSchema = z.object({
   userId: z.string(),
   email: z.string(),
-  suggestedFate: z.enum(['REMOVE_FROM_ORG', 'DELETE_ACCOUNT', 'BLOCKED']),
+  suggestedFate: z.enum(["REMOVE_FROM_ORG", "DELETE_ACCOUNT", "BLOCKED"]),
   reason: z.string(),
 });
 
@@ -595,7 +625,9 @@ export const OwnershipTransferResponseSchema = z.object({
   message: z.string(),
 });
 
-export type OwnershipTransferResponse = z.infer<typeof OwnershipTransferResponseSchema>;
+export type OwnershipTransferResponse = z.infer<
+  typeof OwnershipTransferResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // POST /api/org/transfer-ownership/preview
@@ -610,7 +642,9 @@ export const OwnershipTransferPreviewSchema = z.object({
   token: z.string(),
 });
 
-export type OwnershipTransferPreview = z.infer<typeof OwnershipTransferPreviewSchema>;
+export type OwnershipTransferPreview = z.infer<
+  typeof OwnershipTransferPreviewSchema
+>;
 
 // ---------------------------------------------------------------------------
 // GET /api/org/system-events
@@ -637,7 +671,9 @@ export const AcknowledgeSystemEventResponseSchema = z.object({
   success: z.literal(true),
 });
 
-export type AcknowledgeSystemEventResponse = z.infer<typeof AcknowledgeSystemEventResponseSchema>;
+export type AcknowledgeSystemEventResponse = z.infer<
+  typeof AcknowledgeSystemEventResponseSchema
+>;
 
 // ---------------------------------------------------------------------------
 // GET /api/orgs/:orgId/budget-config
@@ -723,28 +759,36 @@ export type OrgUsageResponse = z.infer<typeof OrgUsageResponseSchema>;
 // ---------------------------------------------------------------------------
 
 export const OrgUnitClassificationSchema = z.enum([
-  'execution_unit',
-  'org_container',
-  'leadership',
-  'custom',
+  "execution_unit",
+  "org_container",
+  "leadership",
+  "custom",
 ]);
 
 export const OrgUnitSyncModeSchema = z.enum([
-  'manual_only',
-  'synced_readonly',
-  'synced_with_overrides',
+  "manual_only",
+  "synced_readonly",
+  "synced_with_overrides",
 ]);
 
-export const OrgUnitVisibilitySchema = z.enum(['public', 'private', 'restricted']);
+export const OrgUnitVisibilitySchema = z.enum([
+  "public",
+  "private",
+  "restricted",
+]);
 
 export const OrgUnitRelationshipTypeSchema = z.enum([
-  'collaborates_with',
-  'reports_to',
-  'depends_on',
-  'custom',
+  "collaborates_with",
+  "reports_to",
+  "depends_on",
+  "custom",
 ]);
 
-export const OrgUnitRelationshipRoleSchema = z.enum(['owner', 'participant', 'supporting']);
+export const OrgUnitRelationshipRoleSchema = z.enum([
+  "owner",
+  "participant",
+  "supporting",
+]);
 
 /**
  * Positional slot a member holds in the org-unit tree. ORTHOGONAL to the
@@ -752,36 +796,40 @@ export const OrgUnitRelationshipRoleSchema = z.enum(['owner', 'participant', 'su
  * not the derived policy role). Level is encoded in the value (l1…l5).
  */
 export const UnitMembershipRoleSchema = z.enum([
-  'member',
-  'l1_unit_owner',
-  'l2_unit_owner',
-  'l3_unit_owner',
-  'l4_unit_owner',
-  'l5_unit_owner',
+  "member",
+  "l1_unit_owner",
+  "l2_unit_owner",
+  "l3_unit_owner",
+  "l4_unit_owner",
+  "l5_unit_owner",
 ]);
 
 export type UnitMembershipRole = z.infer<typeof UnitMembershipRoleSchema>;
 
-export const OrgUnitMembershipStatusSchema = z.enum(['active', 'pending', 'removed']);
+export const OrgUnitMembershipStatusSchema = z.enum([
+  "active",
+  "pending",
+  "removed",
+]);
 
 export const OrgUnitMembershipSourceSchema = z.enum([
-  'manual',
-  'google_groups',
-  'scim',
-  'hris',
+  "manual",
+  "google_groups",
+  "scim",
+  "hris",
 ]);
 
 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',
+  "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({
@@ -853,32 +901,32 @@ export const OrgUnitMembershipSchema = z.object({
  * canonicalized onto delegations.
  */
 export const AuthoritySourceSchema = z.enum([
-  'structural',
-  'delegated',
-  'org_admin',
+  "structural",
+  "delegated",
+  "org_admin",
 ]);
 export type AuthoritySource = z.infer<typeof AuthoritySourceSchema>;
 
 export const AuthorityOriginSchema = z.enum([
-  'topology',
-  'delegation',
-  'administrative_override',
+  "topology",
+  "delegation",
+  "administrative_override",
 ]);
 export type AuthorityOrigin = z.infer<typeof AuthorityOriginSchema>;
 
-export const AuthorityConfidenceSchema = z.enum(['authoritative', 'inferred']);
+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',
+  "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 const AuthorityLocalitySchema = z.enum(["local", "inherited"]);
 export type AuthorityLocality = z.infer<typeof AuthorityLocalitySchema>;
 
 /**
@@ -886,7 +934,7 @@ export type AuthorityLocality = z.infer<typeof AuthorityLocalitySchema>;
  *  - `derived`: change the upstream source instead (the org chart, RBAC roles).
  *  - `user_managed`: removable from this UI.
  */
-export const AuthorityMutabilitySchema = z.enum(['derived', 'user_managed']);
+export const AuthorityMutabilitySchema = z.enum(["derived", "user_managed"]);
 export type AuthorityMutability = z.infer<typeof AuthorityMutabilitySchema>;
 
 export const OwnerAuthoritySchema = z.object({
@@ -953,10 +1001,10 @@ const uniqueByUserId = (arr: ReadonlyArray<{ userId: string }>): boolean =>
 export const OrgUnitOwnersResponseSchema = z.object({
   owners: z
     .array(OrgUnitOwnerSchema)
-    .refine(uniqueByUserId, { message: 'duplicate userId in owners' }),
+    .refine(uniqueByUserId, { message: "duplicate userId in owners" }),
   inherited: z
     .array(OrgUnitOwnerSchema)
-    .refine(uniqueByUserId, { message: 'duplicate userId in inherited' })
+    .refine(uniqueByUserId, { message: "duplicate userId in inherited" })
     .optional(),
 });
 export type OrgUnitOwnersResponse = z.infer<typeof OrgUnitOwnersResponseSchema>;
@@ -969,7 +1017,7 @@ export const DelegationSchema = z.object({
   grantedBy: z.string().uuid().nullable(),
   grantedAt: z.string(),
   revokedAt: z.string().nullable(),
-  status: z.enum(['active', 'revoked']),
+  status: z.enum(["active", "revoked"]),
   note: z.string().nullable(),
   /**
    * ISO-8601 timestamp at which the delegation stops conferring authority, or
@@ -997,7 +1045,9 @@ export const CreateDelegationRequestSchema = z.object({
    */
   notify: z.boolean().optional(),
 });
-export type CreateDelegationRequest = z.infer<typeof CreateDelegationRequestSchema>;
+export type CreateDelegationRequest = z.infer<
+  typeof CreateDelegationRequestSchema
+>;
 
 /**
  * Change a delegation's expiry without revoking it: extend, shorten, or clear
@@ -1007,12 +1057,16 @@ export type CreateDelegationRequest = z.infer<typeof CreateDelegationRequestSche
 export const UpdateDelegationRequestSchema = z.object({
   expiresAt: z.string().datetime().nullable(),
 });
-export type UpdateDelegationRequest = z.infer<typeof UpdateDelegationRequestSchema>;
+export type UpdateDelegationRequest = z.infer<
+  typeof UpdateDelegationRequestSchema
+>;
 
 export const DelegationListResponseSchema = z.object({
   delegations: z.array(DelegationSchema),
 });
-export type DelegationListResponse = z.infer<typeof DelegationListResponseSchema>;
+export type DelegationListResponse = z.infer<
+  typeof DelegationListResponseSchema
+>;
 
 export const OrgUnitRelationshipSchema = z.object({
   id: z.string().uuid(),
@@ -1027,11 +1081,11 @@ export const OrgUnitRelationshipSchema = z.object({
 });
 
 export const OrgLevelIconSchema = z.enum([
-  'city',
-  'buildings',
-  'users-four',
-  'users-three',
-  'users',
+  "city",
+  "buildings",
+  "users-four",
+  "users-three",
+  "users",
 ]);
 
 export const OrgLevelConfigSchema = z.object({
@@ -1116,12 +1170,14 @@ export const ListOrgUnitPermissionsResponseSchema = z.object({
 // 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 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 });
 
@@ -1136,14 +1192,95 @@ 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 OrgUnitPermissionsEntry = z.infer<typeof OrgUnitPermissionsEntrySchema>;
-export type ListOrgUnitPermissionsResponse = z.infer<typeof ListOrgUnitPermissionsResponseSchema>;
+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 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
+// =============================================================================
+// Canonical home for the viewer's resolved mutation-capability projection. The
+// backend derives it (src/capabilities/derive.ts) and validates the response
+// against CapabilitiesResponseSchema via sendValidated; the frontend reads the
+// inferred types to render lock/allow affordances. Previously duplicated as a
+// backend-local Zod + hand-written frontend interfaces — unified here.
+
+/** Scope identifiers are dot-namespaced strings (see backend trust/scopes.ts). */
+const RequiredScopeSchema = z.string();
+
+/** A mutable field's gate: editable, or locked with attribution (sso vs rbac). */
+export const FieldCapabilitySchema = z.object({
+  state: z.enum(["editable", "locked"]),
+  reason: z.enum(["sso", "rbac"]).optional(),
+  requiredScope: RequiredScopeSchema.optional(),
+});
+
+/** An action's gate: allowed, or blocked with the scope that would unlock it. */
+export const ActionCapabilitySchema = z.object({
+  state: z.enum(["allowed", "blocked"]),
+  requiredScope: RequiredScopeSchema.optional(),
+});
+
+/**
+ * The single validated capability surface the UI reads. Every sub-object is
+ * optional, matching the partial derivation in deriveCapabilities() (actions/org
+ * are present only when scopes resolved).
+ */
+export const CapabilitiesResponseSchema = z.object({
+  profile: z
+    .object({
+      fullName: FieldCapabilitySchema,
+      preferredName: FieldCapabilitySchema,
+    })
+    .optional(),
+  org: z
+    .object({
+      name: FieldCapabilitySchema,
+    })
+    .optional(),
+  actions: z
+    .object({
+      members: z.object({
+        invite: ActionCapabilitySchema,
+        remove: ActionCapabilitySchema,
+        changeRole: ActionCapabilitySchema,
+      }),
+      orgAdmins: z.object({
+        manage: ActionCapabilitySchema,
+      }),
+      orgUnit: z.object({
+        manage: ActionCapabilitySchema,
+      }),
+    })
+    .optional(),
+});
+
+export type FieldCapability = z.infer<typeof FieldCapabilitySchema>;
+export type ActionCapability = z.infer<typeof ActionCapabilitySchema>;
+export type CapabilitiesResponse = z.infer<typeof CapabilitiesResponseSchema>;