deepline 0.3.81 → 0.3.83

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.83',
   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

@@ -18,6 +18,7 @@ import {
   reducePlayRunLedgerEvents,
   slicePositionalLogLines,
   type PlayRunLedgerEvent,
+  type PlayRunLedgerIngressEvent,
   type PlayRunLedgerSnapshot,
 } from './/run-ledger';
 import type {
@@ -41,8 +42,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 {
@@ -149,7 +150,7 @@ type RuntimeApiRequest =
   | {
       action: 'append_run_events';
       playId: string;
-      events: PlayRunLedgerEvent[];
+      events: PlayRunLedgerIngressEvent[];
       idempotencyKey?: string;
     }
   | {
@@ -380,18 +381,42 @@ async function suppressBulkClaimResponseUntilTimeout(
   });
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
 function splitRunEventForAppRuntime(
-  event: PlayRunLedgerEvent,
-): PlayRunLedgerEvent[] {
-  if (event.type !== 'log.appended' || event.lines.length === 0) return [event];
-  const split: PlayRunLedgerEvent[] = [];
+  event: PlayRunLedgerIngressEvent,
+): PlayRunLedgerIngressEvent[] {
+  const eventType =
+    typeof event.key === 'string'
+      ? event.key
+      : typeof event.type === 'string'
+        ? event.type
+        : null;
+  const payload = isRecord(event.payload) ? event.payload : null;
+  const payloadLines = payload?.lines;
+  const payloadOwnsLines = Array.isArray(payloadLines);
+  const rawLines = payloadOwnsLines ? payloadLines : event.lines;
+  const lines = Array.isArray(rawLines)
+    ? rawLines.filter((line): line is string => typeof line === 'string')
+    : [];
+  if (eventType !== 'log.appended' || lines.length === 0) return [event];
+  const payloadChannelOffset =
+    typeof payload?.channelOffset === 'number'
+      ? payload.channelOffset
+      : undefined;
+  const eventChannelOffset =
+    typeof event.channelOffset === 'number' ? event.channelOffset : undefined;
+  const split: PlayRunLedgerIngressEvent[] = [];
+  const { lines: _outerLines, ...eventWithoutOuterLines } = event;
   let index = 0;
-  while (index < event.lines.length) {
+  while (index < lines.length) {
     const start = index;
     let bytes = 2;
-    while (index < event.lines.length) {
+    while (index < lines.length) {
       const lineBytes = appRuntimeTextEncoder.encode(
-        JSON.stringify(event.lines[index]!),
+        JSON.stringify(lines[index]!),
       ).length;
       if (
         index > start &&
@@ -402,22 +427,40 @@ function splitRunEventForAppRuntime(
       bytes += lineBytes + 1;
       index += 1;
     }
-    split.push({
-      ...event,
-      lines: event.lines.slice(start, index),
-      ...(typeof event.channelOffset === 'number'
-        ? { channelOffset: event.channelOffset + start }
-        : {}),
-    });
+    const batchLines = lines.slice(start, index);
+    split.push(
+      payload
+        ? {
+            ...eventWithoutOuterLines,
+            ...(payloadOwnsLines ? {} : { lines: batchLines }),
+            payload: {
+              ...payload,
+              ...(payloadOwnsLines ? { lines: batchLines } : {}),
+              ...(payloadChannelOffset === undefined
+                ? {}
+                : { channelOffset: payloadChannelOffset + start }),
+            },
+            ...(eventChannelOffset === undefined
+              ? {}
+              : { channelOffset: eventChannelOffset + start }),
+          }
+        : {
+            ...event,
+            lines: batchLines,
+            ...(eventChannelOffset === undefined
+              ? {}
+              : { channelOffset: eventChannelOffset + start }),
+          },
+    );
   }
   return split;
 }
 
 export function partitionRunEventsForAppRuntime(
-  events: readonly PlayRunLedgerEvent[],
-): PlayRunLedgerEvent[][] {
-  const batches: PlayRunLedgerEvent[][] = [];
-  let current: PlayRunLedgerEvent[] = [];
+  events: readonly PlayRunLedgerIngressEvent[],
+): PlayRunLedgerIngressEvent[][] {
+  const batches: PlayRunLedgerIngressEvent[][] = [];
+  let current: PlayRunLedgerIngressEvent[] = [];
   let currentBytes = 2;
   for (const event of events.flatMap(splitRunEventForAppRuntime)) {
     const eventBytes = appRuntimeTextEncoder.encode(
@@ -742,9 +785,15 @@ function appRuntimeRetryAfterMs(
     }
   } catch {}
 
-  const retryAfterSeconds = Number(response.headers.get('retry-after'));
-  return Number.isFinite(retryAfterSeconds)
-    ? Math.max(0, Math.min(retryAfterSeconds * 1_000, 30_000))
+  const retryAfter = response.headers.get('retry-after')?.trim();
+  if (!retryAfter) return null;
+  const retryAfterSeconds = Number(retryAfter);
+  if (Number.isFinite(retryAfterSeconds)) {
+    return Math.max(0, Math.min(retryAfterSeconds * 1_000, 30_000));
+  }
+  const retryAt = Date.parse(retryAfter);
+  return Number.isFinite(retryAt)
+    ? Math.max(0, Math.min(retryAt - Date.now(), 30_000))
     : null;
 }
 
@@ -997,6 +1046,8 @@ export class AppRuntimeApiResponseError extends Error {
   readonly code: string | null;
   readonly requestId: string | null;
   readonly retryable: boolean;
+  /** Server-requested delay, retained for durable callers after local retries end. */
+  readonly retryAfterMs: number | null;
   readonly detail: string;
 
   constructor(input: {
@@ -1005,6 +1056,7 @@ export class AppRuntimeApiResponseError extends Error {
     code?: string | null;
     requestId?: string | null;
     retryable: boolean;
+    retryAfterMs?: number | null;
     detail: string;
     boundaryLabel?: string;
   }) {
@@ -1020,6 +1072,10 @@ export class AppRuntimeApiResponseError extends Error {
     this.code = input.code?.trim() || null;
     this.requestId = input.requestId?.trim() || null;
     this.retryable = input.retryable;
+    this.retryAfterMs =
+      typeof input.retryAfterMs === 'number' && Number.isFinite(input.retryAfterMs)
+        ? Math.max(0, Math.floor(input.retryAfterMs))
+        : null;
     this.detail = input.detail;
   }
 }
@@ -1038,7 +1094,7 @@ const APP_RUNTIME_CAPACITY_ERROR_CODES = new Set([
  * than spending the ordinary request retry ladder.
  */
 export class AppRuntimeApiCapacityError extends AppRuntimeApiResponseError {
-  readonly retryAfterMs: number;
+  declare readonly retryAfterMs: number;
 
   constructor(input: {
     action: RuntimeApiRequest['action'];
@@ -1138,7 +1194,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()
@@ -1372,6 +1430,7 @@ async function postAppRuntimeApi<TResponse>(
         body: responseText,
         contentType: response.headers.get('content-type'),
       }),
+      retryAfterMs: appRuntimeRetryAfterMs(response, responseText),
       detail: summarizeAppRuntimeErrorBody(responseText),
       boundaryLabel,
     });
@@ -1868,7 +1927,7 @@ async function appendRunEventsViaAppRuntimeRaw(
   context: WorkerRuntimeApiContext,
   input: {
     playId: string;
-    events: PlayRunLedgerEvent[];
+    events: PlayRunLedgerIngressEvent[];
     idempotencyKey?: string;
   },
 ): Promise<void> {
@@ -1888,7 +1947,7 @@ export async function appendRunEventsViaAppRuntime(
   context: WorkerRuntimeApiContext,
   input: {
     playId: string;
-    events: PlayRunLedgerEvent[];
+    events: PlayRunLedgerIngressEvent[];
     idempotencyKey?: string;
   },
 ): Promise<void> {
@@ -1905,10 +1964,14 @@ export async function appendRunEventsViaAppRuntime(
   for (let index = batches.length - 1; index >= 0; index -= 1) {
     if (
       batches[index]!.some(
-        (event) =>
-          event.type === 'run.completed' ||
-          event.type === 'run.failed' ||
-          event.type === 'run.cancelled',
+        (event) => {
+          const key = event.key ?? event.type;
+          return (
+            key === 'run.completed' ||
+            key === 'run.failed' ||
+            key === 'run.cancelled'
+          );
+        },
       )
     ) {
       terminalBatchIndex = index;

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/ledger-safe-payload.ts

@@ -1,6 +1,7 @@
 import { createSecretRedactionContext } from './secret-redaction';
 import {
   assertRuntimeReceiptOutputWithinLimit,
+  inspectConvexLedgerPayload,
   jsonByteLengthUpTo,
   LEDGER_TERMINAL_RESULT_MAX_BYTES,
 } from './output-size-limits';
@@ -31,6 +32,31 @@ export function sanitizeLedgerPayload(value: unknown): unknown {
   return ledgerIngressRedactor.redact(value);
 }
 
+function opaqueLedgerPayloadSummary(
+  issue: NonNullable<ReturnType<typeof inspectConvexLedgerPayload>>,
+): Record<string, unknown> {
+  return {
+    __kind: 'deepline.opaque_ledger_payload_summary.v1',
+    reason: issue.reason,
+    ...(typeof issue.bytes === 'number' ? { bytes: issue.bytes } : {}),
+  };
+}
+
+/**
+ * Preserve unfamiliar event payloads when they fit the Convex event contract.
+ * If they do not, keep a safe diagnostic summary instead of allowing one newer
+ * producer to permanently wedge its ordered ledger outbox behind a document
+ * limit, depth, or field-name rejection.
+ */
+export function sanitizeOpaqueLedgerPayload(value: unknown): unknown {
+  const sourceIssue = inspectConvexLedgerPayload(value);
+  if (sourceIssue) return opaqueLedgerPayloadSummary(sourceIssue);
+
+  const redacted = ledgerIngressRedactor.redact(value);
+  const redactedIssue = inspectConvexLedgerPayload(redacted);
+  return redactedIssue ? opaqueLedgerPayloadSummary(redactedIssue) : redacted;
+}
+
 /** Secret-redact a receipt payload without coupling its 10 MiB cell limit to the ledger. */
 export function sanitizeRuntimeReceiptPayload(value: unknown): unknown {
   // Reject an obviously oversized source before doing redaction work, then

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

@@ -173,6 +173,12 @@ type PlayRunLedgerBaseEvent = {
   seq?: number;
   occurredAt: number;
   source: PlayRunLedgerEventSource;
+  /**
+   * Producer-owned detail. The ledger preserves this without assigning it
+   * snapshot meaning; a known event's projection reads only the fields its
+   * reducer understands.
+   */
+  payload?: unknown;
 };
 
 export type PlayRunLedgerEvent =
@@ -289,6 +295,55 @@ export type PlayRunLedgerEvent =
       observation: PlayActivityObservation;
     });
 
+/**
+ * Wire shape accepted by the Run Ledger ingress.
+ *
+ * Producers can evolve their event vocabulary independently from the current
+ * snapshot reducer. The only producer-owned identity is `key` (or the legacy
+ * `type` spelling); `payload` and all additional fields are open. The receiver
+ * authenticates the delivery and assigns trusted run/time/source fields before
+ * an unfamiliar key becomes {@link PlayRunLedgerOpaqueEvent} in storage.
+ * Keep the known {@link PlayRunLedgerEvent} union closed so reducer authors
+ * retain exhaustive type checking for the semantics they actually own.
+ */
+export type PlayRunLedgerIngressEvent = {
+  /** Preferred generic event identity. */
+  key?: string;
+  /** Backward-compatible event identity used by existing runners. */
+  type?: string;
+  /** Optional redundant target; a supplied value must match the append target. */
+  runId?: string;
+  /** Optional producer timestamp; the receiver supplies one when omitted. */
+  occurredAt?: number;
+  /** Advisory producer label; unknown labels normalize to `system`. */
+  source?: PlayRunLedgerEventSource | string;
+  /** Arbitrary producer-owned detail. */
+  payload?: unknown;
+  [field: string]: unknown;
+};
+
+/**
+ * A well-formed event whose type is not understood by this ledger version.
+ * The original type and its redacted, bounded payload are durable history;
+ * projection deliberately treats this as a strict no-op.
+ */
+export type PlayRunLedgerOpaqueEvent = PlayRunLedgerBaseEvent & {
+  type: string;
+  opaque: true;
+  payload: unknown;
+};
+
+/** A stored event accepted by this ledger version. */
+export type AcceptedPlayRunLedgerEvent =
+  | PlayRunLedgerEvent
+  | PlayRunLedgerOpaqueEvent;
+
+export function isPlayRunLedgerOpaqueEvent(
+  event: AcceptedPlayRunLedgerEvent,
+): event is PlayRunLedgerOpaqueEvent {
+  return 'opaque' in event && event.opaque === true;
+}
+
 export type PlayRunLedgerStatusPatch = {
   runId: string;
   playName?: string | null;
@@ -1102,8 +1157,14 @@ function refineTerminalSyntheticStepStart(
 
 export function reducePlayRunLedgerEvent(
   snapshot: PlayRunLedgerSnapshot,
-  event: PlayRunLedgerEvent,
+  event: AcceptedPlayRunLedgerEvent,
 ): PlayRunLedgerSnapshot {
+  // Storage compatibility is intentionally wider than reducer semantics. An
+  // unknown event is durable evidence for a newer producer, not permission to
+  // guess at run state or to advance any snapshot timestamp.
+  if (isPlayRunLedgerOpaqueEvent(event)) {
+    return snapshot;
+  }
   if (event.runId !== snapshot.runId) {
     return snapshot;
   }
@@ -1525,12 +1586,18 @@ export function reducePlayRunLedgerEvent(
           : event.observation.activityId,
       });
     }
+    default:
+      // `appendPlayRunEventsInternal` has historical callers that predate the
+      // opaque ingress envelope. Keep the reducer fail-closed even if one
+      // reaches storage with a newer raw type: it is durable history, never a
+      // reason to manufacture snapshot state or return `undefined`.
+      return snapshot;
   }
 }
 
 export function reducePlayRunLedgerEvents(
   snapshot: PlayRunLedgerSnapshot,
-  events: readonly PlayRunLedgerEvent[],
+  events: readonly AcceptedPlayRunLedgerEvent[],
 ): PlayRunLedgerSnapshot {
   return events.reduce(reducePlayRunLedgerEvent, snapshot);
 }

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.83",
   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.83",
   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.83",
   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.83",
   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.83",
   "description": "GTM data CLI and TypeScript SDK for coding agents",
   "license": "MIT",
   "homepage": "https://code.deepline.com",