deepline 0.1.150 → 0.1.151

package/dist/bundling-sources/shared_libs/play-runtime/map-row-outcome.ts

@@ -0,0 +1,167 @@
+import type { MapRowOutcome, MapRowOutcomeStatus } from './durability-store';
+
+export const MAP_ROW_OUTCOME_RUNTIME_FIELDS = {
+  rowKey: '__deeplineRowKey',
+  cellMetaPatch: '__deeplineCellMetaPatch',
+  rowStatus: '__deeplineRowStatus',
+  rowError: '__deeplineRowError',
+} as const;
+
+const MAP_ROW_OUTCOME_RUNTIME_FIELD_SET = new Set<string>(
+  Object.values(MAP_ROW_OUTCOME_RUNTIME_FIELDS),
+);
+
+export type MapRowOutcomeRuntimeRow = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+export function resolveMapRowOutcomeKey(
+  row: MapRowOutcomeRuntimeRow,
+): string | null {
+  const key = row[MAP_ROW_OUTCOME_RUNTIME_FIELDS.rowKey];
+  return typeof key === 'string' && key.length > 0 ? key : null;
+}
+
+export function mapRowOutcomeRuntimeFields(input: {
+  key: string;
+  cellMetaPatch?: Record<string, unknown> | null;
+  status?: MapRowOutcomeStatus | null;
+  error?: string | null;
+}): Record<string, unknown> {
+  return {
+    [MAP_ROW_OUTCOME_RUNTIME_FIELDS.rowKey]: input.key,
+    ...(input.cellMetaPatch
+      ? { [MAP_ROW_OUTCOME_RUNTIME_FIELDS.cellMetaPatch]: input.cellMetaPatch }
+      : {}),
+    ...(input.status
+      ? { [MAP_ROW_OUTCOME_RUNTIME_FIELDS.rowStatus]: input.status }
+      : {}),
+    ...(input.error !== undefined
+      ? { [MAP_ROW_OUTCOME_RUNTIME_FIELDS.rowError]: input.error }
+      : {}),
+  };
+}
+
+export function completedMapRowOutcome(input: {
+  key: string;
+  inputIndex?: number | null;
+  data: Record<string, unknown>;
+  cellMetaPatch?: Record<string, unknown> | null;
+}): MapRowOutcome {
+  return {
+    key: input.key,
+    ...(input.inputIndex !== undefined ? { inputIndex: input.inputIndex } : {}),
+    data: input.data,
+    ...(input.cellMetaPatch ? { cellMetaPatch: input.cellMetaPatch } : {}),
+  };
+}
+
+export function failedMapRowOutcome(input: {
+  key: string;
+  inputIndex?: number | null;
+  data: Record<string, unknown>;
+  cellMetaPatch?: Record<string, unknown> | null;
+  error?: string | null;
+}): MapRowOutcome {
+  return {
+    ...completedMapRowOutcome(input),
+    status: 'failed',
+    error: input.error ?? null,
+  };
+}
+
+export function mapRowOutcomeRuntimeRow(
+  outcome: MapRowOutcome,
+): Record<string, unknown> {
+  return {
+    ...outcome.data,
+    ...mapRowOutcomeRuntimeFields({
+      key: outcome.key,
+      cellMetaPatch: outcome.cellMetaPatch,
+      status: outcome.status,
+      error: outcome.error,
+    }),
+  };
+}
+
+export function copyMapRowOutcomeRuntimeFields<
+  TTarget extends MapRowOutcomeRuntimeRow,
+>(target: TTarget, row: MapRowOutcomeRuntimeRow): TTarget {
+  const writableTarget = target as MapRowOutcomeRuntimeRow;
+  for (const runtimeField of MAP_ROW_OUTCOME_RUNTIME_FIELD_SET) {
+    if (runtimeField in row) {
+      writableTarget[runtimeField] = row[runtimeField];
+    }
+  }
+  return target;
+}
+
+export function stripMapRowOutcomeRuntimeFields<
+  TRow extends MapRowOutcomeRuntimeRow,
+>(row: TRow): TRow {
+  const data: MapRowOutcomeRuntimeRow = {};
+  for (const fieldName of Reflect.ownKeys(row)) {
+    if (
+      typeof fieldName === 'string' &&
+      MAP_ROW_OUTCOME_RUNTIME_FIELD_SET.has(fieldName)
+    ) {
+      continue;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(row, fieldName);
+    if (!descriptor) continue;
+    Object.defineProperty(data, fieldName, descriptor);
+  }
+  return data as TRow;
+}
+
+export function mapRowOutcomeFromRuntimeRow(
+  row: MapRowOutcomeRuntimeRow,
+): MapRowOutcome | null {
+  if (typeof row.key === 'string' && isRecord(row.data)) {
+    return {
+      key: row.key,
+      data: row.data,
+      ...(isRecord(row.cellMetaPatch)
+        ? { cellMetaPatch: row.cellMetaPatch }
+        : {}),
+      ...(row.status === 'failed'
+        ? {
+            status: 'failed',
+            error: typeof row.error === 'string' ? row.error : null,
+          }
+        : {}),
+    };
+  }
+
+  const key = resolveMapRowOutcomeKey(row);
+  if (!key) return null;
+  const cellMetaPatch = row[MAP_ROW_OUTCOME_RUNTIME_FIELDS.cellMetaPatch];
+  const rowStatus = row[MAP_ROW_OUTCOME_RUNTIME_FIELDS.rowStatus];
+  const rowError = row[MAP_ROW_OUTCOME_RUNTIME_FIELDS.rowError];
+  return {
+    key,
+    data: stripMapRowOutcomeRuntimeFields(row),
+    ...(isRecord(cellMetaPatch) ? { cellMetaPatch } : {}),
+    ...(rowStatus === 'failed'
+      ? {
+          status: 'failed',
+          error: typeof rowError === 'string' ? rowError : null,
+        }
+      : {}),
+  };
+}
+
+export function requireMapRowOutcomeFromRuntimeRow(
+  row: MapRowOutcomeRuntimeRow,
+  input: { tableNamespace: string },
+): MapRowOutcome {
+  const outcome = mapRowOutcomeFromRuntimeRow(row);
+  if (!outcome) {
+    throw new Error(
+      `persistCompletedMapRows received a row without a key for tableNamespace=${input.tableNamespace}.`,
+    );
+  }
+  return outcome;
+}

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

@@ -0,0 +1,79 @@
+import { resolveBuiltinPacing } from './builtin-pacing';
+import type { PacingRule, PlayQueueHint } from './governor/rate-state-backend';
+
+export type ResolvedPacingPolicy = {
+  provider: string;
+  rules: PacingRule[];
+};
+
+type PacingPolicyQueueHint = Pick<
+  PlayQueueHint,
+  'provider' | 'ruleId' | 'requestsPerWindow' | 'windowMs' | 'maxConcurrency'
+>;
+
+function isFinitePositiveNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+export function pacingPolicyFromQueueHints(
+  hints: readonly PacingPolicyQueueHint[],
+): ResolvedPacingPolicy | null {
+  if (hints.length === 0) return null;
+  const provider = hints[0]?.provider?.trim();
+  if (!provider) return null;
+  const rules = hints.flatMap((hint) => {
+    if (
+      typeof hint.ruleId !== 'string' ||
+      !hint.ruleId.trim() ||
+      !isFinitePositiveNumber(hint.requestsPerWindow) ||
+      !isFinitePositiveNumber(hint.windowMs)
+    ) {
+      return [];
+    }
+    return [
+      {
+        ruleId: hint.ruleId,
+        requestsPerWindow: hint.requestsPerWindow,
+        windowMs: hint.windowMs,
+        maxConcurrency:
+          typeof hint.maxConcurrency === 'number' &&
+          Number.isFinite(hint.maxConcurrency) &&
+          hint.maxConcurrency > 0
+            ? hint.maxConcurrency
+            : null,
+      } satisfies PacingRule,
+    ];
+  });
+  return rules.length > 0 ? { provider, rules } : null;
+}
+
+export function pacingPolicyFromUnknownQueueHints(
+  value: unknown,
+): ResolvedPacingPolicy | null {
+  if (!Array.isArray(value)) return null;
+  return pacingPolicyFromQueueHints(
+    value
+      .filter((hint): hint is Record<string, unknown> =>
+        Boolean(hint && typeof hint === 'object' && !Array.isArray(hint)),
+      )
+      .map((hint) => ({
+        provider: typeof hint.provider === 'string' ? hint.provider : '',
+        ruleId: typeof hint.ruleId === 'string' ? hint.ruleId : '',
+        requestsPerWindow:
+          typeof hint.requestsPerWindow === 'number'
+            ? hint.requestsPerWindow
+            : Number.NaN,
+        windowMs:
+          typeof hint.windowMs === 'number' ? hint.windowMs : Number.NaN,
+        maxConcurrency:
+          typeof hint.maxConcurrency === 'number' ? hint.maxConcurrency : null,
+      })),
+  );
+}
+
+export function pacingPolicyForTool(
+  toolId: string,
+  hints: readonly PlayQueueHint[],
+): ResolvedPacingPolicy | null {
+  return resolveBuiltinPacing(toolId) ?? pacingPolicyFromQueueHints(hints);
+}

package/dist/bundling-sources/shared_libs/play-runtime/row-isolation.ts

@@ -0,0 +1,39 @@
+import { isHardBillingToolHttpError } from './tool-http-errors';
+
+/**
+ * Thrown by runner Adapters when a Play Run is externally cancelled. Row
+ * isolation must let this escape so in-flight user code stops cooperatively.
+ */
+export class WorkflowAbortError extends Error {
+  override readonly name = 'WorkflowAbort';
+  constructor(message = 'Play run cancelled.') {
+    super(message);
+  }
+}
+
+export function isAbortLikeError(error: unknown): boolean {
+  if (!error) return false;
+  if (error instanceof WorkflowAbortError) return true;
+  if (error instanceof Error) {
+    if (error.name === 'WorkflowAbort' || error.name === 'AbortError') {
+      return true;
+    }
+    return /\b(cancell?ed|aborted|terminate[d]?)\b/i.test(error.message);
+  }
+  return false;
+}
+
+/**
+ * Errors that must stay run-fatal even under default map row failure isolation.
+ *
+ * Provider/tool HTTP failures, including exhausted 429/5xx retries, are row
+ * outcomes after the tool-call Adapter spends its local retry budget. Abort,
+ * Governor budget exhaustion, and hard billing failures escape row isolation.
+ */
+export function isRowIsolationExemptError(error: unknown): boolean {
+  if (isAbortLikeError(error)) return true;
+  if (error instanceof Error && error.name === 'GovernorBudgetError') {
+    return true;
+  }
+  return isHardBillingToolHttpError(error);
+}

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

@@ -60,6 +60,15 @@ import {
 import { stringifyPostgresJson } from './postgres-json';
 import { RECEIPT_STATUS_CODE, receiptStatusFromCode } from './receipt-status';
 import type { MapRowOutcome } from './durability-store';
+import {
+  prepareRuntimeSheetRowTransitions,
+  type RuntimePreparedCompletedRow,
+  type RuntimePreparedFailedRow,
+} from './runtime-sheet-row-transition';
+import {
+  mapRowOutcomeRuntimeFields,
+  resolveMapRowOutcomeKey,
+} from './map-row-outcome';
 import {
   DEEPLINE_CELL_META_FIELD,
   cellPolicyFields,
@@ -92,18 +101,6 @@ type RuntimeDatasetRowEntry = {
   row: Record<string, unknown>;
   inputIndex: number;
 };
-type RuntimePreparedCompletedRow = {
-  key: string;
-  input_index: number | null;
-  data_patch: Record<string, unknown>;
-  cell_meta_patch: Record<string, unknown>;
-};
-
-type RuntimePreparedFailedRow = RuntimePreparedCompletedRow & {
-  /** Row-level error persisted to `_error`; never empty. */
-  error: string;
-};
-
 const dbSessionCache = new Map<string, DbSessionCacheEntry>();
 const dbSessionInFlight = new Map<string, Promise<CreateDbSessionResponse>>();
 const postgresPools = new Map<string, RuntimePool>();
@@ -1680,35 +1677,6 @@ function cachedRuntimeCellMetaPatch(runId: string): Record<string, unknown> {
   };
 }
 
-function completedRuntimeCellMetaPatch(input: {
-  runId: string;
-  outputFields: readonly string[];
-  rowPatch?: Record<string, unknown>;
-}): Record<string, unknown> {
-  const patch: Record<string, unknown> = {};
-  const completedAt = Date.now();
-  for (const field of input.outputFields) {
-    const existing =
-      input.rowPatch?.[field] &&
-      typeof input.rowPatch[field] === 'object' &&
-      !Array.isArray(input.rowPatch[field])
-        ? (input.rowPatch[field] as Record<string, unknown>)
-        : {};
-    patch[field] = {
-      status: 'completed',
-      runId: input.runId,
-      completedAt,
-      ...existing,
-    };
-  }
-  for (const [field, meta] of Object.entries(input.rowPatch ?? {})) {
-    if (!Object.hasOwn(patch, field)) {
-      patch[field] = meta;
-    }
-  }
-  return patch;
-}
-
 function cachedRuntimeCellMetaUpdateSql(
   tableAlias: string,
   outputFields: readonly string[],
@@ -2554,7 +2522,7 @@ async function buildRuntimeSheetDatasetStartResult(
             ),
             sheetContract: input.sheetContract,
           }),
-          __deeplineRowKey: entry.key,
+          ...mapRowOutcomeRuntimeFields({ key: entry.key }),
         })),
         tableNamespace: input.tableNamespace,
       };
