@abloatai/transaction 0.37.1 → 0.38.0

package/src/ai-sdk/modelTools.ts

@@ -0,0 +1,165 @@
+/**
+ * Small AI SDK adapters for Ablo model resources.
+ *
+ * The AI SDK owns the agent loop. These helpers only expose Ablo's
+ * authoritative model operations as tools, preserving the same credential,
+ * validation, idempotency, claims, and settlement behavior as direct SDK use.
+ */
+
+import { tool, type ToolExecutionOptions } from 'ai';
+import type { z } from 'zod';
+import type {
+  ClaimParams,
+  ModelCreateParams,
+  ModelDeleteParams,
+  ModelRetrieveParams,
+} from '../resources/modelOperations.js';
+import type { HeldClaim } from '../types/streams.js';
+import type { ModelToolOptions } from './toolOptions.js';
+
+export interface ToolModel<T, CreateInput = Partial<T>, Fields = T> {
+  get(params: ModelRetrieveParams): Promise<T | undefined>;
+  create(params: ModelCreateParams<T, CreateInput>): Promise<T>;
+  delete(params: ModelDeleteParams<T, Fields>): Promise<void>;
+  claim(
+    params: ClaimParams<Fields> & { queue: false },
+  ): Promise<HeldClaim<T> | null>;
+  claim(params: ClaimParams<Fields>): Promise<HeldClaim<T>>;
+}
+
+export interface ReadToolOptions<TInput, T>
+  extends ModelToolOptions<TInput, ReadToolResult<T>> {
+  readonly description: string;
+  readonly inputSchema: z.ZodType<TInput>;
+  readonly id: (input: TInput) => string;
+}
+
+export type ReadToolResult<T> =
+  | { readonly status: 'found'; readonly row: T }
+  | { readonly status: 'not_found'; readonly message: string };
+
+export function readTool<TInput, T>(
+  model: Pick<ToolModel<T>, 'get'>,
+  options: ReadToolOptions<TInput, T>,
+) {
+  return tool<TInput, ReadToolResult<T>>({
+    description: options.description,
+    title: options.title,
+    inputSchema: options.inputSchema,
+    inputExamples: options.inputExamples,
+    needsApproval: options.needsApproval,
+    strict: options.strict,
+    outputSchema: options.outputSchema,
+    toModelOutput: options.toModelOutput,
+    execute: async (input) => {
+      const id = options.id(input);
+      const row = await model.get({ id });
+      return row === undefined
+        ? {
+            status: 'not_found',
+            message: `No accessible row exists with id ${id}.`,
+          }
+        : { status: 'found', row };
+    },
+  });
+}
+
+export interface CreateToolOptions<TInput, CreateInput, T>
+  extends ModelToolOptions<TInput, CreateToolResult<T>> {
+  readonly description: string;
+  readonly inputSchema: z.ZodType<TInput>;
+  readonly data: (input: TInput) => CreateInput;
+  /**
+   * Stable ids make retries idempotent. Omit only when the model or server
+   * generates the id and duplicate creation is acceptable to the application.
+   */
+  readonly id?: (input: TInput) => string | undefined;
+}
+
+export interface CreateToolResult<T> {
+  readonly status: 'created';
+  readonly row: T;
+}
+
+export function createTool<TInput, T, CreateInput>(
+  model: Pick<ToolModel<T, CreateInput>, 'create'>,
+  options: CreateToolOptions<TInput, CreateInput, T>,
+) {
+  return tool<TInput, CreateToolResult<T>>({
+    description: options.description,
+    title: options.title,
+    inputSchema: options.inputSchema,
+    inputExamples: options.inputExamples,
+    needsApproval: options.needsApproval,
+    strict: options.strict,
+    outputSchema: options.outputSchema,
+    toModelOutput: options.toModelOutput,
+    execute: async (input) => {
+      const id = options.id?.(input);
+      const row = await model.create({
+        data: options.data(input),
+        ...(id !== undefined ? { id } : {}),
+        wait: 'confirmed',
+      });
+      return { status: 'created', row };
+    },
+  });
+}
+
+export interface DeleteToolOptions<TInput>
+  extends ModelToolOptions<TInput, DeleteToolResult> {
+  readonly description: string;
+  readonly inputSchema: z.ZodType<TInput>;
+  readonly id: (input: TInput) => string;
+  /** Defaults to waiting in the server-owned FIFO claim queue. */
+  readonly strategy?: 'claim' | 'queue';
+  readonly claim?: { readonly description?: string };
+}
+
+export type DeleteToolResult =
+  | { readonly status: 'deleted'; readonly id: string }
+  | { readonly status: 'claimed'; readonly message: string };
+
+export function deleteTool<TInput, T, Fields = T>(
+  model: Pick<ToolModel<T, Partial<T>, Fields>, 'claim' | 'delete'>,
+  options: DeleteToolOptions<TInput>,
+) {
+  return tool<TInput, DeleteToolResult>({
+    description: options.description,
+    title: options.title,
+    inputSchema: options.inputSchema,
+    inputExamples: options.inputExamples,
+    // Destructive tools require approval unless an application deliberately
+    // opts into autonomous deletion.
+    needsApproval: options.needsApproval ?? true,
+    strict: options.strict,
+    outputSchema: options.outputSchema,
+    toModelOutput: options.toModelOutput,
+    execute: async (
+      input: TInput,
+      execution: ToolExecutionOptions,
+    ): Promise<DeleteToolResult> => {
+      const id = options.id(input);
+      const queue = options.strategy !== 'claim';
+      const claim = await model.claim({
+        id,
+        queue,
+        description: options.claim?.description,
+        signal: execution.abortSignal,
+      });
+      if (!claim) {
+        return {
+          status: 'claimed',
+          message:
+            'Another participant holds this row right now — it was not deleted.',
+        };
+      }
+      try {
+        await model.delete({ id, claim, wait: 'confirmed' });
+        return { status: 'deleted', id };
+      } finally {
+        await claim.release();
+      }
+    },
+  });
+}

