deepline 0.3.19 → 0.3.20

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

@@ -192,7 +192,7 @@ export const SDK_RELEASE = {
   // 0.3.0 introduces raw-v2: complete scrubbed provider responses are
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
-  version: '0.3.19',
+  version: '0.3.20',
   updateSummary:
     'New raw-v2 tool responses preserve complete scrubbed provider envelopes at toolResponse.rawV2, including JSON:API included resources, links, cursors, and totals. Existing toolResponse.raw and declared getters keep working unchanged.',
   contracts: {

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

@@ -376,8 +376,10 @@ type InlineCompositionStore = {
   toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
   /** Immutable authoring semantics pinned by the child play artifact. */
   authoringContractEdition: PlayAuthoringContractEdition;
-  /** Immutable execute response contract pinned by the child artifact. */
+  /** Execute response contract pinned by the child artifact. */
   toolResponseContract: ToolResponseContract;
+  /** Explicit response-transform revision used for durable receipt identity. */
+  toolResponseReceiptRevision?: string;
 };
 const inlineCompositionContext =
   new AsyncLocalStorage<InlineCompositionStore>();
@@ -1340,6 +1342,11 @@ type ToolExecutionApiOptions = {
   timeoutMs?: number;
   durableCallReceiptKey?: string | null;
   executionAuthScopeDigest?: string | null;
+  /**
+   * Historical receipt identity that anchors external provider idempotency
+   * while a newer response contract uses a distinct durable receipt.
+   */
+  providerIdempotencyReceiptKey?: string | null;
   providerIdempotencyKey?: string | null;
   receiptLeaseExpiresAt?: string | null;
   beforeProviderCall?: () => Promise<void> | void;
@@ -2648,6 +2655,18 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
   }
 
+  /**
+   * Only explicitly declared response transformations affect receipt reuse.
+   * Missing preserves historical artifact/receipt identity, while the public
+   * response header still normalizes it to the legacy V2 behavior above.
+   */
+  private get currentToolResponseReceiptRevision(): string | undefined {
+    if (this.activeInlineComposition) {
+      return this.activeInlineComposition.toolResponseReceiptRevision;
+    }
+    return this.#options.toolResponseReceiptRevision;
+  }
+
   private get currentAuthoringContractEdition(): PlayAuthoringContractEdition {
     return (
       this.activeInlineComposition?.authoringContractEdition ??
@@ -4026,13 +4045,17 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
   }
 
-  private async durableToolCallCacheKeyForScope(input: {
-    toolId: string;
-    requestInput: Record<string, unknown>;
-    executionAuthScopeDigest?: string | null;
-    staleAfterSeconds?: number | null;
-    playLocalScope?: string | null;
-  }): Promise<string> {
+  private async durableToolCallCacheKeyForScope(
+    input: {
+      toolId: string;
+      requestInput: Record<string, unknown>;
+      executionAuthScopeDigest?: string | null;
+      staleAfterSeconds?: number | null;
+      playLocalScope?: string | null;
+    },
+    toolResponseReceiptRevision: string | null | undefined = this
+      .currentToolResponseReceiptRevision,
+  ): Promise<string> {
     const providerActionVersion =
       (await this.#options.getToolActionCacheVersion?.(input.toolId))?.trim() ??
       '';
@@ -4051,21 +4074,29 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         executionAuthScopeDigest,
       }),
       providerActionVersion,
+      toolResponseReceiptRevision,
       staleAfterSeconds: input.staleAfterSeconds,
       cacheEpochMs: this.durableCallCacheEpochMs,
     });
   }
 
-  private async durableToolCallCacheKey(input: {
-    toolId: string;
-    requestInput: Record<string, unknown>;
-    executionAuthScopeDigest?: string | null;
-    staleAfterSeconds?: number | null;
-  }): Promise<string> {
-    return await this.durableToolCallCacheKeyForScope({
-      ...input,
-      playLocalScope: this.currentGovernance.currentPlayId,
-    });
+  private async durableToolCallCacheKey(
+    input: {
+      toolId: string;
+      requestInput: Record<string, unknown>;
+      executionAuthScopeDigest?: string | null;
+      staleAfterSeconds?: number | null;
+    },
+    toolResponseReceiptRevision: string | null | undefined = this
+      .currentToolResponseReceiptRevision,
+  ): Promise<string> {
+    return await this.durableToolCallCacheKeyForScope(
+      {
+        ...input,
+        playLocalScope: this.currentGovernance.currentPlayId,
+      },
+      toolResponseReceiptRevision,
+    );
   }
 
   private async resolveToolAuthScopeDigest(
@@ -8968,6 +8999,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       executionAuthScopeDigest,
       staleAfterSeconds: toolCachePolicy.staleAfterSeconds,
     });
+    let providerIdempotencyKeyBase = await this.durableToolCallCacheKey(
+      {
+        toolId,
+        requestInput: input,
+        executionAuthScopeDigest,
+        staleAfterSeconds: toolCachePolicy.staleAfterSeconds,
+      },
+      null,
+    );
     const checkpointCacheKeys = [durableCacheKey];
 
     const executeTool = async (context?: {
@@ -9091,9 +9131,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 callKey: normalizedKey,
               }),
               executionAuthScopeDigest,
+              providerIdempotencyReceiptKey: cacheableToolResult
+                ? providerIdempotencyKeyBase
+                : physicalDirectKey,
               providerIdempotencyKey: cacheableToolResult
                 ? this.providerIdempotencyKeyForToolCall({
-                    cacheKey: directCacheKey,
+                    cacheKey: providerIdempotencyKeyBase,
                     force: toolCachePolicy.force,
                     leaseId: directReceiptLeaseId,
                     logicalCallId,
@@ -9241,6 +9284,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         this.enqueueToolCall({
           callId,
           cacheKey: toolResultCacheKey,
+          providerIdempotencyKeyBase,
           cacheable: cacheableToolResult,
           receiptKey: cacheableToolResult ? durableCacheKey : null,
           executionAuthScopeDigest,
@@ -9361,6 +9405,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
           executionAuthScopeDigest,
           staleAfterSeconds: toolCachePolicy.staleAfterSeconds,
         });
+        providerIdempotencyKeyBase = await this.durableToolCallCacheKey(
+          {
+            toolId,
+            requestInput: input,
+            executionAuthScopeDigest,
+            staleAfterSeconds: toolCachePolicy.staleAfterSeconds,
+          },
+          null,
+        );
         checkpointCacheKeys[0] = durableCacheKey;
       }
     }
@@ -9523,14 +9576,18 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         `Unable to resolve play "${resolvedName}" for ctx.runPlay(...).`,
       );
     }
