deepline 0.3.201 → 0.3.203

package/dist/bundling-sources/shared_libs/play-runtime/output-size-limits.ts

@@ -390,6 +390,8 @@ export type LedgerTerminalResultRef = {
    * fetching the complete scheduler result.
    */
   preview?: BoundedRunListOutputPreview;
+  /** Default detail preview derived while the exact terminal return is in memory. */
+  responsePreview?: LedgerStoredRunOutputPreview;
   /** Failure ownership retained when the full failed result is out of line. */
   failure?: LedgerTerminalFailureSummary;
 };
@@ -471,6 +473,452 @@ export type BoundedRunListOutputPreview = {
   truncated: boolean;
 };
 
+export const RUN_RESPONSE_PREVIEW_LIMITS = {
+  maxRows: 5,
+  maxBytes: 8_000,
+  maxDepth: 4,
+  maxStringLength: 300,
+} as const;
+
+function jsonSize(value: unknown): number {
+  return JSON.stringify(value).length;
+}
+
+export function buildRunDatasetPreview(
+  rows: unknown[],
+  totalRows: number | undefined,
+) {
+  const previewRows: unknown[] = [];
+  let truncated = rows.length > RUN_RESPONSE_PREVIEW_LIMITS.maxRows;
+  for (const row of rows.slice(0, RUN_RESPONSE_PREVIEW_LIMITS.maxRows)) {
+    const compacted = compactRunOutputPreviewValue(row, 0);
+    truncated ||= compacted.truncated;
+    const nextRows = [...previewRows, compacted.value];
+    if (jsonSize(nextRows) > RUN_RESPONSE_PREVIEW_LIMITS.maxBytes) {
+      truncated = true;
+      break;
+    }
+    previewRows.push(compacted.value);
+  }
+  if (typeof totalRows === 'number' && totalRows > previewRows.length) {
+    truncated = true;
+  }
+  return {
+    rows: previewRows,
+    ...(typeof totalRows === 'number' ? { totalRows } : {}),
+    truncated,
+    limits: RUN_RESPONSE_PREVIEW_LIMITS,
+  };
+}
+
+const RUN_OUTPUT_VALUE_PREVIEW_LIMITS = {
+  maxDepth: 4,
+  maxStringLength: 300,
+} as const;
+
+export type BoundedRunOutputValuePreview = {
+  kind: 'value';
+  path: string;
+  value: unknown;
+  truncated?: true;
+  totalItems?: number;
+};
+
+export type BoundedRunDatasetOutputPreview = {
+  kind: 'dataset';
+  path: string;
+  dataset: string;
+  datasetId?: string;
+  tableNamespace?: string;
+  rowCount?: number;
+  datasetKind?: string;
+  runtimeSheetBacked?: true;
+  preview?: ReturnType<typeof buildRunDatasetPreview>;
+  access?: Record<string, unknown>;
+};
+
+export type BoundedRunOutputPreview = {
+  outputs: Record<
+    string,
+    BoundedRunOutputValuePreview | BoundedRunDatasetOutputPreview
+  >;
+  previewTruncated: boolean;
+  omittedFields: number;
+};
+
+type LedgerStoredRunOutputValuePreview = Omit<
+  BoundedRunOutputValuePreview,
+  'value'
+> &
+  (
+    | { value: unknown; valueFromListPreview?: never }
+    | { value?: never; valueFromListPreview: true }
+  );
+
+export type LedgerStoredRunOutputPreview = Omit<
+  BoundedRunOutputPreview,
+  'outputs'
+> & {
+  outputs: Record<
+    string,
+    LedgerStoredRunOutputValuePreview | BoundedRunDatasetOutputPreview
+  >;
+};
+
+function trimString(value: string): { value: string; truncated: boolean } {
+  const compact = value.replace(/\s+/g, ' ').trim();
+  if (compact.length <= RUN_OUTPUT_VALUE_PREVIEW_LIMITS.maxStringLength) {
+    return { value: compact, truncated: compact !== value };
+  }
+  return {
+    value: `${compact.slice(0, RUN_OUTPUT_VALUE_PREVIEW_LIMITS.maxStringLength)}...`,
+    truncated: true,
+  };
+}
+
+export function compactRunOutputPreviewValue(
+  value: unknown,
+  depth: number,
+): { value: unknown; truncated: boolean } {
+  if (
+    value == null ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return { value, truncated: false };
+  }
+  if (typeof value === 'string') {
+    return trimString(value);
+  }
+  if (depth >= RUN_OUTPUT_VALUE_PREVIEW_LIMITS.maxDepth) {
+    return {
+      value: Array.isArray(value) ? '[Array]' : '[Object]',
+      truncated: true,
+    };
+  }
+  if (Array.isArray(value)) {
+    let truncated = false;
+    const items = value.slice(0, 20).map((item) => {
+      const compacted = compactRunOutputPreviewValue(item, depth + 1);
+      truncated ||= compacted.truncated;
+      return compacted.value;
+    });
+    return {
+      value: items,
+      truncated: truncated || value.length > items.length,
+    };
+  }
+  if (!isPlainObject(value)) {
+    return { value: String(value), truncated: true };
+  }
+  let truncated = false;
+  const out: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
+  const entries = Object.entries(value);
+  for (const [key, child] of entries.slice(0, 40)) {
+    const compacted = compactRunOutputPreviewValue(child, depth + 1);
+    truncated ||= compacted.truncated;
+    out[key] = compacted.value;
+  }
+  return {
+    value: out,
+    truncated: truncated || entries.length > Object.keys(out).length,
+  };
+}
+
+/** Stable returned-dataset aliases shared by writer and default package reader. */
+export function runOutputKeyForDataset(
+  path: string,
+  tableNamespace: string | undefined,
+  used: Set<string>,
+): string {
+  const parts = path.split('.');
+  const raw =
+    parts[0] === 'result' && parts.length > 1
+      ? parts.at(-1)
+      : (tableNamespace ?? 'dataset');
+  const base =
+    String(raw || 'dataset')
+      .replace(/[^A-Za-z0-9_-]+/g, '_')
+      .replace(/^_+|_+$/g, '') || 'dataset';
+  let key = base;
+  let index = 2;
+  while (used.has(key)) key = `${base}_${index++}`;
+  used.add(key);
+  return key;
+}
+
+/** Derive the existing default value-output preview once, at terminal persistence. */
+export function buildBoundedRunOutputPreview(
+  value: Record<string, unknown>,
+): BoundedRunOutputPreview {
+  const outputs: BoundedRunOutputPreview['outputs'] = Object.create(null);
+  let bytes = 2;
+  let fields = 0;
+  let previewTruncated = false;
+  let omittedFields = 0;
+  const add = (
+    key: string,
+    output: BoundedRunOutputPreview['outputs'][string],
+  ) => {
+    const fieldBytes = runListPreviewFieldBytes(key, output, fields > 0);
+    // Unsafe names/nesting cannot poison the live ledger. Omission is explicit;
+    // the original value remains in the separately stored full terminal result.
+    if (
+      !isSafeRunListPreviewFieldName(key) ||
+      inspectConvexLedgerPayload(output) ||
+      fields >= 200 ||
+      bytes + fieldBytes > 32_000
+    ) {
+      previewTruncated = true;
+      omittedFields += 1;
+      return;
+    }
+    outputs[key] = output;
+    bytes += fieldBytes;
+    fields += 1;
+  };
+  const used = new Set<string>();
+  const visitDatasets = (
+    candidate: unknown,
+    returnPath: string,
+    depth: number,
+  ) => {
+    if (depth > 8 || candidate == null) return;
+    if (Array.isArray(candidate)) {
+      candidate.forEach((child, index) =>
+        visitDatasets(child, `${returnPath}[${index}]`, depth + 1),
+      );
+      return;
+    }
+    if (!isPlainObject(candidate)) return;
+    if (candidate.kind === 'dataset') {
+      const string = (key: string) =>
+        typeof candidate[key] === 'string' && candidate[key].trim()
+          ? candidate[key].trim()
+          : undefined;
+      const datasetId = string('datasetId');
+      const tableNamespace = string('tableNamespace');
+      const datasetKind = string('datasetKind');
+      const count = candidate.count ?? candidate.rowCount;
+      const rowCount =
+        typeof count === 'number' && Number.isFinite(count) ? count : undefined;
+      if (
+        !tableNamespace &&
+        !datasetKind &&
+        rowCount === undefined &&
+        (!Array.isArray(candidate.preview) || candidate.preview.length === 0)
+      )
+        return;
+      const backing = isPlainObject(candidate.backing)
+        ? candidate.backing
+        : null;
+      const sheet = isPlainObject(backing?.sheet) ? backing.sheet : null;
+      const runtimeSheetBacked =
+        backing?.storage === 'neon_sheet' &&
+        typeof sheet?.tableNamespace === 'string';
+      const sourceAccess = isPlainObject(candidate.access)
+        ? candidate.access
+        : null;
+      let access: Record<string, unknown> | undefined;
+      if (
+        sourceAccess &&
+        typeof sourceAccess.path === 'string' &&
+        typeof sourceAccess.tableNamespace === 'string' &&
+        typeof sourceAccess.sqlQuery === 'string'
+      ) {
+        access = {};
+        for (const field of [
+          'path',
+          'tableNamespace',
+          'sqlSchemaName',
+          'sqlTableName',
+          'sqlQualifiedTableName',
+          'currentTableSqlQuery',
+          'queryCurrentTableCommand',
+          'sqlQuery',
+          'queryDatasetCommand',
+          'slowExportAsCsvCommand',
+          'cliCommand',
+          'toolCommand',
+          'note',
+        ]) {
+          const fieldValue = sourceAccess[field];
+          if (typeof fieldValue === 'string' || fieldValue === null)
+            access[field] = fieldValue;
+        }
+        const api = isPlainObject(sourceAccess.api) ? sourceAccess.api : null;
+        const body = isPlainObject(api?.body) ? api.body : null;
+        if (
+          api &&
+          body &&
+          typeof api.method === 'string' &&
+          typeof api.path === 'string' &&
+          typeof body.sql === 'string' &&
+          typeof body.max_rows === 'number'
+        ) {
+          access.api = {
+            method: api.method,
+            path: api.path,
+            body: { sql: body.sql, max_rows: body.max_rows },
+          };
+        }
+      }
+      const key = runOutputKeyForDataset(returnPath, tableNamespace, used);
+      add(key, {
+        kind: 'dataset',
+        path: returnPath,
+        dataset: string('path') ?? returnPath,
+        ...(datasetId ? { datasetId } : {}),
+        ...(tableNamespace ? { tableNamespace } : {}),
+        ...(datasetKind ? { datasetKind } : {}),
+        ...(rowCount !== undefined ? { rowCount } : {}),
+        ...(runtimeSheetBacked ? { runtimeSheetBacked: true } : {}),
+        ...(Array.isArray(candidate.preview)
+          ? { preview: buildRunDatasetPreview(candidate.preview, rowCount) }
+          : {}),
+        ...(access ? { access } : {}),
+      });
+      return;
+    }
+    for (const [key, child] of Object.entries(candidate)) {
+      if (key !== 'preview')
+        visitDatasets(child, `${returnPath}.${key}`, depth + 1);
+    }
+  };
+  visitDatasets(value, 'result', 0);
+  for (const [key, child] of Object.entries(value)) {
+    if (
+      key.startsWith('_') ||
+      used.has(key) ||
+      (isPlainObject(child) && child.kind === 'dataset')
+    )
+      continue;
+    const compacted = compactRunOutputPreviewValue(child, 0);
+    previewTruncated ||= compacted.truncated;
+    add(key, {
+      kind: 'value',
+      path: `result.${key}`,
+      value: compacted.value,
+      ...(compacted.truncated ? { truncated: true } : {}),
+      ...(Array.isArray(child) ? { totalItems: child.length } : {}),
+    });
+  }
+  return { outputs, previewTruncated, omittedFields };
+}
+
+/**
+ * Reuse the existing run-list copy for exact duplicate scalar previews. The
+ * terminal reference carries both projections for old and current readers,
+ * so duplicating the same bounded value needlessly inflates its ledger event.
+ */
+export function reuseRunListValuesInOutputPreview(
+  responsePreview: BoundedRunOutputPreview,
+  listPreview: BoundedRunListOutputPreview,
+): LedgerStoredRunOutputPreview {
+  const outputs: LedgerStoredRunOutputPreview['outputs'] = Object.create(null);
+  for (const [key, output] of Object.entries(responsePreview.outputs)) {
+    if (
+      output.kind !== 'value' ||
+      !Object.prototype.hasOwnProperty.call(listPreview.output, key)
+    ) {
+      outputs[key] = output;
+      continue;
+    }
+    let matches = false;
+    try {
+      matches =
+        JSON.stringify(output.value) ===
+        JSON.stringify(listPreview.output[key]);
+    } catch {
+      // Non-JSON preview values remain self-contained in the detail projection.
+    }
+    outputs[key] = matches
+      ? {
+          kind: 'value',
+          path: output.path,
+          valueFromListPreview: true,
+          ...(output.truncated ? { truncated: true as const } : {}),
+          ...(output.totalItems !== undefined
+            ? { totalItems: output.totalItems }
+            : {}),
+        }
+      : output;
+  }
+  return { ...responsePreview, outputs };
+}
+
+/** Resolve compact value references before handing previews to response code. */
+export function resolveRunOutputPreviewValues(
+  responsePreview: LedgerStoredRunOutputPreview,
+  listPreview: BoundedRunListOutputPreview,
+): BoundedRunOutputPreview {
+  const outputs: BoundedRunOutputPreview['outputs'] = Object.create(null);
+  for (const [key, output] of Object.entries(responsePreview.outputs)) {
+    if (output.kind !== 'value') {
+      outputs[key] = output;
+      continue;
+    }
+    // Read stored JSON through a runtime view. With strictNullChecks disabled,
+    // TypeScript collapses the optional-never member of the stored union after
+    // discriminant narrowing, even though these optional fields are persisted.
+    const storedValue = output as unknown as {
+      path: string;
+      value?: unknown;
+      valueFromListPreview?: unknown;
+      truncated?: true;
+      totalItems?: number;
+    };
+    const hasValueProperty = Object.prototype.hasOwnProperty.call(
+      storedValue,
+      'value',
+    );
+    const hasReuseMarker = Object.prototype.hasOwnProperty.call(
+      storedValue,
+      'valueFromListPreview',
+    );
+    const value = storedValue.value;
+    const reuseMarker = storedValue.valueFromListPreview;
+    if (reuseMarker === true) {
+      if (hasValueProperty) {
+        throw new Error(
+          `Terminal output preview entry has both a value and a run-list reference: ${key}`,
+        );
+      }
+      if (!Object.prototype.hasOwnProperty.call(listPreview.output, key)) {
+        throw new Error(
+          `Terminal output preview reference is missing its run-list value: ${key}`,
+        );
+      }
+      outputs[key] = {
+        kind: 'value',
+        path: storedValue.path,
+        value: listPreview.output[key],
+        ...(storedValue.truncated ? { truncated: true as const } : {}),
+        ...(storedValue.totalItems !== undefined
+          ? { totalItems: storedValue.totalItems }
+          : {}),
+      };
+      continue;
+    }
+    if (hasReuseMarker || !hasValueProperty || value === undefined) {
+      throw new Error(`Terminal output preview entry is malformed: ${key}`);
+    }
+    outputs[key] = {
+      kind: 'value',
+      path: storedValue.path,
+      value,
+      ...(storedValue.truncated ? { truncated: true as const } : {}),
+      ...(storedValue.totalItems !== undefined
+        ? { totalItems: storedValue.totalItems }
+        : {}),
+    };
+  }
+  return { ...responsePreview, outputs };
+}
+
 function compactRunListPreviewString(value: string): {
   value: string;
   truncated: boolean;
@@ -751,6 +1199,7 @@ function ledgerTerminalResultRef(
     content?: 'full';
     bytes?: number;
     preview?: BoundedRunListOutputPreview;
+    responsePreview?: LedgerStoredRunOutputPreview;
     failure?: LedgerTerminalFailureSummary;
   } = {},
 ): LedgerTerminalResultRef {
@@ -763,6 +1212,9 @@ function ledgerTerminalResultRef(
     projection: 'out_of_line',
     ...(options.content ? { content: options.content } : {}),
     ...(options.preview ? { preview: options.preview } : {}),
+    ...(options.responsePreview
+      ? { responsePreview: options.responsePreview }
+      : {}),
     ...(options.failure ? { failure: options.failure } : {}),
     warning: options.content
       ? LEDGER_TERMINAL_RESULT_STORED_WARNING
@@ -853,9 +1305,14 @@ export function ledgerTerminalResultRefForValue(
     // customer payload again merely to populate reference metadata.
   }
   let preview: BoundedRunListOutputPreview | undefined;
+  let responsePreview: LedgerStoredRunOutputPreview | undefined;
   if (options.content && isPlainObject(value)) {
     try {
       preview = buildBoundedRunListOutputPreview(value);
+      responsePreview = reuseRunListValuesInOutputPreview(
+        buildBoundedRunOutputPreview(value),
+        preview,
+      );
     } catch {
       // The terminal reference is the durable fallback. A hostile/non-JSON
       // value must not turn optional list-preview derivation into a terminal
@@ -866,6 +1323,7 @@ export function ledgerTerminalResultRefForValue(
     ...options,
     bytes,
     preview,
+    responsePreview,
     failure: terminalFailureSummary(value),
   });
 }

package/dist/bundling-sources/shared_libs/play-runtime/provider-no-progress.ts

@@ -0,0 +1,40 @@
+/**
+ * A provider hold is queueing while progress remains possible. A run that has
+ * received no successful response from this credential for ten minutes must
+ * settle its affected work as repairable instead of occupying durable waits
+ * indefinitely. The start time lives in the Play checkpoint, across sandboxes.
+ */
+export const PROVIDER_NO_PROGRESS_MAX_MS = 10 * 60_000;
+
+export function observeProviderNoProgress(input: {
+  startedAtMsByScope: Record<string, number>;
+  scope: string;
+  retryAtMs: number;
+  nowMs: number;
+}): { exhausted: boolean; startedAtMs: number; deadlineMs: number } {
+  const saved = input.startedAtMsByScope[input.scope];
+  const startedAtMs =
+    Number.isFinite(saved) && saved >= 0 && saved <= input.nowMs
+      ? saved
+      : input.nowMs;
+  input.startedAtMsByScope[input.scope] = startedAtMs;
+  const deadlineMs = startedAtMs + PROVIDER_NO_PROGRESS_MAX_MS;
+  return {
+    exhausted: input.nowMs >= deadlineMs || input.retryAtMs > deadlineMs,
+    startedAtMs,
+    deadlineMs,
+  };
+}
+
+export function providerNoProgressExpired(input: {
+  startedAtMsByScope: Record<string, number> | undefined;
+  scope: string;
+  nowMs: number;
+}): boolean {
+  const startedAtMs = input.startedAtMsByScope?.[input.scope];
+  return (
+    typeof startedAtMs === 'number' &&
+    Number.isFinite(startedAtMs) &&
+    input.nowMs >= startedAtMs + PROVIDER_NO_PROGRESS_MAX_MS
+  );
+}

package/dist/bundling-sources/shared_libs/play-runtime/receipt-sql.ts

@@ -38,6 +38,13 @@ export function workReceiptClaimConflictPredicateSql(input: {
   const reclaimRunningSql = input.reclaimRunningSql ?? 'false';
   const forceFailedRefreshSql = input.forceFailedRefreshSql ?? 'false';
   return `${table}.status = ANY(${input.claimableStatusesSql}::smallint[])
+            AND NOT (
+              ${table}.status IN (
+                ${RECEIPT_STATUS_CODE.completed}::smallint,
+                ${RECEIPT_STATUS_CODE.skipped}::smallint
+              )
+              AND ${table}.run_id = ${input.claimantRunIdSql}
+            )
             AND (
               (
                 ${input.forceRefreshSql}::boolean

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger.ts

@@ -106,9 +106,13 @@ export type PlayRunLedgerDatasetSnapshot = {
   tableNamespace: string;
   phase: 'registered' | 'available' | 'failed';
   persistedRows: number;
+  persistedRowsObserved?: boolean;
   succeededRows: number;
+  succeededRowsObserved?: boolean;
   failedRows: number;
+  failedRowsObserved?: boolean;
   complete: boolean;
+  completeObserved?: boolean;
   /**
    * Dataset-grain row birth (ADR 0019). Absent on datasets registered before
    * the contract and on any registration that did not state one — never
@@ -620,9 +624,13 @@ export function normalizePlayRunLedgerSnapshot(
       tableNamespace: optionalString(rawDataset.tableNamespace) ?? datasetId,
       phase,
       persistedRows: Math.max(0, finiteNumber(rawDataset.persistedRows) ?? 0),
+      persistedRowsObserved: rawDataset.persistedRowsObserved === true,
       succeededRows: Math.max(0, finiteNumber(rawDataset.succeededRows) ?? 0),
+      succeededRowsObserved: rawDataset.succeededRowsObserved === true,
       failedRows: Math.max(0, finiteNumber(rawDataset.failedRows) ?? 0),
+      failedRowsObserved: rawDataset.failedRowsObserved === true,
       complete: rawDataset.complete === true,
+      completeObserved: rawDataset.completeObserved === true,
       // ADR 0019 birth survives the snapshot round trip. A partial record is
       // dropped rather than half-admitted, so a dataset either states where its
       // rows came from or says nothing.
@@ -1611,6 +1619,9 @@ export function reducePlayRunLedgerEvent(
     }
     case 'dataset.lifecycle': {
       const current = base.datasetsById[event.datasetId];
+      const persistedRows = optionalFiniteNumber(event.persistedRows);
+      const succeededRows = optionalFiniteNumber(event.succeededRows);
+      const failedRows = optionalFiniteNumber(event.failedRows);
       const mergedBornFrom = mergeDatasetBornFrom(
         current?.bornFrom,
         event.bornFrom,
@@ -1622,14 +1633,25 @@ export function reducePlayRunLedgerEvent(
         phase: event.phase,
         persistedRows: Math.max(
           current?.persistedRows ?? 0,
-          event.persistedRows ?? 0,
+          persistedRows ?? 0,
         ),
+        persistedRowsObserved:
+          current?.persistedRowsObserved === true ||
+          (persistedRows !== undefined && persistedRows >= 0),
         succeededRows: Math.max(
           current?.succeededRows ?? 0,
-          event.succeededRows ?? 0,
+          succeededRows ?? 0,
         ),
-        failedRows: Math.max(current?.failedRows ?? 0, event.failedRows ?? 0),
+        succeededRowsObserved:
+          current?.succeededRowsObserved === true ||
+          (succeededRows !== undefined && succeededRows >= 0),
+        failedRows: Math.max(current?.failedRows ?? 0, failedRows ?? 0),
+        failedRowsObserved:
+          current?.failedRowsObserved === true ||
+          (failedRows !== undefined && failedRows >= 0),
         complete: current?.complete === true || event.complete === true,
+        completeObserved:
+          current?.completeObserved === true || event.complete !== undefined,
         // Birth is stated at registration. A later phase event carries no birth
         // record and must not erase the one that was witnessed; a paged
         // dataset re-registers with a larger admitted-row count.

package/dist/bundling-sources/shared_libs/play-runtime/runner-app/index.ts

@@ -2080,6 +2080,7 @@ async function run(
   const ctx = createPlayContext({
     artifactRuntimeContract,
     rowAdmissionSignal: options?.rowAdmissionSignal,
+    executionSignal: persistenceSignal,
     executorToken: config.context.executorToken,
     baseUrl: config.context.baseUrl,
     // Runtime control stays on baseUrl (the receipt gateway); provider calls