deepline 0.3.258 → 0.3.259

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.258',
+  version: '0.3.259',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

package/dist/bundling-sources/sdk/src/runs/overview.ts

@@ -1,4 +1,10 @@
 import type { PlayStatus } from '../types';
+import {
+  decodeNodeExecutionState,
+  deriveNodeExecutionState,
+  formatNodeExecutionState,
+  type NodeExecutionState,
+} from '../../../shared_libs/play-runtime/run-execution-state';
 import { DATASET_EXECUTION_BUCKETS } from '../../../shared_libs/plays/dataset-summary';
 
 type RecordValue = Record<string, unknown>;
@@ -164,6 +170,37 @@ function actions(value: unknown, names: Record<string, string>) {
   );
 }
 
+/**
+ * A step's canonical execution state: the server's (`steps[].execution`), or,
+ * from a server that predates it, the same derivation over the step's
+ * reported status and map progress.
+ */
+function stepExecution(step: RecordValue, runStatus: string): NodeExecutionState {
+  const decoded = decodeNodeExecutionState(step.execution);
+  if (decoded) return decoded;
+  const progress = record(step.progress);
+  // Rows this step finished: executed plus reused, else its settled rows.
+  const completed =
+    typeof progress?.executed === 'number'
+      ? progress.executed +
+        (typeof progress.reused === 'number' ? progress.reused : 0)
+      : progress?.completedRows;
+  return deriveNodeExecutionState({
+    reported: {
+      status: typeof step.status === 'string' ? step.status : 'idle',
+      error: typeof step.error === 'string' ? step.error : null,
+      progress: progress
+        ? {
+            completed,
+            failed: progress.failed,
+            total: progress.total,
+          }
+        : null,
+    },
+    runStatus,
+  });
+}
+
 /** A read-only overview of recorded run facts, never a complete row export. */
 export function buildRunOverview(status: PlayStatus, fullStatus?: PlayStatus) {
   const pkg = status.package;
@@ -182,10 +219,14 @@ export function buildRunOverview(status: PlayStatus, fullStatus?: PlayStatus) {
     const timing = record(step.timing);
     const started = timing?.startedAt,
       finished = timing?.completedAt;
+    const execution = stepExecution(step, pkg.run.status);
     return {
       id: step.id,
       kind: step.kind,
       status: step.status,
+      /** The canonical state and its one line (what the dashboard pill says). */
+      execution,
+      label: formatNodeExecutionState(execution),
       progress: step.progress,
       timing: step.timing,
       ...(typeof started === 'number' &&
@@ -337,13 +378,15 @@ export function buildRunOverview(status: PlayStatus, fullStatus?: PlayStatus) {
         const progress = record(step.progress);
         const failedRows =
           typeof progress?.failed === 'number' ? progress.failed : undefined;
-        return step.status === 'failed' ||
-          step.error ||
+        // A step the run stopped under did not fail; it is not a failure.
+        return step.execution.kind === 'failed' ||
+          (step.error && step.execution.kind !== 'stopped') ||
           (failedRows !== undefined && failedRows > 0)
           ? [
               {
                 stepId: step.id,
                 status: step.status,
+                label: step.label,
                 failedRows,
                 ...(step.error ? { message: step.error } : {}),
               },

package/dist/bundling-sources/sdk/src/types.ts

@@ -1115,6 +1115,11 @@ export interface RerunOptions {
    * per invocation.
    */
   idempotencyKey?: string;
+  /**
+   * Optional scalar edits to fields present in the original retained input.
+   * The source run stays immutable; the values apply only to the new run.
+   */
+  inputOverrides?: Record<string, string | number | boolean | null>;
 }
 
 /** Result of {@link DeeplineClient.rerun} / `runs.rerun`. */

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

@@ -243,6 +243,12 @@ type RuntimeApiRequest =
       workflowId: string;
       runId: string;
       workflowFamilyKey: string;
+      /**
+       * Epoch ms the scheduler admitted the run (its outbox row's commit
+       * time). Optional: older workers omit it and the projection keeps its
+       * own clock.
+       */
+      acceptedAt?: number | null;
       /** Optional for root and older durable admission envelopes. */
       parentRunId?: string | null;
       rootRunId?: string | null;
@@ -272,6 +278,8 @@ type RuntimeApiRequest =
       retainedPipelineGraph?: unknown;
       source?: 'published' | 'ad_hoc' | 'draft';
       triggerSource?: 'webhook' | 'cron' | 'sql_listener' | 'api';
+      /** Display-only client surface; older envelopes omit it. */
+      launchSurface?: 'ui' | 'cli' | 'api';
       inputFileId?: string;
       inputBytes?: number;
       inputSha256?: string;

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

@@ -657,6 +657,17 @@ export type RuntimeMapReceiptWaitParking = {
   stage: string | null;
 };
 
+/** A cell status that settles the cell (no further patch follows on this run). */
+function isSettledCellStatus(status: string): boolean {
+  return (
+    status === 'completed' ||
+    status === 'failed' ||
+    status === 'cached' ||
+    status === 'missed' ||
+    status === 'skipped'
+  );
+}
+
 export class RuntimeMapStallObserver {
   readonly #resolvers = new Map<
     number,
@@ -7311,9 +7322,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           provider: input.provider ?? null,
           error: input.error ?? null,
           ...(producer !== undefined ? { producer } : {}),
-          // Only attribution-bearing cells carry the run stamp and the trace.
-          // Both ride the retained-row payload, so paying for them on every
-          // status-only cell patch would move the map memory budget.
+          // Only attribution-bearing cells carry the trace; it rides the
+          // retained-row payload, so paying for it on every status-only cell
+          // patch would move the map memory budget.
           ...(producers !== undefined
             ? {
                 runId: this.currentRunId,
@@ -7321,7 +7332,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 // Loud under-count: a capped trace states what it lost.
                 ...(attemptsDropped > 0 ? { attemptsDropped } : {}),
               }
-            : {}),
+            : capture && isSettledCellStatus(input.status)
+              ? // The run stamp alone on a SETTLED cell with no attempt of its
+                // own — a cell a later run reused from its receipt. The durable
+                // jsonb merge keeps keys a patch omits, so without it the cell
+                // kept the run that first wrote it, the run that reused it
+                // counted none of its cells, and the canvas lent a step its
+                // table's count ("8/10 ok" on a step that answered all 10).
+                { runId: this.currentRunId }
+              : {}),
           ...(reads !== undefined ? { reads } : {}),
           ...(decide !== undefined ? { decide } : {}),
           ...(input.reused !== undefined ? { reused: input.reused } : {}),
@@ -16660,15 +16679,23 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             for (const request of entry.request.memberRequests) {
               await reject(request, entry.error);
             }
-            // A provider-unavailable physical batch is a logical outcome for
-            // each member, not a map-fatal scheduler failure. Each rejected
-            // row resolver now receives the typed error above, where a
-            // waterfall may persist the failed leg and advance to its next
-            // provider. Keep infrastructure and contract failures loud.
+            // A failed physical batch is a logical outcome for each member,
+            // not a map-fatal scheduler failure. Each rejected row resolver
+            // now holds the typed error above, where a waterfall may persist
+            // the failed leg and advance, and row isolation settles the rest.
+            // A tool's own failure (any HTTP status, e.g. a 530 edge page in
+            // front of the gateway) is exactly what an unbatched call
+            // isolates to its row; rethrowing it here poisoned the shared
+            // dispatcher, rejected every queued call, and failed the whole
+            // run. Keep run-fatal tool errors (billing denials, cancellation,
+            // persistence) and our own contract failures — plain Errors —
+            // loud.
             if (
               isProviderExhaustedFailure(entry.error) ||
               isProviderUnavailable(entry.error) ||
-              entry.error instanceof PlayRowProviderBackpressureError
+              entry.error instanceof PlayRowProviderBackpressureError ||
+              (entry.error instanceof ToolExecutionError &&
+                !isRowIsolationExemptError(entry.error))
             ) {
               continue;
             }
@@ -19889,6 +19916,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                               bodyText,
                               transientHttpRetrySafe:
                                 retrySafeTransientHttp || fixtureReplaySafe,
+                              executionFenced: usesDurableInvocationFence,
                             });
                             let failure = classifyToolExecuteHttpFailure({
                               toolId,
@@ -19900,6 +19928,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                                 dispatchedResponse.headers.get('retry-after'),
                               transientHttpRetrySafe:
                                 retrySafeTransientHttp || fixtureReplaySafe,
+                              executionFenced: usesDurableInvocationFence,
                               providerLatencyMs:
                                 Date.now() - dispatchedProviderCallStartedAt,
                             });
@@ -19920,6 +19949,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                                   dispatchedResponse.headers.get('retry-after'),
                                 transientHttpRetrySafe:
                                   retrySafeTransientHttp || fixtureReplaySafe,
+                                executionFenced: usesDurableInvocationFence,
                                 providerLatencyMs:
                                   Date.now() - dispatchedProviderCallStartedAt,
                               });
@@ -20287,6 +20317,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   bodyText: text,
                   transientHttpRetrySafe:
                     retrySafeTransientHttp || fixtureReplaySafe,
+                  executionFenced: usesDurableInvocationFence,
                 });
               const failure =
                 preclassifiedHttpFailure.current?.failure ??