-    const childCompatibility = normalizePlayContractCompatibility(
+    const childCompatibilitySnapshot =
       resolvedPlay.contractSnapshot?.compatibility ??
-        resolvedPlay.artifact?.compatibility ??
-        buildPlayContractCompatibility(),
+      resolvedPlay.artifact?.compatibility ??
+      buildPlayContractCompatibility();
+    const childCompatibility = normalizePlayContractCompatibility(
+      childCompatibilitySnapshot,
     );
     const childToolErrorSchemaVersion =
       childCompatibility.toolErrorSchemaVersion;
     const childToolResponseContract = childCompatibility.toolResponseContract;
+    const childToolResponseReceiptRevision =
+      childCompatibility.toolResponseReceiptRevision;
     const childExecutionDecision = resolveChildExecutionStrategy({
       pipeline: resolvedPlay.staticPipeline,
       timeoutMs: options?.timeoutMs,
@@ -9604,6 +9661,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             staticPipeline: resolvedPlay.staticPipeline ?? null,
             toolErrorSchemaVersion: childToolErrorSchemaVersion,
             toolResponseContract: childToolResponseContract,
+            toolResponseReceiptRevision: childToolResponseReceiptRevision,
             authoringContractEdition:
               childCompatibility.authoringContractEdition,
           },
@@ -10882,12 +10940,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                       durableCallReceiptKey: receiptKey,
                       playNodeScope: playNodeScopeForToolCallRequest(owner),
                       executionAuthScopeDigest: owner.executionAuthScopeDigest,
+                      providerIdempotencyReceiptKey:
+                        owner.providerIdempotencyKeyBase ?? owner.cacheKey,
                       receiptLeaseExpiresAt: owner.receiptLeaseExpiresAt,
                       heartbeatReceipt: () =>
                         this.renewRuntimeToolReceiptOwnership([owner]),
                       providerIdempotencyKey:
                         this.providerIdempotencyKeyForToolCall({
-                          cacheKey: owner.cacheKey,
+                          cacheKey:
+                            owner.providerIdempotencyKeyBase ?? owner.cacheKey,
                           force: owner.force === true,
                           leaseId: owner.receiptLeaseId,
                         }),
@@ -11219,6 +11280,11 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                   const receiptKeys = batch.memberRequests.map(
                     (request) => request.cacheKey,
                   );
+                  const providerIdempotencyReceiptKeys =
+                    batch.memberRequests.map(
+                      (request) =>
+                        request.providerIdempotencyKeyBase ?? request.cacheKey,
+                    );
                   const aggregateReceiptKey =
                     buildDurableToolAggregateReceiptKey({
                       receiptKeys,
@@ -11228,6 +11294,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         toolId: batch.batchOperation,
                       }),
                     });
