@opengeni/contracts 2.5.0-canary.2 → 2.7.0

package/src/index.ts

@@ -13,6 +13,12 @@ import { ClientResumableVoiceInputConfig } from "./transcription-recordings";
 import { MediaGenerationResult } from "./video-generation";
 import { KnowledgeProviderCitation } from "./knowledge";
 import { XaiProviderAccountAuthoritySnapshotV1 } from "./xai-provider-account-authority";
+import {
+  MAX_NESTED_AGENT_DEPTH,
+  NestedAgentDepthValue,
+  SessionGoalStatus,
+  SessionStatus,
+} from "./session-topology-primitives";
 
 export * from "./slack-bot-scopes";
 export * from "./slack-task-policy";
@@ -31,6 +37,9 @@ export * from "./interaction";
 export * from "./sandbox-file-artifacts";
 export * from "./permissions";
 export * from "./session-titles";
+export * from "./session-topology-primitives";
+export * from "./agent-topology";
+export * from "./work-claims";
 
 export {
   CreateWorkspaceArtifactRequest,
@@ -149,18 +158,6 @@ export {
   type ModalCheckpointProviderBinding,
 } from "./checkpoint-provider-bindings";
 
-export const SessionStatus = z.enum([
-  "queued",
-  "running",
-  "idle",
-  "requires_action",
-  "recovering",
-  "waiting_capacity",
-  "failed",
-  "cancelled",
-]);
-export type SessionStatus = z.infer<typeof SessionStatus>;
-
 // 12 backends; 3-way enum parity (contracts / sdk / deployment) is pinned by
 // `packages/sdk/test/contract-parity.test.ts`. Every member is ADDITIVE AT THE
 // END (the parity test pins positions): the original four, then the six cloud
@@ -680,10 +677,6 @@ export const ErrorEnvelope = z.object({
 });
 export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
 
-/** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
-export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
-export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
-export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;
 /** A denied child can be one greater than the persisted PostgreSQL int ceiling. */
 export const NestedAgentDepthAttemptValue = z
   .number()
@@ -779,6 +772,8 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "task_note_save",
   "task_note_archive",
   "task_note_replace",
+  "work_claim_upsert",
+  "work_claim_release",
   "knowledge_propose",
   "knowledge_correct",
   "task_note_promote_knowledge",
@@ -2965,13 +2960,15 @@ export const CreateWorkspaceRequest = z.object({
 });
 export type CreateWorkspaceRequest = z.infer<typeof CreateWorkspaceRequest>;
 
-export const UpdateWorkspaceRequest = z.object({
-  name: z.string().min(1).optional(),
-  slug: z.string().min(1).nullable().optional(),
-  // White-label persona override. Pass null to clear it back to the deployment
-  // default; omit to leave it unchanged.
-  agentInstructions: z.string().min(1).nullable().optional(),
-});
+export const UpdateWorkspaceRequest = z
+  .object({
+    name: z.string().min(1).optional(),
+    slug: z.string().min(1).nullable().optional(),
+    // White-label persona override. Pass null to clear it back to the deployment
+    // default; omit to leave it unchanged.
+    agentInstructions: z.string().min(1).nullable().optional(),
+  })
+  .strict();
 export type UpdateWorkspaceRequest = z.infer<typeof UpdateWorkspaceRequest>;
 
 export const ApiKey = z.object({
@@ -5561,9 +5558,6 @@ export type SessionControlState = z.infer<typeof SessionControlState>;
 export const WorkspaceInferenceState = z.enum(["active", "paused"]);
 export type WorkspaceInferenceState = z.infer<typeof WorkspaceInferenceState>;
 
-export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
-export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
-
 export const SessionGoalCreatedBy = z.enum(["api", "agent", "scheduled_task"]);
 export type SessionGoalCreatedBy = z.infer<typeof SessionGoalCreatedBy>;
 
@@ -7727,6 +7721,44 @@ export type VariableSetSecret = z.infer<typeof VariableSetSecret>;
 export const VariableSetScope = z.enum(["organization", "workspace", "user"]);
 export type VariableSetScope = z.infer<typeof VariableSetScope>;
 
+/**
+ * Exact-ID metadata used only to validate attachments. This deliberately omits
+ * names, descriptions, and variable-name metadata so attach/use authority does
+ * not become general catalog access.
+ */
+export const VariableSetAttachmentMetadata = z.object({
+  id: z.string().uuid(),
+  scope: VariableSetScope,
+});
+export type VariableSetAttachmentMetadata = z.infer<typeof VariableSetAttachmentMetadata>;
+
+export const MAX_RESOLVED_VARIABLE_SET_ATTACHMENTS = MAX_SELECTED_VARIABLE_SETS * 2;
+export const ResolveVariableSetAttachmentsRequest = z
+  .object({
+    // One create can carry 25 explicit selections plus 25 defaults from its Rig.
+    variableSetIds: z.array(z.string().uuid()).max(MAX_RESOLVED_VARIABLE_SET_ATTACHMENTS),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (new Set(value.variableSetIds).size !== value.variableSetIds.length) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["variableSetIds"],
+        message: "variableSetIds must not contain duplicates",
+      });
+    }
+  });
+export type ResolveVariableSetAttachmentsRequest = z.infer<
+  typeof ResolveVariableSetAttachmentsRequest
+>;
+
+export const ResolveVariableSetAttachmentsResponse = z.object({
+  variableSets: z.array(VariableSetAttachmentMetadata),
+});
+export type ResolveVariableSetAttachmentsResponse = z.infer<
+  typeof ResolveVariableSetAttachmentsResponse
+>;
+
 export const VariableSet = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -8008,6 +8040,10 @@ export const RigChange = z.object({
 });
 export type RigChange = z.infer<typeof RigChange>;
 