package/src/ai-sdk/toolOptions.ts

@@ -0,0 +1,18 @@
+import type { Tool } from 'ai';
+
+/**
+ * AI SDK-native presentation and execution policy shared by Ablo model tools.
+ * Ablo owns the data operation; AI SDK owns how the tool is presented,
+ * validated, approved, and returned to the model.
+ */
+export type ModelToolOptions<TInput, TResult> = Partial<
+  Pick<
+    Tool<TInput, TResult>,
+    | 'title'
+    | 'inputExamples'
+    | 'needsApproval'
+    | 'strict'
+    | 'outputSchema'
+    | 'toModelOutput'
+  >
+>;

package/src/ai-sdk/{coordinatedTool.ts → updateTool.ts}

@@ -1,5 +1,5 @@
 /**
- * Turns a write to one of your models into a Vercel AI SDK tool that handles
+ * Turns a write to one of your models into an AI SDK tool that handles
  * multi-agent coordination for you, so an agent can contribute to shared state
  * without silently overwriting another writer's concurrent change.
  *
@@ -11,10 +11,10 @@
  * write:
  *
  * ```ts
- * import { coordinatedTool } from '@abloatai/transaction/ai-sdk';
+ * import { updateTool } from '@abloatai/ablo/ai-sdk';
  * import { z } from 'zod';
  *
- * const saveSection = coordinatedTool(ablo.documents, {
+ * const saveSection = updateTool(ablo.documents, {
  *   description: 'Save your section into the shared document.',
  *   inputSchema: z.object({ text: z.string() }),
  *   id: () => DOC_ID,
@@ -25,7 +25,7 @@
  * await streamText({ model, messages, tools: { saveSection } });
  * ```
  *
- * The {@link CoordinatedToolOptions.apply} function is the whole API: a pure
+ * The {@link UpdateToolOptions.apply} function is the whole API: a pure
  * function from the freshest row and the tool input to a patch, in the same
  * spirit as a functional state update. Everything beneath it — reading the latest
  * row, the compare-and-swap, backing off between retries, and releasing claims —
@@ -52,42 +52,39 @@
  *   than a hidden wait when it might spend its turn on something else. Works under
  *   any conflict policy.
  *
- * - `'queue'` serializes writers over stateless HTTP. The tool polls to acquire
- *   the claim until it is granted or `poll.timeoutMs` elapses, so the model calls
- *   once and the tool waits its turn. Ordering is approximate rather than strict
- *   first-in-first-out, which would require a persistent connection.
+ * - `'queue'` joins Ablo's server-owned FIFO queue. The model calls once and
+ *   the tool waits for the canonical claim grant; it does not recreate queueing
+ *   with client-side polling.
  */
 