+                  const aggregateProviderIdempotencyReceiptKey =
+                    buildDurableToolAggregateReceiptKey({
+                      receiptKeys: providerIdempotencyReceiptKeys,
+                      prefix: 'batch',
+                      aggregateReceiptPrefix: buildDurableToolReceiptPrefix({
+                        orgId: this.#options.orgId,
+                        toolId: batch.batchOperation,
+                      }),
+                    });
                   let releaseToolSlot: () => void = () => undefined;
                   try {
                     const execution = await this.callToolExecutionAPI(
@@ -11247,14 +11322,19 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                         executionAuthScopeDigest:
                           batch.memberRequests[0]?.executionAuthScopeDigest ??
                           null,
+                        providerIdempotencyReceiptKey:
+                          aggregateProviderIdempotencyReceiptKey,
                         providerIdempotencyKey:
                           buildDurableToolAggregateProviderIdempotencyKey({
-                            aggregateReceiptKey,
-                            receiptKeys,
+                            aggregateReceiptKey:
+                              aggregateProviderIdempotencyReceiptKey,
+                            receiptKeys: providerIdempotencyReceiptKeys,
                             providerIdempotencyKeys: batch.memberRequests.map(
                               (request) =>
                                 this.providerIdempotencyKeyForToolCall({
-                                  cacheKey: request.cacheKey,
+                                  cacheKey:
+                                    request.providerIdempotencyKeyBase ??
+                                    request.cacheKey,
                                   force: request.force === true,
                                   leaseId: request.receiptLeaseId,
                                 }),
@@ -11481,9 +11561,14 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                               durableCallReceiptKey: request.receiptKey,
                               executionAuthScopeDigest:
                                 request.executionAuthScopeDigest,
+                              providerIdempotencyReceiptKey:
+                                request.providerIdempotencyKeyBase ??
+                                request.receiptKey,
                               providerIdempotencyKey:
                                 this.providerIdempotencyKeyForToolCall({
-                                  cacheKey: request.receiptKey,
+                                  cacheKey:
+                                    request.providerIdempotencyKeyBase ??
+                                    request.receiptKey,
                                   force: request.force === true,
                                   leaseId: request.receiptLeaseId,
                                 }),
@@ -11783,6 +11868,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
             : ((await this.resolveToolAuthScopeDigest(toolId))?.trim() ?? null);
           const providerIdempotencyKey =
             options?.providerIdempotencyKey?.trim() || durableCallReceiptKey;
+          const providerIdempotencyReceiptKey =
+            options?.providerIdempotencyReceiptKey?.trim() ||
+            durableCallReceiptKey;
           // Correlation identity is stable across every transport retry,
           // including calls without a durable receipt.
           const deeplineRequestId = providerIdempotencyKey
@@ -11836,6 +11924,12 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 ...(providerIdempotencyKey
                   ? { provider_idempotency_key: providerIdempotencyKey }
                   : {}),
+                ...(providerIdempotencyReceiptKey
+                  ? {
+                      provider_idempotency_receipt_key:
+                        providerIdempotencyReceiptKey,
+                    }
+                  : {}),
                 ...(playNodeScope
                   ? { play_node_scope: playNodeScopeToWire(playNodeScope) }
                   : {}),

package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts

@@ -60,6 +60,8 @@ export interface RowState {
 export interface ToolCallRequest {
   callId: string;
   cacheKey: string;
+  /** Stable external-operation identity, independent of receipt serialization. */
+  providerIdempotencyKeyBase?: string | null;
   cacheable?: boolean;
   receiptKey?: string | null;
   executionAuthScopeDigest?: string | null;
@@ -575,6 +577,8 @@ export interface ContextOptions {
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
   /** Execute-result contract pinned by the immutable Play artifact. */
   toolResponseContract?: ToolResponseContract;
+  /** Explicit response-transform revision used for durable receipt identity. */
+  toolResponseReceiptRevision?: string;
   /** Short-lived HMAC-signed internal token for tool callbacks. Required for cloud execution. */
   executorToken?: string;
   baseUrl?: string;

package/dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts

@@ -7,6 +7,7 @@ import {
   // resolve.
 } from '../plays/row-identity';
 import { resolveDurableCallCachePolicy } from './durable-call-policy';
+import { normalizeToolResponseReceiptRevision } from './tool-response-contract';
 
 export {
   DURABLE_CALL_STALE_AFTER_SECONDS_ERROR,
@@ -45,6 +46,11 @@ export function buildDurableToolCallCacheKey(input: {
   /** Run-stable clock used to choose the stale bucket. */
   cacheEpochMs?: number;
   playLocalScope?: string | null;
+  /**
+   * Explicit revision for a response transformation. Bump it only when the
+   * serialized tool output changes; omit it for historical artifacts.
+   */
+  toolResponseReceiptRevision?: string | null;
 }): string {
   const orgId = input.orgId?.trim() || 'org';
   const toolId = input.toolId.trim();
@@ -58,6 +64,11 @@ export function buildDurableToolCallCacheKey(input: {
     );
   }
   const playLocalScope = input.playLocalScope?.trim() || 'play';
+  // Keep historical digests byte-for-byte stable when no explicit revision
+  // exists on the stored artifact.
+  const toolResponseReceiptRevision = normalizeToolResponseReceiptRevision(
+    input.toolResponseReceiptRevision,
+  );
   const digest = sha256Hex(
     stableStringify({
       kind: 'tool' satisfies DurableCallKind,
@@ -70,6 +81,7 @@ export function buildDurableToolCallCacheKey(input: {
       providerActionVersion,
       cachePolicyVersion:
         input.cachePolicyVersion ?? DURABLE_CALL_CACHE_POLICY_VERSION,
+      ...(toolResponseReceiptRevision ? { toolResponseReceiptRevision } : {}),
       staleBucket: durableCacheStaleBucket({
         staleAfterSeconds: input.staleAfterSeconds,
         nowMs: input.cacheEpochMs,

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

@@ -141,6 +141,8 @@ export interface PlayRunnerContextConfig {
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
   /** Immutable execute response contract copied from the Play artifact. */
   toolResponseContract?: ToolResponseContract;
+  /** Explicit response-transform revision participating in receipt identity. */
+  toolResponseReceiptRevision?: string;
   orgId?: string;
   workflowId?: string;
   playId?: string;

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

@@ -1,10 +1,23 @@
 /**
  * Public tool-response contracts shared by the API, SDK, Play bundler, and
- * runtime. A response contract is transport behavior, never Play authoring.
+ * runtime. This is a versioned response transformation contract: a change to
+ * the persisted public tool-result shape must introduce a new value here and
+ * have newly built Play artifacts select it. Receipt-cache revisions are
+ * intentionally separate: ordinary response-contract changes do not refresh
+ * durable receipts unless the response transformation changed as well.
  */
 export const V2_TOOL_RESPONSE_CONTRACT = 'v2-tool-response' as const;
 export const RAW_V2_TOOL_RESPONSE_CONTRACT = 'raw-v2' as const;
 
+/**
+ * Deliberate durable-receipt boundary for the raw-v2 response transformation.
+ * Bump only when that transformation changes serialized tool output. Do not
+ * bump for ordinary protocol, authoring, or transport contract changes.
+ */
+export const RAW_V2_TOOL_RESPONSE_RECEIPT_REVISION = 'raw-v2-receipt-v1';
+const TOOL_RESPONSE_RECEIPT_REVISION_PATTERN =
+  /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/;
+
 export type ToolResponseContract =
   | typeof V2_TOOL_RESPONSE_CONTRACT
   | typeof RAW_V2_TOOL_RESPONSE_CONTRACT;
@@ -20,6 +33,19 @@ export function isToolResponseContract(
   );
 }
 
+/**
+ * Preserves the distinction between an old artifact with no declared response
+ * contract and an artifact that explicitly selected the legacy V2 contract.
+ * Receipt reuse is controlled separately by `toolResponseReceiptRevision`.
+ */
+export function declaredToolResponseContract(
+  value: unknown,
+): ToolResponseContract | undefined {
+  if (value == null) return undefined;
+  if (isToolResponseContract(value)) return value;
+  throw new UnsupportedToolResponseContractError(value);
+}
+
 export class UnsupportedToolResponseContractError extends Error {
   constructor(value: unknown) {
     super(
@@ -29,13 +55,34 @@ export class UnsupportedToolResponseContractError extends Error {
   }
 }
 
+export class InvalidToolResponseReceiptRevisionError extends Error {
+  constructor(value: unknown) {
+    super(
+      `Tool response receipt revision must be a non-empty static identifier (letters, numbers, '.', '_', or '-'); received ${String(value)}.`,
+    );
+    this.name = 'InvalidToolResponseReceiptRevisionError';
+  }
+}
+
+/** Missing means a historical artifact and preserves its original receipt key. */
+export function normalizeToolResponseReceiptRevision(
+  value: unknown,
+): string | undefined {
+  if (value == null) return undefined;
+  if (
+    typeof value === 'string' &&
+    TOOL_RESPONSE_RECEIPT_REVISION_PATTERN.test(value)
+  ) {
+    return value;
+  }
+  throw new InvalidToolResponseReceiptRevisionError(value);
+}
+
 /** Missing artifact compatibility predates canonical bodies and stays V2. */
 export function normalizeToolResponseContract(
   value: unknown,
 ): ToolResponseContract {
-  if (value == null) return V2_TOOL_RESPONSE_CONTRACT;
-  if (isToolResponseContract(value)) return value;
-  throw new UnsupportedToolResponseContractError(value);
+  return declaredToolResponseContract(value) ?? V2_TOOL_RESPONSE_CONTRACT;
 }
 
 export function legacyRawFromToolResponseRawV2(

package/dist/bundling-sources/shared_libs/plays/artifact-types.ts

@@ -31,6 +31,8 @@ export type PlayArtifactCompatibility = {
   authoringContractEdition?: PlayAuthoringContractEdition;
   /** Missing preserves the raw-only V2 execute response contract. */
   toolResponseContract?: ToolResponseContract;
+  /** Missing preserves the receipt namespace of artifacts created before this revision existed. */
+  toolResponseReceiptRevision?: string;
 };
 
 /** The only executable Play artifact contract. */

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -344,7 +344,12 @@ export type PlayAuthoringAstBindings = {
 export type PlayAuthoringBindings = {
   description?: string;
   compatibility?: {
-    toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
+    toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
+    /**
+     * Bump only when a Play's response transformation changes serialized tool
+     * output and requires fresh durable tool receipts.
+     */
+    toolResponseReceiptRevision?: string;
   };
   inline?: boolean;
   billing?: {
@@ -1103,6 +1108,28 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'compatibility.toolErrorSchemaVersion must be the static literal 0 or 1.',
   },
+  'compatibility.toolResponseReceiptRevision': {
+    schema: Type.String({
+      minLength: 1,
+      maxLength: 64,
+      pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$',
+    }),
+    fixtures: {
+      valid: 'raw-v2-receipt-v1',
+      invalid: 'has spaces',
+      absent: undefined,
+      unresolved: { expression: 'revision' },
+      edition1: undefined,
+    },
+    referenceType: 'string',
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_binding_invalid',
+    description:
+      'Explicit durable-receipt revision for a response transformation; bump only when serialized tool output changes.',
+    errorMessage:
+      'compatibility.toolResponseReceiptRevision must be a non-empty static identifier using letters, numbers, dots, underscores, or hyphens.',
+  },
   inline: {
     schema: Type.Boolean(),
     fixtures: {
@@ -2488,7 +2515,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '};',
   'export type PlayBindings = {',
   `  description?: ${cloudReferenceType('description')};`,
-  `  compatibility?: { toolErrorSchemaVersion: ${cloudReferenceType('compatibility.toolErrorSchemaVersion')} };`,
+  `  compatibility?: { toolErrorSchemaVersion?: ${cloudReferenceType('compatibility.toolErrorSchemaVersion')}; toolResponseReceiptRevision?: ${cloudReferenceType('compatibility.toolResponseReceiptRevision')} };`,
   `  inline?: ${cloudReferenceType('inline')};`,
   `  billing?: { maxCreditsPerRun?: ${cloudReferenceType('billing.maxCreditsPerRun')} };`,
   `  runtime?: { timeout?: ${cloudReferenceType('runtime.timeout')}; size?: ${cloudReferenceType('runtime.size')} };`,

package/dist/bundling-sources/shared_libs/plays/bundling/index.ts

@@ -66,7 +66,7 @@ import { PLAY_AUTHORING_CONTRACT_EDITION } from '../authoring-contract';
 // of the artifact bytes. Do not reuse a local bundle cached before either
 // compatibility selection or docflow instrumentation entered graph analysis.
 // Keep this aligned with the app and SDK adapters' cache namespace.
-const PLAY_BUNDLE_CACHE_VERSION = 35;
+const PLAY_BUNDLE_CACHE_VERSION = 36;
 const PLAY_ARTIFACT_CACHE_DIR = join(
   tmpdir(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,
@@ -205,6 +205,7 @@ type SourceGraphAnalysis = {
   playDescription: string | null;
   sandboxRuntimeDeclaration: PlaySandboxRuntimeDeclaration | null;
   toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion | null;
+  toolResponseReceiptRevision: string | null;
   importedPlayDependencies: ImportedPlayDependency[];
 };
 
@@ -583,6 +584,8 @@ type ExtractedPlayMetadata = {
   sandboxRuntimeDeclaration: PlaySandboxRuntimeDeclaration | null;
   toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion | null;
   toolErrorSchemaVersionUnknown: boolean;
+  toolResponseReceiptRevision: string | null;
+  toolResponseReceiptRevisionUnknown: boolean;
 };
 
 function parsePlaySourceAst(sourceCode: string): AstNode | null {
@@ -1020,12 +1023,47 @@ function toolErrorSchemaVersionFromOptions(
     'toolErrorSchemaVersion',
     context,
   );
+  if (schema.kind === 'absent') return undefined;
   if (schema.kind !== 'found') return null;
   const schemaVersion = staticNumberFromExpression(schema.value, context);
   if (schemaVersion === 0 || schemaVersion === 1) return schemaVersion;
   return null;
 }
 
+function toolResponseReceiptRevisionFromOptions(
+  node: AstNode | null | undefined,
+  context: PlayMetadataExtractionContext,
+): string | null | undefined {
+  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' } satisfies StaticPropertyResolution);
+  if (bindingCompatibility.kind === 'unknown') return null;
+
+  const compatibility =
+    directCompatibility.kind === 'found'
+      ? directCompatibility
+      : bindingCompatibility;
+  if (compatibility.kind === 'absent') return undefined;
+  const revision = resolveStaticProperty(
+    compatibility.value,
+    'toolResponseReceiptRevision',
+    context,
+  );
+  if (revision.kind === 'absent') return undefined;
+  if (revision.kind !== 'found') return null;
+  return staticStringFromExpression(revision.value, context);
+}
+
 function sandboxRuntimeDeclarationFromOptions(
   node: AstNode | null | undefined,
   context: PlayMetadataExtractionContext,
@@ -1169,12 +1207,20 @@ function playMetadataFromDefinePlayCall(
     context,
   );
   const toolErrorSchemaVersionUnknown = toolErrorSchemaVersion === null;
+  const toolResponseReceiptRevision = toolResponseReceiptRevisionFromOptions(
+    options,
+    context,
+  );
+  const toolResponseReceiptRevisionUnknown =
+    toolResponseReceiptRevision === null;
 
   if (
     !name &&
     !description &&
     toolErrorSchemaVersion === undefined &&
-    !toolErrorSchemaVersionUnknown
+    !toolErrorSchemaVersionUnknown &&
+    toolResponseReceiptRevision === undefined &&
+    !toolResponseReceiptRevisionUnknown
   ) {
     return null;
   }
@@ -1184,6 +1230,8 @@ function playMetadataFromDefinePlayCall(
     sandboxRuntimeDeclaration,
     toolErrorSchemaVersion: toolErrorSchemaVersion ?? null,
     toolErrorSchemaVersionUnknown,
+    toolResponseReceiptRevision: toolResponseReceiptRevision ?? null,
+    toolResponseReceiptRevisionUnknown,
   };
 }
 
@@ -2039,6 +2087,11 @@ async function analyzeSourceGraph(
       'definePlay compatibility.toolErrorSchemaVersion must be the static literal 0 or 1.',
     );
   }
+  if (metadata?.toolResponseReceiptRevisionUnknown) {
+    throw new Error(
+      'definePlay compatibility.toolResponseReceiptRevision must be a static non-empty string.',
+    );
+  }
   const playName = metadata?.name ?? null;
   const playDescription = metadata?.description ?? null;
   const sandboxRuntimeDeclaration = metadata?.sandboxRuntimeDeclaration ?? null;
@@ -2063,6 +2116,7 @@ async function analyzeSourceGraph(
     playDescription,
     sandboxRuntimeDeclaration,
     toolErrorSchemaVersion: metadata?.toolErrorSchemaVersion ?? null,
+    toolResponseReceiptRevision: metadata?.toolResponseReceiptRevision ?? null,
     importedPlayDependencies: [...importedPlayDependencies.values()].sort(
       (left, right) => left.filePath.localeCompare(right.filePath),
     ),
@@ -2340,6 +2394,8 @@ export async function bundlePlayFile(
           compatibility: buildPlayContractCompatibility({
             toolErrorSchemaVersion:
               analysis.toolErrorSchemaVersion ?? undefined,
+            toolResponseReceiptRevision:
+              analysis.toolResponseReceiptRevision ?? undefined,
           }),
           cacheHit: true,
         },
@@ -2408,6 +2464,8 @@ export async function bundlePlayFile(
       importPolicy,
       compatibility: buildPlayContractCompatibility({
         toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? undefined,
+        toolResponseReceiptRevision:
+          analysis.toolResponseReceiptRevision ?? undefined,
       }),
       generatedAt: Date.now(),
       cacheHit: false,