deepline 0.1.109 → 0.1.111

package/dist/repo/shared_libs/play-runtime/fullenrich-batching.ts

@@ -0,0 +1,229 @@
+import {
+  defineBatchStrategyMap,
+  type BatchOperationStrategy,
+} from './batching-types';
+
+const FULLENRICH_BATCH_ITEM_KEY = 'deepline_batch_item_key';
+const FULLENRICH_BATCH_SIZE = 100;
+
+type FullEnrichContactRow = Record<string, unknown> & {
+  custom?: Record<string, string>;
+};
+
+type FullEnrichBulkPayload = {
+  name: string;
+  webhook_url?: string;
+  wait_for_completion?: boolean;
+  poll_interval_ms?: number;
+  max_wait_ms?: number;
+  data: FullEnrichContactRow[];
+};
+
+type FullEnrichBulkResult = Record<string, unknown> & {
+  data?: unknown[];
+};
+
+function sortRecord(value: Record<string, unknown>): Record<string, unknown> {
+  const entries = Object.entries(value)
+    .filter(([, entry]) => entry !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => [key, stableValue(entry)]);
+  return Object.fromEntries(entries);
+}
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stableValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    return sortRecord(value as Record<string, unknown>);
+  }
+  return value;
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(stableValue(value));
+}
+
+function readPath(root: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = root;
+  for (const part of parts) {
+    if (!current || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function readArrayAtPaths(root: unknown, paths: string[]): unknown[] | null {
+  for (const path of paths) {
+    const value = readPath(root, path);
+    if (Array.isArray(value)) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function readRows(payload: FullEnrichBulkPayload): FullEnrichContactRow[] {
+  return Array.isArray(payload.data) ? payload.data : [];
+}
+
+function isOneRowPayload(payload: FullEnrichBulkPayload): boolean {
+  return readRows(payload).length === 1;
+}
+
+function controlKey(payload: FullEnrichBulkPayload): string {
+  return stableStringify({
+    webhook_url: payload.webhook_url ?? null,
+    wait_for_completion: payload.wait_for_completion ?? null,
+    poll_interval_ms: payload.poll_interval_ms ?? null,
+    max_wait_ms: payload.max_wait_ms ?? null,
+  });
+}
+
+function rowIdentity(row: FullEnrichContactRow): string {
+  return stableStringify({
+    first_name: row.first_name ?? null,
+    last_name: row.last_name ?? null,
+    domain: row.domain ?? null,
+    company_name: row.company_name ?? null,
+    linkedin_url: row.linkedin_url ?? null,
+    enrich_fields: row.enrich_fields ?? null,
+    custom: row.custom ?? null,
+  });
+}
+
+function shortStableHash(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(36);
+}
+
+function itemKey(payload: FullEnrichBulkPayload, index = 0): string {
+  return `dl_${index}_${shortStableHash(rowIdentity(readRows(payload)[0] ?? {}))}`;
+}
+
+function withBatchItemKey(
+  row: FullEnrichContactRow,
+  key: string,
+): FullEnrichContactRow {
+  return {
+    ...row,
+    custom: {
+      ...(row.custom ?? {}),
+      [FULLENRICH_BATCH_ITEM_KEY]: key,
+    },
+  };
+}
+
+function extractResultRows(fullResult: FullEnrichBulkResult | unknown) {
+  return readArrayAtPaths(fullResult, ['data']) ?? [];
+}
+
+function readResultItemKey(row: unknown): string | null {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) {
+    return null;
+  }
+  const custom = (row as Record<string, unknown>).custom;
+  if (!custom || typeof custom !== 'object' || Array.isArray(custom)) {
+    return null;
+  }
+  const key = (custom as Record<string, unknown>)[FULLENRICH_BATCH_ITEM_KEY];
+  return typeof key === 'string' && key.trim() ? key.trim() : null;
+}
+
+const fullenrichBulkSelfBatchStrategy: BatchOperationStrategy<
+  FullEnrichBulkPayload,
+  FullEnrichBulkPayload,
+  FullEnrichBulkResult,
+  { data: FullEnrichBulkResult },
+  unknown
+> = {
+  sourceOperation: 'fullenrich_bulk_enrich',
+  batchOperation: 'fullenrich_bulk_enrich',
+  kind: 'identifier_batch',
+  maxBatchSize: FULLENRICH_BATCH_SIZE,
+  canBatchWith(left, right) {
+    return (
+      isOneRowPayload(left) &&
+      isOneRowPayload(right) &&
+      controlKey(left) === controlKey(right)
+    );
+  },
+  toBucketKey(payload) {
+    if (!isOneRowPayload(payload)) {
+      return `fullenrich_bulk_enrich:passthrough:${stableStringify(payload)}`;
+    }
+    return `fullenrich_bulk_enrich:${controlKey(payload)}`;
+  },
+  toItemKey(payload) {
+    return itemKey(payload);
+  },
+  compile(payloads) {
+    const first = payloads[0];
+    const rows = payloads.flatMap((payload, index) =>
+      readRows(payload).map((row) =>
+        withBatchItemKey(row, itemKey(payload, index)),
+      ),
+    );
+    return {
+      batchOperation: 'fullenrich_bulk_enrich',
+      batchPayload: {
+        name:
+          payloads.length === 1
+            ? first?.name || 'deepline-fullenrich-batch'
+            : `deepline-fullenrich-batch-${payloads.length}`,
+        ...(first?.webhook_url ? { webhook_url: first.webhook_url } : {}),
+        ...(first?.wait_for_completion !== undefined
+          ? { wait_for_completion: first.wait_for_completion }
+          : {}),
+        ...(first?.poll_interval_ms !== undefined
+          ? { poll_interval_ms: first.poll_interval_ms }
+          : {}),
+        ...(first?.max_wait_ms !== undefined
+          ? { max_wait_ms: first.max_wait_ms }
+          : {}),
+        data: rows,
+      },
+      items: payloads.map((payload, index) => ({
+        itemKey: itemKey(payload, index),
+        payload,
+      })),
+    };
+  },
+  splitResult(fullResult, compiled) {
+    const resultRows = extractResultRows(fullResult);
+    const rowsByItemKey = new Map<string, unknown>();
+    for (const row of resultRows) {
+      const key = readResultItemKey(row);
+      if (key) {
+        rowsByItemKey.set(key, row);
+      }
+    }
+
+    return compiled.items.map((item, index) => {
+      const matchedRow =
+        rowsByItemKey.get(item.itemKey) ??
+        (index < resultRows.length ? resultRows[index] : null);
+      const singleResult = {
+        ...fullResult,
+        data: matchedRow ? [matchedRow] : [],
+      };
+      return {
+        itemKey: item.itemKey,
+        result: { data: singleResult },
+        rawResult: matchedRow,
+      };
+    });
+  },
+};
+
+export const fullenrichBatchStrategies = defineBatchStrategyMap({
+  fullenrich_bulk_enrich: fullenrichBulkSelfBatchStrategy,
+});

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

@@ -116,7 +116,7 @@ export const SHARED_EXECUTION_POLICY: ResolvedExecutionPolicy = {
   },
   pacing: {
     // Undeclared providers; declared providers (rate-limit-definitions.ts) win.
-    defaultProviderRequestsPerSecond: 30,
+    defaultProviderRequestsPerSecond: 10,
     suggestedMaxParallelism: 50,
   },
 };

package/dist/repo/shared_libs/play-runtime/play-runtime-batching-registry.ts

@@ -0,0 +1,20 @@
+import type { AnyBatchOperationStrategy } from './batching-types';
+import { DEFAULT_PLAY_RUNTIME_BATCH_STRATEGIES } from './default-batch-strategies';
+import { fullenrichBatchStrategies } from './fullenrich-batching';
+
+export const PLAY_RUNTIME_BATCH_OPERATION_REGISTRY: Record<
+  string,
+  AnyBatchOperationStrategy
+> = {
+  ...DEFAULT_PLAY_RUNTIME_BATCH_STRATEGIES,
+  ...fullenrichBatchStrategies,
+};
+
+export function getPlayRuntimeBatchStrategy(
+  operation: string | null | undefined,
+): AnyBatchOperationStrategy | null {
+  if (!operation) {
+    return null;
+  }
+  return PLAY_RUNTIME_BATCH_OPERATION_REGISTRY[operation] ?? null;
+}

package/dist/repo/shared_libs/play-runtime/run-failure.ts

@@ -1,9 +1,12 @@
-export const CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR =
-  'Durable Object reset because its code was updated.';
+const CLOUDFLARE_DURABLE_OBJECT_RESET_RE =
+  /Durable Object.*(?:code was updated|storage caused object)/;
 
 export const PLATFORM_DEPLOY_INTERRUPTED_MESSAGE =
   'Run interrupted by a platform deploy and was not retried automatically. Re-run the same command; the input is unchanged.';
 
+export const INTERNAL_RUNTIME_STORAGE_ERROR_MESSAGE =
+  'Internal play runtime storage failed. Please retry the run; if this keeps happening, contact Deepline support with the run ID.';
+
 export type PlayRunFailureDetails = {
   code: string;
   phase: string;
@@ -19,23 +22,15 @@ function toErrorText(error: unknown): string {
   return String(error);
 }
 
-export function isCloudflareDurableObjectCodeUpdatedError(
-  error: unknown,
-): boolean {
-  return toErrorText(error).includes(
-    CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR,
-  );
-}
-
 export function normalizePlayRunFailure(error: unknown): PlayRunFailureDetails {
   const cause = toErrorText(error);
-  if (isCloudflareDurableObjectCodeUpdatedError(cause)) {
+  if (CLOUDFLARE_DURABLE_OBJECT_RESET_RE.test(cause)) {
     return {
       code: 'PLATFORM_DEPLOY_INTERRUPTED',
       phase: 'runtime',
       message: PLATFORM_DEPLOY_INTERRUPTED_MESSAGE,
       retryable: true,
-      cause: CLOUDFLARE_DURABLE_OBJECT_CODE_UPDATED_ERROR,
+      cause,
     };
   }
   const playDepthBudgetMatch = cause.match(
@@ -50,6 +45,19 @@ export function normalizePlayRunFailure(error: unknown): PlayRunFailureDetails {
       cause,
     };
   }
+  const lowerCause = cause.toLowerCase();
+  if (
+    lowerCause.includes('neondberror') ||
+    lowerCause.includes('bind message supplies') ||
+    lowerCause.includes('prepared statement')
+  ) {
+    return {
+      code: 'RUN_STORAGE_FAILED',
+      phase: 'storage',
+      message: INTERNAL_RUNTIME_STORAGE_ERROR_MESSAGE,
+      retryable: true,
+    };
+  }
   return {
     code: 'RUN_FAILED',
     phase: 'runtime',

package/dist/repo/shared_libs/play-runtime/run-ledger.ts

@@ -549,22 +549,17 @@ function appendLogLines(
 
 /**
  * Terminal-status precedence. Re-delivery of the same terminal status is a
- * benign no-op handled by the regular reduction. A terminal event that
- * disagrees with an already-terminal snapshot is ignored (keeping e.g. an
- * explicit user cancellation from being flipped to completed by a late
- * worker terminal), and the conflict is recorded as one anomaly log line —
- * with ONE exception: `run.failed` DEMOTES a `completed` snapshot. The
- * worker appends run.completed BEFORE awaiting post-completion accounting
- * (compute billing finalize), so a billing business denial there — e.g. the
- * per-run credit cap (maxCreditsPerRun) — arrives as a later run.failed
- * that MUST fail the run. Blanket first-terminal-wins silently completed
- * capped runs (regression pinned by
- * tests/v2-plays/plays/44-compute-billing-cap.play.ts). A cancelled run
- * stays cancelled, and a failed run can never be flipped to completed.
+ * benign no-op handled by the regular reduction. Conflicting terminal events
+ * use newest-terminal-wins by event time: older events are ignored and logged,
+ * newer events reconcile the snapshot. This is the idempotency model callers
+ * expect when duplicate/retried work completes out of order. It also preserves
+ * post-completion billing cap demotion because that denial arrives as a newer
+ * run.failed event.
  */
 function conflictingTerminalSnapshot(
   base: PlayRunLedgerSnapshot,
   eventType: keyof typeof TERMINAL_STATUS_BY_EVENT_TYPE,
+  occurredAt: number,
 ): PlayRunLedgerSnapshot | null {
   if (!isTerminalPlayRunLedgerStatus(base.status)) {
     return null;
@@ -572,14 +567,16 @@ function conflictingTerminalSnapshot(
   if (TERMINAL_STATUS_BY_EVENT_TYPE[eventType] === base.status) {
     return null;
   }
-  if (base.status === 'completed' && eventType === 'run.failed') {
-    // Post-completion accounting demotion (e.g. per-run billing cap denial):
-    // let the regular run.failed reduction flip the run to failed.
+  const terminalAt = base.finishedAt ?? base.updatedAt ?? 0;
+  if (occurredAt > terminalAt) {
+    // Newer terminal evidence reconciles the run. This covers replay/receipt
+    // races where an earlier attempt failed but a later attempt recovered and
+    // completed with the durable result.
     return null;
   }
   return withTiming(
     appendLogLines(base, [
-      `[ledger] conflicting terminal event ${eventType} ignored; status already ${base.status}`,
+      `[ledger] stale conflicting terminal event ${eventType} ignored; status already ${base.status}`,
     ]),
   );
 }
@@ -617,6 +614,23 @@ function settleRunningStepsOnTerminal(
   return changed ? { ...snapshot, stepsById } : snapshot;
 }
 
+function terminalFinishedAt(
+  base: PlayRunLedgerSnapshot,
+  eventType: keyof typeof TERMINAL_STATUS_BY_EVENT_TYPE,
+  occurredAt: number,
+): number {
+  const nextStatus = TERMINAL_STATUS_BY_EVENT_TYPE[eventType];
+  const terminalAt = base.finishedAt ?? base.updatedAt ?? 0;
+  if (
+    isTerminalPlayRunLedgerStatus(base.status) &&
+    nextStatus !== base.status &&
+    occurredAt > terminalAt
+  ) {
+    return occurredAt;
+  }
+  return base.finishedAt ?? occurredAt;
+}
+
 export function reducePlayRunLedgerEvent(
   snapshot: PlayRunLedgerSnapshot,
   event: PlayRunLedgerEvent,
@@ -654,52 +668,46 @@ export function reducePlayRunLedgerEvent(
       });
     case 'run.completed':
       return (
-        conflictingTerminalSnapshot(base, event.type) ??
-        withTiming(
-          {
-            ...settleRunningStepsOnTerminal(base, 'completed', occurredAt),
-            status: 'completed',
-            error: null,
-            startedAt: base.startedAt ?? occurredAt,
-            finishedAt: base.finishedAt ?? occurredAt,
-            activeStepId: null,
-            activeArtifactTableNamespace: null,
-            result: event.result ?? base.result,
-            resultSummary: event.resultSummary ?? base.resultSummary,
-          },
-        )
+        conflictingTerminalSnapshot(base, event.type, occurredAt) ??
+        withTiming({
+          ...settleRunningStepsOnTerminal(base, 'completed', occurredAt),
+          status: 'completed',
+          error: null,
+          startedAt: base.startedAt ?? occurredAt,
+          finishedAt: terminalFinishedAt(base, event.type, occurredAt),
+          activeStepId: null,
+          activeArtifactTableNamespace: null,
+          result: event.result ?? base.result,
+          resultSummary: event.resultSummary ?? base.resultSummary,
+        })
       );
     case 'run.failed':
       return (
-        conflictingTerminalSnapshot(base, event.type) ??
-        withTiming(
-          {
-            ...settleRunningStepsOnTerminal(base, 'failed', occurredAt),
-            status: 'failed',
-            error: event.error ?? base.error ?? null,
-            startedAt: base.startedAt ?? occurredAt,
-            finishedAt: base.finishedAt ?? occurredAt,
-            activeStepId: null,
-            activeArtifactTableNamespace: null,
-            result: event.result ?? base.result,
-          },
-        )
+        conflictingTerminalSnapshot(base, event.type, occurredAt) ??
+        withTiming({
+          ...settleRunningStepsOnTerminal(base, 'failed', occurredAt),
+          status: 'failed',
+          error: event.error ?? base.error ?? null,
+          startedAt: base.startedAt ?? occurredAt,
+          finishedAt: terminalFinishedAt(base, event.type, occurredAt),
+          activeStepId: null,
+          activeArtifactTableNamespace: null,
+          result: event.result ?? base.result,
+        })
       );
     case 'run.cancelled':
       return (
-        conflictingTerminalSnapshot(base, event.type) ??
-        withTiming(
-          {
-            ...settleRunningStepsOnTerminal(base, 'failed', occurredAt),
-            status: 'cancelled',
-            error: event.error ?? base.error ?? null,
-            startedAt: base.startedAt ?? occurredAt,
-            finishedAt: base.finishedAt ?? occurredAt,
-            activeStepId: null,
-            activeArtifactTableNamespace: null,
-            result: event.result ?? base.result,
-          },
-        )
+        conflictingTerminalSnapshot(base, event.type, occurredAt) ??
+        withTiming({
+          ...settleRunningStepsOnTerminal(base, 'failed', occurredAt),
+          status: 'cancelled',
+          error: event.error ?? base.error ?? null,
+          startedAt: base.startedAt ?? occurredAt,
+          finishedAt: terminalFinishedAt(base, event.type, occurredAt),
+          activeStepId: null,
+          activeArtifactTableNamespace: null,
+          result: event.result ?? base.result,
+        })
       );
     case 'log.appended':
       return withTiming(
@@ -712,6 +720,11 @@ export function reducePlayRunLedgerEvent(
       );
     case 'step.started': {
       const current = base.stepsById[event.stepId];
+      const shouldRefineSyntheticStart =
+        current?.startedAt != null &&
+        current.completedAt != null &&
+        current.startedAt === current.completedAt &&
+        occurredAt < current.startedAt;
       const nextStep: PlayRunLedgerStepSnapshot = {
         ...(current ?? { stepId: event.stepId, status: 'running' as const }),
         stepId: event.stepId,
@@ -725,8 +738,10 @@ export function reducePlayRunLedgerEvent(
           event.artifactTableNamespace ??
           current?.artifactTableNamespace ??
           null,
-        startedAt: current?.startedAt ?? occurredAt,
-        updatedAt: occurredAt,
+        startedAt: shouldRefineSyntheticStart
+          ? occurredAt
+          : (current?.startedAt ?? occurredAt),
+        updatedAt: Math.max(current?.updatedAt ?? 0, occurredAt),
       };
       return withTiming({
         ...base,
@@ -767,6 +782,25 @@ export function reducePlayRunLedgerEvent(
           : event.status === 'running' && inferredStatus === 'completed'
             ? 'completed'
             : (event.status ?? current?.status ?? inferredStatus);
+      const completedAt =
+        current?.completedAt ??
+        event.progress.completedAt ??
+        (status === 'completed'
+          ? (event.progress.updatedAt ?? occurredAt)
+          : null);
+      const shouldRefineSyntheticStart =
+        current?.startedAt != null &&
+        current.completedAt != null &&
+        current.startedAt === current.completedAt &&
+        event.progress.startedAt != null &&
+        event.progress.startedAt < current.startedAt;
+      const startedAt =
+        (shouldRefineSyntheticStart ? event.progress.startedAt : null) ??
+        current?.startedAt ??
+        event.progress.startedAt ??
+        (status === 'completed' || status === 'failed'
+          ? (completedAt ?? event.progress.updatedAt ?? occurredAt)
+          : null);
       const nextStep: PlayRunLedgerStepSnapshot = {
         ...(current ?? { stepId: event.stepId, status }),
         stepId: event.stepId,
@@ -777,13 +811,8 @@ export function reducePlayRunLedgerEvent(
           progress.artifactTableNamespace ??
           current?.artifactTableNamespace ??
           null,
-        startedAt: current?.startedAt ?? event.progress.startedAt ?? null,
-        completedAt:
-          current?.completedAt ??
-          event.progress.completedAt ??
-          (status === 'completed'
-            ? (event.progress.updatedAt ?? occurredAt)
-            : null),
+        startedAt,
+        completedAt,
         updatedAt: occurredAt,
         progress,
       };
@@ -818,6 +847,10 @@ export function reducePlayRunLedgerEvent(
           : event.type === 'step.failed'
             ? 'failed'
             : 'skipped';
+      const completedAt =
+        status === 'skipped' || preserveFailedStatus
+          ? (current?.completedAt ?? null)
+          : occurredAt;
       const nextStep: PlayRunLedgerStepSnapshot = {
         ...(current ?? { stepId: event.stepId, status }),
         stepId: event.stepId,
@@ -828,11 +861,12 @@ export function reducePlayRunLedgerEvent(
           event.artifactTableNamespace ??
           current?.artifactTableNamespace ??
           null,
-        startedAt: current?.startedAt ?? null,
-        completedAt:
-          status === 'skipped' || preserveFailedStatus
-            ? (current?.completedAt ?? null)
-            : occurredAt,
+        startedAt:
+          current?.startedAt ??
+          (status === 'completed' || status === 'failed'
+            ? (completedAt ?? occurredAt)
+            : null),
+        completedAt,
         updatedAt: occurredAt,
         progress: current?.progress ?? null,
       };
@@ -927,6 +961,20 @@ export function slicePositionalLogLines(input: {
   return { lines: [...lines], channelOffset: sendFromOffset };
 }
 
+function terminalLogReplayChannelOffset(input: {
+  liveLogTotalCount?: number;
+  liveLogsLength: number;
+}): number | null {
+  if (
+    typeof input.liveLogTotalCount !== 'number' ||
+    !Number.isFinite(input.liveLogTotalCount) ||
+    input.liveLogTotalCount < input.liveLogsLength
+  ) {
+    return null;
+  }
+  return input.liveLogTotalCount - input.liveLogsLength;
+}
+
 /**
  * Forward producer log lines as one `log.appended` event.
  *
@@ -968,6 +1016,35 @@ export function buildPlayRunLedgerEventsFromLogLines(input: {
   ];
 }
 
+/**
+ * Re-send a terminal retained log tail through terminal transport recovery.
+ *
+ * Live worker flushes use positional channel offsets. Terminal replay is a
+ * different transport: it replays the runner's retained output after terminal
+ * state is known. When the producer knows the retained tail's offset, Convex
+ * uses that offset only to bound occurrence-count reconciliation to the same
+ * tail window; it does not route the replay through the worker cursor.
+ */
+export function buildTerminalLogReplayEvents(input: {
+  runId: string;
+  lines: readonly string[];
+  source?: PlayRunLedgerEventSource;
+  occurredAt?: number;
+  liveLogTotalCount?: number;
+}): PlayRunLedgerEvent[] {
+  const channelOffset = terminalLogReplayChannelOffset({
+    liveLogTotalCount: input.liveLogTotalCount,
+    liveLogsLength: input.lines.length,
+  });
+  return buildPlayRunLedgerEventsFromLogLines({
+    runId: input.runId,
+    lines: input.lines,
+    source: 'coordinator',
+    occurredAt: input.occurredAt,
+    channelOffset,
+  });
+}
+
 export function buildPlayRunLedgerEventsFromStatusPatch(input: {
   patch: PlayRunLedgerStatusPatch;
   previousSnapshot: PlayRunLedgerSnapshot;

package/dist/repo/shared_libs/play-runtime/scheduler-backend.ts

@@ -4,8 +4,8 @@
  * One of three pluggable axes (alongside runner-backends and dedup-backends).
  * Selected per-run via PlayExecutionProfile.
  *
- * Temporal is the existing production scheduler. Cloudflare Workflows is the
- * edge scheduler used by the workers_edge profile.
+ * Cloudflare Workflows is the default production scheduler through the
+ * workers_edge profile. Hatchet is selected explicitly by the hatchet profile.
  *
  * Customer plays are unaffected — this is purely the orchestration layer.
  */
@@ -18,6 +18,7 @@ import type {
 import type { ExecutionPlan } from './execution-plan';
 import type { PlayRuntimeManifestMap } from '../plays/compiler-manifest';
 import type { PreloadedRuntimeDbSession } from './db-session';
+import type { PlayRunnerRuntimeTiming } from './protocol';
 
 export const PLAY_SCHEDULER_BACKENDS = {
   temporal: 'temporal',
@@ -128,6 +129,8 @@ export type PlaySchedulerSubmitInput = {
   userId?: string | null;
   source?: 'published' | 'ad_hoc' | 'draft';
   executionProfile?: string | null;
+  /** Durable per-workspace active run cap enforced when the run row is projected. */
+  activeRunLimit?: number | null;
   /** runner backend to use for executing attempts */
   runtimeBackend: string;
   /** dedup backend for cross-attempt cross-process idempotency */
@@ -195,6 +198,7 @@ export type PlaySchedulerResultEnvelope = {
   finalCheckpoint?: PlayCheckpoint;
   totalRows?: number;
   durationMs?: number;
+  runtimeTiming?: PlayRunnerRuntimeTiming;
 };
 
 export interface PlaySchedulerBackend {