deepline 0.3.393 → 0.3.394

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

@@ -202,7 +202,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.393',
+  version: '0.3.394',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

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

@@ -195,6 +195,7 @@ import {
   type ToolExecuteResult,
   type ToolResultExecutionMetadata,
   type ToolResultMetadataInput,
+  type CallFreshnessMetadata,
 } from './tool-result';
 import {
   EXECUTION_GATEWAY_RECEIPT_OUTPUT_REFERENCE_HEADER,
@@ -269,9 +270,12 @@ import {
   scopeToolReceiptToInvocation,
   resolveDurableCallCachePolicy,
 } from './durable-call-cache';
+import { resolveExplicitDurableCallPolicy } from './durable-call-policy';
+import { executeWithFreshnessReceipt } from './freshness-receipt-execution';
 import {
   CtxFetchHttpError,
   PLAY_AUTHORING_CONTRACT_EDITION,
+  PlayAuthoringFieldValidationError,
   normalizePlayAuthoringCustomerDbStatement,
   validateOptionalPlayAuthoringField,
   validatePlayAuthoringField,
@@ -639,6 +643,7 @@ const inlineCompositionContext =
 const authoredStepContext = new AsyncLocalStorage<{
   context: PlayContextImpl;
   stepId: string;
+  invocationId?: string;
 }>();
 const toolExecutionOverrides = new AsyncLocalStorage<{ force: boolean }>();
 const PROGRESS_HEARTBEAT_INTERVAL_MS = 1_000;
@@ -2931,6 +2936,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   private mapInvocationIndex = 0;
   private readonly stepCallIndexByKey = new Map<string, number>();
   private readonly toolCallIndexByKey = new Map<string, number>();
+  private readonly freshnessCallIndexByKey = new Map<string, number>();
   /**
    * Parent-level inline-child aggregates. Maintained only by the single-writer
    * progress path (never per child) so concurrent fan-out cannot contend. See
@@ -3208,7 +3214,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     key: string,
     toolId: string,
     input: Record<string, unknown>,
-    options?: { description?: string },
+    options?: {
+      description?: string;
+      staleAfterSeconds?: number | null;
+    },
   ): Promise<ToolExecuteResult<TOutput>> {
     validatePlayAuthoringField('ctx.tool.key', key);
     validatePlayAuthoringField('ctx.tool.tool', toolId);
@@ -3224,6 +3233,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       tool: toolId,
       input,
       ...(options?.description ? { description: options.description } : {}),
+      ...(options?.staleAfterSeconds !== undefined
+        ? { staleAfterSeconds: options.staleAfterSeconds }
+        : {}),
     })) as ToolExecuteResult<TOutput>;
   }
 
@@ -3233,9 +3245,41 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
   readonly customerDb = {
     query: async <TRow extends object = Record<string, unknown>>(
       statement: PlaySqlQuery | string,
-      options?: { maxRows?: number; timeoutMs?: number },
+      options?: {
+        id?: string;
+        staleAfterSeconds?: number | null;
+        maxRows?: number;
+        timeoutMs?: number;
+      },
     ): Promise<TRow[]> => {
       const sql = normalizePlayAuthoringCustomerDbStatement(statement);
+      if (this.usesExplicitFreshness) {
+        validatePlayAuthoringField(
+          'ctx.customerDb.query.options.id',
+          options?.id,
+        );
+      } else if (options?.id !== undefined) {
+        validatePlayAuthoringField(
+          'ctx.customerDb.query.options.id',
+          options.id,
+        );
+      }
+      if (options?.staleAfterSeconds !== undefined) {
+        validatePlayAuthoringField(
+          'ctx.customerDb.query.options.staleAfterSeconds',
+          options.staleAfterSeconds,
+        );
+      }
+      if (
+        this.usesExplicitFreshness &&
+        options?.staleAfterSeconds === undefined
+      ) {
+        throw new PlayAuthoringFieldValidationError(
+          'ctx.customerDb.query.options.staleAfterSeconds',
+          'play_authoring_durable_policy_invalid',
+          'Edition 11 Customer DB queries require staleAfterSeconds: 0.',
+        );
+      }
       if (options?.maxRows !== undefined) {
         validatePlayAuthoringField(
           'ctx.customerDb.query.options.maxRows',
@@ -3249,7 +3293,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         );
       }
       const result = (await this.tools.execute({
-        id: `customer_db_query_${this.customerDbQueryIndex++}`,
+        id: options?.id ?? `customer_db_query_${this.customerDbQueryIndex++}`,
         tool: 'query_customer_db',
         input: {
           sql,
@@ -3260,7 +3304,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         description: 'Customer DB query',
         // The direct executor never reused a prior SQL result. Preserve that
         // imperative behavior for reads and mutations alike.
-        force: true,
+        ...(this.usesExplicitFreshness
+          ? { staleAfterSeconds: options?.staleAfterSeconds }
+          : { force: true }),
         ...(options?.timeoutMs !== undefined
           ? { timeoutMs: options.timeoutMs }
           : {}),
@@ -3866,6 +3912,95 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     return this.currentRuntimeContract.semantics;
   }
 
+  private get usesExplicitFreshness(): boolean {
+    return (
+      this.currentRuntimeSemantics.freshness ===
+      'actual_age_with_operation_recovery'
+    );
+  }
+
+  private freshnessInvocationId(operation: string, id: string): string {
+    const row = rowContext.getStore();
+    const step = authoredStepContext.getStore();
+    const scope = stableStringify({
+      namespace: this.currentExecutionScope.receipt.namespace,
+      operation,
+      id,
+      step: step?.context === this ? (step.invocationId ?? step.stepId) : null,
+      row: row
+        ? {
+            table: row.tableNamespace ?? null,
+            key: row.rowKey ?? row.rowId,
+            field: row.fieldName ?? null,
+          }
+        : null,
+    });
+    const freshIndex = this.freshnessCallIndexByKey.get(scope) ?? 0;
+    this.freshnessCallIndexByKey.set(scope, freshIndex + 1);
+    // Invocation identity follows authored scope and call order. Keep it
+    // separate from the request/auth/action fingerprint used by reusable
+    // result caching, so credential or response-contract changes cannot mint
+    // a second provider operation key for the same authored effect.
+    // A mapped row can be re-entered after provider backpressure; its replay
+    // cursor restores the original call position.
+    const index = nextReplayableCallIndex(`freshness:${scope}`, freshIndex);
+    return sha256Hex(`${scope}:${index}`);
+  }
+
+  private async executeFreshnessControlledCall<T>(input: {
+    operation: DurableCtxOperation;
+    id: string;
+    semanticKey: string;
+    invocationId: string;
+    policy: { requested: number | null; effective: number | null };
+    execute: () => Promise<T>;
+    completedAt?: (value: T) => number | undefined;
+    onOutcome?: (value: T, metadata: CallFreshnessMetadata) => T;
+  }): Promise<T> {
+    const orgId = this.#options.orgId?.trim();
+    if (!orgId) {
+      throw new Error(
+        'Freshness-controlled calls require a resolved organization identity.',
+      );
+    }
+    return executeWithFreshnessReceipt({
+      orgId,
+      semanticKey: input.semanticKey,
+      invocationId: input.invocationId,
+      runId: this.currentRunId,
+      requestedStaleAfterSeconds: input.policy.requested,
+      effectiveStaleAfterSeconds: input.policy.effective,
+      store: this.durableReceiptExecutionStore(),
+      completedAt: input.completedAt,
+      withHydration: (read) =>
+        this.withRuntimeReceiptHydrationTurn(
+          (turn) =>
+            read((receipt) =>
+              turn.settleBytes(
+                runtimeStepReceiptPayloadBytes(receipt ? [receipt] : []),
+              ),
+            ),
+          { source: 'durable_operation' },
+        ),
+      execute: async () => {
+        const value = await input.execute();
+        this.assertNoPendingDurableSuspension();
+        return value;
+      },
+      onOutcome: (value, metadata) => {
+        this.runtimeLog(
+          JSON.stringify({
+            event: 'call_freshness',
+            operation: input.operation,
+            call_key: input.id,
+            ...metadata,
+          }),
+        );
+        return input.onOutcome ? input.onOutcome(value, metadata) : value;
+      },
+    });
+  }
+
   private recordPlayCallStep(input: {
     playId: string;
     execution?: 'inline';
@@ -6297,6 +6432,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       force?: boolean;
       receiptKey?: string | null;
       semanticKey?: string | null;
+      invocationId?: string;
       staleAfterSeconds?: number | null;
       repairRunningReceiptForSameRun?: boolean;
       repairRunningReceiptForSameRunAfterWaitTimeout?: boolean;
@@ -6340,6 +6476,15 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         },
       });
     if (opts.transient === true) {
+      if (
+        this.usesExplicitFreshness &&
+        opts.staleAfterSeconds !== undefined &&
+        opts.staleAfterSeconds !== 0
+      ) {
+        throw new Error(
+          'Transient fetch does not support retained result reuse; omit freshness or choose staleAfterSeconds: 0.',
+        );
+      }
       try {
         return await execute(null);
       } finally {
@@ -6347,6 +6492,44 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
         release?.();
       }
     }
+    if (this.usesExplicitFreshness && operation === 'fetch') {
+      const policy = resolveExplicitDurableCallPolicy(opts);
+      const semanticKey = stableStringify({
+        orgId: this.#options.orgId,
+        namespace: this.currentExecutionScope.receipt.namespace,
+        operation,
+        id,
+        semanticKey: opts.semanticKey,
+      });
+      try {
+        return await this.executeFreshnessControlledCall({
+          operation,
+          id,
+          semanticKey,
+          invocationId:
+            opts.invocationId ?? this.freshnessInvocationId(operation, id),
+          policy,
+          execute: () => execute(null),
+          onOutcome: (value, freshness) => {
+            const output =
+              opts.onRecovered && freshness.source !== 'executed'
+                ? opts.onRecovered(
+                    value,
+                    {
+                      key: freshness.operationReceiptKey!,
+                      status: 'completed',
+                    },
+                    'cache',
+                  )
+                : value;
+            return { ...output, freshness };
+          },
+        });
+      } finally {
+        const release = releaseExternalCallSlot as (() => void) | null;
+        release?.();
+      }
+    }
     const stalePolicy = resolveDurableCallCachePolicy(
       opts.staleAfterSeconds,
       operation === 'step'
@@ -11662,6 +11845,9 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                     stepPath,
                   }),
                 ),
+                ...(step.staleAfterSeconds !== undefined
+                  ? { staleAfterSeconds: step.staleAfterSeconds }
+                  : {}),
               },
             )
           : await this.executeStepProgramStep(
@@ -12951,6 +13137,165 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     toolId: string,
     input: Record<string, unknown>,
     options?: ToolCallOptions,
+  ): Promise<unknown> {
+    if (!this.usesExplicitFreshness) {
+      return this.executeToolLegacyInternal(key, toolId, input, options);
+    }
+    const policy = resolveExplicitDurableCallPolicy(options ?? {});
+    if (
+      this.#options.cachePolicy?.forceToolRefresh === true ||
+      toolExecutionOverrides.getStore()?.force === true
+    ) {
+      policy.effective = 0;
+    }
+    const normalizedKey = this.normalizeContextKey(key, 'tool');
+    // Reserve operation identity before asynchronous metadata lookup. Two
+    // concurrent calls may share an authored id; assigning their identity
+    // after auth/action metadata resolves would make recovery depend on lookup
+    // completion order instead of authored call order.
+    const invocationId = this.freshnessInvocationId('tool', normalizedKey);
+    const sqlTool = isCustomerDbDatasetTool(toolId);
+    const scalarCustomerDbQuery = sqlTool && input.result_mode === 'rows';
+    const liveDataset =
+      isQueryResultDatasetReadRequest(toolId, input) && !scalarCustomerDbQuery;
+    const sqlMutation =
+      sqlTool &&
+      !isQueryResultDatasetReadRequest(toolId, {
+        ...input,
+        result_mode: undefined,
+      });
+    const [eventWait, invocationScoped, retryPolicy, reusableSupport] =
+      policy.effective === 0
+        ? ([null, false, null, null] as const)
+        : await Promise.all([
+            this.#options.getIntegrationEventWaitHandler?.(toolId) ?? null,
+            this.#options
+              .getToolIdempotencyScope?.(toolId)
+              .then((scope) => scope === 'invocation') ?? false,
+            this.#options.getToolRetryPolicy?.(toolId, input) ?? null,
+            this.#options.getToolReusableResultSupport?.(toolId) ?? null,
+          ]);
+    const requiresExecutionFence = retryPolicy?.requiresExecutionFence === true;
+    if (policy.effective !== 0 && reusableSupport?.supported !== true) {
+      throw new Error(
+        `Tool ${toolId} does not support reusable freshness; use staleAfterSeconds: 0. ${reusableSupport?.unavailableReason ?? 'No read-result reuse capability was supplied by the action owner.'}`,
+      );
+    }
+    if (
+      policy.effective !== 0 &&
+      (eventWait ||
+        invocationScoped ||
+        requiresExecutionFence ||
+        liveDataset ||
+        sqlMutation ||
+        isAlwaysFreshIntegrationTool(toolId))
+    ) {
+      throw new Error(
+        `Tool ${toolId} does not support reusable freshness; use staleAfterSeconds: 0. Live datasets, event waits, invocation-scoped actions, writes, and Workspace operations cannot reuse an older result.`,
+      );
+    }
+
+    const authScope = await this.resolveToolAuthScopeDigest(toolId);
+    const actionVersion =
+      (await this.#options.getToolActionCacheVersion?.(toolId))?.trim() ?? '';
+    if (!actionVersion) {
+      throw new Error(`Tool ${toolId} has no action identity for freshness.`);
+    }
+    const semanticKey = stableStringify({
+      kind: 'tool',
+      orgId: this.#options.orgId,
+      toolId,
+      input,
+      authScope,
+      actionVersion,
+      responseContract: this.currentToolResponseContract,
+      responseRevision: this.currentToolResponseReceiptRevision,
+    });
+    if (sqlTool && input.operation_key !== undefined) {
+      throw new Error(
+        'Play SQL operation identity is assigned by the runtime. Use the authored call id to identify the operation.',
+      );
+    }
+    const requestInput =
+      sqlTool && (sqlMutation || scalarCustomerDbQuery)
+        ? { ...input, operation_key: `${this.currentRunId}:${invocationId}` }
+        : input;
+
+    if (liveDataset || isAlwaysFreshIntegrationTool(toolId)) {
+      const value = await this.executeToolLegacyInternal(
+        key,
+        toolId,
+        requestInput,
+        { ...options, force: true, staleAfterSeconds: 0 },
+      );
+      const freshness: CallFreshnessMetadata = {
+        requestedStaleAfterSeconds: policy.requested,
+        effectiveStaleAfterSeconds: 0,
+        source: 'live_observation',
+        resultAgeMs: 0,
+        completedAt: Date.now(),
+        unavailableReason: liveDataset
+          ? 'Dataset rows are live observations; the dataset owner controls pagination and recovery.'
+          : 'Workspace reviewer edits and conflict checks must be observed on every invocation.',
+      };
+      return isToolExecuteResult(value)
+        ? cloneToolExecuteResultWithExecution(value, {
+            ...value._metadata.execution,
+            freshness,
+          })
+        : value;
+    }
+
+    return this.executeFreshnessControlledCall({
+      operation: 'tool',
+      id: normalizedKey,
+      semanticKey,
+      invocationId,
+      policy,
+      completedAt: (value) => {
+        if (!isToolExecuteResult(value)) return undefined;
+        const raw = value.toolResponse.raw as {
+          operation?: { completed_at_ms?: unknown };
+        } | null;
+        const completedAt = raw?.operation?.completed_at_ms;
+        return typeof completedAt === 'number' &&
+          Number.isSafeInteger(completedAt)
+          ? completedAt
+          : value._metadata.execution.completedAt;
+      },
+      execute: async () => {
+        const value = await this.executeToolLegacyInternal(
+          key,
+          toolId,
+          requestInput,
+          { ...options, force: true, staleAfterSeconds: 0 },
+        );
+        if ((await this.resolveToolAuthScopeDigest(toolId)) !== authScope) {
+          throw new Error(
+            'Tool credential identity changed during execution. Resume under the current credential identity before retaining this result.',
+          );
+        }
+        return value;
+      },
+      onOutcome: (value, freshness) =>
+        isToolExecuteResult(value)
+          ? cloneToolExecuteResultWithExecution(value, {
+              ...value._metadata.execution,
+              cached: freshness.source !== 'executed',
+              source: freshness.source === 'executed' ? 'live' : 'cache',
+              resultReceiptKey: freshness.operationReceiptKey,
+              freshness,
+              completedAt: freshness.completedAt,
+            })
+          : value,
+    });
+  }
+
+  private async executeToolLegacyInternal(
+    key: string,
+    toolId: string,
+    input: Record<string, unknown>,
+    options?: ToolCallOptions,
   ): Promise<unknown> {
     if (!rowContext.getStore()) this.assertRowAdmissionOpen();
     this.assertNoPendingDurableSuspension();
@@ -15085,6 +15430,10 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     if (!rowContext.getStore()) this.assertRowAdmissionOpen();
     validatePlayAuthoringField('ctx.fetch.key', key);
     const normalizedKey = this.normalizeContextKey(key, 'fetch');
+    const invocationId =
+      this.usesExplicitFreshness && options?.transient !== true
+        ? this.freshnessInvocationId('fetch', normalizedKey)
+        : undefined;
     const rowStore = rowContext.getStore();
     const rowFetchScope = rowStore
       ? {
@@ -15098,6 +15447,30 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     const url = input.toString();
     const parsedUrl = new URL(url);
     const method = (init.method ?? 'GET').toUpperCase();
+    const reusableReadMethod = ['GET', 'HEAD', 'OPTIONS'].includes(method);
+    if (this.usesExplicitFreshness && options?.transient === true) {
+      if (!reusableReadMethod) {
+        throw new Error(
+          'Edition 11 transient fetches are limited to read-only HTTP methods.',
+        );
+      }
+      if (
+        options.staleAfterSeconds !== undefined &&
+        options.staleAfterSeconds !== 0
+      ) {
+        throw new Error(
+          'Transient fetch does not support retained result reuse; omit freshness or choose staleAfterSeconds: 0.',
+        );
+      }
+    } else if (
+      this.usesExplicitFreshness &&
+      !reusableReadMethod &&
+      options?.staleAfterSeconds !== 0
+    ) {
+      throw new Error(
+        'Edition 11 mutating or non-read-only fetches require staleAfterSeconds: 0.',
+      );
+    }
     const urlContainsResolvedSecret =
       this.secretRedactor.containsRegisteredSecret(url, {
         includeEncoded: true,
@@ -15187,6 +15560,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               : {}),
           }),
         ),
+        invocationId,
         staleAfterSeconds: options?.staleAfterSeconds,
         transient: options?.transient === true,
         onRecovered: (output) => {
@@ -15238,6 +15612,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
                 },
                 body: receiptBody,
                 row: rowFetchScope,
+                ...(invocationId ? { invocationId } : {}),
               }),
             )}`,
           );
@@ -15386,6 +15761,24 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       'ctx.step.semanticKey',
       options?.semanticKey,
     );
+    const freshnessPolicy = this.usesExplicitFreshness
+      ? resolveExplicitDurableCallPolicy(options ?? {})
+      : null;
+    if (
+      freshnessPolicy &&
+      this.#options.cachePolicy?.forceStepRefresh === true
+    ) {
+      freshnessPolicy.effective = 0;
+    }
+    if (
+      freshnessPolicy &&
+      freshnessPolicy.requested !== 0 &&
+      !options?.semanticKey?.trim()
+    ) {
+      throw new Error(
+        'Reusable ctx.step results require a stable semanticKey.',
+      );
+    }
     const normalizedKey = this.normalizeContextKey(key, 'step');
     if (!normalizedKey.trim()) {
       throw new Error('ctx.step(key, fn) requires a non-empty stable step id.');
@@ -15393,7 +15786,26 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
 
     const rowStore = rowContext.getStore();
     const scope = rowStore ? `row-${rowStore.rowId}` : 'workflow';
-    const callIndexKey = `${this.currentExecutionScope.receipt.namespace}:${scope}:${normalizedKey}`;
+    const parentStep = authoredStepContext.getStore();
+    const explicitStepScope = freshnessPolicy
+      ? stableDigest(
+          stableStringify({
+            semanticKey: options?.semanticKey ?? null,
+            parent:
+              parentStep?.context === this
+                ? (parentStep.invocationId ?? parentStep.stepId)
+                : null,
+            row: rowStore
+              ? {
+                  table: rowStore.tableNamespace,
+                  key: rowStore.rowKey ?? rowStore.rowId,
+                  field: rowStore.fieldName,
+                }
+              : null,
+          }),
+        )
+      : null;
+    const callIndexKey = `${this.currentExecutionScope.receipt.namespace}:${scope}:${normalizedKey}${explicitStepScope ? `:${explicitStepScope}` : ''}`;
     const freshCallIndex = this.stepCallIndexByKey.get(callIndexKey) ?? 0;
     const callIndex = nextReplayableCallIndex(
       `step:${callIndexKey}`,
@@ -15405,7 +15817,7 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
     );
     const boundarySuffix = callIndex === 0 ? '' : `:${callIndex}`;
     const boundaryId = this.durableBoundaryId(
-      `step-${scope}:${normalizedKey}${boundarySuffix}`,
+      `step-${scope}:${normalizedKey}${explicitStepScope ? `:${explicitStepScope}` : ''}${boundarySuffix}`,
     );
     const advanceRecoveredSleepCursor = async (
       receipt?: RuntimeStepReceipt,
@@ -15488,9 +15900,63 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
       });
     try {
       const output = await authoredStepContext.run(
-        { context: this, stepId: normalizedKey },
-        () =>
-          this.executeWithRuntimeReceipt<T>(
+        {
+          context: this,
+          stepId: normalizedKey,
+          ...(freshnessPolicy ? { invocationId: boundaryId } : {}),
+        },
+        async () => {
+          if (freshnessPolicy) {
+            const semanticKey = stableStringify({
+              operation: 'step',
+              orgId: this.#options.orgId,
+              namespace: this.currentExecutionScope.receipt.namespace,
+              id: normalizedKey,
+              semanticKey: options?.semanticKey,
+              row: rowStore
+                ? {
+                    table: rowStore.tableNamespace,
+                    key: rowStore.rowKey ?? rowStore.rowId,
+                    field: rowStore.fieldName,
+                  }
+                : null,
+            });
+            const completed = await this.executeFreshnessControlledCall({
+              operation: 'step',
+              id: normalizedKey,
+              semanticKey,
+              invocationId: boundaryId,
+              policy: freshnessPolicy,
+              completedAt: (value) => value.completedAt,
+              execute: async () => {
+                const before = this.sleepBoundaryIndex;
+                const value = await executeStep();
+                const boundary =
+                  this.checkpoint.resolvedBoundaries?.[boundaryId];
+                return {
+                  output: value === undefined ? null : value,
+                  undefinedOutput: value === undefined,
+                  sleepCount: this.sleepBoundaryIndex - before,
+                  completedAt:
+                    (boundary?.kind === 'step'
+                      ? boundary.completedAt
+                      : undefined) ?? Date.now(),
+                };
+              },
+              onOutcome: (value, freshness) => {
+                if (freshness.source !== 'executed') {
+                  this.sleepBoundaryIndex += value.sleepCount;
+                }
+                return value;
+              },
+            });
+            const result = completed.undefinedOutput
+              ? undefined
+              : completed.output;
+            assertJsonSerializableStepOutput(normalizedKey, result);
+            return result as T;
+          }
+          return await this.executeWithRuntimeReceipt<T>(
             'step',
             normalizedKey,
             this.currentRunId,
@@ -15520,7 +15986,8 @@ export class PlayContextImpl implements ScalarPlayAuthoringRuntimeContext {
               },
               execute: executeStep,
             },
-          ),
+          );
+        },
       );
       if (observe)
         this.emitExecutionEvent({

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

@@ -338,7 +338,7 @@ export interface RuntimeDatasetOptions<TItem = Record<string, unknown>> {
    * Set staleAfterSeconds to rerun after that many seconds while retries/replays
    * inside the same window still hit the cache. Daily refreshes use 86400.
    */
-  staleAfterSeconds?: number;
+  staleAfterSeconds?: number | null;
   /**
    * Optional stable key per row. When provided, row identity is derived from
    * the selected input field(s) or returned value instead of hashing the full
@@ -1083,6 +1083,9 @@ export interface ContextOptions {
   /** Identity policy is required before reading receipts; lookup errors are
    * fatal, unlike the legacy best-effort retry advice below. */
   getToolIdempotencyScope?: (toolId: string) => Promise<'invocation' | null>;
+  getToolReusableResultSupport?: (
+    toolId: string,
+  ) => Promise<{ supported: boolean; unavailableReason: string | null }>;
   getToolRetryPolicy?: (
     toolId: string,
     input: Record<string, unknown>,
@@ -1365,6 +1368,7 @@ export type PlayFetchResponse = {
   headers: Record<string, string>;
   bodyText: string;
   json: unknown | null;
+  freshness?: import('../plays/tool-result-types').CallFreshnessMetadata;
 };
 
 export interface BatchResult {