deepline 0.3.81 → 0.3.82

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

@@ -199,7 +199,7 @@ export const SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: '0.3.81',
+  version: '0.3.82',
   updateSummary:
     'Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.',
   packageCapabilities: {

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

@@ -41,8 +41,8 @@ import type {
 } from './/protocol';
 import {
   PLAY_RUNTIME_TRANSPORT_ATTEMPT_HEADER,
-  PLAY_RUNTIME_CONTRACT,
-  PLAY_RUNTIME_CONTRACT_HEADER,
+  LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT,
+  LEGACY_RUNTIME_RECEIPT_WIRE_HEADER,
 } from './/runtime-contract';
 import { PLAY_RUNTIME_API_COMPAT_PATH } from './/runtime-api-paths';
 import {
@@ -1138,7 +1138,9 @@ async function postAppRuntimeApi<TResponse>(
         headers: {
           'content-type': 'application/json',
           authorization: `Bearer ${token}`,
-          [PLAY_RUNTIME_CONTRACT_HEADER]: String(PLAY_RUNTIME_CONTRACT),
+          [LEGACY_RUNTIME_RECEIPT_WIRE_HEADER]: String(
+            LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT,
+          ),
           [PLAY_RUNTIME_TRANSPORT_ATTEMPT_HEADER]: transportAttemptId,
           ...vercelHeaders,
           ...(context.preferredReceiptGatewayMachineId?.trim()

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

@@ -64,6 +64,10 @@ import {
   PLAY_RUNTIME_OPERATION_ATTEMPT_HEADER,
   PLAY_RUNTIME_OPERATION_ID_HEADER,
 } from './runtime-api-paths';
+import {
+  DURABLE_INVOCATION_FENCE_VERSION,
+  durableInvocationFenceExecutePath,
+} from './durable-invocation-fence';
 import {
   isRetryableSecretResolutionStatus,
   secretResolutionRetryDecision,
@@ -1145,7 +1149,7 @@ function isUnmarkedExecutionGateway502(input: {
     return false;
   }
   try {
-    return new URL(input.url).pathname.endsWith('/execute-fenced-v1');
+    return /\/execute-fenced-v[12]$/.test(new URL(input.url).pathname);
   } catch {
     return false;
   }
@@ -2110,6 +2114,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
    */
   private readonly durableMappedToolResultsBackedByReceipts: boolean;
   private readonly durableDirectToolResultsBackedByReceipts: boolean;
+  private durableInvocationFenceVerification: Promise<boolean> | null = null;
   private steps: PlayStep[] = [];
   private explicitMapInvocationKeys = new Set<string>();
   /** The map step currently being built — substeps go here instead of top-level. */
@@ -13452,17 +13457,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const uncachedAsyncLifecycleCall =
       options?.uncachedAsyncLifecycleCall === true ||
       shouldWaitForAsyncOperation;
-    const usesDurableInvocationFence =
-      requestsDurableInvocationFence && !uncachedAsyncLifecycleCall;
-    const executeSuffix = usesDurableInvocationFence
-      ? 'execute-fenced-v1'
-      : 'execute';
     // Keep receipts, runner heartbeats, terminals, sheets, and runtime control
     // on baseUrl (the receipt gateway). Only the potentially long-lived
     // provider request may use the separately managed execution relay.
     const executionBaseUrl =
       this.#options.executionGatewayBaseUrl?.trim() || this.#options.baseUrl;
-    const url = `${executionBaseUrl.replace(/\/$/, '')}/api/v2/integrations/${encodeURIComponent(toolId)}/${executeSuffix}`;
     const toolErrorSchemaVersion = this.currentToolErrorSchemaVersion;
     const timeoutMs = resolveToolRuntimeTimeoutMs(
       toolId,
@@ -13551,6 +13550,49 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             retryPolicy?.retrySafeTransientHttp === true;
           const requiresExecutionFence =
             retryPolicy?.requiresExecutionFence === true;
+          // Fenced execution is an operation-specific opt-in. A gateway may
+          // support execute-fenced-v2 while ordinary provider calls continue
+          // through /execute with no durable-operation metadata at all.
+          const usesDurableInvocationFence =
+            requestsDurableInvocationFence &&
+            requiresExecutionFence &&
+            !uncachedAsyncLifecycleCall;
+          if (
+            usesDurableInvocationFence &&
+            this.#options.verifyDurableInvocationFence
+          ) {
+            const verification =
+              this.durableInvocationFenceVerification ??
+              this.#options.verifyDurableInvocationFence();
+            this.durableInvocationFenceVerification = verification;
+            let supportsDurableInvocationFence: boolean;
+            try {
+              supportsDurableInvocationFence = await verification;
+            } catch (error) {
+              if (this.durableInvocationFenceVerification === verification) {
+                this.durableInvocationFenceVerification = null;
+              }
+              throw error;
+            }
+            // A health probe is only a positive capability observation. A
+            // transient probe failure must not poison every later fenced call
+            // in this Play after the gateway has recovered.
+            if (!supportsDurableInvocationFence) {
+              if (this.durableInvocationFenceVerification === verification) {
+                this.durableInvocationFenceVerification = null;
+              }
+              throw new Error(
+                'The active execution gateway does not support execute-fenced-v2. ' +
+                  'No provider request was submitted; deploy the compatible gateway receiver first.',
+              );
+            }
+          }
+          const executeSuffix = usesDurableInvocationFence
+            ? durableInvocationFenceExecutePath(
+                DURABLE_INVOCATION_FENCE_VERSION,
+              )
+            : 'execute';
+          const url = `${executionBaseUrl.replace(/\/$/, '')}/api/v2/integrations/${encodeURIComponent(toolId)}/${executeSuffix}`;
           const fixtureReplaySafe = this.#options.integrationMode === 'fixture';
           const readOnlyQuery = isQueryResultDatasetReadRequest(
             toolId,
@@ -13631,7 +13673,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   ? { async_operation_wait: true }
                   : {}),
                 ...(usesDurableInvocationFence
-                  ? { invocation_fence_version: 1 }
+                  ? {
+                      invocation_fence_version:
+                        DURABLE_INVOCATION_FENCE_VERSION,
+                    }
                   : {}),
                 ...(durableCallReceiptKey
                   ? {
@@ -13859,16 +13904,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       (await this.#options.getToolProvider?.(toolId))?.trim() ||
                       provider;
                     if (shouldRouteFixtureProvider(canonicalProvider)) {
-                      if (!durableCallReceiptKey) {
-                        throw new Error(
-                          'Configured fixture response timing requires a durable call receipt key.',
-                        );
-                      }
                       const canonicalOperation =
                         (
                           await this.#options.getToolOperation?.(toolId)
                         )?.trim() || toolId;
-                      const stableRequestKey = `${canonicalProvider}:${canonicalOperation}:${durableCallReceiptKey}`;
+                      // A fixture schedule needs a stable logical-call identity,
+                      // not a cache receipt. Ordinary /execute calls deliberately
+                      // do not create durable receipts; deeplineRequestId remains
+                      // stable across their physical transport retries.
+                      const fixtureRequestIdentity =
+                        durableCallReceiptKey ?? deeplineRequestId;
+                      const stableRequestKey = `${canonicalProvider}:${canonicalOperation}:${fixtureRequestIdentity}`;
                       const behaviorDigest = stableDigest(
                         JSON.stringify(fixtureBehavior),
                       );

package/dist/bundling-sources/shared_libs/play-runtime/durable-invocation-fence.ts

@@ -0,0 +1,35 @@
+/**
+ * `execute-fenced-v2` is the first operation that requires semantic provider
+ * identity. It is intentionally a named operation rather than a runtime-wide
+ * deployment contract: callers can preflight this one receiver capability
+ * before they submit a provider request.
+ */
+export const DURABLE_INVOCATION_FENCE_VERSION = 2 as const;
+/** Attestation understood by pre-v2 runners during their drain window. */
+export const LEGACY_DURABLE_INVOCATION_FENCE_ATTESTATION_HEADER =
+  'x-deepline-invocation-fence';
+export const LEGACY_DURABLE_INVOCATION_FENCE_ATTESTATION_VALUE = 'v1';
+/**
+ * v2 is a distinct receiver capability, not a replacement value for the v1
+ * header. Keeping the two headers separate lets a receiver serve sleeping v1
+ * runners while new callers prove that execute-fenced-v2 is available.
+ */
+export const DURABLE_INVOCATION_FENCE_ATTESTATION_HEADER =
+  'x-deepline-invocation-fence-v2';
+export const DURABLE_INVOCATION_FENCE_ATTESTATION_VALUE = 'v2';
+
+export function durableInvocationFenceAttestationHeaders(): Record<
+  string,
+  string
+> {
+  return {
+    [LEGACY_DURABLE_INVOCATION_FENCE_ATTESTATION_HEADER]:
+      LEGACY_DURABLE_INVOCATION_FENCE_ATTESTATION_VALUE,
+    [DURABLE_INVOCATION_FENCE_ATTESTATION_HEADER]:
+      DURABLE_INVOCATION_FENCE_ATTESTATION_VALUE,
+  };
+}
+
+export function durableInvocationFenceExecutePath(version: 1 | 2): string {
+  return `execute-fenced-v${version}`;
+}

package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-payload-transport.ts

@@ -5,10 +5,6 @@ import {
   RUNNER_TERMINAL_CHECKPOINT_DISPOSITION,
   type PlayRunnerExecutionConfig,
 } from '../../protocol';
-import {
-  PLAY_RUNTIME_CONTRACT,
-  PLAY_RUNTIME_CONTRACT_HEADER,
-} from '../../runtime-contract';
 import {
   PLAY_RUNNER_TERMINAL_GRACE_SECONDS,
   PLAY_RUNNER_STARTUP_GRACE_SECONDS,
@@ -380,7 +376,6 @@ async function main() {
         headers: {
           'content-type': 'application/json',
           authorization: 'Bearer ' + token,
-          '${PLAY_RUNTIME_CONTRACT_HEADER}': '${String(PLAY_RUNTIME_CONTRACT)}',
           ...(preferredGatewayMachineId
             ? { 'fly-force-instance-id': preferredGatewayMachineId }
             : {}),

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

@@ -97,8 +97,8 @@ import {
 } from './map-row-outcome';
 import { DEEPLINE_CELL_META_FIELD } from '../plays/cell-staleness';
 import {
-  PLAY_RUNTIME_CONTRACT,
-  PLAY_RUNTIME_CONTRACT_HEADER,
+  LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT,
+  LEGACY_RUNTIME_RECEIPT_WIRE_HEADER,
 } from './runtime-contract';
 import { PLAY_RUNTIME_API_COMPAT_PATH } from './runtime-api-paths';
 import {
@@ -615,7 +615,9 @@ function resolveRuntimeApiHeaders(
   return {
     'content-type': 'application/json',
     authorization: `Bearer ${token}`,
-    [PLAY_RUNTIME_CONTRACT_HEADER]: String(PLAY_RUNTIME_CONTRACT),
+    [LEGACY_RUNTIME_RECEIPT_WIRE_HEADER]: String(
+      LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT,
+    ),
     // A run has many callback HTTP attempts. Preserve the logical run
     // correlation in headers while Vercel keeps its own per-attempt request id.
     ...(context.runId?.trim()

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

@@ -1,6 +1,16 @@
-export const PLAY_RUNTIME_CONTRACT = 6;
-export const PLAY_RUNTIME_CONTRACT_MIN_SUPPORTED = 1;
-export const PLAY_RUNTIME_CONTRACT_HEADER = 'x-deepline-runtime-contract';
+/**
+ * Kept on the old header name so sleeping runners can decode historical
+ * receipt presentations. New operations must not use this as a version gate.
+ */
+export const LEGACY_RUNTIME_RECEIPT_WIRE_HEADER = 'x-deepline-runtime-contract';
+export const LEGACY_RUNTIME_RECEIPT_WIRE_FORMAT = 3 as const;
+/**
+ * Historical workers validate this readiness range before they claim work.
+ * It is an output-only compatibility presentation; current callers use named
+ * operation capabilities and do not treat it as a global admission contract.
+ */
+export const LEGACY_RUNTIME_READINESS_MIN_SUPPORTED = 1 as const;
+export const LEGACY_RUNTIME_READINESS_CURRENT = 6 as const;
 /** Shared runner/gateway envelope limit for unacknowledged progress recovery. */
 export const RUNTIME_RUNNER_TERMINAL_PROGRESS_MAX_EVENTS = 2_000;
 /**
@@ -26,78 +36,26 @@ export function resolvePlayRuntimeTransportAttemptId(
   return trimmed && RUNTIME_TRANSPORT_ATTEMPT_ID.test(trimmed) ? trimmed : null;
 }
 
-export const RUNTIME_CONTRACT_CHANGELOG = [
-  {
-    contract: 6,
-    changed:
-      'Durable invocation metadata identifies the semantic provider operation and is admitted only by a gateway that declares contract 6 support.',
-    compatOwner: 'runtime',
-    compatRemoval: 'contract 5 runtime lane drain',
-  },
-  {
-    contract: 5,
-    changed:
-      'Runtime Sheet completion and lazy launch lookup use bounded, cancellation-aware gateway operations.',
-    compatOwner: 'runtime',
-    compatRemoval: 'contract 4 runtime lane drain',
-  },
-  {
-    contract: 4,
-    changed:
-      'Runtime receipt heartbeat requests can carry one positional lease ID per receipt key.',
-    compatOwner: 'runtime',
-    compatRemoval: 'contract 3 runtime lane drain',
-  },
-  {
-    contract: 3,
-    changed:
-      'Runtime receipt completion responses are compact acknowledgements; receipt reads remain the payload replay path.',
-    compatOwner: 'runtime',
-    compatRemoval: 'contract 2 support window closure',
-  },
-  {
-    contract: 2,
-    changed:
-      'Runtime receipt batch responses use positional nulls and v2 lease-aware receipt semantics.',
-    compatOwner: 'runtime',
-    compatRemoval: 'ledger cutover milestone M1',
-  },
-] as const;
+/**
+ * The pre-operation-runtime header is retained only to decode historical
+ * receipt response shapes. It never admits or rejects a runtime request.
+ */
+export type LegacyRuntimeReceiptWireFormat = 1 | 2 | 3;
+
+export function resolveLegacyRuntimeReceiptWireFormat(
+  rawContract: string | null | undefined,
+): LegacyRuntimeReceiptWireFormat {
+  const requested = Number(rawContract?.trim());
+  if (!Number.isSafeInteger(requested) || requested <= 1) return 1;
+  if (requested === 2) return 2;
+  return 3;
+}
 
 export function runtimeReceiptCompletionResponse<
   T extends { output?: unknown },
->(runtimeContract: number | null | undefined, receipt: T | null): T | null {
-  if (!receipt || (runtimeContract ?? 1) < 3) return receipt;
+>(wireFormat: LegacyRuntimeReceiptWireFormat, receipt: T | null): T | null {
+  if (!receipt || wireFormat < 3) return receipt;
   const { output, ...ack } = receipt;
   void output;
   return ack as T;
 }
-
-export type RuntimeContractResolution =
-  | { ok: true; contract: number }
-  | {
-      ok: false;
-      requestedContract: number;
-      currentContract: number;
-      minSupportedContract: number;
-    };
-
-export function resolvePlayRuntimeContract(
-  rawContract: string | null | undefined,
-): RuntimeContractResolution {
-  const trimmed = rawContract?.trim();
-  const requestedContract = trimmed ? Number(trimmed) : 1;
-  if (
-    !Number.isInteger(requestedContract) ||
-    requestedContract < PLAY_RUNTIME_CONTRACT_MIN_SUPPORTED ||
-    requestedContract > PLAY_RUNTIME_CONTRACT
-  ) {
-    return {
-      ok: false,
-      requestedContract,
-      currentContract: PLAY_RUNTIME_CONTRACT,
-      minSupportedContract: PLAY_RUNTIME_CONTRACT_MIN_SUPPORTED,
-    };
-  }
-  return { ok: true, contract: requestedContract };
-}

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

@@ -0,0 +1,51 @@
+/**
+ * A named runtime operation is its complete public wire contract. Runtime
+ * deployment builds are deliberately not part of this type: a receiver must
+ * either understand the named operation or reject that operation before it
+ * performs an effect.
+ */
+export type RuntimeOperation<
+  Name extends string,
+  Request,
+  Response,
+> = Readonly<{
+  name: Name;
+  request: Request;
+  response: Response;
+}>;
+
+export function defineRuntimeOperation<
+  const Name extends string,
+  Request,
+  Response,
+>(
+  input: RuntimeOperation<Name, Request, Response>,
+): RuntimeOperation<Name, Request, Response> {
+  return input;
+}
+
+/**
+ * Author a compatible evolution of one operation.
+ *
+ * The next request must accept every old request and the next response must
+ * remain consumable by every old caller. A breaking wire meaning therefore
+ * cannot be hidden behind a global deployment number: it needs a new named
+ * operation instead.
+ */
+export function evolveRuntimeOperation<
+  const Name extends string,
+  PreviousRequest,
+  PreviousResponse,
+  NextRequest,
+  NextResponse,
+>(
+  previous: RuntimeOperation<Name, PreviousRequest, PreviousResponse>,
+  next: PreviousRequest extends NextRequest
+    ? NextResponse extends PreviousResponse
+      ? RuntimeOperation<Name, NextRequest, NextResponse>
+      : never
+    : never,
+): RuntimeOperation<Name, NextRequest, NextResponse> {
+  void previous;
+  return next;
+}

package/dist/cli/index.js

@@ -1225,7 +1225,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.81",
+  version: "0.3.82",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/cli/index.mjs

@@ -1210,7 +1210,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.81",
+  version: "0.3.82",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.js

@@ -832,7 +832,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.81",
+  version: "0.3.82",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/index.mjs

@@ -744,7 +744,7 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.81",
+  version: "0.3.82",
   updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
   packageCapabilities: {
     updatePreferences: 1

package/dist/install-integrity.json

@@ -69,6 +69,7 @@
     "dist/bundling-sources/shared_libs/play-runtime/durability-store.ts",
     "dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts",
     "dist/bundling-sources/shared_libs/play-runtime/durable-call-policy.ts",
+    "dist/bundling-sources/shared_libs/play-runtime/durable-invocation-fence.ts",
     "dist/bundling-sources/shared_libs/play-runtime/durable-receipt-execution.ts",
     "dist/bundling-sources/shared_libs/play-runtime/dynamic-worker-version.ts",
     "dist/bundling-sources/shared_libs/play-runtime/email-status.ts",
@@ -160,6 +161,7 @@
     "dist/bundling-sources/shared_libs/play-runtime/runtime-environment.ts",
     "dist/bundling-sources/shared_libs/play-runtime/runtime-incident-drills.ts",
     "dist/bundling-sources/shared_libs/play-runtime/runtime-infra-mode.ts",
+    "dist/bundling-sources/shared_libs/play-runtime/runtime-operation.ts",
     "dist/bundling-sources/shared_libs/play-runtime/runtime-pg-driver-pg.ts",
     "dist/bundling-sources/shared_libs/play-runtime/runtime-pg-driver.ts",
     "dist/bundling-sources/shared_libs/play-runtime/runtime-postgres-admission.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.3.81",
+  "version": "0.3.82",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",