deepline 0.1.212 → 0.1.214

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

@@ -1563,8 +1563,8 @@ export class DeeplineClient {
           ? { waitForCompletionMs: request.waitForCompletionMs }
           : {}),
         // Profile selection is the API's job, not the CLI's. The server
-        // defaults to workers_edge; tests and runtime probes that want a
-        // different profile pass `request.profile` explicitly.
+        // defaults to absurd; callers that need workers_edge pass
+        // `request.profile` explicitly.
         ...(request.profile ? { profile: request.profile } : {}),
         ...(integrationMode ? { integrationMode } : {}),
         ...(testPolicyOverrides ? { testPolicyOverrides } : {}),

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

@@ -184,6 +184,8 @@ export type {
   PreviousCell,
   PlayDataset,
   PlayDatasetInput,
+  PlayCallExecution,
+  PlayCallOptions,
   PlayStepProgramStep,
   PrebuiltPlayRef,
   StepOptions,

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

@@ -114,6 +114,13 @@ import type {
 } from './types.js';
 import type { ToolExecution } from './client.js';
 
+export type PlayCallExecution = 'inline' | 'child-workflow';
+
+export interface PlayCallOptions {
+  description?: string;
+  execution?: PlayCallExecution;
+}
+
 /**
  * Optional trigger bindings for a play.
  *
@@ -891,7 +898,7 @@ export interface DeeplinePlayRuntimeContext {
     key: string,
     playRef: string | PlayReferenceLike,
     input: Record<string, unknown>,
-    options: { description: string },
+    options?: PlayCallOptions,
   ): Promise<TOutput>;
 
   /**

package/dist/bundling-sources/sdk/src/plays/harness-stub.ts

@@ -274,6 +274,7 @@ export async function harnessStartSheetDataset(input: {
   attemptExpiresAt?: string | null;
   attemptSeq?: number | null;
   attemptLeaseTtlMs?: number | null;
+  writeVersion?: number | null;
   inputOffset?: number;
   force?: boolean;
   userEmail?: string | null;
@@ -288,6 +289,7 @@ export async function harnessStartSheetDataset(input: {
   attemptOwnerRunId?: string;
   attemptExpiresAt?: string;
   attemptSeq?: number;
+  writeVersion?: number;
   timings?: Array<Record<string, unknown>>;
 }> {
   return requireBinding().startSheetDataset(input);
@@ -312,8 +314,16 @@ export async function harnessPersistCompletedSheetRows(input: {
   attemptOwnerRunId?: string | null;
   attemptExpiresAt?: string | null;
   attemptSeq?: number | null;
+  writeVersion?: number | null;
   forceFailedRows?: boolean;
   userEmail?: string | null;
-}): Promise<{ ok: true; rowsWritten: number; tableNamespace: string }> {
+}): Promise<{
+  ok: true;
+  rowsWritten: number;
+  tableNamespace: string;
+  fencedKeys?: string[];
+  staleDropped?: number;
+  staleDroppedKeys?: string[];
+}> {
   return requireBinding().persistCompletedMapRows(input);
 }

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

@@ -106,10 +106,10 @@ export const SDK_RELEASE = {
   // 0.1.154 removes the short-lived generated enrich StepOptions recompute
   // fields shipped in 0.1.153.
   // 0.1.175 ships loud `deepline enrich` empty-waterfall reporting.
-  version: '0.1.212',
+  version: '0.1.214',
   apiContract: '2026-06-dataset-handle-results-hard-cutover',
   supportPolicy: {
-    latest: '0.1.212',
+    latest: '0.1.214',
     minimumSupported: '0.1.53',
     deprecatedBelow: '0.1.53',
     commandMinimumSupported: [

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

@@ -1138,9 +1138,9 @@ export interface StartPlayRunRequest {
   /** Optionally let the start request wait briefly and return a terminal result. */
   waitForCompletionMs?: number;
   /**
-   * Per-run execution profile override. The server defaults to workers_edge;
-   * tests and runtime probes can pass a different profile here. Most callers
-   * should leave this unset.
+   * Per-run execution profile override. The server defaults to absurd;
+   * callers that need workers_edge can pass it here. Most callers should leave
+   * this unset.
    */
   profile?: string;
   /** Optional per-run provider execution mode for eval/smoke runs. */

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

@@ -207,11 +207,27 @@ type RuntimeApiRequest =
       runId: string;
       key: string;
     }