-import { tool } from 'ai';
+import { tool, type ToolExecutionOptions } from 'ai';
 import type { z } from 'zod';
-import { AbloClaimedError, AbloNotFoundError } from '@abloatai/transaction/errors';
 import type {
   ClaimParams,
-  ModelRetrieveParams,
   ModelUpdateParams,
 } from '../resources/modelOperations.js';
 import type { ModelUpdater, ContentionOptions } from '../resources/functionalUpdate.js';
 import type { HeldClaim } from '../types/streams.js';
+import type { ModelToolOptions } from './toolOptions.js';
 
-export type CoordinationStrategy = 'merge' | 'claim' | 'queue';
+export type UpdateStrategy = 'merge' | 'claim' | 'queue';
 
 /** The structured result the tool hands back to the model (or the caller). */
-export interface CoordinatedWriteResult<T> {
+export interface UpdateToolResult<T> {
   /**
    * `'written'` means the change was saved. `'claimed'` means another participant
    * holds the row, so nothing was saved and the model should try again.
-   * `'timeout'` means the `'queue'` strategy could not acquire the row within
-   * `poll.timeoutMs`.
    */
-  status: 'written' | 'claimed' | 'timeout';
+  status: 'written' | 'claimed';
   /** The reconciled row, on `'written'`. */
   row?: T;
   message?: string;
-  /** On `'written'` via the `queue` strategy, how long the tool waited in line. */
+  /** On `'written'` via the `queue` strategy, how long the tool waited. */
   waitedMs?: number;
 }
 
-export interface CoordinatedToolOptions<TInput, T> {
+export interface UpdateToolOptions<TInput, T>
+  extends ModelToolOptions<TInput, UpdateToolResult<T>> {
   /** Tool description shown to the model. */
   description: string;
   /** The schema of what the model may send, as a standard AI SDK / Zod input schema. */
@@ -103,45 +100,50 @@ export interface CoordinatedToolOptions<TInput, T> {
    */
   apply: (current: T, input: TInput) => Partial<T>;
   /** How concurrent writers relate. Defaults to `'merge'`. */
-  strategy?: CoordinationStrategy;
+  strategy?: UpdateStrategy;
   /** Human-readable coordination metadata attached to the claim, used by the `'claim'` and `'queue'` strategies. */
   claim?: { description?: string };
   /** How many reconcile rounds `'merge'` may take before it gives up with `AbloContentionError`. */
   retries?: number;
-  /** Poll interval and overall timeout for `'queue'`. Defaults to 250ms and 30s. */
-  poll?: { intervalMs?: number; timeoutMs?: number };
 }
 
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
 /**
  * The small model port this helper needs. Both typed transports implement this
  * exact contract; local-cache methods, wire receipts, and transport lifecycle
  * deliberately stay out of an AI tool's dependency surface.
  */
-export interface CoordinatedModel<T> {
-  get(params: ModelRetrieveParams): Promise<T | undefined>;
-  /** @deprecated Use `get({ id })`. */
-  retrieve?(params: ModelRetrieveParams): Promise<T | undefined>;
+export interface UpdateToolModel<T> {
   update(params: ModelUpdateParams<T>): Promise<T>;
   update(
     id: string,
     updater: ModelUpdater<T>,
     options?: ContentionOptions,
   ): Promise<T | undefined>;
+  claim(
+    params: ClaimParams<T> & { queue: false },
+  ): Promise<HeldClaim<T> | null>;
   claim(params: ClaimParams<T>): Promise<HeldClaim<T>>;
 }
 
-export function coordinatedTool<
+export function updateTool<
   TInput,
   T = Record<string, unknown>,
->(model: CoordinatedModel<T>, options: CoordinatedToolOptions<TInput, T>) {
+>(model: UpdateToolModel<T>, options: UpdateToolOptions<TInput, T>) {
   const strategy = options.strategy ?? 'merge';
 
-  return tool<TInput, CoordinatedWriteResult<T>>({
+  return tool<TInput, UpdateToolResult<T>>({
     description: options.description,
+    title: options.title,
     inputSchema: options.inputSchema,
-    execute: async (input: TInput): Promise<CoordinatedWriteResult<T>> => {
+    inputExamples: options.inputExamples,
+    needsApproval: options.needsApproval,
+    strict: options.strict,
+    outputSchema: options.outputSchema,
+    toModelOutput: options.toModelOutput,
+    execute: async (
+      input: TInput,
+      execution: ToolExecutionOptions,
+    ): Promise<UpdateToolResult<T>> => {
       const id = options.id(input);
 
       if (strategy === 'merge') {
@@ -150,29 +152,39 @@ export function coordinatedTool<
         // backoff. The model never sees a conflict.
         const row = await model.update(id, (current) => options.apply(current, input), {
           retries: options.retries,
+          signal: execution.abortSignal,
         });
         return { status: 'written', row: row ?? undefined };
       }
 
       // The 'claim' and 'queue' strategies both acquire a claim, write under it,
       // and release it. They differ only in what they do when the row is already
-      // held: 'claim' returns a signal to the model, while 'queue' waits and
-      // retries by polling to acquire.
-      const acquireWriteRelease = async (): Promise<CoordinatedWriteResult<T>> => {
+      // held: 'claim' returns a signal to the model, while 'queue' waits for
+      // the server-owned FIFO grant.
+      const acquireWriteRelease = async (
+        queue: boolean,
+      ): Promise<UpdateToolResult<T>> => {
         const claim = await model.claim({
           id,
-          queue: false,
+          queue,
           description: options.claim?.description,
+          signal: execution.abortSignal,
         });
+        if (!claim) {
+          return {
+            status: 'claimed',
+            message:
+              'Another participant holds this row right now — it was not saved.',
+          };
+        }
         try {
-          const current = await model.get({ id });
-          if (current === undefined) {
-            throw new AbloNotFoundError(
-              `Cannot write ${id}: it does not exist (or is outside this credential's scope).`,
-              [id],
-            );
-          }
-          const row = await model.update({ id, data: options.apply(current, input), claim, wait: 'confirmed' });
+          const current = claim.data;
+          const row = await model.update({
+            id,
+            data: options.apply(current, input),
+            claim,
+            wait: 'confirmed',
+          });
           return { status: 'written', row };
         } finally {
           await claim.release();
@@ -180,35 +192,13 @@ export function coordinatedTool<
       };
 
       if (strategy === 'claim') {
-        try {
-          return await acquireWriteRelease();
-        } catch (e) {
-          if (e instanceof AbloClaimedError) {
-            return { status: 'claimed', message: 'Another participant holds this row right now — it was NOT saved. Wait briefly and try again.' };
-          }
-          throw e;
-        }
+        return acquireWriteRelease(false);
       }
 
-      // strategy === 'queue': poll to acquire the claim over stateless HTTP.
-      const interval = options.poll?.intervalMs ?? 250;
-      const timeout = options.poll?.timeoutMs ?? 30_000;
+      // The transaction client owns the server FIFO and resolves once granted.
       const start = Date.now();
-      for (;;) {
-        try {
-          const result = await acquireWriteRelease();
-          return { ...result, waitedMs: Date.now() - start };
-        } catch (e) {
-          if (e instanceof AbloClaimedError) {
-            if (Date.now() - start >= timeout) {
-              return { status: 'timeout', message: `Could not acquire the row within ${timeout}ms.` };
-            }
-            await sleep(interval);
-            continue;
-          }
-          throw e;
-        }
-      }
+      const result = await acquireWriteRelease(true);
+      return { ...result, waitedMs: Date.now() - start };
     },
   });
 }

package/src/auth/capability.ts

@@ -239,6 +239,10 @@ export function grantedOperations(
  */
 export const capabilityScopeSchema = z.object({
   organizationId: z.string().min(1),
+  /** Credential target. Branch id is authoritative; null supports self-hosted identities. */
+  projectId: z.string().min(1).nullable().default(null),
+  branchId: z.string().min(1).nullable().default(null),
+  branchRoot: z.boolean().default(false),
   /**
    * The ROW axis — which sync groups this credential may act within. Read back
    * as plain strings rather than the branded form the request enforces: this is

package/src/auth/identity.ts

@@ -42,7 +42,11 @@ export interface IdentityResolveInput {
     readonly agentId?: string;
     readonly syncGroups?: string[];
   };
-  readonly internalOptions: { readonly organizationId?: string };
+  readonly internalOptions: {
+    readonly organizationId?: string;
+    readonly branchId?: string;
+    readonly branchRoot?: boolean;
+  };
   readonly url: string;
   readonly kind: ParticipantKind;
   readonly configuredApiKey: string | CredentialProvider | null;
@@ -57,10 +61,10 @@ export interface ResolvedIdentity {
   readonly accountScope: string;
   /** Concrete project selected by the credential. The org id is the default project. */
   readonly projectId: string | null;
-  /** Data environment selected by the credential. Null for explicit/self-hosted identities. */
-  readonly environment: 'sandbox' | 'production' | null;
-  /** Concrete sandbox selected by the credential, when applicable. */
-  readonly sandboxId: string | null;
+  /** Immutable transaction branch selected by the credential. */
+  readonly branchId: string | null;
+  /** True only when branchId is the project's production root. */
+  readonly branchRoot: boolean;
   readonly teamIds: string[] | undefined;
   readonly capabilityToken: string | undefined;
   readonly syncGroups: readonly string[] | undefined;
@@ -182,8 +186,8 @@ export async function resolveParticipantIdentity(
         userId,
         accountScope,
         projectId: accountScope,
-        environment: null,
-        sandboxId: null,
+        branchId: internalOptions.branchId ?? null,
+        branchRoot: internalOptions.branchRoot ?? false,
         teamIds: kind === 'user' ? options.user?.teamIds : undefined,
         capabilityToken: cred.getBearer,
         syncGroups: options.syncGroups,
@@ -232,8 +236,8 @@ async function resolveViaIdentity(
     userId: identity.participantId,
     accountScope: identity.accountScope,
     projectId: identity.projectId ?? identity.accountScope,
-    environment: identity.environment ?? null,
-    sandboxId: identity.sandboxId ?? null,
+    branchId: identity.branchId ?? null,
+    branchRoot: identity.branchRoot,
     teamIds: undefined,
     capabilityToken: bearer,
     syncGroups: mergedSyncGroups,
@@ -312,13 +316,9 @@ async function resolveHosted(input: HostedInput): Promise<ResolvedIdentity> {
   return {
     userId: exchange.scope.participantId,
     accountScope: exchange.scope.organizationId,
-    // The legacy capability exchange response predates the explicit plane
-    // fields returned by `/auth/identity`. A hosted secret-key client defaults
-    // to the org-default project; browser sessions use resolveViaIdentity and
-    // therefore receive the concrete project/environment/sandbox tuple.
-    projectId: exchange.scope.organizationId,
-    environment: null,
-    sandboxId: null,
+    projectId: exchange.scope.projectId ?? exchange.scope.organizationId,
+    branchId: exchange.scope.branchId,
+    branchRoot: exchange.scope.branchRoot,
     // teamIds isn't needed because the server already encoded
     // team-level access into scope.syncGroups.
     teamIds: undefined,

package/src/auth/schemas.ts

@@ -21,8 +21,8 @@ export const IdentityResolveResponseSchema = z.object({
   // The rest of the resolved plane. The server always emits these keys; null
   // means the credential does not bind that axis.
   projectId: z.string().min(1).nullable(),
-  environment: z.enum(['sandbox', 'production']).nullable(),
-  sandboxId: z.string().min(1).nullable(),
+  branchId: z.string().min(1).nullable().default(null),
+  branchRoot: z.boolean().default(false),
   syncGroups: z.array(z.string()),
   userMeta: z.record(z.string(), z.unknown()),
 });
@@ -42,6 +42,9 @@ export const EphemeralKeyResponseSchema = z.object({
   expiresAt: z.string().min(1),
   organizationId: z.string().min(1),
   participantId: z.string().min(1),
+  projectId: z.string().min(1).nullable().default(null),
+  branchId: z.string().min(1).nullable().default(null),
+  branchRoot: z.boolean().default(false),
   syncGroups: z.array(z.string()),
   /** Effective operation grant stored on the credential. */
   operations: z.array(grantedOperationSchema).min(1),

package/src/auth/sessionMint.ts

@@ -91,6 +91,9 @@ export async function mintSession<S extends SchemaRecord>(
       // response into the session resource's scope block.
       scope: {
         organizationId: res.organizationId,
+        projectId: res.projectId,
+        branchId: res.branchId,
+        branchRoot: res.branchRoot,
         syncGroups: res.syncGroups,
         operations: res.operations,
         participantKind: 'user',

package/src/branches.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+
+/**
+ * A branch handle is for people and URLs. Durable routing always uses the
+ * immutable branch id returned by the server.
+ */
+export const branchSlugSchema = z
+  .string()
+  .min(1)
+  // During the additive rollout this is also the legacy plane adapter, whose
+  // persisted environment contract is capped at 40 characters.
+  .max(40)
+  .regex(
+    /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/,
+    'must be a lowercase slug containing only letters, numbers, and hyphens',
+  );
+
+export const branchKindSchema = z.enum(['dev', 'preview', 'test', 'long_lived']);
+export type BranchKind = z.infer<typeof branchKindSchema>;
+
+export const branchStateSchema = z.enum([
+  'provisioning',
+  'ready',
+  'failed',
+  'deleting',
+  'deleted',
+]);
+export type BranchState = z.infer<typeof branchStateSchema>;
+
+export const branchOriginSchema = z.enum(['empty', 'source_snapshot', 'coordinated_fork']);
+export type BranchOrigin = z.infer<typeof branchOriginSchema>;
+
+export const branchResponseSchema = z.object({
+  object: z.literal('branch'),
+  id: z.string(),
+  project_id: z.string(),
+  parent_branch_id: z.string().nullable(),
+  slug: branchSlugSchema,
+  name: z.string().nullable(),
+  kind: branchKindSchema,
+  state: branchStateSchema,
+  origin: branchOriginSchema,
+  root: z.boolean(),
+  expires_at: z.string().nullable(),
+  created_at: z.string(),
+  deleted_at: z.string().nullable(),
+});
+export type BranchResponse = z.infer<typeof branchResponseSchema>;
+
+export const branchListResponseSchema = z.object({
+  object: z.literal('list'),
+  data: z.array(branchResponseSchema).readonly(),
+});
+export type BranchListResponse = z.infer<typeof branchListResponseSchema>;
+
+export const createBranchRequestSchema = z.object({
+  slug: branchSlugSchema,
+  name: z.string().min(1).max(200).optional(),
+  parent_branch_id: z.string().optional(),
+  kind: branchKindSchema.optional(),
+  origin: branchOriginSchema.optional(),
+  expires_at: z.iso.datetime().optional(),
+});
+export type CreateBranchRequest = z.infer<typeof createBranchRequestSchema>;
+
+export const branchCredentialRequestSchema = z
+  .object({
+    ttl_hours: z.number().int().min(1).max(168).optional(),
+  })
+  .strict();
+export type BranchCredentialRequest = z.infer<typeof branchCredentialRequestSchema>;
+
+export const branchCredentialResponseSchema = z.object({
+  object: z.literal('branch_credential'),
+  branch_id: z.string(),
+  api_key: z.string(),
+  expires_at: z.string(),
+});
+export type BranchCredentialResponse = z.infer<typeof branchCredentialResponseSchema>;
+
+export const branchParentCompatibilitySchema = z.enum([
+  'same',
+  'compatible',
+  'review',
+  'blocked',
+  'unknown',
+]);
+export type BranchParentCompatibility = z.infer<typeof branchParentCompatibilitySchema>;
+
+export const branchStatusSchemaSummarySchema = z
+  .object({
+    active: z.boolean(),
+    version: z.number().int().nullable(),
+    hash: z.string().nullable(),
+    parent_compatibility: branchParentCompatibilitySchema,
+    changes: z.number().int().nonnegative(),
+    warnings: z.number().int().nonnegative(),
+    blockers: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export const branchStatusDataSourceSchema = z
+  .object({
+    kind: z.enum(['hosted', 'direct', 'endpoint']),
+    status: z.enum(['unverified', 'active', 'rejected']).nullable(),
+    host: z.string().nullable(),
+    database: z.string().nullable(),
+    cursor: z.string().nullable(),
+    event_lag: z.number().int().nonnegative(),
+    retry_count: z.number().int().nonnegative(),
+    last_success_at: z.string().nullable(),
+    last_error: z.string().nullable(),
+  })
+  .strict();
+
+export const branchStatusBlockerSchema = z
+  .object({
+    code: z.enum(['branch_not_ready', 'schema_missing', 'data_source_not_ready']),
+    problem: z.string(),
+    fix: z.string(),
+  })
+  .strict();
+
+export const branchStatusResponseSchema = z
+  .object({
+    object: z.literal('branch_status'),
+    branch: branchResponseSchema,
+    ready: z.boolean(),
+    schema: branchStatusSchemaSummarySchema,
+    data_source: branchStatusDataSourceSchema,
+    blockers: z.array(branchStatusBlockerSchema).readonly(),
+  })
+  .strict();
+export type BranchStatusResponse = z.infer<typeof branchStatusResponseSchema>;