@@ -2671,7 +2639,7 @@ async function buildRuntimeSheetDatasetStartResult(
         ),
         sheetContract: input.sheetContract,
       }),
-      __deeplineRowKey: entry.key,
+      ...mapRowOutcomeRuntimeFields({ key: entry.key }),
     }));
   return {
     inserted: input.inserted,
@@ -2683,7 +2651,7 @@ async function buildRuntimeSheetDatasetStartResult(
         completedData: existingPendingRowsByKey.get(entry.key) ?? {},
         sheetContract: input.sheetContract,
       }),
-      __deeplineRowKey: entry.key,
+      ...mapRowOutcomeRuntimeFields({ key: entry.key }),
     })),
     completedRows,
     tableNamespace: input.tableNamespace,
@@ -3061,9 +3029,8 @@ export async function startRuntimeSheetDataset(
     // non-enumerable alias fields on the JSON payload boundary.
     const cleanedRow = toSerializableCsvAliasedRow(row);
     const key =
-      typeof row.__deeplineRowKey === 'string'
-        ? row.__deeplineRowKey
-        : derivePlayRowIdentity(cleanedRow, input.tableNamespace);
+      resolveMapRowOutcomeKey(row) ??
+      derivePlayRowIdentity(cleanedRow, input.tableNamespace);
     if (key && !uniqueRows.has(key)) {
       uniqueRows.set(key, cleanedRow);
     }
@@ -3517,14 +3484,6 @@ async function failRuntimeMapRowChunks(
   return { updated };
 }
 
-function normalizeRuntimeMapInputIndex(value: unknown): number | null {
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    return null;
-  }
-  const normalized = Math.floor(value);
-  return normalized >= 0 ? normalized : null;
-}
-
 /**
  * Mark map rows terminal in the per-run scoped Postgres sheet table by key.
  * Mirrors server-side `store.completeSheetRows` semantics: UPDATE-by-key with
@@ -3603,37 +3562,11 @@ export async function completeRuntimeMapRows(
           .join(',\n        ')}`
       : '';
 
-  const completedRows: RuntimePreparedCompletedRow[] = [];
-  const failedRows: RuntimePreparedFailedRow[] = [];
-  for (const [key, row] of uniqueRows.entries()) {
-    if (row.status === 'failed') {
-      // Failed rows persist only the cell meta the caller recorded (completed
-      // sibling cells + the failed cell). Defaulting every output field to
-      // 'completed' here would lie about the failed cell and break re-run
-      // recompute.
-      failedRows.push({
-        key,
-        input_index: normalizeRuntimeMapInputIndex(row.inputIndex),
-        data_patch: row.data,
-        cell_meta_patch: row.cellMetaPatch ?? {},
-        error:
-          typeof row.error === 'string' && row.error.trim()
-            ? row.error
-            : 'Row execution failed.',
-      });
-      continue;
-    }
-    completedRows.push({
-      key,
-      input_index: normalizeRuntimeMapInputIndex(row.inputIndex),
-      data_patch: row.data,
-      cell_meta_patch: completedRuntimeCellMetaPatch({
-        runId: input.runId,
-        outputFields: input.outputFields ?? [],
-        rowPatch: row.cellMetaPatch,
-      }),
-    });
-  }
+  const { completedRows, failedRows } = prepareRuntimeSheetRowTransitions({
+    rows: uniqueRows.values(),
+    runId: input.runId,
+    outputFields: input.outputFields ?? [],
+  });
   const chunks = chunkValues(completedRows, DIRECT_POSTGRES_BATCH_SIZE);
   const failedChunks = chunkValues(failedRows, DIRECT_POSTGRES_BATCH_SIZE);
   const needsTransaction = chunks.length + failedChunks.length > 1;

package/dist/bundling-sources/shared_libs/play-runtime/runtime-sheet-row-transition.ts

@@ -0,0 +1,90 @@
+import type { MapRowOutcome } from './durability-store';
+
+export type RuntimePreparedCompletedRow = {
+  key: string;
+  input_index: number | null;
+  data_patch: Record<string, unknown>;
+  cell_meta_patch: Record<string, unknown>;
+};
+
+export type RuntimePreparedFailedRow = RuntimePreparedCompletedRow & {
+  /** Row-level error persisted to `_error`; never empty. */
+  error: string;
+};
+
+export function normalizeRuntimeMapInputIndex(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return null;
+  }
+  const normalized = Math.floor(value);
+  return normalized >= 0 ? normalized : null;
+}
+
+export function completedRuntimeCellMetaPatch(input: {
+  runId: string;
+  outputFields: readonly string[];
+  rowPatch?: Record<string, unknown>;
+  nowMs?: number;
+}): Record<string, unknown> {
+  const patch: Record<string, unknown> = {};
+  const completedAt = input.nowMs ?? Date.now();
+  for (const field of input.outputFields) {
+    const existing =
+      input.rowPatch?.[field] &&
+      typeof input.rowPatch[field] === 'object' &&
+      !Array.isArray(input.rowPatch[field])
+        ? (input.rowPatch[field] as Record<string, unknown>)
+        : {};
+    patch[field] = {
+      status: 'completed',
+      runId: input.runId,
+      completedAt,
+      ...existing,
+    };
+  }
+  for (const [field, meta] of Object.entries(input.rowPatch ?? {})) {
+    if (!Object.hasOwn(patch, field)) {
+      patch[field] = meta;
+    }
+  }
+  return patch;
+}
+
+export function prepareRuntimeSheetRowTransitions(input: {
+  rows: Iterable<MapRowOutcome>;
+  runId: string;
+  outputFields: readonly string[];
+}): {
+  completedRows: RuntimePreparedCompletedRow[];
+  failedRows: RuntimePreparedFailedRow[];
+} {
+  const completedRows: RuntimePreparedCompletedRow[] = [];
+  const failedRows: RuntimePreparedFailedRow[] = [];
+  for (const row of input.rows) {
+    if (!row.key) continue;
+    if (row.status === 'failed') {
+      failedRows.push({
+        key: row.key,
+        input_index: normalizeRuntimeMapInputIndex(row.inputIndex),
+        data_patch: row.data,
+        cell_meta_patch: row.cellMetaPatch ?? {},
+        error:
+          typeof row.error === 'string' && row.error.trim()
+            ? row.error
+            : 'Row execution failed.',
+      });
+      continue;
+    }
+    completedRows.push({
+      key: row.key,
+      input_index: normalizeRuntimeMapInputIndex(row.inputIndex),
+      data_patch: row.data,
+      cell_meta_patch: completedRuntimeCellMetaPatch({
+        runId: input.runId,
+        outputFields: input.outputFields,
+        rowPatch: row.cellMetaPatch,
+      }),
+    });
+  }
+  return { completedRows, failedRows };
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-sheet-session.ts

@@ -0,0 +1,43 @@
+export type RuntimeSheetSessionScope<TPreloadedSession = unknown> = {
+  baseUrl: string;
+  executorToken: string;
+  orgId: string;
+  preloadedDbSessions?: TPreloadedSession[] | null;
+  playName: string;
+  runId: string;
+  userEmail?: string | null;
+};
+
+function requireRuntimeSheetSessionField(
+  fieldName: string,
+  value: string,
+): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`Runtime Sheet Session requires ${fieldName}.`);
+  }
+  return trimmed;
+}
+
+export function runtimeSheetSessionScope<TPreloadedSession = unknown>(input: {
+  baseUrl: string;
+  executorToken: string;
+  orgId: string;
+  preloadedDbSessions?: TPreloadedSession[] | null;
+  playName: string;
+  runId: string;
+  userEmail?: string | null;
+}): RuntimeSheetSessionScope<TPreloadedSession> {
+  return {
+    baseUrl: requireRuntimeSheetSessionField('baseUrl', input.baseUrl),
+    executorToken: requireRuntimeSheetSessionField(
+      'executorToken',
+      input.executorToken,
+    ),
+    orgId: requireRuntimeSheetSessionField('orgId', input.orgId),
+    preloadedDbSessions: input.preloadedDbSessions ?? null,
+    playName: requireRuntimeSheetSessionField('playName', input.playName),
+    runId: requireRuntimeSheetSessionField('runId', input.runId),
+    userEmail: input.userEmail ?? null,
+  };
+}