deepline 0.2.30 → 0.2.32

package/dist/bundling-sources/shared_libs/play-runtime/runtime-api.ts

@@ -512,6 +512,55 @@ type RuntimeApiActionRequest =
       input: Parameters<typeof releaseRuntimeWorkReceipts>[1];
     };
 
+/**
+ * The Runtime Sheet persistence lane is temporarily full. This is an
+ * admission signal, not a failed transport attempt: the runner must park the
+ * same idempotent write and retry it after capacity becomes available.
+ */
+export class RuntimeApiCapacityError extends Error {
+  readonly status: number;
+  readonly code: 'runtime_postgres_admission_backpressure';
+  readonly action: RuntimeApiActionRequest['action'];
+  readonly requestId: string | null;
+  readonly retryAfterMs: number;
+
+  constructor(input: {
+    status: number;
+    action: RuntimeApiActionRequest['action'];
+    requestId?: string | null;
+    retryAfterMs: number;
+    detail: string;
+  }) {
+    super(
+      `Runtime API ${input.action} delayed by persistence capacity` +
+        `${input.requestId ? ` request_id=${input.requestId}` : ''}: ${input.detail}`,
+    );
+    this.name = 'RuntimeApiCapacityError';
+    this.status = input.status;
+    this.code = 'runtime_postgres_admission_backpressure';
+    this.action = input.action;
+    this.requestId = input.requestId?.trim() || null;
+    this.retryAfterMs = Math.max(0, Math.floor(input.retryAfterMs));
+  }
+}
+
+export function isRuntimeApiCapacityError(
+  error: unknown,
+): error is RuntimeApiCapacityError {
+  if (error instanceof RuntimeApiCapacityError) return true;
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as {
+    name?: unknown;
+    code?: unknown;
+    retryAfterMs?: unknown;
+  };
+  return (
+    candidate.name === 'RuntimeApiCapacityError' &&
+    candidate.code === 'runtime_postgres_admission_backpressure' &&
+    typeof candidate.retryAfterMs === 'number'
+  );
+}
+
 export type RuntimeApiRowRecord = MapRowOutcome & {
   inputIndex?: number | null;
 };
@@ -588,13 +637,17 @@ async function postRuntimeApi<TResponse>(
         method: 'POST',
         headers: resolveRuntimeApiHeaders(context, vercelHeaders),
         body: JSON.stringify(body),
-        signal: abortController.signal,
+        signal: context.abortSignal
+          ? AbortSignal.any([context.abortSignal, abortController.signal])
+          : abortController.signal,
       });
       let parsedValue: unknown;
       try {
         parsedValue = await response.json();
       } catch (error) {
-        if (abortController.signal.aborted) throw error;
+        if (abortController.signal.aborted || context.abortSignal?.aborted) {
+          throw error;
+        }
         parsedValue = null;
       }
       parsed =
