deepline 0.3.64 → 0.3.65

package/dist/bundling-sources/shared_libs/play-runtime/async-operation.ts

@@ -0,0 +1,999 @@
+export type AsyncOperationJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly AsyncOperationJsonValue[]
+  | { readonly [key: string]: AsyncOperationJsonValue };
+
+export type AsyncOperationTerminalOutcome =
+  | 'running'
+  | 'succeeded'
+  | 'no_result'
+  | 'failed'
+  | 'cancelled';
+
+export type AsyncOperationValueSource =
+  | { source: 'job_id' }
+  | { source: 'start_input'; path: string }
+  | { source: 'start_result'; path: string }
+  | { source: 'poll_result'; path: string }
+  | { source: 'literal'; value: AsyncOperationJsonValue };
+
+export type AsyncOperationResultValueSource =
+  | AsyncOperationValueSource
+  | { source: 'finish_result'; path: string };
+
+export type AsyncOperationInputMapping = Readonly<
+  Record<string, AsyncOperationValueSource>
+>;
+
+export type AsyncOperationCondition = {
+  path: string;
+  equals?: string | number | boolean | null;
+  in?: readonly (string | number | boolean | null)[];
+  exists?: boolean;
+  normalize?: 'lowercase' | 'uppercase';
+};
+
+export type AsyncOperationTerminalRule = {
+  outcome: AsyncOperationTerminalOutcome;
+  mode?: 'all' | 'any';
+  conditions: readonly AsyncOperationCondition[];
+  messagePath?: string;
+};
+
+export type AsyncOperationActionCall = {
+  action: string;
+  input: AsyncOperationInputMapping;
+  /** Reuse the terminal poll response when poll and finish are the same read. */
+  reuseTerminalPollResult?: boolean;
+  pagination?: {
+    pageInputField: string;
+    startPage: number;
+    maxPages: number;
+    itemsPath: string;
+    totalPagesPath?: string;
+    lastPagePath?: string;
+  };
+};
+
+export type AsyncOperationResultMaterialization = {
+  source: 'start_result' | 'poll_result' | 'finish_result';
+  path?: string;
+  emptyIsNoResult?: boolean;
+  /**
+   * Compose the public result envelope without provider-specific runner code.
+   * Fields overwrite the selected result object. Set mergeSourceObject=false
+   * when the historical interface is an envelope rather than the raw result.
+   */
+  objectFields?: Readonly<Record<string, AsyncOperationResultValueSource>>;
+  mergeSourceObject?: boolean;
+  /** Restore batch item identities from submitted input when a provider omits them. */
+  correlateByPosition?: {
+    inputPath: string;
+    resultPath: string;
+    fields: readonly string[];
+  };
+};
+
+export type AsyncOperationContractWire = {
+  version: 1;
+  /** Preserve the provider's historical public async metadata exactly. */
+  compatibility?: {
+    /** null intentionally suppresses the legacy asyncGetAction projection. */
+    asyncGetAction?: string | null;
+  };
+  lifecycle: {
+    startAction: string;
+    pollActions: readonly AsyncOperationActionCall[];
+    finishAction?: AsyncOperationActionCall;
+    cancelAction?: AsyncOperationActionCall;
+  };
+  capacity: {
+    scope:
+      | 'organization_provider'
+      | 'organization_connection'
+      | 'organization_action';
+    limit:
+      | { kind: 'provider_registry' }
+      | { kind: 'fixed'; maxConcurrentJobs: number };
+    onConflict: 'wait' | 'fail';
+    leaseTtlMs: number;
+  };
+  job: { idPaths: readonly string[] };
+  polling: {
+    initialDelayMs: number;
+    intervalMs: number;
+    /** Optional public start-input field that overrides intervalMs for this call. */
+    intervalInputField?: string;
+    backoffMultiplier?: number;
+    maxIntervalMs?: number;
+    timeoutMs: number;
+    /** Optional public start-input field that overrides timeoutMs for this call. */
+    timeoutInputField?: string;
+  };
+  terminal: {
+    rules: readonly AsyncOperationTerminalRule[];
+    defaultOutcome: 'running' | 'failed';
+  };
+  result: AsyncOperationResultMaterialization;
+  wait:
+    | { kind: 'always' }
+    | {
+        kind: 'input_flag';
+        field: string;
+        default: boolean;
+        durableValue?: boolean;
+      }
+    | { kind: 'caller_managed' };
+};
+
+export type AsyncOperationContract = AsyncOperationContractWire;
+export type AsyncActionFlowCompatibilityProjection = {
+  pollActions: readonly string[];
+  finishAction?: string;
+};
+
+function required(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`AsyncOperationContract requires ${label}.`);
+  return normalized;
+}
+
+function positiveInteger(value: number, label: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(
+      `AsyncOperationContract ${label} must be a positive safe integer.`,
+    );
+  }
+  return value;
+}
+
+function nonNegativeInteger(value: number, label: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(
+      `AsyncOperationContract ${label} must be a non-negative safe integer.`,
+    );
+  }
+  return value;
+}
+
+function validateActionCall(
+  call: AsyncOperationActionCall,
+  label: string,
+): void {
+  required(call.action, `${label}.action`);
+  for (const [field, source] of Object.entries(call.input)) {
+    required(field, `${label}.input field`);
+    if (source.source !== 'job_id' && source.source !== 'literal') {
+      required(source.path, `${label}.input.${field}.path`);
+    }
+  }
+}
+
+function validateResultValueSource(
+  source: AsyncOperationResultValueSource,
+  label: string,
+): void {
+  if (source.source !== 'job_id' && source.source !== 'literal') {
+    required(source.path, `${label}.path`);
+  }
+}
+
+export function defineAsyncOperation(
+  contract: AsyncOperationContract,
+): AsyncOperationContract {
+  required(contract.lifecycle.startAction, 'lifecycle.startAction');
+  if (contract.lifecycle.pollActions.length === 0) {
+    throw new Error(
+      'AsyncOperationContract requires at least one lifecycle.pollActions entry.',
+    );
+  }
+  contract.lifecycle.pollActions.forEach((call, index) =>
+    validateActionCall(call, `lifecycle.pollActions[${index}]`),
+  );
+  if (contract.lifecycle.finishAction) {
+    validateActionCall(
+      contract.lifecycle.finishAction,
+      'lifecycle.finishAction',
+    );
+    const pagination = contract.lifecycle.finishAction.pagination;
+    if (pagination) {
+      required(
+        pagination.pageInputField,
+        'lifecycle.finishAction.pagination.pageInputField',
+      );
+      nonNegativeInteger(
+        pagination.startPage,
+        'lifecycle.finishAction.pagination.startPage',
+      );
+      positiveInteger(
+        pagination.maxPages,
+        'lifecycle.finishAction.pagination.maxPages',
+      );
+      required(
+        pagination.itemsPath,
+        'lifecycle.finishAction.pagination.itemsPath',
+      );
+      if (pagination.totalPagesPath !== undefined) {
+        required(
+          pagination.totalPagesPath,
+          'lifecycle.finishAction.pagination.totalPagesPath',
+        );
+      }
+      if (pagination.lastPagePath !== undefined) {
+        required(
+          pagination.lastPagePath,
+          'lifecycle.finishAction.pagination.lastPagePath',
+        );
+      }
+      if (
+        pagination.totalPagesPath === undefined &&
+        pagination.lastPagePath === undefined
+      ) {
+        throw new Error(
+          'AsyncOperationContract paginated finish action requires totalPagesPath or lastPagePath.',
+        );
+      }
+    }
+  }
+  if (contract.lifecycle.cancelAction) {
+    validateActionCall(
+      contract.lifecycle.cancelAction,
+      'lifecycle.cancelAction',
+    );
+  }
+  if (contract.job.idPaths.length === 0) {
+    throw new Error(
+      'AsyncOperationContract requires at least one job.idPaths entry.',
+    );
+  }
+  contract.job.idPaths.forEach((path, index) =>
+    required(path, `job.idPaths[${index}]`),
+  );
+  if (contract.result.objectFields) {
+    for (const [field, source] of Object.entries(
+      contract.result.objectFields,
+    )) {
+      required(field, 'result.objectFields field');
+      validateResultValueSource(source, `result.objectFields.${field}`);
+    }
+  }
+  positiveInteger(contract.capacity.leaseTtlMs, 'capacity.leaseTtlMs');
+  if (contract.capacity.limit.kind === 'fixed') {
+    positiveInteger(
+      contract.capacity.limit.maxConcurrentJobs,
+      'capacity.limit.maxConcurrentJobs',
+    );
+  }
+  nonNegativeInteger(contract.polling.initialDelayMs, 'polling.initialDelayMs');
+  positiveInteger(contract.polling.intervalMs, 'polling.intervalMs');
+  positiveInteger(contract.polling.timeoutMs, 'polling.timeoutMs');
+  if (contract.polling.intervalInputField !== undefined) {
+    required(contract.polling.intervalInputField, 'polling.intervalInputField');
+  }
+  if (contract.polling.timeoutInputField !== undefined) {
+    required(contract.polling.timeoutInputField, 'polling.timeoutInputField');
+  }
+  if (
+    contract.polling.backoffMultiplier !== undefined &&
+    (!Number.isFinite(contract.polling.backoffMultiplier) ||
+      contract.polling.backoffMultiplier < 1)
+  ) {
+    throw new Error(
+      'AsyncOperationContract polling.backoffMultiplier must be at least 1.',
+    );
+  }
+  if (contract.polling.maxIntervalMs !== undefined) {
+    positiveInteger(contract.polling.maxIntervalMs, 'polling.maxIntervalMs');
+    if (contract.polling.maxIntervalMs < contract.polling.intervalMs) {
+      throw new Error(
+        'AsyncOperationContract polling.maxIntervalMs must be at least polling.intervalMs.',
+      );
+    }
+  }
+  if (contract.terminal.rules.length === 0) {
+    throw new Error('AsyncOperationContract requires terminal.rules.');
+  }
+  contract.terminal.rules.forEach((rule, ruleIndex) => {
+    if (rule.conditions.length === 0) {
+      throw new Error(
+        `AsyncOperationContract terminal.rules[${ruleIndex}] requires conditions.`,
+      );
+    }
+    rule.conditions.forEach((condition, conditionIndex) => {
+      required(
+        condition.path,
+        `terminal.rules[${ruleIndex}].conditions[${conditionIndex}].path`,
+      );
+      const predicates = [
+        condition.equals !== undefined,
+        condition.in !== undefined,
+        condition.exists !== undefined,
+      ].filter(Boolean).length;
+      if (predicates !== 1) {
+        throw new Error(
+          `AsyncOperationContract terminal.rules[${ruleIndex}].conditions[${conditionIndex}] requires exactly one predicate.`,
+        );
+      }
+    });
+  });
+  if (
+    contract.result.source === 'finish_result' &&
+    !contract.lifecycle.finishAction
+  ) {
+    throw new Error(
+      'AsyncOperationContract result.source="finish_result" requires lifecycle.finishAction.',
+    );
+  }
+  if (contract.result.path !== undefined)
+    required(contract.result.path, 'result.path');
+  if (contract.wait.kind === 'input_flag')
+    required(contract.wait.field, 'wait.field');
+  if (typeof contract.compatibility?.asyncGetAction === 'string') {
+    required(
+      contract.compatibility.asyncGetAction,
+      'compatibility.asyncGetAction',
+    );
+  }
+  return contract;
+}
+
+export function projectAsyncActionFlow(
+  contract: AsyncOperationContract,
+): AsyncActionFlowCompatibilityProjection {
+  return {
+    pollActions: contract.lifecycle.pollActions.map((call) => call.action),
+    ...(contract.lifecycle.finishAction
+      ? { finishAction: contract.lifecycle.finishAction.action }
+      : {}),
+  };
+}
+
+export function projectAsyncGetAction(
+  contract: AsyncOperationContract,
+): string | undefined {
+  if (contract.compatibility?.asyncGetAction !== undefined) {
+    return contract.compatibility.asyncGetAction ?? undefined;
+  }
+  return (
+    contract.lifecycle.finishAction?.action ??
+    contract.lifecycle.pollActions[contract.lifecycle.pollActions.length - 1]!
+      .action
+  );
+}
+
+function positiveStartInputNumber(
+  input: Readonly<Record<string, unknown>>,
+  field: string | undefined,
+): number | null {
+  if (!field) return null;
+  const value = readAsyncOperationPath(input, field);
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : null;
+}
+
+/** Resolve per-call polling controls without changing the provider's public input. */
+export function resolveAsyncOperationPolling(input: {
+  contract: AsyncOperationContract;
+  startInput: Readonly<Record<string, unknown>>;
+}): { intervalMs: number; timeoutMs: number } {
+  return {
+    intervalMs:
+      positiveStartInputNumber(
+        input.startInput,
+        input.contract.polling.intervalInputField,
+      ) ?? input.contract.polling.intervalMs,
+    timeoutMs:
+      positiveStartInputNumber(
+        input.startInput,
+        input.contract.polling.timeoutInputField,
+      ) ?? input.contract.polling.timeoutMs,
+  };
+}
+
+/**
+ * Compatibility-preserving declaration for intentionally caller-managed jobs.
+ * The runner publishes the full lifecycle metadata but never polls it unless a
+ * later provider migration explicitly changes `wait`.
+ */
+export function defineCallerManagedAsyncOperation(input: {
+  startAction: string;
+  pollActions: readonly string[];
+  finishAction?: string;
+  jobIdPaths?: readonly string[];
+  /**
+   * Preserve an existing public asyncGetAction, or pass null when the legacy
+   * action exposed only asyncFlow metadata.
+   */
+  asyncGetAction?: string | null;
+}): AsyncOperationContract {
+  const companion = (action: string): AsyncOperationActionCall => ({
+    action,
+    input: {},
+  });
+  return defineAsyncOperation({
+    version: 1,
+    compatibility: {
+      asyncGetAction:
+        input.asyncGetAction !== undefined
+          ? input.asyncGetAction
+          : (input.finishAction ?? null),
+    },
+    lifecycle: {
+      startAction: input.startAction,
+      pollActions: input.pollActions.map(companion),
+      ...(input.finishAction
+        ? { finishAction: companion(input.finishAction) }
+        : {}),
+    },
+    capacity: {
+      scope: 'organization_provider',
+      limit: { kind: 'provider_registry' },
+      onConflict: 'wait',
+      leaseTtlMs: 15 * 60_000,
+    },
+    job: {
+      idPaths: input.jobIdPaths ?? [
+        'job_id',
+        'jobId',
+        'task_id',
+        'taskId',
+        'run_id',
+        'runId',
+        'id',
+        'data.id',
+      ],
+    },
+    polling: {
+      initialDelayMs: 0,
+      intervalMs: 1_000,
+      timeoutMs: 15 * 60_000,
+    },
+    terminal: {
+      rules: [
+        {
+          outcome: 'running',
+          conditions: [{ path: '$', exists: true }],
+        },
+      ],
+      defaultOutcome: 'running',
+    },
+    result: { source: 'start_result' },
+    wait: { kind: 'caller_managed' },
+  });
+}
+
+export function asyncOperationCompanionActions(
+  contract: AsyncOperationContract,
+): string[] {
+  return [
+    ...contract.lifecycle.pollActions.map((call) => call.action),
+    ...(contract.lifecycle.finishAction
+      ? [contract.lifecycle.finishAction.action]
+      : []),
+    ...(contract.lifecycle.cancelAction
+      ? [contract.lifecycle.cancelAction.action]
+      : []),
+  ];
+}
+
+export function readAsyncOperationPath(value: unknown, path: string): unknown {
+  if (path === '$' || path === '') return value;
+  let current = value;
+  for (const segment of path.split('.').filter(Boolean)) {
+    if (!current || typeof current !== 'object' || Array.isArray(current))
+      return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+export function writeAsyncOperationPath(
+  value: unknown,
+  path: string,
+  replacement: unknown,
+): unknown {
+  if (path === '$' || path === '') return replacement;
+  const segments = path.split('.').filter(Boolean);
+  if (segments.length === 0) return replacement;
+  const root =
+    value && typeof value === 'object' && !Array.isArray(value)
+      ? { ...(value as Record<string, unknown>) }
+      : {};
+  let target = root;
+  for (const segment of segments.slice(0, -1)) {
+    const child = target[segment];
+    const cloned =
+      child && typeof child === 'object' && !Array.isArray(child)
+        ? { ...(child as Record<string, unknown>) }
+        : {};
+    target[segment] = cloned;
+    target = cloned;
+  }
+  target[segments.at(-1)!] = replacement;
+  return root;
+}
+
+export function asyncOperationShouldWait(
+  contract: AsyncOperationContractWire,
+  input: Record<string, unknown>,
+): boolean {
+  if (contract.wait.kind === 'always') return true;
+  if (contract.wait.kind === 'caller_managed') return false;
+  const value = input[contract.wait.field];
+  return typeof value === 'boolean' ? value : contract.wait.default;
+}
+
+export function asyncOperationDurableStartInput(
+  contract: AsyncOperationContractWire,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  if (contract.wait.kind !== 'input_flag') return input;
+  return {
+    ...input,
+    [contract.wait.field]: contract.wait.durableValue ?? false,
+  };
+}
+
+export function extractAsyncOperationJobId(
+  contract: AsyncOperationContractWire,
+  startResult: unknown,
+): string | null {
+  for (const path of contract.job.idPaths) {
+    const value = readAsyncOperationPath(startResult, path);
+    if (typeof value === 'string' && value.trim()) return value.trim();
+    if (typeof value === 'number' && Number.isFinite(value))
+      return String(value);
+  }
+  return null;
+}
+
+export function buildAsyncOperationActionInput(input: {
+  mapping: AsyncOperationInputMapping;
+  jobId: string;
+  startInput: Record<string, unknown>;
+  startResult: unknown;
+  pollResult?: unknown;
+}): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(input.mapping).map(([field, source]) => {
+      switch (source.source) {
+        case 'job_id':
+          return [field, input.jobId];
+        case 'literal':
+          return [field, source.value];
+        case 'start_input':
+          return [field, readAsyncOperationPath(input.startInput, source.path)];
+        case 'start_result':
+          return [
+            field,
+            readAsyncOperationPath(input.startResult, source.path),
+          ];
+        case 'poll_result':
+          return [field, readAsyncOperationPath(input.pollResult, source.path)];
+      }
+    }),
+  );
+}
+
+function conditionMatches(
+  result: unknown,
+  condition: AsyncOperationCondition,
+): boolean {
+  const raw = readAsyncOperationPath(result, condition.path);
+  const value =
+    typeof raw === 'string' && condition.normalize === 'lowercase'
+      ? raw.toLowerCase()
+      : typeof raw === 'string' && condition.normalize === 'uppercase'
+        ? raw.toUpperCase()
+        : raw;
+  if (condition.exists !== undefined)
+    return condition.exists === (raw !== undefined && raw !== null);
+  if (condition.in !== undefined)
+    return condition.in.some((candidate) => candidate === value);
+  return value === condition.equals;
+}
+
+export function classifyAsyncOperationResult(
+  contract: AsyncOperationContractWire,
+  result: unknown,
+): { outcome: AsyncOperationTerminalOutcome; message?: string } {
+  for (const rule of contract.terminal.rules) {
+    const matches = rule.conditions.map((condition) =>
+      conditionMatches(result, condition),
+    );
+    const matched =
+      rule.mode === 'any' ? matches.some(Boolean) : matches.every(Boolean);
+    if (!matched) continue;
+    const message = rule.messagePath
+      ? readAsyncOperationPath(result, rule.messagePath)
+      : undefined;
+    return {
+      outcome: rule.outcome,
+      ...(typeof message === 'string' && message.trim()
+        ? { message: message.trim() }
+        : {}),
+    };
+  }
+  return { outcome: contract.terminal.defaultOutcome };
+}
+
+function isEmptyAsyncResult(value: unknown): boolean {
+  return (
+    value == null ||
+    (Array.isArray(value) && value.length === 0) ||
+    (typeof value === 'object' &&
+      !Array.isArray(value) &&
+      Object.keys(value as Record<string, unknown>).length === 0)
+  );
+}
+
+export function materializeAsyncOperationResult(input: {
+  contract: AsyncOperationContractWire;
+  startInput: Record<string, unknown>;
+  startResult: unknown;
+  pollResult: unknown;
+  finishResult?: unknown;
+}): { outcome: 'succeeded' | 'no_result'; result: unknown } {
+  const selected =
+    input.contract.result.source === 'start_result'
+      ? input.startResult
+      : input.contract.result.source === 'finish_result'
+        ? input.finishResult
+        : input.pollResult;
+  let result = input.contract.result.path
+    ? readAsyncOperationPath(selected, input.contract.result.path)
+    : selected;
+  const objectFields = input.contract.result.objectFields;
+  if (objectFields) {
+    const composed =
+      input.contract.result.mergeSourceObject !== false &&
+      result &&
+      typeof result === 'object' &&
+      !Array.isArray(result)
+        ? { ...(result as Record<string, unknown>) }
+        : {};
+    const jobId = extractAsyncOperationJobId(input.contract, input.startResult);
+    for (const [field, source] of Object.entries(objectFields)) {
+      switch (source.source) {
+        case 'job_id':
+          composed[field] = jobId;
+          break;
+        case 'literal':
+          composed[field] = source.value;
+          break;
+        case 'start_input':
+          composed[field] = readAsyncOperationPath(
+            input.startInput,
+            source.path,
+          );
+          break;
+        case 'start_result':
+          composed[field] = readAsyncOperationPath(
+            input.startResult,
+            source.path,
+          );
+          break;
+        case 'poll_result':
+          composed[field] = readAsyncOperationPath(
+            input.pollResult,
+            source.path,
+          );
+          break;
+        case 'finish_result':
+          composed[field] = readAsyncOperationPath(
+            input.finishResult,
+            source.path,
+          );
+          break;
+      }
+    }
+    result = composed;
+  }
+  const correlation = input.contract.result.correlateByPosition;
+  if (correlation) {
+    const sourceRows = readAsyncOperationPath(
+      input.startInput,
+      correlation.inputPath,
+    );
+    const resultRows = readAsyncOperationPath(result, correlation.resultPath);
+    if (Array.isArray(sourceRows) && Array.isArray(resultRows)) {
+      const correlatedRows = resultRows.map((row, index) => {
+        const sourceRow = sourceRows[index];
+        if (
+          !row ||
+          typeof row !== 'object' ||
+          Array.isArray(row) ||
+          !sourceRow ||
+          typeof sourceRow !== 'object' ||
+          Array.isArray(sourceRow)
+        ) {
+          return row;
+        }
+        const output = { ...(row as Record<string, unknown>) };
+        for (const field of correlation.fields) {
+          if (output[field] == null || output[field] === '') {
+            output[field] = (sourceRow as Record<string, unknown>)[field];
+          }
+        }
+        return output;
+      });
+      if (correlation.resultPath === '$' || correlation.resultPath === '') {
+        result = correlatedRows;
+      } else {
+        result = writeAsyncOperationPath(
+          result,
+          correlation.resultPath,
+          correlatedRows,
+        );
+      }
+    }
+  }
+  return {
+    outcome:
+      input.contract.result.emptyIsNoResult && isEmptyAsyncResult(result)
+        ? 'no_result'
+        : 'succeeded',
+    result,
+  };
+}
+
+export function asyncOperationPollDelayMs(
+  contract: AsyncOperationContractWire,
+  pollAttempt: number,
+): number {
+  if (pollAttempt <= 0) return contract.polling.initialDelayMs;
+  const delay = Math.round(
+    contract.polling.intervalMs *
+      Math.pow(contract.polling.backoffMultiplier ?? 1, pollAttempt - 1),
+  );
+  return Math.min(delay, contract.polling.maxIntervalMs ?? delay);
+}
+
+/**
+ * Runtime-neutral executor for a declared async lifecycle.
+ *
+ * Provider runtimes and Play execution intentionally share this state machine:
+ * the provider contract owns polling inputs, terminal classification, result
+ * pagination, and materialization. Callers own transport, durable receipts,
+ * retry policy, billing, and recovery persistence around each action.
+ */
+export async function executeAsyncOperationLifecycle<Response>(input: {
+  contract: AsyncOperationContractWire;
+  startInput: Record<string, unknown>;
+  startResult: unknown;
+  /** Transport envelopes may carry a job id outside the provider result body. */
+  jobId?: string | null;
+  executeAction: (request: {
+    action: string;
+    input: Record<string, unknown>;
+    jobId: string;
+    phase: 'poll' | 'finish' | 'finish_page';
+    pollAttempt: number;
+    page?: number;
+  }) => Promise<Response>;
+  responseValue: (response: Response) => unknown;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  /** Legacy direct callers historically poll once immediately after launch. */
+  pollImmediately?: boolean;
+}): Promise<
+  | {
+      kind: 'terminal';
+      jobId: string;
+      classification: {
+        outcome: Exclude<AsyncOperationTerminalOutcome, 'running'>;
+        message?: string;
+      };
+      pollResponse: Response;
+      pollResult: unknown;
+      finishResponse?: Response;
+      finishResult?: unknown;
+      materialized?: { outcome: 'succeeded' | 'no_result'; result: unknown };
+    }
+  | {
+      kind: 'timed_out';
+      jobId: string;
+      pollAttempt: number;
+      previousPollResult: unknown;
+    }
+> {
+  const jobId =
+    extractAsyncOperationJobId(input.contract, input.startResult) ??
+    input.jobId?.trim() ??
+    null;
+  if (!jobId) {
+    throw new Error(
+      `Async operation ${input.contract.lifecycle.startAction} returned running without a provider job id.`,
+    );
+  }
+  const sleep =
+    input.sleep ??
+    ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const now = input.now ?? Date.now;
+  const startedAt = now();
+  const polling = resolveAsyncOperationPolling({
+    contract: input.contract,
+    startInput: input.startInput,
+  });
+  const effectiveContract: AsyncOperationContractWire = {
+    ...input.contract,
+    polling: { ...input.contract.polling, intervalMs: polling.intervalMs },
+  };
+  let pollAttempt = 0;
+  let previousPollResult: unknown = undefined;
+  while (true) {
+    if (now() - startedAt >= polling.timeoutMs) {
+      return { kind: 'timed_out', jobId, pollAttempt, previousPollResult };
+    }
+    const delayMs =
+      pollAttempt === 0 && input.pollImmediately === true
+        ? 0
+        : asyncOperationPollDelayMs(effectiveContract, pollAttempt);
+    if (delayMs > 0) await sleep(delayMs);
+    let pollResponse: Response | null = null;
+    for (const action of input.contract.lifecycle.pollActions) {
+      pollResponse = await input.executeAction({
+        action: action.action,
+        input: buildAsyncOperationActionInput({
+          mapping: action.input,
+          jobId,
+          startInput: input.startInput,
+          startResult: input.startResult,
+          pollResult: previousPollResult,
+        }),
+        jobId,
+        phase: 'poll',
+        pollAttempt,
+      });
+      previousPollResult = input.responseValue(pollResponse);
+    }
+    if (!pollResponse) {
+      throw new Error(
+        `Async operation ${input.contract.lifecycle.startAction} has no executable poll action.`,
+      );
+    }
+    const classification = classifyAsyncOperationResult(
+      input.contract,
+      previousPollResult,
+    );
+    if (classification.outcome === 'running') {
+      pollAttempt += 1;
+      continue;
+    }
+    const terminalClassification = classification as {
+      outcome: Exclude<AsyncOperationTerminalOutcome, 'running'>;
+      message?: string;
+    };
+    if (
+      terminalClassification.outcome === 'failed' ||
+      terminalClassification.outcome === 'cancelled'
+    ) {
+      return {
+        kind: 'terminal',
+        jobId,
+        classification: terminalClassification,
+        pollResponse,
+        pollResult: previousPollResult,
+      };
+    }
+
+    let finishResponse: Response | undefined;
+    let finishResult: unknown = undefined;
+    const finishAction = input.contract.lifecycle.finishAction;
+    // A terminal no-result is already authoritative. Fetching a result page
+    // after it both contradicts the terminal classification and can turn a
+    // successful empty lookup into a spurious provider-read failure.
+    if (finishAction && terminalClassification.outcome === 'succeeded') {
+      if (finishAction.reuseTerminalPollResult) {
+        finishResponse = pollResponse;
+        finishResult = previousPollResult;
+      } else {
+        const finishInput = buildAsyncOperationActionInput({
+          mapping: finishAction.input,
+          jobId,
+          startInput: input.startInput,
+          startResult: input.startResult,
+          pollResult: previousPollResult,
+        });
+        finishResponse = await input.executeAction({
+          action: finishAction.action,
+          input: finishInput,
+          jobId,
+          phase: 'finish',
+          pollAttempt,
+        });
+        finishResult = input.responseValue(finishResponse);
+        const pagination = finishAction.pagination;
+        if (pagination) {
+          const firstItems = readAsyncOperationPath(
+            finishResult,
+            pagination.itemsPath,
+          );
+          if (!Array.isArray(firstItems)) {
+            throw new Error(
+              `Async operation ${input.contract.lifecycle.startAction} paginated finish result is missing array ${pagination.itemsPath}.`,
+            );
+          }
+          const allItems = [...firstItems];
+          let page = pagination.startPage;
+          let currentResult = finishResult;
+          const isLastPage = () => {
+            const totalPages = pagination.totalPagesPath
+              ? readAsyncOperationPath(currentResult, pagination.totalPagesPath)
+              : undefined;
+            if (
+              typeof totalPages === 'number' &&
+              Number.isSafeInteger(totalPages)
+            ) {
+              return page + 1 >= totalPages;
+            }
+            // Older providers sometimes omit both pagination markers for a
+            // one-page result. Treat only an explicit `last: false` as proof
+            // that another page exists; otherwise preserve that one-page
+            // response instead of issuing unbounded empty page reads.
+            return (
+              !pagination.lastPagePath ||
+              readAsyncOperationPath(
+                currentResult,
+                pagination.lastPagePath,
+              ) !== false
+            );
+          };
+          while (!isLastPage()) {
+            page += 1;
+            if (page - pagination.startPage >= pagination.maxPages) {
+              throw new Error(
+                `Async operation ${input.contract.lifecycle.startAction} exceeded its ${pagination.maxPages}-page result limit.`,
+              );
+            }
+            const pageResponse = await input.executeAction({
+              action: finishAction.action,
+              input: { ...finishInput, [pagination.pageInputField]: page },
+              jobId,
+              phase: 'finish_page',
+              pollAttempt,
+              page,
+            });
+            currentResult = input.responseValue(pageResponse);
+            const pageItems = readAsyncOperationPath(
+              currentResult,
+              pagination.itemsPath,
+            );
+            if (!Array.isArray(pageItems)) {
+              throw new Error(
+                `Async operation ${input.contract.lifecycle.startAction} result page ${page} is missing array ${pagination.itemsPath}.`,
+              );
+            }
+            allItems.push(...pageItems);
+          }
+          finishResult = writeAsyncOperationPath(
+            finishResult,
+            pagination.itemsPath,
+            allItems,
+          );
+        }
+      }
+    }
+    const materialized = materializeAsyncOperationResult({
+      contract: input.contract,
+      startInput: input.startInput,
+      startResult: input.startResult,
+      pollResult: previousPollResult,
+      finishResult,
+    });
+    return {
+      kind: 'terminal',
+      jobId,
+      classification: terminalClassification,
+      pollResponse,
+      pollResult: previousPollResult,
+      ...(finishResponse ? { finishResponse } : {}),
+      ...(finishAction ? { finishResult } : {}),
+      materialized,
+    };
+  }
+}