deepline 0.1.79 → 0.1.80

package/dist/repo/apps/play-runner-workers/src/workflow-retry-state.ts

@@ -6,10 +6,16 @@ import type {
   PlayRuntimeManifestMap,
 } from '../../../shared_libs/plays/compiler-manifest';
 
-export const WORKFLOW_RETRY_STATE_TARGET_BYTES = 100_000;
+import {
+  PLAY_SUBMIT_INPUT_INLINE_MAX_BYTES,
+  PLAY_SUBMIT_INPUT_MAX_BYTES,
+} from '../../../shared_libs/play-runtime/submit-limits';
+
+export const WORKFLOW_RETRY_STATE_TARGET_BYTES =
+  PLAY_SUBMIT_INPUT_INLINE_MAX_BYTES;
 export const WORKFLOW_RETRY_PARAMS_EXTERNALIZE_AFTER_BYTES =
   WORKFLOW_RETRY_STATE_TARGET_BYTES;
-export const WORKFLOW_RETRY_PARAMS_MAX_BYTES = 1024 * 1024;
+export const WORKFLOW_RETRY_PARAMS_MAX_BYTES = PLAY_SUBMIT_INPUT_MAX_BYTES;
 
 export type WorkflowRetryParamsRef = {
   storageKind: 'r2';

package/dist/repo/sdk/src/client.ts

@@ -642,6 +642,7 @@ export class DeeplineClient {
     categories?: string;
     grep?: string;
     grepMode?: 'all' | 'any' | 'phrase';
+    compact?: boolean;
   }): Promise<ToolDefinition[]> {
     const params = new URLSearchParams();
     if (options?.categories?.trim()) {
@@ -651,6 +652,7 @@ export class DeeplineClient {
       params.set('grep', options.grep.trim());
       params.set('grep_mode', options.grepMode ?? 'all');
     }
+    params.set('compact', options?.compact === true ? 'true' : 'false');
     const suffix = params.toString() ? `?${params.toString()}` : '';
     const res = await this.http.get<{ tools: ToolDefinition[] }>(
       `/api/v2/tools${suffix}`,
@@ -1433,6 +1435,7 @@ export class DeeplineClient {
     if (status) {
       params.set('status', status);
     }
+    params.set('compact', 'true');
     const response = await this.http.get<{ runs: PlayRunListItem[] }>(
       `/api/v2/runs?${params.toString()}`,
     );
@@ -1636,10 +1639,14 @@ export class DeeplineClient {
    * @param name - Play name
    * @returns Version list (newest first)
    */
-  async listPlayVersions(name: string): Promise<PlayRevisionSummary[]> {
+  async listPlayVersions(
+    name: string,
+    options?: { full?: boolean },
+  ): Promise<PlayRevisionSummary[]> {
     const encodedName = encodeURIComponent(name);
+    const suffix = options?.full ? '?full=true' : '';
     const response = await this.http.get<{ versions: PlayRevisionSummary[] }>(
-      `/api/v2/plays/${encodedName}/versions`,
+      `/api/v2/plays/${encodedName}/versions${suffix}`,
     );
     return response.versions ?? [];
   }

package/dist/repo/sdk/src/release.ts

@@ -50,10 +50,10 @@ export type SdkRelease = {
 };
 
 export const SDK_RELEASE = {
-  version: '0.1.79',
+  version: '0.1.80',
   apiContract: '2026-06-dataset-column-cell-stale-hard-cutover',
   supportPolicy: {
-    latest: '0.1.79',
+    latest: '0.1.80',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
   },

package/dist/repo/sdk/src/types.ts

@@ -131,6 +131,10 @@ export interface ToolDefinition {
   operationId?: string;
   /** Alternative names that resolve to this tool. */
   operationAliases?: string[];
+  /** Whether detailed input schema is available from `tools describe`. */
+  hasInputSchema?: boolean;
+  /** Whether detailed output schema is available from `tools describe`. */
+  hasOutputSchema?: boolean;
   /** JSON Schema describing the tool's input parameters. */
   inputSchema?: Record<string, unknown>;
   /** JSON Schema describing the tool's output shape. */
@@ -661,6 +665,7 @@ export interface PlayListItem {
   currentPublishedVersion?: number | null;
   tableNamespace?: string | null;
   isDraftDirty?: boolean;
+  hasInputSchema?: boolean;
   inputSchema?: Record<string, unknown> | null;
   outputSchema?: Record<string, unknown> | null;
   staticPipeline?: unknown;

package/dist/repo/shared_libs/play-runtime/governor/coordinator-rate-state-backend.ts

@@ -0,0 +1,231 @@
+import {
+  noopPacingPermit,
+  type PacingPermit,
+  type PacingRule,
+  type RateStateBackend,
+} from './rate-state-backend';
+
+/**
+ * Distributed Rate State Backend for the `esm_workers` substrate.
+ *
+ * On Cloudflare a single play run fans child plays and map rows across many
+ * V8 isolates, so the per-`(org, provider)` request window cannot be
+ * process-local — each isolate would otherwise pace against its own private
+ * counter and the org could blow past a provider's real limit by the number of
+ * isolates. This backend makes the window GLOBAL by RPCing the coordinator
+ * Durable Object addressed per bucket (`idFromName('rate:<orgId>:<provider>')`).
+ * The DO is single-threaded, so it runs the same sliding-window algorithm as
+ * `InMemoryRateStateBackend` correctly for all isolates at once.
+ *
+ * Latency: a full DO round-trip on every outbound tool call would tax the
+ * hello-world latency baseline. Instead the backend LEASES SMALL PERMIT BLOCKS:
+ * one `/rate-acquire` round-trip debits up to {@link LEASE_BLOCK_SIZE} permits
+ * from the global window, and subsequent acquires draw from the local block
+ * until it is exhausted or its short TTL expires. This bounds round-trips to
+ * roughly `calls / LEASE_BLOCK_SIZE` while keeping over-issuance bounded by one
+ * block per isolate per window.
+ *
+ * Fail-open: if the coordinator is unreachable the backend logs once and
+ * PROCEEDS (grants the permit) rather than stalling the run, matching the
+ * semantics of `src/lib/redis/customer-rate-limiter.ts` — a degraded limiter
+ * must never become an availability outage. The Governor's global
+ * tool-concurrency semaphore remains the unconditional backstop.
+ */
+
+/** Permits leased per round-trip. Tuned to amortize the DO hop, not to batch. */
+const LEASE_BLOCK_SIZE = 16;
+/**
+ * Max age of a leased block. A leased permit debited the global window already,
+ * but if it is held past roughly one window it could let an isolate run ahead
+ * of a rolled-over window. Discarding stale blocks bounds that to sub-window.
+ */
+const LEASE_BLOCK_TTL_MS = 250;
+/** Cap on how long the backend will park waiting on a saturated window. */
+const MAX_ACQUIRE_WAIT_MS = 5_000;
+
+export interface CoordinatorRatePort {
+  /**
+   * Lease up to `requested` request-window permits for `bucketId` under all
+   * `rules` from the coordinator DO. Returns how many were `granted` (0 when the
+   * window is saturated) and a `waitMs` hint before retrying.
+   */
+  rateAcquire(input: {
+    bucketId: string;
+    rules: PacingRule[];
+    requested: number;
+  }): Promise<{ granted: number; waitMs: number }>;
+  /** Feed a Retry-After cooldown back into the global bucket. */
+  ratePenalize(input: { bucketId: string; cooldownMs: number }): Promise<void>;
+}
+
+interface LeasedBlock {
+  remaining: number;
+  expiresAt: number;
+  /** Stable signature of the rules this block was leased under. */
+  rulesKey: string;
+}
+
+interface Options {
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  onDegraded?: (info: { bucketId: string; error: string }) => void;
+}
+
+function rulesSignature(rules: readonly PacingRule[]): string {
+  return [...rules]
+    .map(
+      (rule) =>
+        `${rule.ruleId}:${rule.requestsPerWindow}:${rule.windowMs}:${rule.maxConcurrency ?? ''}`,
+    )
+    .sort()
+    .join('|');
+}
+
+export class CoordinatorRateStateBackend implements RateStateBackend {
+  private readonly port: CoordinatorRatePort;
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly onDegraded: (info: {
+    bucketId: string;
+    error: string;
+  }) => void;
+  private readonly blocks = new Map<string, LeasedBlock>();
+  private degradedLogged = false;
+
+  constructor(port: CoordinatorRatePort, options: Options = {}) {
+    this.port = port;
+    this.now = options.now ?? (() => Date.now());
+    this.sleep =
+      options.sleep ??
+      ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.onDegraded =
+      options.onDegraded ??
+      ((info) => {
+        if (this.degradedLogged) return;
+        this.degradedLogged = true;
+        console.warn('[coordinator-rate-state] acquire failed open', info);
+      });
+  }
+
+  async acquire(input: {
+    bucketId: string;
+    rules: readonly PacingRule[];
+    signal?: AbortSignal;
+  }): Promise<PacingPermit> {
+    const { bucketId, rules, signal } = input;
+    if (rules.length === 0) {
+      return noopPacingPermit();
+    }
+    const rulesKey = rulesSignature(rules);
+
+    // Draw from a still-valid local block first — no round-trip.
+    if (this.drawFromBlock(bucketId, rulesKey)) {
+      return noopPacingPermit();
+    }
+
+    const waitStartedAt = this.now();
+    while (true) {
+      if (signal?.aborted) {
+        throw signal.reason instanceof Error
+          ? signal.reason
+          : new Error('Rate-state acquire aborted.');
+      }
+      let response: { granted: number; waitMs: number };
+      try {
+        response = await this.port.rateAcquire({
+          bucketId,
+          rules: [...rules],
+          requested: LEASE_BLOCK_SIZE,
+        });
+      } catch (error) {
+        // Fail open: a degraded coordinator must not stall the run.
+        this.onDegraded({
+          bucketId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return noopPacingPermit();
+      }
+      if (response.granted > 0) {
+        // Consume one for this call; cache the rest as a short-lived block.
+        const remaining = response.granted - 1;
+        if (remaining > 0) {
+          this.mergeBlock(bucketId, remaining, rulesKey);
+        }
+        return noopPacingPermit();
+      }
+      // Window saturated. Park for the hint, then re-acquire. Cap total wait so
+      // a stuck bucket surfaces through the Governor's wall-clock guard instead
+      // of hanging forever.
+      if (this.now() - waitStartedAt >= MAX_ACQUIRE_WAIT_MS) {
+        return noopPacingPermit();
+      }
+      const waitMs = Math.max(1, Math.min(response.waitMs, MAX_ACQUIRE_WAIT_MS));
+      await this.sleep(waitMs);
+    }
+  }
+
+  penalize(input: { bucketId: string; cooldownMs: number }): void {
+    if (input.cooldownMs <= 0) return;
+    // Drop any cached block for this bucket so the cooldown takes effect on the
+    // very next acquire instead of being masked by already-leased permits.
+    this.blocks.delete(input.bucketId);
+    void this.port
+      .ratePenalize({
+        bucketId: input.bucketId,
+        cooldownMs: input.cooldownMs,
+      })
+      .catch((error) => {
+        this.onDegraded({
+          bucketId: input.bucketId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+  }
+
+  /**
+   * Add freshly-leased permits to the bucket's block instead of overwriting it.
+   * Two concurrent acquires can both miss the local block and both round-trip;
+   * each debited the global window, so the DO already issued both blocks'
+   * permits. Overwriting would drop one set — under-issuance that wastes window
+   * capacity and over-throttles. Merging preserves every debited permit:
+   *  - same rulesKey + still valid → sum remaining, keep the earlier expiry so
+   *    the merged block never outlives the older lease's sub-window bound.
+   *  - missing / stale / different rules → start fresh from this lease.
+   */
+  private mergeBlock(
+    bucketId: string,
+    remaining: number,
+    rulesKey: string,
+  ): void {
+    const freshExpiresAt = this.now() + LEASE_BLOCK_TTL_MS;
+    const existing = this.blocks.get(bucketId);
+    if (
+      existing &&
+      existing.rulesKey === rulesKey &&
+      existing.expiresAt > this.now()
+    ) {
+      existing.remaining += remaining;
+      existing.expiresAt = Math.min(existing.expiresAt, freshExpiresAt);
+      return;
+    }
+    this.blocks.set(bucketId, {
+      remaining,
+      expiresAt: freshExpiresAt,
+      rulesKey,
+    });
+  }
+
+  private drawFromBlock(bucketId: string, rulesKey: string): boolean {
+    const block = this.blocks.get(bucketId);
+    if (!block) return false;
+    if (block.rulesKey !== rulesKey || block.expiresAt <= this.now()) {
+      this.blocks.delete(bucketId);
+      return false;
+    }
+    block.remaining -= 1;
+    if (block.remaining <= 0) {
+      this.blocks.delete(bucketId);
+    }
+    return true;
+  }
+}

package/dist/repo/shared_libs/play-runtime/governor/governor.ts

@@ -0,0 +1,376 @@
+/**
+ * Play Execution Governor — the deep module that owns execution policy.
+ *
+ * Both runner Adapters (`cjs_node20`, `esm_workers`) gate their work through one
+ * Governor instance per run-attempt so the substrates cannot diverge on
+ * concurrency, budgets, or pacing. Adapters keep only substrate mechanism (how
+ * to resolve a row, batch a tool call, or submit a child); the Governor owns the
+ * "may I, and how many at once" policy. See ADR 0007 + CONTEXT.md.
+ *
+ * Surface (small, by design):
+ *   - acquireRowSlot / acquireChildPlaySlot / acquireToolSlot → blocking leases
+ *   - chargeBudget                                            → throws on breach
+ *   - forkChild                                               → child lineage snapshot
+ *   - resolveRowConcurrency / reportProviderBackpressure / snapshot
+ */
+import {
+  type AdapterId,
+  type ResolvedExecutionPolicy,
+  resolveExecutionPolicy,
+  resolveRowConcurrency,
+} from './policy';
+import {
+  noopPacingPermit,
+  type PacingRule,
+  type RateStateBackend,
+} from './rate-state-backend';
+
+export interface WorkLease {
+  /** Free the slot / pacing permit. Idempotent. MUST be called in a finally. */
+  release(): void;
+}
+
+export type BudgetKind =
+  | 'playCall'
+  | 'toolCall'
+  | 'retry'
+  | 'descendant'
+  | 'waterfallStep';
+
+/** Counters that accumulate down the dispatch lineage; thread via the snapshot. */
+export interface GovernanceSnapshot {
+  rootRunId: string;
+  currentRunId: string;
+  currentPlayId: string;
+  ancestryPlayIds: string[];
+  ancestryRunIds: string[];
+  callDepth: number;
+  playCallCount: number;
+  toolCallCount: number;
+  retryCount: number;
+  descendantCount: number;
+  waterfallStepExecutions: number;
+  /** Direct child plays launched, keyed by parent play id. */
+  parentChildCalls: Record<string, number>;
+}
+
+export class GovernorBudgetError extends Error {
+  constructor(
+    readonly budget: BudgetKind | 'playDepth' | 'childPerParent',
+    readonly observed: number,
+    readonly limit: number,
+  ) {
+    const message =
+      budget === 'playDepth'
+        ? `Play-call depth exceeded (${observed}/${limit}).`
+        : `Play execution ${budget} budget exceeded (${observed}/${limit}).`;
+    super(message);
+    this.name = 'GovernorBudgetError';
+  }
+}
+
+/** Maps a toolId to its provider + resolved pacing rules (from rate-limit defs). */
+export type PacingResolver = (
+  toolId: string,
+) => Promise<{ provider: string; rules: PacingRule[] } | null>;
+
+export interface PlayExecutionGovernor {
+  readonly adapter: AdapterId;
+  readonly policy: ResolvedExecutionPolicy;
+
+  /** Block until a map-row slot is free. */
+  acquireRowSlot(opts?: { signal?: AbortSignal }): Promise<WorkLease>;
+  /** Block until a child-play slot is free. */
+  acquireChildPlaySlot(opts?: { signal?: AbortSignal }): Promise<WorkLease>;
+  /**
+   * Block until a global tool-concurrency slot AND the per-(org,provider) pacer
+   * permit are free, then charge the tool-call budget and return a lease. Order:
+   * concurrency slot → provider pace → tool budget (charged last so a
+   * failed/aborted acquire never consumes budget). A run over tool budget still
+   * acquires and holds a slot + pacing permit before the breach is detected; the
+   * breach surfaces only once the call is otherwise cleared to run.
+   */
+  acquireToolSlot(
+    toolId: string,
+    opts?: { signal?: AbortSignal },
+  ): Promise<WorkLease>;
+
+  /**
+   * Suggested batch parallelism for a tool: the provider's own rate hints
+   * tightened to the policy's suggested ceiling. No hints → the fallback.
+   */
+  suggestedParallelism(toolId: string, fallback: number): Promise<number>;
+
+  /** Increment a monotonic budget counter; throws GovernorBudgetError on breach. */
+  chargeBudget(kind: BudgetKind, amount?: number): void;
+
+  /**
+   * Reserve depth + per-parent + descendant budget for a child play and return
+   * the snapshot to thread into the child run so budgets accumulate across the
+   * lineage (and across isolates on `esm_workers`). Throws on breach.
+   *
+   * Unlike {@link acquireToolSlot} (which charges last so an aborted acquire
+   * never consumes budget), child-lineage counters are charged here at fork
+   * time, BEFORE the caller acquires a child-play slot. A slot acquire that then
+   * fails (e.g. abort) does NOT refund these counters. This is intentional and
+   * safe given the 100k child caps: the charge reserves lineage-global capacity
+   * for a launch the caller has committed to, and forkChild must return the
+   * threaded snapshot synchronously, so the charge cannot be deferred behind the
+   * async slot acquire.
+   */
+  forkChild(input: {
+    childPlayName: string;
+    childRunId: string;
+  }): GovernanceSnapshot;
+
+  /** Effective row concurrency: explicit request clamped to [1, rowMax], else default. */
+  resolveRowConcurrency(requested?: number): number;
+
+  /** Feed a provider's Retry-After back into the shared pacer. */
+  reportProviderBackpressure(input: {
+    provider: string;
+    retryAfterMs: number;
+  }): void;
+
+  snapshot(): GovernanceSnapshot;
+}
+
+interface GovernorInput {
+  adapter: AdapterId;
+  scope: { orgId: string; rootRunId: string };
+  rateState: RateStateBackend;
+  resolvePacing: PacingResolver;
+  resume?: GovernanceSnapshot;
+}
+
+class Semaphore {
+  private inFlight = 0;
+  private readonly waiters: Array<() => void> = [];
+  constructor(private readonly limit: number) {}
+
+  async acquire(signal?: AbortSignal): Promise<WorkLease> {
+    // Fail fast on an already-aborted signal: the parked-promise abort listener
+    // below registers with { once: true } and never fires for a signal that was
+    // aborted before we parked, so without this check a full pool would block
+    // the waiter until a slot frees (or forever if it never drains).
+    if (signal?.aborted) {
+      throw signal.reason instanceof Error
+        ? signal.reason
+        : new Error('Slot acquire aborted.');
+    }
+    while (this.inFlight >= this.limit) {
+      await new Promise<void>((resolve, reject) => {
+        const onResolve = () => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve();
+        };
+        const onAbort = () => {
+          const idx = this.waiters.indexOf(onResolve);
+          if (idx >= 0) this.waiters.splice(idx, 1);
+          reject(
+            signal?.reason instanceof Error
+              ? signal.reason
+              : new Error('Slot acquire aborted.'),
+          );
+        };
+        this.waiters.push(onResolve);
+        signal?.addEventListener('abort', onAbort, { once: true });
+      });
+      if (signal?.aborted) {
+        throw signal.reason instanceof Error
+          ? signal.reason
+          : new Error('Slot acquire aborted.');
+      }
+    }
+    this.inFlight += 1;
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        this.waiters.shift()?.();
+      },
+    };
+  }
+}
+
+export function createDefaultGovernanceSnapshot(scope: {
+  orgId: string;
+  rootRunId: string;
+  rootPlayId?: string;
+}): GovernanceSnapshot {
+  return {
+    rootRunId: scope.rootRunId,
+    currentRunId: scope.rootRunId,
+    currentPlayId: scope.rootPlayId ?? scope.rootRunId,
+    ancestryPlayIds: scope.rootPlayId ? [scope.rootPlayId] : [],
+    ancestryRunIds: [scope.rootRunId],
+    callDepth: scope.rootPlayId ? 1 : 0,
+    playCallCount: 0,
+    toolCallCount: 0,
+    retryCount: 0,
+    descendantCount: 0,
+    waterfallStepExecutions: 0,
+    parentChildCalls: {},
+  };
+}
+
+export function createPlayExecutionGovernor(
+  input: GovernorInput,
+): PlayExecutionGovernor {
+  const policy = resolveExecutionPolicy(input.adapter);
+  const state: GovernanceSnapshot =
+    input.resume ?? createDefaultGovernanceSnapshot(input.scope);
+
+  const rowSlots = new Semaphore(policy.concurrency.rowMax);
+  const childPlaySlots = new Semaphore(policy.concurrency.childPlay);
+  const toolSlots = new Semaphore(policy.concurrency.toolCalls);
+
+  const bucketId = (provider: string) => `${input.scope.orgId}:${provider}`;
+
+  function chargeBudget(kind: BudgetKind, amount = 1): void {
+    switch (kind) {
+      case 'playCall':
+        state.playCallCount += amount;
+        if (state.playCallCount > policy.budgets.maxPlayCallCount)
+          throw new GovernorBudgetError('playCall', state.playCallCount, policy.budgets.maxPlayCallCount);
+        return;
+      case 'toolCall':
+        state.toolCallCount += amount;
+        if (state.toolCallCount > policy.budgets.maxToolCallCount)
+          throw new GovernorBudgetError('toolCall', state.toolCallCount, policy.budgets.maxToolCallCount);
+        return;
+      case 'retry':
+        state.retryCount += amount;
+        if (state.retryCount > policy.budgets.maxRetryCount)
+          throw new GovernorBudgetError('retry', state.retryCount, policy.budgets.maxRetryCount);
+        return;
+      case 'descendant':
+        state.descendantCount += amount;
+        if (state.descendantCount > policy.budgets.maxDescendants)
+          throw new GovernorBudgetError('descendant', state.descendantCount, policy.budgets.maxDescendants);
+        return;
+      case 'waterfallStep':
+        state.waterfallStepExecutions += amount;
+        if (state.waterfallStepExecutions > policy.budgets.maxWaterfallStepExecutions)
+          throw new GovernorBudgetError('waterfallStep', state.waterfallStepExecutions, policy.budgets.maxWaterfallStepExecutions);
+        return;
+    }
+  }
+
+  return {
+    adapter: input.adapter,
+    policy,
+
+    acquireRowSlot: (opts) => rowSlots.acquire(opts?.signal),
+    acquireChildPlaySlot: (opts) => childPlaySlots.acquire(opts?.signal),
+
+    async acquireToolSlot(toolId, opts) {
+      // 1. global tool-concurrency slot.
+      const slot = await toolSlots.acquire(opts?.signal);
+      // 2. per-(org,provider) pacing. The provider comes from the pacing
+      //    resolver, so callers only need the toolId. No rules → no pacing.
+      let permit: { release(): void };
+      try {
+        const pacing = await input.resolvePacing(toolId);
+        permit =
+          pacing && pacing.rules.length > 0
+            ? await input.rateState.acquire({
+                bucketId: bucketId(pacing.provider),
+                rules: pacing.rules,
+                signal: opts?.signal,
+              })
+            : noopPacingPermit();
+      } catch (error) {
+        slot.release();
+        throw error;
+      }
+      // 3. charge the budget only once the call is actually cleared to run, so a
+      // failed/aborted acquisition never permanently consumes tool budget.
+      try {
+        chargeBudget('toolCall');
+      } catch (error) {
+        permit.release();
+        slot.release();
+        throw error;
+      }
+      let released = false;
+      return {
+        release: () => {
+          if (released) return;
+          released = true;
+          permit.release();
+          slot.release();
+        },
+      };
+    },
+
+    async suggestedParallelism(toolId, fallback) {
+      const pacing = await input.resolvePacing(toolId);
+      if (!pacing || pacing.rules.length === 0) return fallback;
+      const limits = pacing.rules.flatMap((rule) =>
+        rule.maxConcurrency != null
+          ? [rule.requestsPerWindow, rule.maxConcurrency]
+          : [rule.requestsPerWindow],
+      );
+      return Math.max(
+        1,
+        Math.min(policy.pacing.suggestedMaxParallelism, ...limits),
+      );
+    },
+
+    chargeBudget,
+
+    forkChild(childInput) {
+      if (state.ancestryPlayIds.includes(childInput.childPlayName)) {
+        const chain = [...state.ancestryPlayIds, childInput.childPlayName].join(' -> ');
+        throw new Error(`Recursive play graph detected: ${chain}`);
+      }
+      const nextDepth = state.callDepth + 1;
+      if (nextDepth > policy.budgets.maxPlayCallDepth)
+        throw new GovernorBudgetError('playDepth', nextDepth, policy.budgets.maxPlayCallDepth);
+      const parentKey = state.currentPlayId;
+      const nextParent = (state.parentChildCalls[parentKey] ?? 0) + 1;
+      if (nextParent > policy.budgets.maxChildPlayCallsPerParent)
+        throw new GovernorBudgetError('childPerParent', nextParent, policy.budgets.maxChildPlayCallsPerParent);
+      // Charge the run-wide play/descendant budgets on the parent. Charged at
+      // fork time (not after the caller's child-play slot acquire) and never
+      // refunded if that acquire fails — see the forkChild interface doc.
+      chargeBudget('playCall');
+      chargeBudget('descendant');
+      state.parentChildCalls[parentKey] = nextParent;
+      // Child seeds from the parent's accumulated counters → lineage-global budget.
+      return {
+        rootRunId: state.rootRunId,
+        currentRunId: childInput.childRunId,
+        currentPlayId: childInput.childPlayName,
+        ancestryPlayIds: [...state.ancestryPlayIds, childInput.childPlayName],
+        ancestryRunIds: [...state.ancestryRunIds, childInput.childRunId],
+        callDepth: nextDepth,
+        playCallCount: state.playCallCount,
+        toolCallCount: state.toolCallCount,
+        retryCount: state.retryCount,
+        descendantCount: state.descendantCount,
+        waterfallStepExecutions: state.waterfallStepExecutions,
+        parentChildCalls: {},
+      };
+    },
+
+    resolveRowConcurrency: (requested) => resolveRowConcurrency(policy, requested),
+
+    reportProviderBackpressure(bp) {
+      input.rateState.penalize({
+        bucketId: bucketId(bp.provider),
+        cooldownMs: bp.retryAfterMs,
+      });
+    },
+
+    snapshot: () => ({
+      ...state,
+      ancestryPlayIds: [...state.ancestryPlayIds],
+      ancestryRunIds: [...state.ancestryRunIds],
+      parentChildCalls: { ...state.parentChildCalls },
+    }),
+  };
+}