@@ -605,6 +658,9 @@ async function postRuntimeApi<TResponse>(
           : null;
     } catch (error) {
       clearTimeout(timeout);
+      if (context.abortSignal?.aborted) {
+        throw context.abortSignal.reason ?? error;
+      }
       if (attempt < maxAttempts) {
         await sleepRuntimeApiRetry(body.action, attempt);
         continue;
@@ -654,6 +710,23 @@ async function postRuntimeApi<TResponse>(
           : typeof parsed?.debug_error === 'string'
             ? parsed.debug_error
             : null;
+    if (
+      response.status === 503 &&
+      parsed?.code === 'runtime_postgres_admission_backpressure'
+    ) {
+      const requestId = response.headers.get('x-deepline-request-id');
+      const errorMessage =
+        typeof parsed.error === 'string'
+          ? parsed.error
+          : 'Runtime Postgres admission delayed.';
+      throw new RuntimeApiCapacityError({
+        status: response.status,
+        action: body.action,
+        requestId,
+        retryAfterMs,
+        detail: details ? `${errorMessage}: ${details}` : errorMessage,
+      });
+    }
     const shouldRetryRuntimeResponse =
       (response.status === 503 &&
         parsed?.code === 'ingestion_plane_not_ready') ||
@@ -713,7 +786,8 @@ function runtimeApiRetryDelayMs(
 function runtimeApiRequestTimeoutMs(
   action: RuntimeApiActionRequest['action'],
 ): number {
-  return action === 'runtime_sheet_start'
+  return action === 'runtime_sheet_start' ||
+    action === 'runtime_sheet_complete_map_rows'
     ? RUNTIME_SHEET_ADMISSION_REQUEST_TIMEOUT_MS
     : RUNTIME_API_REQUEST_TIMEOUT_MS;
 }
@@ -7896,6 +7970,29 @@ export async function completeRuntimeMapRows(
   );
 }
 
+/**
+ * Freeze the transport-ready completion payload before a higher-level
+ * capacity retry loop starts. In particular, completedAt must remain stable:
+ * a retry is the same idempotent write, not a newly authored row transition.
+ */
+export function createCompleteRuntimeMapRowsOperation(
+  context: RuntimeApiContext & { playName: string },
+  input: Parameters<typeof completeRuntimeMapRows>[1],
+): () => Promise<RuntimeMapRowsWriteResult> {
+  if (context.dbSessionStrategy !== 'gateway_only') {
+    return () => completeRuntimeMapRows(context, input);
+  }
+  const frozenInput = {
+    ...input,
+    rows: prepareRuntimeSheetRowsForJsonTransport({
+      rows: input.rows,
+      runId: input.runId,
+      outputFields: input.outputFields ?? [],
+    }),
+  };
+  return () => completeRuntimeMapRows(context, frozenInput);
+}
+
 export async function readRuntimeSheetDatasetRows(
   context: RuntimeApiContext & { playName: string },
   input: {

package/dist/cli/index.js

@@ -1044,7 +1044,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.30",
+  version: "0.2.32",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -4204,6 +4204,7 @@ var DeeplineClient = class {
         // defaults to absurd; callers normally omit this field.
         ...request.profile ? { profile: request.profile } : {},
         ...integrationMode ? { integrationMode } : {},
+        ...request.fixtureBehavior ? { fixtureBehavior: request.fixtureBehavior } : {},
         ...runtime ? { runtime } : {},
         ...testPolicyOverrides ? { testPolicyOverrides } : {}
       },
@@ -4253,6 +4254,7 @@ var DeeplineClient = class {
       ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
       ...request.profile ? { profile: request.profile } : {},
       ...integrationMode ? { integrationMode } : {},
+      ...request.fixtureBehavior ? { fixtureBehavior: request.fixtureBehavior } : {},
       ...runtime ? { runtime } : {},
       ...testPolicyOverrides ? { testPolicyOverrides } : {}
     };
@@ -17018,6 +17020,188 @@ function isInternalGlueStepId(stepId) {
   return typeof stepId === "string" && stepId.startsWith(INTERNAL_GLUE_NODE_ID_PREFIX);
 }
 
+// ../shared_libs/play-runtime/fixture-behavior.ts
+var FIXTURE_BEHAVIOR_VERSION = 1;
+var FIXTURE_BEHAVIOR_RESPONSE_VERSION = 2;
+var MAX_FIXTURE_RESPONSE_DELAY_SAMPLES = 256;
+var MAX_FIXTURE_RESPONSE_DELAY_MS = 8 * 6e4;
+var MAX_FIXTURE_RESPONSE_ERROR_MESSAGE_LENGTH = 500;
+function validateFixtureBehavior(value) {
+  if (value === void 0 || value === null) {
+    return { ok: true, behavior: null };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, error: "fixtureBehavior must be a JSON object." };
+  }
+  const record = value;
+  const supportedKeys = record.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION ? /* @__PURE__ */ new Set(["version", "responseSamples"]) : /* @__PURE__ */ new Set(["version", "responseDelaySamplesMs"]);
+  const unknownKeys = Object.keys(record).filter(
+    (key) => !supportedKeys.has(key)
+  );
+  if (unknownKeys.length > 0) {
+    return {
+      ok: false,
+      error: `Unsupported fixtureBehavior field "${unknownKeys[0]}".`
+    };
+  }
+  if (record.version !== FIXTURE_BEHAVIOR_VERSION && record.version !== FIXTURE_BEHAVIOR_RESPONSE_VERSION) {
+    return {
+      ok: false,
+      error: `fixtureBehavior.version must be ${FIXTURE_BEHAVIOR_VERSION} or ${FIXTURE_BEHAVIOR_RESPONSE_VERSION}.`
+    };
+  }
+  if (record.version === FIXTURE_BEHAVIOR_RESPONSE_VERSION) {
+    if (!Array.isArray(record.responseSamples) || record.responseSamples.length === 0 || record.responseSamples.length > MAX_FIXTURE_RESPONSE_DELAY_SAMPLES) {
+      return {
+        ok: false,
+        error: `fixtureBehavior.responseSamples must contain between 1 and ${MAX_FIXTURE_RESPONSE_DELAY_SAMPLES} values.`
+      };
+    }
+    const samples2 = [];
+    for (let index = 0; index < record.responseSamples.length; index += 1) {
+      const value2 = record.responseSamples[index];
+      if (!value2 || typeof value2 !== "object" || Array.isArray(value2)) {
+        return {
+          ok: false,
+          error: `fixtureBehavior.responseSamples[${index}] must be an object.`
+        };
+      }
+      const sample = value2;
+      const sampleUnknownKeys = Object.keys(sample).filter(
+        (key) => key !== "delayMs" && key !== "when" && key !== "httpError"
+      );
+      if (sampleUnknownKeys.length > 0) {
+        return {
+          ok: false,
+          error: `Unsupported fixtureBehavior.responseSamples[${index}] field "${sampleUnknownKeys[0]}".`
+        };
+      }
+      if (typeof sample.delayMs !== "number" || !Number.isSafeInteger(sample.delayMs) || sample.delayMs < 0 || sample.delayMs > MAX_FIXTURE_RESPONSE_DELAY_MS) {
+        return {
+          ok: false,
+          error: `fixtureBehavior.responseSamples[${index}].delayMs must be an integer between 0 and ${MAX_FIXTURE_RESPONSE_DELAY_MS}.`
+        };
+      }
+      let when;
+      if (sample.when !== void 0) {
+        if (!sample.when || typeof sample.when !== "object" || Array.isArray(sample.when)) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].when must be an object.`
+          };
+        }
+        const condition = sample.when;
+        const conditionUnknownKeys = Object.keys(condition).filter(
+          (key) => key !== "provider" && key !== "operation"
+        );
+        if (conditionUnknownKeys.length > 0) {
+          return {
+            ok: false,
+            error: `Unsupported fixtureBehavior.responseSamples[${index}].when field "${conditionUnknownKeys[0]}".`
+          };
+        }
+        const provider = normalizeFixtureScopeValue(condition.provider, 100);
+        const operation = normalizeFixtureScopeValue(condition.operation, 200);
+        if (provider.error || operation.error) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].when ` + (provider.error ?? operation.error)
+          };
+        }
+        if (!provider.value && !operation.value) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].when must select a provider or operation.`
+          };
+        }
+        when = {
+          ...provider.value ? { provider: provider.value } : {},
+          ...operation.value ? { operation: operation.value } : {}
+        };
+      }
+      let httpError;
+      if (sample.httpError !== void 0) {
+        if (!sample.httpError || typeof sample.httpError !== "object" || Array.isArray(sample.httpError)) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].httpError must be an object.`
+          };
+        }
+        const error = sample.httpError;
+        const errorUnknownKeys = Object.keys(error).filter(
+          (key) => key !== "status" && key !== "message"
+        );
+        if (errorUnknownKeys.length > 0) {
+          return {
+            ok: false,
+            error: `Unsupported fixtureBehavior.responseSamples[${index}].httpError field "${errorUnknownKeys[0]}".`
+          };
+        }
+        if (typeof error.status !== "number" || !Number.isSafeInteger(error.status) || error.status < 400 || error.status > 599) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].httpError.status must be an integer between 400 and 599.`
+          };
+        }
+        if (typeof error.message !== "string" || !error.message.trim() || error.message.length > MAX_FIXTURE_RESPONSE_ERROR_MESSAGE_LENGTH) {
+          return {
+            ok: false,
+            error: `fixtureBehavior.responseSamples[${index}].httpError.message must contain 1-${MAX_FIXTURE_RESPONSE_ERROR_MESSAGE_LENGTH} characters.`
+          };
+        }
+        httpError = { status: error.status, message: error.message.trim() };
+      }
+      samples2.push({
+        delayMs: sample.delayMs,
+        ...when ? { when } : {},
+        ...httpError ? { httpError } : {}
+      });
+    }
+    return {
+      ok: true,
+      behavior: {
+        version: FIXTURE_BEHAVIOR_RESPONSE_VERSION,
+        responseSamples: samples2
+      }
+    };
+  }
+  if (!Array.isArray(record.responseDelaySamplesMs) || record.responseDelaySamplesMs.length === 0 || record.responseDelaySamplesMs.length > MAX_FIXTURE_RESPONSE_DELAY_SAMPLES) {
+    return {
+      ok: false,
+      error: `fixtureBehavior.responseDelaySamplesMs must contain between 1 and ${MAX_FIXTURE_RESPONSE_DELAY_SAMPLES} values.`
+    };
+  }
+  const samples = [];
+  for (let index = 0; index < record.responseDelaySamplesMs.length; index += 1) {
+    const value2 = record.responseDelaySamplesMs[index];
+    if (typeof value2 !== "number" || !Number.isSafeInteger(value2) || value2 < 0 || value2 > MAX_FIXTURE_RESPONSE_DELAY_MS) {
+      return {
+        ok: false,
+        error: `fixtureBehavior.responseDelaySamplesMs[${index}] must be an integer between 0 and ${MAX_FIXTURE_RESPONSE_DELAY_MS}.`
+      };
+    }
+    samples.push(value2);
+  }
+  return {
+    ok: true,
+    behavior: {
+      version: FIXTURE_BEHAVIOR_VERSION,
+      responseDelaySamplesMs: samples
+    }
+  };
+}
+function normalizeFixtureScopeValue(value, maxLength) {
+  if (value === void 0) return {};
+  if (typeof value !== "string" || !value.trim()) {
+    return { error: "values must be non-empty strings." };
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized.length > maxLength) {
+    return { error: `values must be at most ${maxLength} characters.` };
+  }
+  return { value: normalized };
+}
+
 // src/cli/commands/play.ts
 var PLAY_BUNDLER_MODULE_PATHS = [
   // Built CLI bundle: dist/cli/index.mjs -> dist/plays/bundle-play-file.mjs.
@@ -17062,7 +17246,8 @@ var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--full",
   "--force",
   "--open",
-  "--debug-map-latency"
+  "--debug-map-latency",
+  "--debug-fixture-provider-pacing"
 ]);
 function traceCliSync(phase, fields, run) {
   const startedAt = Date.now();
@@ -20904,8 +21089,12 @@ function parsePlayRunOptions(args) {
   const force = args.includes("--force");
   const open = args.includes("--open");
   const debugMapLatency = args.includes("--debug-map-latency");
+  const debugFixtureProviderPacing = args.includes(
+    "--debug-fixture-provider-pacing"
+  );
   let waitTimeoutMs = null;
   let profile = null;
+  let fixtureBehavior = null;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--file" && args[index + 1]) {
@@ -20934,6 +21123,23 @@ function parsePlayRunOptions(args) {
       index += 1;
       continue;
     }
+    if (arg === "--fixture-behavior") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error(
+          "--fixture-behavior requires a JSON object or @file path."
+        );
+      }
+      const parsed = validateFixtureBehavior(parseJsonInput(value));
+      if (!parsed.ok || !parsed.behavior) {
+        throw new Error(
+          parsed.ok ? "--fixture-behavior is required." : parsed.error
+        );
+      }
+      fixtureBehavior = parsed.behavior;
+      index += 1;
+      continue;
+    }
     if (arg === "--live") {
       revisionSelector = "live";
       continue;
@@ -21028,7 +21234,9 @@ function parsePlayRunOptions(args) {
     force,
     open,
     profile,
-    debugMapLatency
+    debugMapLatency,
+    debugFixtureProviderPacing,
+    fixtureBehavior
   };
 }
 function parsePlayCheckOptions(args) {
@@ -21586,6 +21794,20 @@ async function handleFileBackedRun(options, hooks) {
     })
   );
   const integrationMode = resolveEvalIntegrationMode();
+  if (options.fixtureBehavior && integrationMode !== "fixture") {
+    throw new Error(
+      "--fixture-behavior requires DEEPLINE_EVAL_INTEGRATION_MODE=fixture."
+    );
+  }
+  if (options.debugFixtureProviderPacing && integrationMode !== "fixture") {
+    throw new Error(
+      "--debug-fixture-provider-pacing requires DEEPLINE_EVAL_INTEGRATION_MODE=fixture."
+    );
+  }
+  const testPolicyOverrides = {
+    ...options.debugMapLatency ? { mapLatencyProfile: true } : {},
+    ...options.debugFixtureProviderPacing ? { enforceFixtureProviderPacing: true } : {}
+  };
   const startRequest = {
     name: playName,
     sourceCode: bundleResult.sourceCode,
@@ -21599,8 +21821,9 @@ async function handleFileBackedRun(options, hooks) {
     ...stagedFileInputs.packagedFiles.length ? { packagedFiles: stagedFileInputs.packagedFiles } : {},
     ...options.force ? { force: true } : {},
     ...options.profile ? { profile: options.profile } : {},
-    ...options.debugMapLatency ? { testPolicyOverrides: { mapLatencyProfile: true } } : {},
-    ...integrationMode ? { integrationMode } : {}
+    ...Object.keys(testPolicyOverrides).length > 0 ? { testPolicyOverrides } : {},
+    ...integrationMode ? { integrationMode } : {},
+    ...options.fixtureBehavior ? { fixtureBehavior: options.fixtureBehavior } : {}
   };
   if (options.watch) {
     progress.phase("starting run");
@@ -21755,6 +21978,20 @@ async function handleNamedRun(options, hooks) {
     })
   );
   const integrationMode = resolveEvalIntegrationMode();
+  if (options.fixtureBehavior && integrationMode !== "fixture") {
+    throw new Error(
+      "--fixture-behavior requires DEEPLINE_EVAL_INTEGRATION_MODE=fixture."
+    );
+  }
+  if (options.debugFixtureProviderPacing && integrationMode !== "fixture") {
+    throw new Error(
+      "--debug-fixture-provider-pacing requires DEEPLINE_EVAL_INTEGRATION_MODE=fixture."
+    );
+  }
+  const testPolicyOverrides = {
+    ...options.debugMapLatency ? { mapLatencyProfile: true } : {},
+    ...options.debugFixtureProviderPacing ? { enforceFixtureProviderPacing: true } : {}
+  };
   const startRequest = {
     name: playName,
     ...selectedRevisionId ? { revisionId: selectedRevisionId } : {},
@@ -21763,8 +22000,9 @@ async function handleNamedRun(options, hooks) {
     ...stagedFileInputs.packagedFiles.length ? { packagedFiles: stagedFileInputs.packagedFiles } : {},
     ...options.force ? { force: true } : {},
     ...options.profile ? { profile: options.profile } : {},
-    ...options.debugMapLatency ? { testPolicyOverrides: { mapLatencyProfile: true } } : {},
-    ...integrationMode ? { integrationMode } : {}
+    ...Object.keys(testPolicyOverrides).length > 0 ? { testPolicyOverrides } : {},
+    ...integrationMode ? { integrationMode } : {},
+    ...options.fixtureBehavior ? { fixtureBehavior: options.fixtureBehavior } : {}
   };
   if (options.watch) {
     progress.phase("starting run");
@@ -23230,12 +23468,18 @@ Examples:
   ).option(
     "--profile <id>",
     "Internal/testing: override the execution profile for this run"
+  ).option(
+    "--fixture-behavior <json>",
+    "Internal/testing: fixture response behavior JSON object or @file path"
   ).option("--watch", "Compatibility alias; run waits by default").option("--wait", "Compatibility alias; run waits by default").option("--no-wait", "Start the run and return immediately").option(
     "--logs",
     "When output is non-interactive, stream play logs to stderr while waiting"
   ).option("--tail-timeout-ms <ms>", "Timeout while watching the run stream").option("--force", "Start a fresh run graph").option("--open", "Open the play page in a browser after the run starts").option(
     "--debug-map-latency",
     "Internal diagnostics: emit one aggregate latency profile per dataset map"
+  ).option(
+    "--debug-fixture-provider-pacing",
+    "Internal diagnostics: retain provider pacing while fixture mode is active"
   ).option("--json", "Emit JSON output").option("--full", "Debug only: with --json, emit the raw status payload").addHelpText(
     "afterAll",
     `
@@ -23267,6 +23511,7 @@ Pass-through input flags:
       ...options.latest ? ["--latest"] : [],
       ...options.revisionId ? ["--revision-id", options.revisionId] : [],
       ...options.profile ? ["--profile", options.profile] : [],
+      ...options.fixtureBehavior ? ["--fixture-behavior", options.fixtureBehavior] : [],
       ...options.wait === false ? ["--no-wait"] : [],
       ...options.watch || options.wait ? ["--watch"] : [],
       ...options.logs ? ["--logs"] : [],
@@ -23274,6 +23519,7 @@ Pass-through input flags:
       ...options.force ? ["--force"] : [],
       ...options.open ? ["--open"] : [],
       ...options.debugMapLatency ? ["--debug-map-latency"] : [],
+      ...options.debugFixtureProviderPacing ? ["--debug-fixture-provider-pacing"] : [],
       ...options.json ? ["--json"] : [],
       ...options.full ? ["--full"] : [],
       ...passthroughArgs