deepline 0.1.301 → 0.1.302

package/dist/plays/bundle-play-file.d.mts

@@ -1,5 +1,5 @@
-import { P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../compiler-manifest-BjopNIqx.mjs';
-export { b as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-BjopNIqx.mjs';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-9mH4i-mJ.mjs';
+export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-9mH4i-mJ.mjs';
 
 type PlayPackageImport = {
     name: string;
@@ -17,6 +17,8 @@ type PlayArtifactCompatibility = {
     minRunnerVersion: number;
     runtimeFeatures: PlayRuntimeFeature[];
     runtimeBackend?: string | null;
+    /** Missing preserves the legacy schema used before this field existed. */
+    toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
 };
 /** The only executable Play artifact contract. */
 type PlayArtifactKind = 'cjs_node20';

package/dist/plays/bundle-play-file.d.ts

@@ -1,5 +1,5 @@
-import { P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../compiler-manifest-BjopNIqx.js';
-export { b as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-BjopNIqx.js';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayArtifactKind$1, a as PlayCompilerManifest } from '../tool-execution-error-9mH4i-mJ.js';
+export { b as PLAY_ARTIFACT_KINDS } from '../tool-execution-error-9mH4i-mJ.js';
 
 type PlayPackageImport = {
     name: string;
@@ -17,6 +17,8 @@ type PlayArtifactCompatibility = {
     minRunnerVersion: number;
     runtimeFeatures: PlayRuntimeFeature[];
     runtimeBackend?: string | null;
+    /** Missing preserves the legacy schema used before this field existed. */
+    toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
 };
 /** The only executable Play artifact contract. */
 type PlayArtifactKind = 'cjs_node20';

package/dist/plays/bundle-play-file.mjs

@@ -43,9 +43,15 @@ var PLAY_BACKEND_DESCRIPTORS = {
   }
 };
 
+// ../shared_libs/tool-execution-error.ts
+var TOOL_EXECUTION_ERROR_SCHEMA_VERSION = 1;
+
+// ../shared_libs/plays/artifact-contract-version.ts
+var CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION = 2;
+
 // ../shared_libs/plays/contracts.ts
 var PLAY_PUBLIC_API_VERSION = 1;
-var PLAY_ARTIFACT_VERSION = 1;
+var PLAY_ARTIFACT_VERSION = CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION;
 var PLAY_MIN_RUNNER_VERSION = 1;
 var PLAY_RUNTIME_FEATURES = [
   "artifact_storage",
@@ -59,7 +65,8 @@ function buildPlayContractCompatibility(input) {
     artifactVersion: PLAY_ARTIFACT_VERSION,
     minRunnerVersion: PLAY_MIN_RUNNER_VERSION,
     runtimeFeatures: [...PLAY_RUNTIME_FEATURES],
-    runtimeBackend: input?.runtimeBackend ?? null
+    runtimeBackend: input?.runtimeBackend ?? null,
+    toolErrorSchemaVersion: input?.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION
   };
 }
 
@@ -133,7 +140,7 @@ function validatePlaySourceFilesHaveNoInlineSecrets(sourceFiles) {
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 
 // ../shared_libs/plays/bundling/index.ts
-var PLAY_BUNDLE_CACHE_VERSION = 25;
+var PLAY_BUNDLE_CACHE_VERSION = 27;
 var PLAY_ARTIFACT_CACHE_DIR = join(
   tmpdir(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
@@ -283,15 +290,6 @@ function findSourceImportReferences(sourceCode) {
 function extractDefinedPlayName(sourceCode) {
   return extractDefinedPlayMetadata(sourceCode, null)?.name ?? null;
 }
-function extractDefinedPlayNameForExport(sourceCode, exportName) {
-  return extractDefinedPlayMetadata(sourceCode, exportName)?.name ?? null;
-}
-function extractDefinedPlayDescription(sourceCode) {
-  return extractDefinedPlayMetadata(sourceCode, null)?.description ?? null;
-}
-function extractDefinedPlayDescriptionForExport(sourceCode, exportName) {
-  return extractDefinedPlayMetadata(sourceCode, exportName)?.description ?? null;
-}
 var TypeScriptParser = Parser.extend(
   tsPlugin({
     allowSatisfies: true,
@@ -499,9 +497,11 @@ function staticStringFromExpression(node, context, seen = /* @__PURE__ */ new Se
   );
 }
 function propertyNameFromKey(property) {
-  if (property.computed) return null;
   const key = isAstNode(property.key) ? property.key : null;
   if (!key) return null;
+  if (property.computed) {
+    return key.type === "Literal" && typeof key.value === "string" ? key.value : null;
+  }
   if (key.type === "Identifier" && typeof key.name === "string") {
     return key.name;
   }
@@ -523,6 +523,77 @@ function objectExpressionFromNode(node, context, seen = /* @__PURE__ */ new Set(
     seen
   );
 }
+function resolveStaticProperty(node, propertyName, context, ancestors = /* @__PURE__ */ new Set()) {
+  if (!node) return { kind: "absent" };
+  const object = objectExpressionFromNode(node, context);
+  if (!object) return { kind: "unknown" };
+  if (ancestors.has(object)) return { kind: "unknown" };
+  const nextAncestors = new Set(ancestors).add(object);
+  let resolution = { kind: "absent" };
+  for (const property of astArray(object.properties)) {
+    if (property.type === "SpreadElement") {
+      const spreadResolution = resolveStaticProperty(
+        isAstNode(property.argument) ? property.argument : null,
+        propertyName,
+        context,
+        nextAncestors
+      );
+      if (spreadResolution.kind !== "absent") {
+        resolution = spreadResolution;
+      }
+      continue;
+    }
+    if (property.type !== "Property") continue;
+    const resolvedPropertyName = propertyNameFromKey(property);
+    if (resolvedPropertyName !== propertyName) {
+      if (property.computed && resolvedPropertyName === null) {
+        resolution = { kind: "unknown" };
+      }
+      continue;
+    }
+    const propertyValue = property.shorthand ? property.key : property.value;
+    resolution = isAstNode(propertyValue) ? { kind: "found", value: propertyValue } : { kind: "unknown" };
+  }
+  return resolution;
+}
+function staticNumberFromExpression(node, context, seen = /* @__PURE__ */ new Set()) {
+  const expression = unwrapStaticExpression(node);
+  if (!expression) return null;
+  if (expression.type === "Literal" && typeof expression.value === "number") {
+    return expression.value;
+  }
+  const identifier = getIdentifierName(expression);
+  if (!identifier || seen.has(identifier)) return null;
+  seen.add(identifier);
+  return staticNumberFromExpression(
+    context.declarations.get(identifier),
+    context,
+    seen
+  );
+}
+function toolErrorSchemaVersionFromOptions(node, context) {
+  const directCompatibility = resolveStaticProperty(
+    node,
+    "compatibility",
+    context
+  );
+  if (directCompatibility.kind === "unknown") return null;
+  const bindings = resolveStaticProperty(node, "bindings", context);
+  if (bindings.kind === "unknown") return null;
+  const bindingCompatibility = bindings.kind === "found" ? resolveStaticProperty(bindings.value, "compatibility", context) : { kind: "absent" };
+  if (bindingCompatibility.kind === "unknown") return null;
+  const compatibility = directCompatibility.kind === "found" ? directCompatibility : bindingCompatibility;
+  if (compatibility.kind === "absent") return void 0;
+  const schema = resolveStaticProperty(
+    compatibility.value,
+    "toolErrorSchemaVersion",
+    context
+  );
+  if (schema.kind !== "found") return null;
+  const schemaVersion = staticNumberFromExpression(schema.value, context);
+  if (schemaVersion === 0 || schemaVersion === 1) return schemaVersion;
+  return null;
+}
 function stringPropertyFromObjectExpression(node, propertyName, context, seenObjects = /* @__PURE__ */ new Set()) {
   const object = objectExpressionFromNode(node, context);
   if (!object || seenObjects.has(object)) return null;
@@ -568,12 +639,13 @@ function playMetadataFromDefinePlayCall(node, context) {
   }
   const args = astArray(expression.arguments);
   const firstArg = args[0] ?? null;
+  const isObjectForm = args.length === 1 || objectExpressionFromNode(firstArg, context) !== null;
   const objectName = stringPropertyFromObjectExpression(
     firstArg,
     "id",
     context
   );
-  const name = objectName ?? staticStringFromExpression(firstArg, context);
+  const name = isObjectForm ? objectName : staticStringFromExpression(firstArg, context);
   let description = stringPropertyFromObjectExpression(firstArg, "description", context) ?? null;
   for (let index = args.length - 1; !description && index >= 2; index -= 1) {
     description = stringPropertyFromObjectExpression(
@@ -582,8 +654,21 @@ function playMetadataFromDefinePlayCall(node, context) {
       context
     );
   }
-  if (!name && !description) return null;
-  return { name, description };
+  const options = isObjectForm ? firstArg : args[2] ?? null;
+  const toolErrorSchemaVersion = toolErrorSchemaVersionFromOptions(
+    options,
+    context
+  );
+  const toolErrorSchemaVersionUnknown = toolErrorSchemaVersion === null;
+  if (!name && !description && toolErrorSchemaVersion === void 0 && !toolErrorSchemaVersionUnknown) {
+    return null;
+  }
+  return {
+    name,
+    description,
+    toolErrorSchemaVersion: toolErrorSchemaVersion ?? null,
+    toolErrorSchemaVersionUnknown
+  };
 }
 function resolveExportExpression(exportName, context) {
   if (exportName === "default") {
@@ -960,8 +1045,14 @@ async function analyzeSourceGraph(entryFile, adapter, exportName) {
       })).sort((left, right) => left.filePath.localeCompare(right.filePath))
     })
   );
-  const playName = extractDefinedPlayNameForExport(sourceCode, exportName) ?? (exportName === "default" ? extractDefinedPlayName(sourceCode) : null);
-  const playDescription = extractDefinedPlayDescriptionForExport(sourceCode, exportName) ?? (exportName === "default" ? extractDefinedPlayDescription(sourceCode) : null);
+  const metadata = extractDefinedPlayMetadata(sourceCode, exportName) ?? (exportName === "default" ? extractDefinedPlayMetadata(sourceCode, null) : null);
+  if (metadata?.toolErrorSchemaVersionUnknown) {
+    throw new Error(
+      "definePlay compatibility.toolErrorSchemaVersion must be the static literal 0 or 1."
+    );
+  }
+  const playName = metadata?.name ?? null;
+  const playDescription = metadata?.description ?? null;
   return {
     sourceCode,
     sourceFiles: Object.fromEntries(
@@ -978,6 +1069,7 @@ async function analyzeSourceGraph(entryFile, adapter, exportName) {
     },
     playName,
     playDescription,
+    toolErrorSchemaVersion: metadata?.toolErrorSchemaVersion ?? null,
     importedPlayDependencies: [...importedPlayDependencies.values()].sort(
       (left, right) => left.filePath.localeCompare(right.filePath)
     )
@@ -1149,6 +1241,9 @@ entry-export:${exportName}`
           entryFile: absolutePath,
           sourceHash: analysis.sourceHash,
           importPolicy: analysis.importPolicy,
+          compatibility: buildPlayContractCompatibility({
+            toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? void 0
+          }),
           cacheHit: true
         },
         sourceCode: analysis.sourceCode,
@@ -1209,7 +1304,9 @@ entry-export:${exportName}`
       bundledCode: executableCode,
       sourceMap: normalizedSourceMap,
       importPolicy: analysis.importPolicy,
-      compatibility: buildPlayContractCompatibility(),
+      compatibility: buildPlayContractCompatibility({
+        toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? void 0
+      }),
       generatedAt: Date.now(),
       cacheHit: false
     };

package/dist/{compiler-manifest-BjopNIqx.d.mts → tool-execution-error-9mH4i-mJ.d.mts}

@@ -237,4 +237,82 @@ type PlayCompilerManifest = {
     importedPlayDependencies: PlayCompilerDependencyManifest[];
 };
 
-export { type PlayArtifactKind as P, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b };
+declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
+declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
+type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+type ToolExecutionFailureV1 = {
+    schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    toolId: string;
+    provider: string | null;
+    operation: string | null;
+    code: string | null;
+    origin: ToolExecutionErrorOrigin;
+    category: ToolExecutionErrorCategory;
+    retryable: boolean;
+    statusCode: number | null;
+    requestId: string | null;
+    retryAfterMs: number | null;
+    networkKind: ToolExecutionNetworkKind | null;
+    networkScope: ToolExecutionNetworkScope | null;
+};
+type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
+    /**
+     * Local diagnostic context inherited from DeeplineError. This is not part of
+     * the portable failure payload and is intentionally omitted by serialization.
+     */
+    details?: Record<string, unknown>;
+};
+type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
+/**
+ * Base error class shared by the SDK and play runtime.
+ *
+ * The global brand preserves `instanceof DeeplineError` when a bundled play
+ * and the runtime load separate physical copies of this module.
+ */
+declare class DeeplineError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: Record<string, unknown> | undefined);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A failed `tools.execute` call with stable, allowlisted provenance.
+ *
+ * `retryable` means Deepline's delivery/idempotency contract says it is safe
+ * to repeat the same semantic call. It does not describe durable receipt
+ * repairability and does not make arbitrary side-effecting fallbacks safe.
+ */
+declare class ToolExecutionError extends DeeplineError {
+    readonly toolId: string;
+    readonly provider: string | null;
+    readonly operation: string | null;
+    readonly origin: ToolExecutionErrorOrigin;
+    readonly category: ToolExecutionErrorCategory;
+    readonly retryable: boolean;
+    readonly requestId: string | null;
+    readonly retryAfterMs: number | null;
+    readonly networkKind: ToolExecutionNetworkKind | null;
+    readonly networkScope: ToolExecutionNetworkScope | null;
+    constructor(message: string, options: ToolExecutionErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A provider-owned transient failure that is safe to handle as an empty
+ * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
+ * never satisfy this type.
+ */
+declare class ProviderTransientError extends ToolExecutionError {
+    readonly origin: "provider";
+    readonly category: ProviderTransientErrorCategory;
+    constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
+        category: ProviderTransientErrorCategory;
+    });
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+
+export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e };

package/dist/{compiler-manifest-BjopNIqx.d.ts → tool-execution-error-9mH4i-mJ.d.ts}

@@ -237,4 +237,82 @@ type PlayCompilerManifest = {
     importedPlayDependencies: PlayCompilerDependencyManifest[];
 };
 
-export { type PlayArtifactKind as P, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b };
+declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
+declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
+type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
+type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
+type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
+type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
+type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
+type ToolExecutionFailureV1 = {
+    schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+    toolId: string;
+    provider: string | null;
+    operation: string | null;
+    code: string | null;
+    origin: ToolExecutionErrorOrigin;
+    category: ToolExecutionErrorCategory;
+    retryable: boolean;
+    statusCode: number | null;
+    requestId: string | null;
+    retryAfterMs: number | null;
+    networkKind: ToolExecutionNetworkKind | null;
+    networkScope: ToolExecutionNetworkScope | null;
+};
+type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
+    /**
+     * Local diagnostic context inherited from DeeplineError. This is not part of
+     * the portable failure payload and is intentionally omitted by serialization.
+     */
+    details?: Record<string, unknown>;
+};
+type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
+/**
+ * Base error class shared by the SDK and play runtime.
+ *
+ * The global brand preserves `instanceof DeeplineError` when a bundled play
+ * and the runtime load separate physical copies of this module.
+ */
+declare class DeeplineError extends Error {
+    statusCode?: number | undefined;
+    code?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string | undefined, details?: Record<string, unknown> | undefined);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A failed `tools.execute` call with stable, allowlisted provenance.
+ *
+ * `retryable` means Deepline's delivery/idempotency contract says it is safe
+ * to repeat the same semantic call. It does not describe durable receipt
+ * repairability and does not make arbitrary side-effecting fallbacks safe.
+ */
+declare class ToolExecutionError extends DeeplineError {
+    readonly toolId: string;
+    readonly provider: string | null;
+    readonly operation: string | null;
+    readonly origin: ToolExecutionErrorOrigin;
+    readonly category: ToolExecutionErrorCategory;
+    readonly retryable: boolean;
+    readonly requestId: string | null;
+    readonly retryAfterMs: number | null;
+    readonly networkKind: ToolExecutionNetworkKind | null;
+    readonly networkScope: ToolExecutionNetworkScope | null;
+    constructor(message: string, options: ToolExecutionErrorOptions);
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+/**
+ * A provider-owned transient failure that is safe to handle as an empty
+ * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
+ * never satisfy this type.
+ */
+declare class ProviderTransientError extends ToolExecutionError {
+    readonly origin: "provider";
+    readonly category: ProviderTransientErrorCategory;
+    constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
+        category: ProviderTransientErrorCategory;
+    });
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+
+export { DeeplineError as D, type PlayArtifactKind as P, type ToolExecutionErrorSchemaVersion as T, type PlayCompilerManifest as a, PLAY_ARTIFACT_KINDS as b, ToolExecutionError as c, type ToolExecutionErrorOptions as d, ProviderTransientError as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.1.301",
+  "version": "0.1.302",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {

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

@@ -1,166 +0,0 @@
-/**
- * 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())));
-  }
-}