+  | {
+      action: 'acquire_runtime_receipt_execution_lock';
+      playName: string;
+      runId: string;
+      key: string;
+      ownerExecutionId: string;
+      ttlMs: number;
+    }
+  | {
+      action: 'release_runtime_receipt_execution_lock';
+      playName: string;
+      runId: string;
+      key: string;
+      ownerExecutionId: string;
+    }
   | {
       action: 'claim_runtime_step_receipt';
       playName: string;
       runId: string;
       key: string;
+      leaseId?: string;
       runAttempt?: number | null;
       leaseAware?: boolean;
       reclaimRunning?: boolean;
@@ -265,6 +281,7 @@ type RuntimeApiRequest =
       playName: string;
       runId: string;
       keys: string[];
+      leaseIds?: string[];
       runAttempt?: number | null;
       leaseAware?: boolean;
       reclaimRunning?: boolean;
@@ -1332,6 +1349,38 @@ export async function getRuntimeStepReceiptViaAppRuntime(
   });
 }
 
+export async function acquireRuntimeReceiptExecutionLockViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: Omit<
+    Extract<
+      RuntimeApiRequest,
+      { action: 'acquire_runtime_receipt_execution_lock' }
+    >,
+    'action'
+  >,
+): Promise<{ ownerExecutionId: string; expiresAt: string } | null> {
+  return await postAppRuntimeApi(context, {
+    action: 'acquire_runtime_receipt_execution_lock',
+    ...input,
+  });
+}
+
+export async function releaseRuntimeReceiptExecutionLockViaAppRuntime(
+  context: WorkerRuntimeApiContext,
+  input: Omit<
+    Extract<
+      RuntimeApiRequest,
+      { action: 'release_runtime_receipt_execution_lock' }
+    >,
+    'action'
+  >,
+): Promise<boolean> {
+  return await postAppRuntimeApi(context, {
+    action: 'release_runtime_receipt_execution_lock',
+    ...input,
+  });
+}
+
 export async function getRuntimeStepReceiptsViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: Omit<

package/dist/bundling-sources/shared_libs/play-runtime/child-execution-placement.ts