@@ -20299,6 +20330,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   retryAfterHeader: response.headers.get('retry-after'),
                   transientHttpRetrySafe:
                     retrySafeTransientHttp || fixtureReplaySafe,
+                  executionFenced: usesDurableInvocationFence,
                   ...(providerCallElapsedMs !== null
                     ? { providerLatencyMs: providerCallElapsedMs }
                     : {}),

package/dist/bundling-sources/shared_libs/play-runtime/launch-identity.ts

@@ -60,6 +60,9 @@ export const PLAY_LAUNCH_ENVELOPE_FIELD_ROLES: {
   inputBytes: 'detail',
   inputFileId: 'detail',
   replayedFromRunId: 'detail',
+  // Display-only provenance: a retry of the same run from another surface is
+  // the same launch.
+  launchSurface: 'detail',
   totalRows: 'detail',
   contractSnapshot: 'detail',
   executionPlan: 'detail',

package/dist/bundling-sources/shared_libs/play-runtime/launch-source-policy.ts

@@ -10,6 +10,29 @@ export type PlayLaunchTriggerSource =
   | 'sql_listener'
   | 'async_child';
 
+/**
+ * Which client surface submitted a run a person started: the dashboard
+ * (session auth), the Deepline CLI/SDK (an API key carrying the SDK client
+ * headers), or any other API-key caller. Display-only provenance, recorded at
+ * admission and never consulted by queue policy or launch identity. Automated
+ * launches (cron, webhook, SQL listener, async child) carry no surface; their
+ * `triggerSource` already names them.
+ */
+export type PlayLaunchSurface = 'ui' | 'cli' | 'api';
+
+export const PLAY_LAUNCH_SURFACES: readonly PlayLaunchSurface[] = Object.freeze(
+  ['ui', 'cli', 'api'] as const,
+);
+
+export function readPlayLaunchSurface(
+  value: unknown,
+): PlayLaunchSurface | null {
+  return typeof value === 'string' &&
+    (PLAY_LAUNCH_SURFACES as readonly string[]).includes(value)
+    ? (value as PlayLaunchSurface)
+    : null;
+}
+
 export type PlayLaunchQueuePolicy = {
   triggerSource: PlayLaunchTriggerSource;
   /**

package/dist/bundling-sources/shared_libs/play-runtime/live-state-contract.ts

@@ -1,5 +1,6 @@
 import type { PlayRunLifecycleStatus } from './run-lifecycle-policy';
 import type { PlayDocflowNodeIoState } from './docflow-node-io';
+import type { RunStopCause } from './run-execution-state';
 import type {
   PlayActivityObservation,
   PlayRunActivityProjection,
@@ -65,6 +66,8 @@ export type PlayVisualNodeStateSnapshot = {
   nodeId: string;
   status: PlayVisualNodeStatus;
   error?: string | null;
+  /** The run's terminal event settled this node in flight (ledger fact). */
+  stoppedBy?: RunStopCause;
   artifactTableNamespace?: string | null;
   progress?: PlayVisualNodeProgressSnapshot | null;
   startedAt?: number | null;

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

@@ -32,6 +32,13 @@ export const PLAY_RUN_ADMISSION_REPLAY_MISSING =
   'PLAY_RUN_ADMISSION_REPLAY_MISSING' as const;
 /** A reused Run identity with different launch facts is permanently invalid. */
 export const PLAY_RUN_LAUNCH_CONFLICT = 'PLAY_RUN_LAUNCH_CONFLICT' as const;
+/**
+ * The admitting deployment has no public callback its runtime backend can
+ * reach. Retrying the same deployment cannot change that; the source waits as
+ * blocked until the deployment is repaired and an admin retries it.
+ */
+export const PLAY_RUNTIME_CALLBACK_UNCONFIGURED =
+  'PLAY_RUNTIME_CALLBACK_UNCONFIGURED' as const;
 
 export type PlayAdmissionBlockedCode =
   | typeof PLAY_ADMISSION_PAYLOAD_UNREADABLE
@@ -39,7 +46,8 @@ export type PlayAdmissionBlockedCode =
   | typeof PLAY_RUN_PRE_RUN_VALIDATION_FAILED
   | typeof RUNTIME_DB_SESSION_PRELOAD_INCOMPLETE
   | typeof PLAY_RUN_ADMISSION_REPLAY_MISSING
-  | typeof PLAY_RUN_LAUNCH_CONFLICT;
+  | typeof PLAY_RUN_LAUNCH_CONFLICT
+  | typeof PLAY_RUNTIME_CALLBACK_UNCONFIGURED;
 
 export type PlayAdmissionRetryableCode = typeof PLAY_ADMISSION_INTERNAL_FAILURE;
 
@@ -62,6 +70,7 @@ const TERMINAL_PRE_ADMISSION_CODES = new Set<PlayAdmissionBlockedCode>([
   RUNTIME_DB_SESSION_PRELOAD_INCOMPLETE,
   PLAY_RUN_ADMISSION_REPLAY_MISSING,
   PLAY_RUN_LAUNCH_CONFLICT,
+  PLAY_RUNTIME_CALLBACK_UNCONFIGURED,
 ]);
 
 function stableErrorCode(error: unknown): string | null {
@@ -74,13 +83,22 @@ function blocked(code: PlayAdmissionBlockedCode): PlayAdmissionFailure {
   return {
     disposition: 'blocked',
     code,
-    message:
-      code === PLAY_SECRET_UNAVAILABLE
+    message: playAdmissionBlockedMessage(code),
+  };
+}
+
+/**
+ * The customer-facing reason for a blocked source. A deferred batch settles by
+ * code alone, so the reason must be derivable from the stable code.
+ */
+export function playAdmissionBlockedMessage(code: string): string {
+  return code === PLAY_SECRET_UNAVAILABLE
         ? 'The Play configuration is unavailable. Repair it, then retry this delivery.'
         : code === PLAY_RUN_LAUNCH_CONFLICT
           ? 'This run identity is already bound to a different launch. Repair the trigger identity before retrying this delivery.'
-          : 'This delivery needs attention before it can be retried.',
-  };
+          : code === PLAY_RUNTIME_CALLBACK_UNCONFIGURED
+            ? 'This deployment has no public runtime callback URL, so Play workers cannot report progress. Configure the callback (local dev: start the dev tunnel), then retry this delivery.'
+            : 'This delivery needs attention before it can be retried.';
 }
 
 /**

package/dist/bundling-sources/shared_libs/play-runtime/play-runs/projection/gateway-adapter.ts

@@ -49,7 +49,7 @@ export function createGatewayRunLedgerProjectionAdapter(
       }
       return await dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
         input.withClient,
-        dispatchInput,
+        { ...dispatchInput, continueThroughTerminal: true },
         options,
       );
     },