+// Rig setup payloads are transferred to sandboxes in bounded chunks. Keep the
+// public definition limit independent from provider command-argument ceilings.
+export const RIG_SETUP_SCRIPT_MAX_CHARS = 1024 * 1024;
+
 export const CreateRigRequest = z.object({
   // Omitted remains the compatibility workspace-owned creation path.
   scope: ResourceAuthorityScope.default("workspace"),
@@ -8020,7 +8056,7 @@ export const CreateRigRequest = z.object({
   // explicit never-field instead of silently stripping `image` from older
   // clients: callers must receive a validation error and remove the override.
   image: z.never().optional(),
-  setupScript: z.string().max(131072).optional(),
+  setupScript: z.string().max(RIG_SETUP_SCRIPT_MAX_CHARS).optional(),
   checks: z.array(RigCheck).max(100).default([]),
   credentialHooks: z.array(z.string().min(1).max(200)).max(50).default([]),
   defaultVariableSetIds: z.array(z.string().uuid()).max(25).default([]),
@@ -8090,7 +8126,7 @@ export const RigDefinitionEditPayload = z.object({
   // the read model for compatibility, but no new definition may set or clear
   // one through the public write contract.
   image: z.never().optional(),
-  setupScript: z.string().max(131072).nullish(),
+  setupScript: z.string().max(RIG_SETUP_SCRIPT_MAX_CHARS).nullish(),
   checks: z.array(RigCheck).max(100).optional(),
   credentialHooks: z.array(z.string().min(1).max(200)).max(50).optional(),
   defaultVariableSetIds: z.array(z.string().uuid()).max(25).optional(),
@@ -11681,57 +11717,6 @@ export const SessionListResponse = z.object({
 });
 export type SessionListResponse = z.infer<typeof SessionListResponse>;
 
-/** Compact, bounded session projection for workspace agent-topology browsers. */
-export const AgentTopologySession = z.object({
-  id: z.string().uuid(),
-  title: z.string().nullable(),
-  titleTruncated: z.boolean(),
-  parentSessionId: z.string().uuid().nullable(),
-  rootSessionId: z.string().uuid(),
-  nestedAgentDepth: NestedAgentDepthValue,
-  ancestorPath: z.array(
-    z.object({
-      id: z.string().uuid(),
-      title: z.string().nullable(),
-      titleTruncated: z.boolean(),
-    }),
-  ),
-  status: SessionStatus,
-  pause: z.object({
-    state: z.enum(["active", "paused"]),
-    additionalBlockerCount: z.number().int().nonnegative(),
-    source: z
-      .object({
-        kind: z.enum(["session", "workspace"]),
-        sessionId: z.string().uuid().optional(),
-        displayName: z.string(),
-        displayNameTruncated: z.boolean(),
-      })
-      .nullable(),
-  }),
-  children: z.object({
-    directChildren: z.number().int().nonnegative(),
-    totalDescendants: z.number().int().nonnegative(),
-    runningDescendants: z.number().int().nonnegative(),
-    queuedDescendants: z.number().int().nonnegative(),
-    attentionDescendants: z.number().int().nonnegative(),
-    pausedDescendants: z.number().int().nonnegative(),
-    failedDescendants: z.number().int().nonnegative(),
-    truncated: z.boolean(),
-  }),
-  createdAt: z.string(),
-  updatedAt: z.string(),
-});
-export type AgentTopologySession = z.infer<typeof AgentTopologySession>;
-
-export const AgentTopologyPageResponse = z.object({
-  sessions: z.array(AgentTopologySession),
-  total: z.number().int().nonnegative(),
-  hasMore: z.boolean(),
-  nextCursor: z.string().nullable(),
-});
-export type AgentTopologyPageResponse = z.infer<typeof AgentTopologyPageResponse>;
-
 // Recursive: the TS type is declared first so the schema annotation can carry
 // the FULL recursive shape (a shallow annotation loses type information for
 // contracts consumers after one level of nesting).
@@ -15704,8 +15689,7 @@ export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalog
  * that rollout boundary. Mutating clients send this value in
  * `x-opengeni-api-contract`; the API rejects any other value before routing.
  */
-export const OPENGENI_API_CONTRACT_REVISION =
-  "2026-08-personal-only-organization-setup-v1" as const;
+export const OPENGENI_API_CONTRACT_REVISION = "2026-08-organization-recovery-custody-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
 /** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
 export const OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id" as const;
@@ -15755,6 +15739,9 @@ export const ClientConfig = /* @__PURE__ */ defineModelContractSchema(() =>
       acceptedMimeTypes: [...VOICE_INPUT_ACCEPTED_MIME_TYPES],
     }),
     productAccessMode: ProductAccessMode,
+    // Safe rollout discriminator: the browser only mounts the optional
+    // @opengeni/sdk/accounts controller when this is dual or broker.
+    managedAuthSessionSetMode: z.enum(["legacy", "dual", "broker"]).default("legacy"),
     auth: ClientAuthConfig.default({ mode: "none" }),
     analytics: z
       .object({
@@ -15891,6 +15878,7 @@ export * from "./governed-learning-activation";
 export * from "./knowledge";
 export * from "./task-notes";
 export * from "./canonical-human-identities";
+export * from "./organization-recovery";
 export * from "./organization-membership-lifecycle";
 export * from "./remember";
 export * from "./agent-authored-durable-text";

package/src/managed-auth-session-sets.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+
+export const MANAGED_AUTH_SESSION_SET_MAX_SLOTS = 8 as const;
+export const MANAGED_AUTH_TRANSACTION_TTL_SECONDS = 600 as const;
+export const MANAGED_AUTH_RETURN_INTENT_MAX_BYTES = 2_048 as const;
+export const MANAGED_AUTH_SESSION_SET_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+export const MANAGED_AUTH_SESSION_SET_API_CONTRACT_REVISION =
+  "2026-08-personal-only-organization-setup-v1" as const;
+
+export const ManagedAuthSessionSetMode = z.enum(["legacy", "dual", "broker"]);
+export type ManagedAuthSessionSetMode = z.infer<typeof ManagedAuthSessionSetMode>;
+
+export const ManagedAuthLoginSlotState = z.enum(["active", "reauth_required"]);
+export type ManagedAuthLoginSlotState = z.infer<typeof ManagedAuthLoginSlotState>;
+
+export const ManagedAuthVerifiedClaim = z.object({
+  kind: z.literal("email"),
+  value: z.string().email().max(320),
+});
+export type ManagedAuthVerifiedClaim = z.infer<typeof ManagedAuthVerifiedClaim>;
+
+/** Secret-free, browser-safe summary. Provider session ids and tokens never enter this shape. */
+export const ManagedAuthLoginSlot = z.object({
+  id: z.string().uuid(),
+  displayName: z.string().min(1).max(256),
+  verifiedClaim: ManagedAuthVerifiedClaim,
+  state: ManagedAuthLoginSlotState,
+});
+export type ManagedAuthLoginSlot = z.infer<typeof ManagedAuthLoginSlot>;
+
+export const ManagedAuthSessionSetState = z.enum(["ready", "actor_change_required"]);
+export type ManagedAuthSessionSetState = z.infer<typeof ManagedAuthSessionSetState>;
+
+export const ManagedAuthSessionSetProjection = z.object({
+  mode: ManagedAuthSessionSetMode,
+  generation: z.string().regex(/^[1-9][0-9]*$/),
+  actorEpoch: z.string().regex(/^[1-9][0-9]*$/),
+  csrfToken: z.string().min(32).max(512),
+  selectedSlotId: z.string().uuid().nullable(),
+  state: ManagedAuthSessionSetState,
+  slots: z.array(ManagedAuthLoginSlot).max(MANAGED_AUTH_SESSION_SET_MAX_SLOTS),
+});
+export type ManagedAuthSessionSetProjection = z.infer<typeof ManagedAuthSessionSetProjection>;
+
+export const ManagedAuthOperationIdentity = z.object({
+  operationId: z.string().uuid(),
+  expectedGeneration: z.string().regex(/^[1-9][0-9]*$/),
+});
+export type ManagedAuthOperationIdentity = z.infer<typeof ManagedAuthOperationIdentity>;
+
+export const BootstrapManagedAuthSessionSetRequest = ManagedAuthOperationIdentity;
+export type BootstrapManagedAuthSessionSetRequest = z.infer<
+  typeof BootstrapManagedAuthSessionSetRequest
+>;
+
+export const ManagedAuthReturnIntent = z
+  .string()
+  .min(1)
+  .superRefine((value, context) => {
+    if (new TextEncoder().encode(value).byteLength > MANAGED_AUTH_RETURN_INTENT_MAX_BYTES) {
+      context.addIssue({ code: "custom", message: "return intent exceeds its UTF-8 byte limit" });
+    }
+    if (
+      !value.startsWith("/") ||
+      value.startsWith("//") ||
+      value.includes("?") ||
+      value.includes("#") ||
+      /[\u0000-\u001f\u007f\\]/.test(value)
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "return intent must be a safe same-origin path",
+      });
+      return;
+    }
+    try {
+      const parsed = new URL(value, "https://opengeni.invalid");
+      const uuid = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+      const supportedPath = new RegExp(
+        `^/(?:sessions/${uuid}|workspaces/${uuid}(?:/sessions(?:/${uuid})?)?)$`,
+        "i",
+      );
+      if (
+        parsed.origin !== "https://opengeni.invalid" ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash ||
+        !supportedPath.test(value) ||
+        parsed.pathname !== value
+      ) {
+        context.addIssue({
+          code: "custom",
+          message: "return intent contains unsafe authority data",
+        });
+      }
+    } catch {
+      context.addIssue({
+        code: "custom",
+        message: "return intent is not a valid same-origin path",
+      });
+    }
+  });
+
+export const BeginManagedAuthLoginTransactionRequest = ManagedAuthOperationIdentity.extend({
+  kind: z.enum(["add", "reauth"]),
+  slotId: z.string().uuid().optional(),
+  returnIntent: ManagedAuthReturnIntent.optional(),
+}).superRefine((value, context) => {
+  if ((value.kind === "reauth") !== Boolean(value.slotId)) {
+    context.addIssue({
+      code: "custom",
+      path: ["slotId"],
+      message: "reauth requires exactly one slot id and add forbids one",
+    });
+  }
+});
+export type BeginManagedAuthLoginTransactionRequest = z.infer<
+  typeof BeginManagedAuthLoginTransactionRequest
+>;
+
+export const ManagedAuthLoginTransaction = z.object({
+  id: z.string().uuid(),
+  kind: z.enum(["add", "reauth"]),
+  expiresAt: z.string().datetime(),
+  returnIntentId: z.string().uuid().nullable(),
+});
+export type ManagedAuthLoginTransaction = z.infer<typeof ManagedAuthLoginTransaction>;
+
+export const CompleteManagedAuthEmailPasswordTransactionRequest =
+  ManagedAuthOperationIdentity.extend({
+    transactionId: z.string().uuid(),
+    email: z.string().email().max(320),
+    password: z.string().min(1).max(1_024),
+  });
+export type CompleteManagedAuthEmailPasswordTransactionRequest = z.infer<
+  typeof CompleteManagedAuthEmailPasswordTransactionRequest
+>;
+
+export const CompleteManagedAuthLoginTransactionResponse = z.object({
+  projection: ManagedAuthSessionSetProjection,
+  returnIntent: ManagedAuthReturnIntent.nullable(),
+});
+export type CompleteManagedAuthLoginTransactionResponse = z.infer<
+  typeof CompleteManagedAuthLoginTransactionResponse
+>;
+
+export const CancelManagedAuthLoginTransactionRequest = ManagedAuthOperationIdentity.extend({
+  transactionId: z.string().uuid(),
+});
+export type CancelManagedAuthLoginTransactionRequest = z.infer<
+  typeof CancelManagedAuthLoginTransactionRequest
+>;
+
+export const SelectManagedAuthLoginSlotRequest = ManagedAuthOperationIdentity.extend({
+  slotId: z.string().uuid(),
+});
+export type SelectManagedAuthLoginSlotRequest = z.infer<typeof SelectManagedAuthLoginSlotRequest>;
+
+export const LogoutManagedAuthLoginSlotRequest = ManagedAuthOperationIdentity.extend({
+  slotId: z.string().uuid(),
+  replacementSlotId: z.string().uuid().nullable(),
+});
+export type LogoutManagedAuthLoginSlotRequest = z.infer<typeof LogoutManagedAuthLoginSlotRequest>;
+
+export const LogoutManagedAuthSessionSetRequest = ManagedAuthOperationIdentity;
+export type LogoutManagedAuthSessionSetRequest = z.infer<typeof LogoutManagedAuthSessionSetRequest>;
+
+export const ManagedAuthLogoutAllReceipt = z.object({
+  generation: z.string().regex(/^[1-9][0-9]*$/),
+  actorEpoch: z.string().regex(/^[1-9][0-9]*$/),
+  state: z.literal("logged_out"),
+});
+export type ManagedAuthLogoutAllReceipt = z.infer<typeof ManagedAuthLogoutAllReceipt>;
+
+export const ResolveManagedAuthDeepLinkRequest = z.object({
+  path: ManagedAuthReturnIntent,
+});
+export type ResolveManagedAuthDeepLinkRequest = z.infer<typeof ResolveManagedAuthDeepLinkRequest>;
+
+export const ManagedAuthDeepLinkResolution = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("current") }),
+  z.object({ kind: z.literal("switch_required"), slot: ManagedAuthLoginSlot }),
+  z.object({ kind: z.literal("unavailable") }),
+]);
+export type ManagedAuthDeepLinkResolution = z.infer<typeof ManagedAuthDeepLinkResolution>;
+
+export const ManagedAuthSessionSetErrorCode = z.enum([
+  "actor_change_required",
+  "actor_mutation_in_flight",
+  "api_contract_changed",
+  "browser_session_set_required",
+  "browser_session_set_unavailable",
+  "generation_conflict",
+  "invalid_browser_session_set_request",
+  "invalid_transaction",
+  "managed_authentication_required",
+  "managed_authentication_unavailable",
+  "operation_outcome_unknown",
+  "operation_reused",
+  "origin_rejected",
+  "login_transaction_rate_limited",
+  "provider_route_blocked",
+  "slot_limit_reached",
+  "slot_already_exists",
+  "slot_unavailable",
+]);
+export type ManagedAuthSessionSetErrorCode = z.infer<typeof ManagedAuthSessionSetErrorCode>;

package/src/organization-recovery.ts

@@ -0,0 +1,186 @@
+import { z } from "zod";
+
+const Uuid = z.string().uuid();
+const Timestamp = z.string().datetime({ offset: true });
+
+export const OrganizationRecoveryPolicyState = z.enum([
+  "pending_acceptance",
+  "active",
+  "degraded",
+  "superseded",
+  "disabled",
+]);
+export type OrganizationRecoveryPolicyState = z.infer<typeof OrganizationRecoveryPolicyState>;
+
+export const OrganizationRecoveryOperationState = z.enum([
+  "collecting",
+  "cooling",
+  "executed",
+  "cancelled",
+  "expired",
+  "superseded",
+]);
+export type OrganizationRecoveryOperationState = z.infer<typeof OrganizationRecoveryOperationState>;
+
+export const OrganizationRecoveryUnavailableReason = z.enum([
+  "no_policy",
+  "pending_acceptance",
+  "degraded",
+  "disabled",
+  "identity_unavailable",
+]);
+export type OrganizationRecoveryUnavailableReason = z.infer<
+  typeof OrganizationRecoveryUnavailableReason
+>;
+
+export const OrganizationRecoveryMemberSummary = z
+  .object({
+    membershipId: Uuid,
+    name: z.string().trim().min(1).max(1024).nullable(),
+    email: z.string().email().max(320).nullable(),
+  })
+  .strict();
+export type OrganizationRecoveryMemberSummary = z.infer<typeof OrganizationRecoveryMemberSummary>;
+
+export const OrganizationRecoveryCustodian = OrganizationRecoveryMemberSummary.extend({
+  ordinal: z.number().int().min(1).max(3),
+  enrollmentState: z.enum(["pending_acceptance", "accepted", "ineligible"]),
+  acceptedAt: Timestamp.nullable(),
+}).strict();
+export type OrganizationRecoveryCustodian = z.infer<typeof OrganizationRecoveryCustodian>;
+
+export const OrganizationRecoveryPolicy = z
+  .object({
+    id: Uuid,
+    organizationId: Uuid,
+    revision: z.number().int().positive(),
+    state: OrganizationRecoveryPolicyState,
+    custodians: z.array(OrganizationRecoveryCustodian).length(3),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+  })
+  .strict();
+export type OrganizationRecoveryPolicy = z.infer<typeof OrganizationRecoveryPolicy>;
+
+export const OrganizationRecoveryApproval = OrganizationRecoveryMemberSummary.extend({
+  approvedAt: Timestamp,
+}).strict();
+export type OrganizationRecoveryApproval = z.infer<typeof OrganizationRecoveryApproval>;
+
+export const OrganizationRecoveryOperation = z
+  .object({
+    id: Uuid,
+    organizationId: Uuid,
+    policyId: Uuid,
+    policyRevision: z.number().int().positive(),
+    revision: z.number().int().positive(),
+    state: OrganizationRecoveryOperationState,
+    target: OrganizationRecoveryMemberSummary,
+    approvals: z.array(OrganizationRecoveryApproval).max(3),
+    approvalCount: z.number().int().min(0).max(3),
+    quorumAt: Timestamp.nullable(),
+    executableAt: Timestamp.nullable(),
+    expiresAt: Timestamp,
+    executedAt: Timestamp.nullable(),
+    cancelledAt: Timestamp.nullable(),
+    notificationJournaled: z.boolean(),
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+  })
+  .strict();
+export type OrganizationRecoveryOperation = z.infer<typeof OrganizationRecoveryOperation>;
+
+export const OrganizationRecoveryCapabilities = z
+  .object({
+    configure: z.boolean(),
+    accept: z.boolean(),
+    disable: z.boolean(),
+    start: z.boolean(),
+    approve: z.boolean(),
+    cancel: z.boolean(),
+    execute: z.boolean(),
+  })
+  .strict();
+export type OrganizationRecoveryCapabilities = z.infer<typeof OrganizationRecoveryCapabilities>;
+
+export const OrganizationRecoveryOverview = z
+  .object({
+    organizationId: Uuid,
+    availability: z.enum(["available", "recovery_unavailable"]),
+    unavailableReason: OrganizationRecoveryUnavailableReason.nullable(),
+    recentReauthenticationAt: Timestamp.nullable(),
+    eligibleMembers: z.array(OrganizationRecoveryMemberSummary).max(1000),
+    policy: OrganizationRecoveryPolicy.nullable(),
+    operation: OrganizationRecoveryOperation.nullable(),
+    capabilities: OrganizationRecoveryCapabilities,
+  })
+  .strict();
+export type OrganizationRecoveryOverview = z.infer<typeof OrganizationRecoveryOverview>;
+
+const ExpectedPolicyRevision = z.number().int().nonnegative();
+const ExpectedOperationRevision = z.number().int().positive();
+const CommandOperationId = Uuid;
+
+export const ConfigureOrganizationRecoveryPolicyRequest = z
+  .object({
+    custodianMembershipIds: z.tuple([Uuid, Uuid, Uuid]).superRefine((ids, context) => {
+      if (new Set(ids).size !== 3) {
+        context.addIssue({
+          code: "custom",
+          message: "recovery custodians must be three distinct memberships",
+        });
+      }
+    }),
+    expectedPolicyRevision: ExpectedPolicyRevision,
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type ConfigureOrganizationRecoveryPolicyRequest = z.infer<
+  typeof ConfigureOrganizationRecoveryPolicyRequest
+>;
+
+export const AcceptOrganizationRecoveryCustodyRequest = z
+  .object({
+    expectedPolicyRevision: ExpectedPolicyRevision,
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type AcceptOrganizationRecoveryCustodyRequest = z.infer<
+  typeof AcceptOrganizationRecoveryCustodyRequest
+>;
+
+export const DisableOrganizationRecoveryPolicyRequest = AcceptOrganizationRecoveryCustodyRequest;
+export type DisableOrganizationRecoveryPolicyRequest = z.infer<
+  typeof DisableOrganizationRecoveryPolicyRequest
+>;
+
+export const StartOrganizationRecoveryOperationRequest = z
+  .object({
+    targetMembershipId: Uuid,
+    expectedPolicyRevision: z.number().int().positive(),
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type StartOrganizationRecoveryOperationRequest = z.infer<
+  typeof StartOrganizationRecoveryOperationRequest
+>;
+
+export const OrganizationRecoveryOperationCommandRequest = z
+  .object({
+    expectedOperationRevision: ExpectedOperationRevision,
+    operationId: CommandOperationId,
+  })
+  .strict();
+export type OrganizationRecoveryOperationCommandRequest = z.infer<
+  typeof OrganizationRecoveryOperationCommandRequest
+>;
+
+export const OrganizationRecoveryMutationResponse = z
+  .object({
+    replay: z.boolean(),
+    overview: OrganizationRecoveryOverview,
+  })
+  .strict();
+export type OrganizationRecoveryMutationResponse = z.infer<
+  typeof OrganizationRecoveryMutationResponse
+>;

package/src/session-topology-primitives.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const SessionStatus = z.enum([
+  "queued",
+  "running",
+  "idle",
+  "requires_action",
+  "recovering",
+  "waiting_capacity",
+  "failed",
+  "cancelled",
+]);
+export type SessionStatus = z.infer<typeof SessionStatus>;
+
+export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
+export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
+
+/** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
+export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
+export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
+export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;