deepline 0.3.392 → 0.3.394

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/runtime-event-search.ts

@@ -2040,7 +2040,7 @@ export async function attachRuntimeEventSearchTriggers(
   await client.query(`
     CREATE OR REPLACE FUNCTION ${schema}.project_origin_log_batch(observation ${schema}.outbox, item jsonb, run_org text, play text, compact_logs boolean, canonical_events boolean, at_time timestamptz, doc jsonb, closed boolean)
     RETURNS text[] LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog AS $function$
-    DECLARE fresh text[]; mismatches bigint; expected_ids text[]; existing_identities jsonb;
+    DECLARE fresh text[]; mismatches bigint; expected_keys jsonb; existing_identities jsonb;
       batch_lines jsonb := item->'lines';
       batch_ids jsonb := item->'lineIds';
       batch_contexts jsonb := item->'lineContexts';
@@ -2110,24 +2110,33 @@ export async function attachRuntimeEventSearchTriggers(
       -- Resolve the whole key set once. A per-line LATERAL lookup can choose
       -- a non-leading event_id index scan when scope/org statistics are skewed,
       -- re-reading the same history for every ID even though the PK is unique.
-      SELECT array_agg('log-origin:' || observation.run_id || ':' || (id #>> '{}') ORDER BY ordinal)
-        INTO expected_ids FROM jsonb_array_elements(batch_ids) WITH ORDINALITY AS ids(id, ordinal);
+      -- Generic plans may scan the scope/org prefix and test ANY(text[]) for
+      -- every row. Use the indexed run prefix and a once-built JSON key set.
+      SELECT jsonb_object_agg('log-origin:' || observation.run_id || ':' || (id #>> '{}'), true)
+        INTO expected_keys FROM jsonb_array_elements(batch_ids) AS ids(id);
       SELECT jsonb_object_agg(event.event_id, jsonb_build_object(
         'runId', event.run_id, 'kind', event.kind, 'digest', event.source_digest))
         INTO existing_identities
         FROM runtime_observability.events event
        WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-         AND event.event_id = ANY(expected_ids);
+         AND event.run_id = observation.run_id AND expected_keys ? event.event_id;
       -- JSON key lookups preserve one proof per identity without a join whose
       -- generic plan can multiply the two variable-size sets. Tombstones keep
       -- their digest/identity: retry never restores an expired body.
-      SELECT count(*) INTO mismatches
-      FROM jsonb_array_elements(batch_lines) WITH ORDINALITY AS entries(body, ordinal)
-      WHERE existing_identities->expected_ids[ordinal]->>'runId' IS DISTINCT FROM observation.run_id
-        OR existing_identities->expected_ids[ordinal]->>'kind' IS DISTINCT FROM ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
-        OR existing_identities->expected_ids[ordinal]->>'digest' IS DISTINCT FROM CASE WHEN NULLIF(batch_contexts->(ordinal-1)::int, 'null'::jsonb) IS NULL
+      -- Stream aligned IDs with their lines: positional text[] subscripting
+      -- walks variable-width elements from the start on every lookup.
+      WITH entries AS MATERIALIZED (
+        SELECT body, 'log-origin:' || observation.run_id || ':' || id AS eid,
+          NULLIF(batch_contexts->(ordinal-1)::int, 'null'::jsonb) AS ctx
+        FROM ROWS FROM (jsonb_array_elements(batch_lines), jsonb_array_elements_text(batch_ids))
+          WITH ORDINALITY AS aligned(body, id, ordinal)
+      )
+      SELECT count(*) INTO mismatches FROM entries
+      WHERE existing_identities->eid->>'runId' IS DISTINCT FROM observation.run_id
+        OR existing_identities->eid->>'kind' IS DISTINCT FROM ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
+        OR existing_identities->eid->>'digest' IS DISTINCT FROM CASE WHEN ctx IS NULL
           THEN encode(sha256(convert_to(body #>> '{}','UTF8')),'hex')
-          ELSE encode(sha256(convert_to(jsonb_build_array(body #>> '{}',batch_contexts->(ordinal-1)::int)::text,'UTF8')),'hex') END;
+          ELSE encode(sha256(convert_to(jsonb_build_array(body #>> '{}',ctx)::text,'UTF8')),'hex') END;
       IF mismatches > 0 THEN
         RAISE EXCEPTION 'Origin log identity changed its content or ingress is closed after terminal acceptance';
       END IF;
@@ -2796,8 +2805,9 @@ export async function attachRuntimeEventSearchTriggers(
         RETURNING last_seq INTO assigned_seq;
         -- Build ordinal lookup once. Generic plans estimate a run and unnest
         -- as tiny, then compare every inserted line against the entire ID list
-        -- in a nested loop. Fresh IDs came only from this transaction's inserts
-        -- for this scope/org/run, so the primary-key set is the complete target.
+        -- in a nested loop or a per-row ANY filter. Fresh IDs came only from
+        -- this transaction's inserts for this scope/org/run, so JSON key
+        -- membership preserves the complete target within the indexed run.
         SELECT jsonb_object_agg(fresh.event_id, fresh.ordinality)
           INTO fresh_positions
           FROM unnest(fresh_event_ids) WITH ORDINALITY AS fresh(event_id, ordinality);
@@ -2805,7 +2815,8 @@ export async function attachRuntimeEventSearchTriggers(
            SET log_seq = assigned_seq - line_count + (fresh_positions->>event.event_id)::bigint
          WHERE event.runtime_scope = ${quoteLiteral(scope)}
            AND event.org_id = run_org
-           AND event.event_id = ANY(fresh_event_ids);
+           AND event.run_id = observation.run_id
+           AND fresh_positions ? event.event_id;
       END IF;
       RETURN;
     END
@@ -3730,11 +3741,13 @@ export async function prepareRuntimeEventRetentionIndex(
     };
     let ready = (await inspect()).rows[0];
     if (ready) {
+      // Even IF NOT EXISTS acquires a table lock. A fully proved existing index
+      // needs no shared DDL; invalid or mismatched definitions still fail loudly.
       assertReady(ready);
     } else {
       await client.query(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${input.name}
-      ON runtime_observability.events (ingested_at, event_id)
-      WHERE ${input.predicate}`);
+        ON runtime_observability.events (ingested_at, event_id)
+        WHERE ${input.predicate}`);
       ready = (await inspect()).rows[0];
       if (!ready) {
         throw new Error(

package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts

@@ -798,10 +798,28 @@ export function classifyToolExecuteHttpFailure(input: {
     executionFenced,
     explicitRetryable,
   });
+  // A status GET may fail after a stateful provider operation was accepted.
+  // Provider pacing remains useful, but retrying the whole tool would repeat
+  // its POST. This explicit recovery proof is stronger than a rejected-call
+  // 429; ordinary pacing denials retain their established retry semantics.
+  const failureBody = parseJsonObject(input.bodyText);
+  const flatPublicDetails = failureBody?.details;
+  const acceptedOperationNeedsRecovery =
+    explicitRetryable === false &&
+    (error instanceof ToolExecutionError
+      ? error.origin === 'provider'
+      : failureBody?.failure_origin === 'provider') &&
+    ((error instanceof ToolExecutionError &&
+      error.publicDetails?.operationAccepted === true) ||
+      (flatPublicDetails !== null &&
+        typeof flatPublicDetails === 'object' &&
+        (flatPublicDetails as Record<string, unknown>).operationAccepted ===
+          true));
   const shouldRetry =
-    providerOwnedRateLimit ||
-    attestedProviderDeadline ||
-    (retryDecision.retryable && input.attempt < retryDecision.attemptCap);
+    !acceptedOperationNeedsRecovery &&
+    (providerOwnedRateLimit ||
+      attestedProviderDeadline ||
+      (retryDecision.retryable && input.attempt < retryDecision.attemptCap));
   // In-attempt retry safety and later-run repairability are different
   // decisions. A non-idempotent 5xx must not be repeated automatically inside
   // this execution attempt, but an explicit later `plays run` must be able to
@@ -862,6 +880,9 @@ export function classifyToolExecuteHttpFailure(input: {
                     : TOOL_EXECUTE_RETRY_DELAY_FALLBACK_MS;
   return {
     ...retryDecision,
+    ...(acceptedOperationNeedsRecovery
+      ? { retryable: false, reason: 'non_retryable_status' as const }
+      : {}),
     error,
     shouldRetry,
     isRateLimit: input.status === 429,

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

@@ -3,6 +3,7 @@ import {
   RUNTIME_RECEIPT_OUTPUT_MAX_BYTES,
 } from './output-size-limits';
 export type {
+  CallFreshnessMetadata,
   SerializedToolExecuteResult,
   ToolExecuteResult,
   ToolResultBilling,
@@ -710,7 +711,18 @@ function toV2RawToolOutputPathPreservingProviderData(path: string): string {
 }
 
 function candidateResultPaths(path: string): string[] {
+  // `result.data` is the public envelope. A following `data` belongs to the
+  // provider and must survive (e.g. QuickEnrich's result.data.data rows).
+  const normalized = String(path || '')
+    .trim()
+    .replace(/^\./, '');
+  const providerPath = normalized.startsWith('result.data.')
+    ? `toolResponse.raw.${normalized.slice('result.data.'.length)}`
+    : normalized === 'result.data'
+      ? 'toolResponse.raw'
+      : '';
   const candidates = [
+    providerPath,
     normalizeResultPath(path),
     toV2RawToolOutputPathPreservingProviderData(path),
   ];
@@ -802,9 +814,29 @@ function acceptedTargetValue(
   ) {
     return undefined;
   }
+  if (target === 'email') return emailTargetValue(value) ?? undefined;
   return isMeaningfulValue(value) ? value : undefined;
 }
 
+function emailTargetValue(value: unknown): string | null {
+  if (typeof value === 'string') {
+    const email = value.trim();
+    return /^[^\s@*]+@[^\s@*]+\.[^\s@*]+$/.test(email) ? email : null;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const email = emailTargetValue(entry);
+      if (email) return email;
+    }
+  } else if (isRecord(value)) {
+    for (const key of ['email', 'email_address', 'address', 'value']) {
+      const email = emailTargetValue(value[key]);
+      if (email) return email;
+    }
+  }
+  return null;
+}
+
 function getFirstMeaningfulValueAtPath(
   root: unknown,
   path: string,

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

@@ -12,12 +12,22 @@ import type { ToolExecutionErrorSchemaVersion } from './tool-execution-error';
 import type { PlayDataset, PlayDatasetInput, PlayDatasetRow } from './dataset';
 
 export const LEGACY_PLAY_AUTHORING_CONTRACT_EDITION = 1 as const;
-// New source uses ordinary list values. Historical artifacts keep their pinned
-// edition; deploy the edition-10 reader before promoting this writer.
+// Edition 11 readers retain every CSV source row. Promote this writer in the
+// follow-up PR after those readers are deployed everywhere.
 export const PLAY_AUTHORING_CONTRACT_EDITION = 10 as const;
+export const PLAY_AUTHORING_SLACK_INTERACTIVE_MESSAGE_STRICT_THRESHOLD =
+  10 as const;
+export const EXPLICIT_FRESHNESS_PLAY_AUTHORING_THRESHOLD = 11 as const;
+const EXPLICIT_FRESHNESS_STALE_AFTER_SECONDS_DESCRIPTION = [
+  'Edition 11 requires an explicit choice.',
+  '`0` starts a fresh logical call, though a matching operation receipt may recover that same operation after resume;',
+  '`null` allows indefinite result reuse;',
+  'a positive integer is the maximum result age in seconds.',
+  'Omitted values retain legacy behavior in older editions.',
+].join(' ');
 export const PLAY_AUTHORING_INPUT_SCHEMA_SNAPSHOT_EDITION = 3 as const;
 export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
-  1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
 ] as const;
 
 export type PlayAuthoringContractEdition =
@@ -96,6 +106,13 @@ const PLAY_AUTHORING_CONTRACT_CHANGELOG_DETAILS = [
     newWritesEnd: null,
     readerRemoval: null,
   },
+  {
+    changed:
+      'Requires explicit freshness and semantic identity for supported durable calls, and gives CSV datasets source-row identity so every input occurrence is processed even when key or rowIdentity: "key" is supplied. Edition 10 retains its list-getter behavior and editions 1–10 retain their admitted CSV identity and completed receipts; non-CSV datasets keep explicit key deduplication.',
+    compatibilityOwner: 'Plays Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
 ] as const;
 
 /** Authoring types and runtime projection must select the same getter contract. */
@@ -105,6 +122,12 @@ export function playToolListGetterMode(
   return edition >= 10 ? 'array' : 'dataset';
 }
 
+export function playCsvDatasetRowIdentity(
+  edition: PlayAuthoringContractEdition,
+): 'source_row' | 'key' {
+  return edition >= 11 ? 'source_row' : 'key';
+}
+
 export const PLAY_AUTHORING_CONTRACT_CHANGELOG =
   SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS.map((edition, index) => ({
     edition,
@@ -128,7 +151,7 @@ export const PLAY_AUTHORING_RUNTIME_CAPABILITIES = [
     capability: 'Web Crypto',
     surface: '`crypto.subtle`',
     contract:
-      'WebCrypto is available for standards-based signing, verification, encryption, and key import. Keep private material in `ctx.secrets`; `docs-examples/sdk-v2/github-app-jwt.play.ts` signs an RS256 GitHub App JWT and uses `staleAfterSeconds: 0` for its time-varying auth exchange.',
+      'WebCrypto is available for standards-based signing, verification, encryption, and key import. Keep private material in `ctx.secrets`. `docs-examples/sdk-v2/github-app-jwt.play.ts` is an edition-10 compatibility example; edition 11 allows transient fetches only for read-only methods, so do not copy its credential-returning POST into new source.',
   },
   {
     capability: 'Workspace secrets',
@@ -140,7 +163,7 @@ export const PLAY_AUTHORING_RUNTIME_CAPABILITIES = [
     capability: 'Freshness',
     surface: '`staleAfterSeconds` on durable calls',
     contract:
-      'This is call-receipt freshness: omitted/null reuses forever, zero always executes, and a positive integer is a TTL in seconds. It never changes dataset or request identity.',
+      'New source in edition 11 must choose freshness explicitly. Zero executes a new logical call, a positive integer is a maximum result age in seconds, and null allows indefinite reuse. A completed operation receipt separately recovers the same intended operation after resume.',
   },
 ] as const;
 
@@ -1027,7 +1050,7 @@ export type PlayAuthoringStepOptions<Row, Value = unknown> = {
   /** Legacy error-recompute flag accepted for older authored Plays. */
   readonly recomputeOnError?: boolean;
   /** Legacy cell staleness metadata accepted for older authored Plays. */
-  readonly staleAfterSeconds?: number;
+  readonly staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
 
 /** Explicitly mark a step program as a provider fallback waterfall. */
@@ -1091,7 +1114,7 @@ export type PlayAuthoringStepProgramStep<TContext> = {
   readonly name: string;
   readonly recompute?: boolean;
   readonly recomputeOnError?: boolean;
-  readonly staleAfterSeconds?: number;
+  readonly staleAfterSeconds?: DurableCallStaleAfterSeconds;
   readonly resolver:
     | PlayAuthoringStepResolver<Record<string, unknown>, unknown, TContext>
     | PlayAuthoringConditionalStepResolver<
@@ -1133,6 +1156,8 @@ export type PlayAuthoringDatasetDefinitionOptions<InputRow extends object> = {
 export type PlayAuthoringDatasetRunOptions<InputRow extends object> = {
   description?: string;
   key?: PlayAuthoringDatasetRowKey<InputRow>;
+  /** Edition 11 CSVs always use source-row identity; key-based deduplication remains for non-CSV inputs and earlier editions. */
+  rowIdentity?: 'source_row' | 'key';
   onRowError?: 'isolate' | 'fail';
   mode?: 'upsert' | 'net_new';
   /**
@@ -1147,6 +1172,7 @@ export type PlayAuthoringDatasetRunOptions<InputRow extends object> = {
 export const PLAY_AUTHORING_DATASET_RUN_OPTION_FIELDS = [
   'description',
   'key',
+  'rowIdentity',
   'onRowError',
   'mode',
   'undrawnColumns',
@@ -1343,8 +1369,10 @@ export type PlayAuthoringRuntimeStepOptions = {
 /**
  * Durable freshness for one `ctx.fetch` call. The key identifies the request;
  * `staleAfterSeconds` controls when that completed request may be reused across
- * Play runs. Omit it (or pass `null`) to reuse indefinitely, pass `0` to
- * execute on every new run, or pass a positive number of seconds for a TTL.
+ * Play runs. Edition 11 requires an explicit choice: `null` reuses indefinitely,
+ * `0` executes on every new run, and a positive whole number sets the maximum
+ * result age. Retained results are supported only for read methods (GET, HEAD,
+ * OPTIONS); mutating methods require `0`. Transient calls do not retain results.
  *
  * Use this for polling or periodically refreshing one external resource. It
  * does not change dataset row identity.
@@ -1352,7 +1380,7 @@ export type PlayAuthoringRuntimeStepOptions = {
  */
 export type PlayAuthoringFetchOptions = {
   staleAfterSeconds?: DurableCallStaleAfterSeconds;
-  /** Run through Deepline's guarded outbound path without retaining a response receipt or checkpoint. Use this for short-lived credential exchanges or other response data that should stay in the running Play only. */
+  /** Run through Deepline's guarded outbound path without retaining a response receipt or checkpoint. Edition 11 permits transient fetches only for GET, HEAD, and OPTIONS. */
   transient?: boolean;
 };
 
@@ -1430,6 +1458,8 @@ export class CtxFetchHttpError extends Error {
 }
 
 export type PlayAuthoringCustomerDbQueryOptions = {
+  id?: string;
+  staleAfterSeconds?: 0;
   maxRows?: number;
   timeoutMs?: number;
 };
@@ -1555,7 +1585,10 @@ export interface PlayAuthoringRuntimeContext<
     key: string,
     toolId: string,
     input: Record<string, unknown>,
-    options?: { description?: string },
+    options?: {
+      description?: string;
+      staleAfterSeconds?: DurableCallStaleAfterSeconds;
+    },
   ): Promise<
     TListGetter extends 'array'
       ? BasicToolExecuteResult<TOutput>
@@ -1586,7 +1619,7 @@ export interface PlayAuthoringRuntimeContext<
   ): Promise<T>;
 
   /**
-   * Execute a guarded HTTP request. By default, completed responses are durably reused; `staleAfterSeconds` governs only that completed call receipt, never dataset/request identity. Failed requests do not publish completed cache entries. A headers timeout leaves an upstream write's outcome unknown and does not establish whether its body was sent. The transport does not automatically retry that timed-out write, but a later invocation can execute it again. Mutating requests require provider-supported idempotency with the same key retained across retries and replay. Deadlines are platform-controlled; callers may cancel through `init.signal`. Pass `{ transient: true }` for short-lived credential exchanges or other response data that must not be retained in a receipt or checkpoint. Edition 5+ throws `CtxFetchHttpError` for non-2xx; catch it only when the Play intentionally recovers, otherwise let it fail the Play. Editions 1–4 retain their previous response projections.
+   * Execute a guarded HTTP request. Edition 11 requires an explicit freshness choice; only GET, HEAD, and OPTIONS can retain completed responses. Mutating methods must use `staleAfterSeconds: 0`; the choice governs only the completed call receipt, never dataset/request identity. Failed requests do not publish completed cache entries. A headers timeout leaves an upstream write's outcome unknown and does not establish whether its body was sent. The transport does not automatically retry that timed-out write, but a later invocation can execute it again. Mutating requests require provider-supported idempotency with the same key retained across retries and replay. Deadlines are platform-controlled; callers may cancel through `init.signal`. Pass `{ transient: true }` only on GET, HEAD, and OPTIONS when the response must not be retained in a receipt or checkpoint; edition 11 rejects transient writes. Edition 5+ throws `CtxFetchHttpError` for non-2xx; catch it only when the Play intentionally recovers, otherwise let it fail the Play. Editions 1–4 retain their previous response projections.
    *
    * @sdkReference runtime 170 ctx.fetch(key, url, init)
    */
@@ -2257,8 +2290,7 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     required: false,
     resolution: 'runtime-allowed',
     issueCode: 'play_authoring_durable_policy_invalid',
-    description:
-      '`0` always executes; `null`/omitted never expires; a positive integer is a TTL in seconds.',
+    description: EXPLICIT_FRESHNESS_STALE_AFTER_SECONDS_DESCRIPTION,
     errorMessage:
       'staleAfterSeconds must be null, 0 (always execute), or a positive whole number of seconds.',
   },
@@ -2517,6 +2549,23 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'ctx.dataset run key must be a non-empty field, field list, or key function.',
   },
+  'ctx.dataset.run.rowIdentity': {
+    schema: Type.Union([Type.Literal('source_row'), Type.Literal('key')]),
+    fixtures: {
+      valid: 'source_row',
+      invalid: 'dedupe',
+      absent: undefined,
+      unresolved: { expression: 'rowIdentity' },
+      edition1: 'key',
+    },
+    referenceType: "'source_row' | 'key'",
+    required: false,
+    resolution: 'static-when-present',
+    issueCode: 'play_authoring_dataset_option_invalid',
+    description:
+      'Edition 11 CSV inputs always use source-row occurrence identity, even with rowIdentity: key; key-based deduplication remains available for non-CSV inputs and editions 1–10.',
+    errorMessage: 'ctx.dataset run rowIdentity must be "source_row" or "key".',
+  },
   'ctx.dataset.run.onRowError': {
     schema: Type.Union([Type.Literal('isolate'), Type.Literal('fail')]),
     fixtures: {
@@ -2613,8 +2662,7 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     required: false,
     resolution: 'runtime-dynamic',
     issueCode: 'play_authoring_durable_policy_invalid',
-    description:
-      'Checkpoint freshness: null/omitted never expires, 0 always executes.',
+    description: EXPLICIT_FRESHNESS_STALE_AFTER_SECONDS_DESCRIPTION,
     errorMessage:
       'staleAfterSeconds must be null, 0 (always execute), or a positive whole number of seconds.',
   },
@@ -2648,8 +2696,7 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     required: false,
     resolution: 'runtime-dynamic',
     issueCode: 'play_authoring_durable_policy_invalid',
-    description:
-      'Fetch freshness: null/omitted never expires, 0 always executes.',
+    description: EXPLICIT_FRESHNESS_STALE_AFTER_SECONDS_DESCRIPTION,
     errorMessage:
       'staleAfterSeconds must be null, 0 (always execute), or a positive whole number of seconds.',
   },
@@ -2903,6 +2950,39 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'ctx.customerDb.query statement must be a non-empty SQL string. Deprecated SqlQuery objects cannot contain parameter values.',
   },
+  'ctx.customerDb.query.options.id': {
+    schema: Type.String({ pattern: '\\S' }),
+    fixtures: {
+      valid: 'customer-report-read',
+      invalid: '',
+      absent: undefined,
+      unresolved: { expression: 'operationId' },
+      edition1: 'query',
+    },
+    referenceType: 'string',
+    required: true,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_tool_request_invalid',
+    description: 'Stable operation identity for Customer DB query recovery.',
+    errorMessage:
+      'ctx.customerDb.query options.id must be a non-empty stable string.',
+  },
+  'ctx.customerDb.query.options.staleAfterSeconds': {
+    schema: Type.Literal(0),
+    fixtures: {
+      valid: 0,
+      invalid: 1,
+      absent: undefined,
+      unresolved: { expression: 'ttl' },
+      edition1: 0,
+    },
+    referenceType: 'number | null',
+    required: false,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_durable_policy_invalid',
+    description: 'Customer DB queries always execute with freshness 0.',
+    errorMessage: 'Customer DB queries must use staleAfterSeconds: 0.',
+  },
   'ctx.customerDb.query.options.maxRows': {
     schema: Type.Integer({ minimum: 1 }),
     fixtures: {
@@ -3304,18 +3384,18 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   'export type DatasetColumnRunInput<Row, Value> = { readonly row: Row; readonly ctx: DeeplinePlayRuntimeContext; readonly index: number; readonly previousCell?: PreviousCell<Value> };',
   'export type DatasetColumnDefinition<Row, Value> = { readonly run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>; readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean> };',
   "export type ConditionalStepResolver<Row, Value, Else = null> = { readonly kind: 'conditional'; readonly when: (row: Row, index: number) => boolean | Promise<boolean>; readonly run: StepResolver<Row, Value>; readonly elseValue: Else; else<ValueElse>(value: ValueElse): ConditionalStepResolver<Row, Value, ValueElse>; };",
-  'export type StepOptions<Row, Value = unknown> = { readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>; readonly recompute?: boolean; readonly recomputeOnError?: boolean; readonly staleAfterSeconds?: number };',
+  'export type StepOptions<Row, Value = unknown> = { readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>; readonly recompute?: boolean; readonly recomputeOnError?: boolean; readonly staleAfterSeconds?: DurableCallStaleAfterSeconds };',
   'export type StepProgramOptions = { readonly continueOnProviderUnavailable?: boolean };',
   "export type StepProgram<Input, Output, Return = Output> = { readonly kind: 'steps'; readonly steps: readonly PlayStepProgramStep[]; readonly returnResolver?: StepResolver<Output, Return>; readonly continueOnProviderUnavailable?: boolean; readonly __inputType?: (input: Input) => void; step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | ConditionalStepResolver<Output, Value> | StepProgramResolver<Output, Value>): StepProgram<Input, Output & Record<Name, Value>, Return>; step<Name extends string, Value>(name: Name, resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>, options: StepOptions<Output, Value>): StepProgram<Input, Output & Record<Name, Value | null>, Return>; return<Value>(resolver: StepResolver<Output, Value>): StepProgram<Input, Output, Value>; };",
   "export type StepProgramResolver<Input, Return> = { readonly kind: 'steps'; readonly steps: readonly PlayStepProgramStep[]; readonly returnResolver?: StepResolver<never, Return>; readonly __inputType?: (input: Input) => void };",
   "export type RunnableStepProgram<Input, Return> = Pick<StepProgram<Input, never, Return>, 'kind' | 'steps' | 'returnResolver' | '__inputType'>;",
   "export type RunnableColumnStepProgram<Return> = Pick<StepProgramResolver<unknown, Return>, 'kind' | 'steps' | 'returnResolver'>;",
-  'export type PlayStepProgramStep = { readonly name: string; readonly recompute?: boolean; readonly recomputeOnError?: boolean; readonly staleAfterSeconds?: number; readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown> };',
+  'export type PlayStepProgramStep = { readonly name: string; readonly recompute?: boolean; readonly recomputeOnError?: boolean; readonly staleAfterSeconds?: DurableCallStaleAfterSeconds; readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown> };',
   'export type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | RunnableColumnStepProgram<Value>;',
   'export type StepProgramOutput<TProgram> = TProgram extends StepProgram<unknown, infer Output, unknown> ? Output : never;',
   'export type DatasetRowKey<InputRow extends object> = (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);',
   'export type DatasetDefinitionOptions<InputRow extends object> = { key?: DatasetRowKey<InputRow> };',
-  `export type DatasetRunOptions<InputRow extends object> = { description?: ${cloudReferenceType('ctx.dataset.run.description')}; key?: DatasetRowKey<InputRow>; onRowError?: ${cloudReferenceType('ctx.dataset.run.onRowError')}; mode?: ${cloudReferenceType('ctx.dataset.run.mode')}; undrawnColumns?: ${cloudReferenceType('ctx.dataset.run.undrawnColumns')} };`,
+  `export type DatasetRunOptions<InputRow extends object> = { description?: ${cloudReferenceType('ctx.dataset.run.description')}; key?: DatasetRowKey<InputRow>; rowIdentity?: ${cloudReferenceType('ctx.dataset.run.rowIdentity')}; onRowError?: ${cloudReferenceType('ctx.dataset.run.onRowError')}; mode?: ${cloudReferenceType('ctx.dataset.run.mode')}; undrawnColumns?: ${cloudReferenceType('ctx.dataset.run.undrawnColumns')} };`,
   'export type DatasetBuilder<InputRow extends object, OutputRow extends object> = {',
   '  withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;',
   '  withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & { readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean> }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;',
@@ -3335,8 +3415,8 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '  readonly run: { readonly id: string };',
   `  runSteps<TInput extends Record<string, unknown>, TOutput>(program: RunnableStepProgram<TInput, TOutput>, input: TInput, options?: { description?: ${cloudReferenceType('ctx.runSteps.options.description')} }): Promise<TOutput>;`,
   '  tools: { execute<K extends string>(request: ToolExecutionRequest<K>): Promise<ToolExecutionOutput<K>> };',
-  `  customerDb: { query<TRow extends Record<string, unknown> = Record<string, unknown>>(statement: SqlQuery, options?: { maxRows?: ${cloudReferenceType('ctx.customerDb.query.options.maxRows')}; timeoutMs?: ${cloudReferenceType('ctx.customerDb.query.options.timeoutMs')} }): Promise<TRow[]> };`,
-  `  tool<K extends string>(key: ${cloudReferenceType('ctx.tool.key')}, toolId: K, input: ${cloudReferenceType('ctx.tool.input')}, options?: { description?: ${cloudReferenceType('ctx.tool.options.description')} }): Promise<ToolExecutionOutput<K>>;`,
+  `  customerDb: { query<TRow extends Record<string, unknown> = Record<string, unknown>>(statement: SqlQuery, options?: { id?: ${cloudReferenceType('ctx.customerDb.query.options.id')}; staleAfterSeconds?: ${cloudReferenceType('ctx.customerDb.query.options.staleAfterSeconds')}; maxRows?: ${cloudReferenceType('ctx.customerDb.query.options.maxRows')}; timeoutMs?: ${cloudReferenceType('ctx.customerDb.query.options.timeoutMs')} }): Promise<TRow[]> };`,
+  `  tool<K extends string>(key: ${cloudReferenceType('ctx.tool.key')}, toolId: K, input: ${cloudReferenceType('ctx.tool.input')}, options?: { description?: ${cloudReferenceType('ctx.tool.options.description')}; staleAfterSeconds?: DurableCallStaleAfterSeconds }): Promise<ToolExecutionOutput<K>>;`,
   '  step<T>(id: string, run: () => T | Promise<T>, options?: RuntimeStepOptions): Promise<T>;',
   "  fetch(key: string, url: string | URL, init?: RequestInit & { headers?: HeadersInit & { 'Idempotency-Key'?: string; 'X-Idempotency-Key'?: string }; auth?: SecretAuthInput }, options?: FetchOptions): Promise<PlayFetchResponse>;",
   '  secrets: { get(name: string): SecretPromise; bearer(secret: string | SecretPromise | SecretHandle): SecretAuth; header(header: string, secret: string | SecretPromise | SecretHandle): SecretAuth };',

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

@@ -270,7 +270,7 @@ class PlayCoreStepProgram<Input, Output, ReturnValue> implements StepProgram<
           ...(options?.recomputeOnError === true
             ? { recomputeOnError: true }
             : {}),
-          ...(typeof options?.staleAfterSeconds === 'number'
+          ...(options?.staleAfterSeconds !== undefined
             ? { staleAfterSeconds: options.staleAfterSeconds }
             : {}),
           resolver: stepResolver as PlayStepProgramStep['resolver'],