@@ -0,0 +1,14 @@
+import type { PlayCallExecution } from './play-call-execution';
+
+export function resolveChildExecutionPlacement(input: {
+  requiresWorkflow: boolean;
+  execution?: PlayCallExecution | null;
+}): { strategy: 'inline' | 'scheduled' } {
+  return {
+    strategy:
+      input.execution === 'child-workflow' ||
+      (input.execution !== 'inline' && input.requiresWorkflow)
+        ? 'scheduled'
+        : 'inline',
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/child-execution-strategy.ts

@@ -2,6 +2,8 @@ import {
   flattenStaticPipeline,
   type PlayStaticPipeline,
 } from '../plays/static-pipeline';
+import type { PlayCallExecution } from './play-call-execution';
+import { resolveChildExecutionPlacement } from './child-execution-placement';
 
 export type ChildExecutionStrategy = 'inline' | 'scheduled';
 
@@ -12,7 +14,9 @@ export type ChildExecutionDecision = {
     | 'missing_static_contract'
     | 'dataset_child'
     | 'event_wait_child'
-    | 'explicit_timeout';
+    | 'explicit_timeout'
+    | 'explicit_inline'
+    | 'explicit_child_workflow';
 };
 
 /**
@@ -23,31 +27,61 @@ export type ChildExecutionDecision = {
 export function resolveChildExecutionStrategy(input: {
   pipeline: PlayStaticPipeline | null | undefined;
   timeoutMs?: number | null;
+  execution?: PlayCallExecution | null;
+  childPlayName?: string | null;
 }): ChildExecutionDecision {
-  if (input.timeoutMs != null) {
-    return { strategy: 'scheduled', reason: 'explicit_timeout' };
+  if (input.execution === 'child-workflow') {
+    return { strategy: 'scheduled', reason: 'explicit_child_workflow' };
   }
-  if (!input.pipeline) {
-    return { strategy: 'scheduled', reason: 'missing_static_contract' };
+  const steps = input.pipeline ? flattenStaticPipeline(input.pipeline) : [];
+  const authoredDecision: ChildExecutionDecision =
+    input.timeoutMs != null
+      ? { strategy: 'scheduled', reason: 'explicit_timeout' }
+      : !input.pipeline
+        ? { strategy: 'scheduled', reason: 'missing_static_contract' }
+        : input.pipeline.tableNamespace ||
+            input.pipeline.sheetContract ||
+            steps.some((step) => step.type === 'dataset' || step.type === 'csv')
+          ? { strategy: 'scheduled', reason: 'dataset_child' }
+          : steps.some(
+                (step) =>
+                  step.type === 'tool' &&
+                  (step.isEventWait || step.toolId === 'test_wait_for_event'),
+              )
+            ? { strategy: 'scheduled', reason: 'event_wait_child' }
+            : { strategy: 'inline', reason: 'scalar_child' };
+  if (input.execution === 'inline') {
+    if (
+      authoredDecision.strategy === 'scheduled' &&
+      authoredDecision.reason !== 'missing_static_contract'
+    ) {
+      throw new Error(
+        inlineExecutionRequiresScalarChildMessage(
+          input.childPlayName?.trim() || 'child',
+          authoredDecision.reason,
+        ),
+      );
+    }
+    return { strategy: 'inline', reason: 'explicit_inline' };
   }
-  const substeps = flattenStaticPipeline(input.pipeline);
-  if (
-    input.pipeline.tableNamespace ||
-    input.pipeline.sheetContract ||
-    substeps.some((step) => step.type === 'dataset' || step.type === 'csv')
-  ) {
-    return { strategy: 'scheduled', reason: 'dataset_child' };
+  const placement = resolveChildExecutionPlacement({
+    requiresWorkflow: authoredDecision.strategy === 'scheduled',
+    execution: input.execution,
+  });
+  if (placement.strategy === 'inline') {
+    return { strategy: 'inline', reason: 'scalar_child' };
   }
-  if (
-    substeps.some(
-      (step) =>
-        step.type === 'tool' &&
-        (step.isEventWait === true || step.toolId === 'test_wait_for_event'),
-    )
-  ) {
-    return { strategy: 'scheduled', reason: 'event_wait_child' };
-  }
-  return { strategy: 'inline', reason: 'scalar_child' };
+  return authoredDecision;
+}
+
+export function inlineExecutionRequiresScalarChildMessage(
+  childPlayName: string,
+  reason: ChildExecutionDecision['reason'],
+): string {
+  return (
+    `ctx.runPlay("${childPlayName}") requested execution: "inline", but the child requires a child workflow ` +
+    `(${reason}). Remove the explicit execution option or use execution: "child-workflow".`
+  );
 }
 
 /**
@@ -63,7 +97,7 @@ export function inlineChildScheduledInRowMessage(
   return (
     `ctx.runPlay("${childPlayName}") runs per row in the "${rowContextField}" batch, ` +
     'but it is a scheduling-required child (it uses ctx.dataset()/ctx.csv(), waits on an ' +
-    'event, or sets an explicit timeout). Row-scoped children must be scalar. ' +
+    'event, sets an explicit timeout, or explicitly requests a child workflow). Row-scoped children must be scalar. ' +
     'Give the batch ONE dataset child at play level instead of fanning a scheduled run out per row.'
   );
 }

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

@@ -0,0 +1,166 @@
+/**
+ * A completed receipt is an immutable cache fact. Execution coordination is a
+ * separate, short-lived concern and must never be represented by a "running"
+ * receipt.
+ */
+export type CompletedReceipt<T> = {
+  key: string;
+  output: T;
+  createdAt: string;
+  expiresAt?: string | null;
+};
+
+export type CompletedReceiptCache<T> = {
+  get(key: string): Promise<CompletedReceipt<T> | null>;
+  /**
+   * Insert only when the key is absent. On conflict, return the already stored
+   * immutable fact. Implementations should use INSERT ... ON CONFLICT DO
+   * NOTHING followed by a point read.
+   */
+  putIfAbsent(receipt: CompletedReceipt<T>): Promise<CompletedReceipt<T>>;
+};
+
+export type ReceiptExecutionLock = {
+  receiptKey: string;
+  ownerExecutionId: string;
+  expiresAt: string;
+};
+
+export type ReceiptExecutionLockStore = {
+  tryAcquire(input: {
+    receiptKey: string;
+    ownerExecutionId: string;
+    expiresAt: string;
+  }): Promise<ReceiptExecutionLock | null>;
+  release(input: {
+    receiptKey: string;
+    ownerExecutionId: string;
+  }): Promise<void>;
+};
+
+export type ReceiptMissCoordination =
+  | { kind: 'provider_idempotency' }
+  | {
+      kind: 'execution_lock';
+      store: ReceiptExecutionLockStore;
+      ownerExecutionId: string;
+      lockTtlMs: number;
+      waitTimeoutMs: number;
+      pollIntervalMs?: number;
+    };
+
+export class ReceiptExecutionLockTimeoutError extends Error {
+  constructor(receiptKey: string, waitTimeoutMs: number) {
+    super(
+      `Timed out waiting ${waitTimeoutMs}ms for receipt execution lock ${receiptKey}.`,
+    );
+    this.name = 'ReceiptExecutionLockTimeoutError';
+  }
+}
+
+const MAX_EXECUTION_LOCK_TTL_MS = 10 * 60_000;
+
+function assertBoundedLockPolicy(
+  policy: Extract<ReceiptMissCoordination, { kind: 'execution_lock' }>,
+): void {
+  if (
+    !Number.isFinite(policy.lockTtlMs) ||
+    policy.lockTtlMs <= 0 ||
+    policy.lockTtlMs > MAX_EXECUTION_LOCK_TTL_MS
+  ) {
+    throw new Error(
+      `Receipt execution lock TTL must be between 1 and ${MAX_EXECUTION_LOCK_TTL_MS}ms.`,
+    );
+  }
+  if (!Number.isFinite(policy.waitTimeoutMs) || policy.waitTimeoutMs <= 0) {
+    throw new Error('Receipt execution lock wait timeout must be positive.');
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function executeAndPublish<T>(input: {
+  receiptKey: string;
+  cache: CompletedReceiptCache<T>;
+  execute: () => Promise<T>;
+  now: () => number;
+  receiptTtlMs?: number | null;
+}): Promise<T> {
+  const output = await input.execute();
+  const now = input.now();
+  const receipt = await input.cache.putIfAbsent({
+    key: input.receiptKey,
+    output,
+    createdAt: new Date(now).toISOString(),
+    ...(input.receiptTtlMs
+      ? { expiresAt: new Date(now + input.receiptTtlMs).toISOString() }
+      : {}),
+  });
+  return receipt.output;
+}
+
+/**
+ * Execute one semantic operation against an immutable completed-receipt cache.
+ *
+ * Providers with native idempotency do not need a Deepline execution lock:
+ * concurrent misses may dispatch with the same provider idempotency key, then
+ * converge on the first immutable cache insert. A separate temporary lock is
+ * reserved for actions explicitly classified as dangerous non-idempotent side
+ * effects. Ordinary enrichment misses may do bounded duplicate work and
+ * converge on the first published receipt.
+ */
+export async function executeWithCompletedReceiptCache<T>(input: {
+  receiptKey: string;
+  cache: CompletedReceiptCache<T>;
+  missCoordination: ReceiptMissCoordination;
+  execute: () => Promise<T>;
+  now?: () => number;
+  receiptTtlMs?: number | null;
+}): Promise<T> {
+  const cached = await input.cache.get(input.receiptKey);
+  if (cached) return cached.output;
+
+  const now = input.now ?? Date.now;
+  if (input.missCoordination.kind === 'provider_idempotency') {
+    return await executeAndPublish({ ...input, now });
+  }
+
+  const policy = input.missCoordination;
+  assertBoundedLockPolicy(policy);
+  const deadline = now() + policy.waitTimeoutMs;
+  const pollIntervalMs = Math.max(1, policy.pollIntervalMs ?? 100);
+
+  while (true) {
+    const lock = await policy.store.tryAcquire({
+      receiptKey: input.receiptKey,
+      ownerExecutionId: policy.ownerExecutionId,
+      expiresAt: new Date(now() + policy.lockTtlMs).toISOString(),
+    });
+    if (lock) {
+      try {
+        // The previous owner may have published between our cache read and
+        // lock acquisition. Never execute after that terminal fact exists.
+        const afterAcquire = await input.cache.get(input.receiptKey);
+        if (afterAcquire) return afterAcquire.output;
+        return await executeAndPublish({ ...input, now });
+      } finally {
+        await policy.store.release({
+          receiptKey: input.receiptKey,
+          ownerExecutionId: policy.ownerExecutionId,
+        });
+      }
+    }
+
+    const completed = await input.cache.get(input.receiptKey);
+    if (completed) return completed.output;
+    if (now() >= deadline) {
+      throw new ReceiptExecutionLockTimeoutError(
+        input.receiptKey,
+        policy.waitTimeoutMs,
+      );
+    }
+    await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - now())));
+  }
+}