deepline 0.3.408 → 0.3.410

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

@@ -11,10 +11,12 @@ import type {
 import type { ToolExecutionErrorSchemaVersion } from './tool-execution-error';
 import type { PlayDataset, PlayDatasetInput, PlayDatasetRow } from './dataset';
 
+export { playToolListGetterMode } from './tool-list-getter-mode';
+export { CtxFetchAmbiguousWriteError } from './ambiguous-write-error';
+
 export const LEGACY_PLAY_AUTHORING_CONTRACT_EDITION = 1 as const;
-// 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;
+// Edition 11 readers are deployed before this writer promotes new artifacts.
+export const PLAY_AUTHORING_CONTRACT_EDITION = 11 as const;
 export const PLAY_AUTHORING_SLACK_INTERACTIVE_MESSAGE_STRICT_THRESHOLD =
   10 as const;
 export const EXPLICIT_FRESHNESS_PLAY_AUTHORING_THRESHOLD = 11 as const;
@@ -108,20 +110,13 @@ const PLAY_AUTHORING_CONTRACT_CHANGELOG_DETAILS = [
   },
   {
     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.',
+      'Requires explicit freshness and semantic identity for supported durable calls, and gives edition 11 CSV datasets source-row occurrence identity so every input occurrence is processed even when key or rowIdentity: "key" is supplied. Edition 10 retains its list-getter behavior; 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. */
-export function playToolListGetterMode(
-  edition: PlayAuthoringContractEdition = PLAY_AUTHORING_CONTRACT_EDITION,
-): 'dataset' | 'array' {
-  return edition >= 10 ? 'array' : 'dataset';
-}
-
 export function playCsvDatasetRowIdentity(
   edition: PlayAuthoringContractEdition,
 ): 'source_row' | 'key' {
@@ -839,6 +834,8 @@ export type PlayAuthoringBindings<TInput = Record<string, unknown>> = {
   displayName?: string;
   description?: string;
   compatibility?: {
+    /** Opt new source into the current explicit-freshness authoring edition. */
+    authoringContract?: 'explicit-freshness';
     toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
     /**
      * Bump only when a Play's response transformation changes serialized tool
@@ -1081,15 +1078,19 @@ export type PlayAuthoringStepProgram<
     TContext,
     Return
   >;
-  step<Name extends string, Value>(
+  step<
+    Name extends string,
+    Value,
+    Options extends PlayAuthoringStepOptions<Output, Value>,
+  >(
     name: Name,
     resolver:
       | PlayAuthoringStepResolver<Output, Value, TContext>
       | PlayAuthoringStepProgramResolver<Output, Value, TContext>,
-    options: PlayAuthoringStepOptions<Output, Value>,
+    options: Options,
   ): PlayAuthoringStepProgram<
     Input,
-    Output & Record<Name, Value | null>,
+    Output & Record<Name, 'runIf' extends keyof Options ? Value | null : Value>,
     TContext,
     Return
   >;
@@ -1156,7 +1157,7 @@ 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. */
+  /** Edition 11 CSVs always use source-row occurrence identity; key-based deduplication remains available for non-CSV inputs and editions 1–10. */
   rowIdentity?: 'source_row' | 'key';
   onRowError?: 'isolate' | 'fail';
   mode?: 'upsert' | 'net_new';
@@ -1390,6 +1391,8 @@ export type PlayAuthoringFetchOptions = {
  * @sdkReference runtime 175 PlayFetchResponse
  */
 export type PlayAuthoringFetchResponse = {
+  /** Freshness and same-run recovery metadata for edition 11 calls. */
+  freshness?: import('./tool-result-types').CallFreshnessMetadata;
   /** True when the response status is in the 2xx range. */
   ok: boolean;
   /** HTTP status code as returned by the upstream server. */
@@ -1413,54 +1416,7 @@ export type PlayAuthoringFetchResponse = {
   json: unknown | null;
 };
 
-/**
- * Edition 5+ `ctx.fetch` error for a non-2xx response. Its full readable body is secret-redacted; editions 1–4 retain `PlayFetchResponse { ok: false }`.
- *
- * @sdkReference runtime 178 CtxFetchHttpError
- */
-export class CtxFetchHttpError extends Error {
-  /**
-   * Play source and the runtime are separately bundled. Recognize the stable
-   * public error code so `instanceof` works across that boundary as well.
-   */
-  static [Symbol.hasInstance](value: unknown): boolean {
-    return (
-      value !== null &&
-      typeof value === 'object' &&
-      (value as { code?: unknown }).code === 'CTX_FETCH_HTTP_ERROR'
-    );
-  }
-
-  /** Stable machine-readable HTTP-failure code. */
-  readonly code = 'CTX_FETCH_HTTP_ERROR' as const;
-  /** Upstream HTTP status. */
-  readonly status: number;
-  /** Upstream HTTP status text. */
-  readonly statusText: string;
-  /** Final response URL after redirects. */
-  readonly url: string;
-  /** Secret-redacted response headers. */
-  readonly headers: Record<string, string>;
-  /** Complete secret-redacted response body. */
-  readonly bodyText: string;
-  /** Eagerly parsed secret-redacted JSON, or null. */
-  readonly json: unknown | null;
-
-  /** Build the error from the durable response record. */
-  constructor(readonly response: PlayAuthoringFetchResponse) {
-    const body = response.bodyText || 'empty response body';
-    super(
-      `ctx.fetch(${response.url}) returned HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}: ${body}`,
-    );
-    this.name = 'CtxFetchHttpError';
-    this.status = response.status;
-    this.statusText = response.statusText;
-    this.url = response.url;
-    this.headers = response.headers;
-    this.bodyText = response.bodyText;
-    this.json = response.json;
-  }
-}
+export { CtxFetchHttpError } from './fetch-http-error';
 
 export type PlayAuthoringCustomerDbQueryOptions = {
   id?: string;
@@ -1471,6 +1427,7 @@ export type PlayAuthoringCustomerDbQueryOptions = {
 
 export type PlayAuthoringRunStepsOptions = {
   description?: string;
+  staleAfterSeconds?: DurableCallStaleAfterSeconds;
 };
 
 /**
@@ -1781,6 +1738,24 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'compatibility.toolErrorSchemaVersion must be the static literal 0 or 1.',
   },
+  'compatibility.authoringContract': {
+    schema: Type.Literal('explicit-freshness'),
+    fixtures: {
+      valid: 'explicit-freshness',
+      invalid: 'legacy',
+      absent: undefined,
+      unresolved: { expression: 'authoringContract' },
+      edition1: undefined,
+    },
+    referenceType: "'explicit-freshness'",
+    required: false,
+    resolution: 'static-required',
+    issueCode: 'play_authoring_binding_invalid',
+    description:
+      'Opts new source into the current explicit-freshness authoring edition; an already-pinned edition-10 artifact retains its admitted behavior.',
+    errorMessage:
+      'compatibility.authoringContract must be the static literal "explicit-freshness".',
+  },
   'compatibility.toolResponseReceiptRevision': {
     schema: Type.String({
       minLength: 1,
@@ -2568,7 +2543,7 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     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.',
+      'Edition 11 requires explicit freshness and semantic identity for supported durable calls. CSV inputs always use source-row occurrence identity, even with rowIdentity: "key"; key-based dedup 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': {
@@ -3102,6 +3077,23 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     description: 'Non-empty purpose for a reusable step program.',
     errorMessage: 'ctx.runSteps options.description must be non-empty.',
   },
+  'ctx.runSteps.options.staleAfterSeconds': {
+    schema: Type.Union([Type.Null(), Type.Integer({ minimum: 0 })]),
+    fixtures: {
+      valid: 0,
+      invalid: -1,
+      absent: undefined,
+      unresolved: { expression: 'ttl' },
+      edition1: null,
+    },
+    referenceType: 'number | null',
+    required: false,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_durable_policy_invalid',
+    description: EXPLICIT_FRESHNESS_STALE_AFTER_SECONDS_DESCRIPTION,
+    errorMessage:
+      'staleAfterSeconds must be null, 0 (always execute), or a positive whole number of seconds.',
+  },
   'ctx.sleep.ms': {
     schema: Type.Integer({ minimum: 0 }),
     fixtures: {
@@ -3352,7 +3344,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   'export type PlayBindings<TInput = Record<string, unknown>> = {',
   `  displayName?: ${cloudReferenceType('displayName')};`,
   `  description?: ${cloudReferenceType('description')};`,
-  `  compatibility?: { toolErrorSchemaVersion?: ${cloudReferenceType('compatibility.toolErrorSchemaVersion')}; toolResponseReceiptRevision?: ${cloudReferenceType('compatibility.toolResponseReceiptRevision')} };`,
+  `  compatibility?: { authoringContract?: ${cloudReferenceType('compatibility.authoringContract')}; 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')} };`,
@@ -3383,7 +3375,10 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   'export type AsyncPlayRunRef = Readonly<{ runId: PlayRunId }>;',
   `export type RuntimeStepOptions = { semanticKey?: ${cloudReferenceType('ctx.step.semanticKey')}; staleAfterSeconds?: ${cloudReferenceType('ctx.step.staleAfterSeconds')} };`,
   `export type FetchOptions = { staleAfterSeconds?: ${cloudReferenceType('ctx.fetch.staleAfterSeconds')}; transient?: boolean };`,
-  'export type PlayFetchResponse = { ok: boolean; status: number; statusText: string; url: string; headers: Record<string, string>; bodyText: string; json: unknown | null };',
+  "export type CallFreshnessMetadata = { requestedStaleAfterSeconds: number | null; effectiveStaleAfterSeconds: number | null; source: 'executed' | 'operation_recovery' | 'reusable_result' | 'live_observation'; resultAgeMs: number; completedAt: number; operationReceiptKey?: string; unavailableReason?: string };",
+  "export type ToolResultExecutionMetadata = { idempotent: true; cached: boolean; source: 'live' | 'checkpoint' | 'cache' | 'in_flight' | 'source_run'; cacheKey?: string; receiptRole?: 'owner' | 'follower'; receiptKey?: string; resultReceiptKey?: string; attachedToReceiptKey?: string; freshness?: CallFreshnessMetadata; completedAt?: number };",
+  'export type PlayFetchResponse = { freshness?: CallFreshnessMetadata; ok: boolean; status: number; statusText: string; url: string; headers: Record<string, string>; bodyText: string; json: unknown | null };',
+  "export declare class CtxFetchAmbiguousWriteError extends Error { readonly code: 'CTX_FETCH_WRITE_OUTCOME_UNKNOWN'; readonly outcome: 'unknown'; readonly method: string; readonly origin: string; }",
   "export declare class CtxFetchHttpError extends Error { readonly code: 'CTX_FETCH_HTTP_ERROR'; readonly response: PlayFetchResponse; readonly status: number; readonly statusText: string; readonly url: string; readonly headers: Record<string, string>; readonly bodyText: string; readonly json: unknown | null; }",
   'export type StepResolver<Row, Value> = (row: Row, ctx: DeeplinePlayRuntimeContext, index: number, previousCell?: PreviousCell<Value>) => Value | Promise<Value>;',
   'export type DatasetColumnRunInput<Row, Value> = { readonly row: Row; readonly ctx: DeeplinePlayRuntimeContext; readonly index: number; readonly previousCell?: PreviousCell<Value> };',
@@ -3391,7 +3386,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "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?: 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 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, Options extends StepOptions<Output, Value>>(name: Name, resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>, options: Options): StepProgram<Input, Output & Record<Name, 'runIf' extends keyof Options ? Value | null : Value>, 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'>;",
@@ -3419,7 +3414,7 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '  dataset<TSource extends PlayDatasetInput<object>>(key: string, items: TSource): DatasetBuilder<PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object>;',
   '  map<TSource extends PlayDatasetInput<object>>(key: string, items: TSource, options?: DatasetDefinitionOptions<PlayDatasetRow<TSource> & object>): never;',
   '  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>;`,
+  `  runSteps<TInput extends Record<string, unknown>, TOutput>(program: RunnableStepProgram<TInput, TOutput>, input: TInput, options?: { description?: ${cloudReferenceType('ctx.runSteps.options.description')}; staleAfterSeconds?: ${cloudReferenceType('ctx.runSteps.options.staleAfterSeconds')} }): 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?: { 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>>;`,

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

@@ -30,7 +30,10 @@ import type {
   PlayPackageImport,
   PlayRuntimeFeature,
 } from '../artifact-types';
-import { buildPlayContractCompatibility } from '../contracts';
+import {
+  buildPlayContractCompatibility,
+  normalizePlayContractCompatibility,
+} from '../contracts';
 import { parsePlayDocflowFile, type PlayDocflowBinding } from '../docflow';
 import {
   TypeScriptParser,
@@ -57,12 +60,16 @@ import type { ToolExecutionErrorSchemaVersion } from '../tool-execution-error';
 import type { PlaySandboxRuntimeDeclaration } from '../sandbox-runtime-limits';
 import { validatePlaySourceFilesHaveNoInlineSecrets } from '../secret-guardrails';
 import { MAX_PLAY_BUNDLE_BYTES } from './limits';
-import { PLAY_AUTHORING_CONTRACT_EDITION } from '../authoring-contract';
+import {
+  extractPlaySourceAuthoringEdition,
+  resolvePlaySourceAuthoringContractEdition,
+  type PlaySourceAuthoringEdition,
+} from '../source-authoring-edition';
 
 // Local bundle caches may be discarded when compiler-only analysis changes;
 // this descriptive namespace is not a runtime wire or schema version.
 export const PLAY_BUNDLE_CACHE_NAMESPACE =
-  'deepline-play-artifacts-docflow-jsdoc';
+  'deepline-play-artifacts-docflow-jsdoc-pure-contracts';
 const PLAY_ARTIFACT_CACHE_DIR = join(tmpdir(), PLAY_BUNDLE_CACHE_NAMESPACE);
 const PLAY_PROXY_NAMESPACE = 'deepline-play-runtime-ref';
 const SOURCE_EXTENSIONS = [
@@ -209,6 +216,8 @@ type SourceGraphAnalysis = {
   sandboxRuntimeDeclaration: PlaySandboxRuntimeDeclaration | null;
   toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion | null;
   toolResponseReceiptRevision: string | null;
+  sourceAuthoringEdition: PlaySourceAuthoringEdition;
+  sourceHasLocalPlayExport: boolean;
   importedPlayDependencies: ImportedPlayDependency[];
 };
 
@@ -997,29 +1006,46 @@ function staticNumberFromExpression(
   );
 }
 
-function toolErrorSchemaVersionFromOptions(
+function compatibilityFromOptions(
   node: AstNode | null | undefined,
   context: PlayMetadataExtractionContext,
-): ToolExecutionErrorSchemaVersion | null | undefined {
-  const directCompatibility = resolveStaticProperty(
-    node,
-    'compatibility',
-    context,
-  );
-  if (directCompatibility.kind === 'unknown') return null;
-
+): StaticPropertyResolution {
+  const direct = resolveStaticProperty(node, 'compatibility', context);
+  if (direct.kind !== 'found') {
+    if (direct.kind === 'unknown') return direct;
+  } else {
+    let value: AstNode | null = unwrapStaticExpression(direct.value);
+    const seen = new Set<string>();
+    while (value?.type === 'Identifier') {
+      const name = getIdentifierName(value)!;
+      if (name === 'undefined' && !context.declarations.has(name)) {
+        value = { type: 'Literal', value: undefined };
+        break;
+      }
+      if (seen.has(name)) return { kind: 'unknown' };
+      seen.add(name);
+      value = unwrapStaticExpression(context.declarations.get(name));
+    }
+    const nullish = value?.type === 'Literal' && value.value == null;
+    const voidLiteral =
+      value?.type === 'UnaryExpression' &&
+      value.operator === 'void' &&
+      isAstNode(value.argument) &&
+      value.argument.type === 'Literal';
+    if (!nullish && !voidLiteral) return direct;
+  }
   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;
+  return bindings.kind === 'found'
+    ? resolveStaticProperty(bindings.value, 'compatibility', context)
+    : bindings;
+}
 
-  const compatibility =
-    directCompatibility.kind === 'found'
-      ? directCompatibility
-      : bindingCompatibility;
+function toolErrorSchemaVersionFromOptions(
+  node: AstNode | null | undefined,
+  context: PlayMetadataExtractionContext,
+): ToolExecutionErrorSchemaVersion | null | undefined {
+  const compatibility = compatibilityFromOptions(node, context);
+  if (compatibility.kind === 'unknown') return null;
   if (compatibility.kind === 'absent') return undefined;
   const schema = resolveStaticProperty(
     compatibility.value,
@@ -1037,25 +1063,8 @@ 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;
+  const compatibility = compatibilityFromOptions(node, context);
+  if (compatibility.kind === 'unknown') return null;
   if (compatibility.kind === 'absent') return undefined;
   const revision = resolveStaticProperty(
     compatibility.value,
@@ -2234,21 +2243,43 @@ async function analyzeSourceGraph(
         .sort((left, right) => left.filePath.localeCompare(right.filePath)),
     }),
   );
+  const sourceAst = parsePlaySourceAst(sourceCode);
+  if (!sourceAst)
+    throw new Error(
+      'Play source syntax must be valid before selecting its authoring edition.',
+    );
+  const selection = extractPlaySourceAuthoringEdition(
+    sourceAst,
+    exportName === 'default' ? null : exportName,
+  );
   const metadata =
-    extractDefinedPlayMetadata(sourceCode, exportName) ??
+    (selection.marker.kind === 'value' && selection.definition
+      ? playMetadataFromDefinePlayCall(
+          selection.definition,
+          buildPlayMetadataContext(sourceAst),
+        )
+      : extractDefinedPlayMetadata(sourceCode, exportName)) ??
     (exportName === 'default'
       ? extractDefinedPlayMetadata(sourceCode, null)
       : null);
-  if (metadata?.toolErrorSchemaVersionUnknown) {
-    throw new Error(
-      '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 compatibilityDiagnostic = metadata?.toolErrorSchemaVersionUnknown
+    ? 'definePlay compatibility.toolErrorSchemaVersion must be the static literal 0 or 1.'
+    : metadata?.toolResponseReceiptRevisionUnknown
+      ? 'definePlay compatibility.toolResponseReceiptRevision must be a static non-empty string.'
+      : null;
+  try {
+    resolvePlaySourceAuthoringContractEdition(selection.marker);
+  } catch (error) {
+    // Unresolved compatibility may hide both an opt-in and a historical pin.
+    // Retain both actionable diagnostics before any cache read or bundle.
+    if (compatibilityDiagnostic && selection.marker.kind === 'unknown') {
+      throw new Error(
+        `${compatibilityDiagnostic}\n${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    throw error;
   }
+  if (compatibilityDiagnostic) throw new Error(compatibilityDiagnostic);
   const playName = metadata?.name ?? null;
   const playDescription = metadata?.description ?? null;
   const sandboxRuntimeDeclaration = metadata?.sandboxRuntimeDeclaration ?? null;
@@ -2274,6 +2305,8 @@ async function analyzeSourceGraph(
     sandboxRuntimeDeclaration,
     toolErrorSchemaVersion: metadata?.toolErrorSchemaVersion ?? null,
     toolResponseReceiptRevision: metadata?.toolResponseReceiptRevision ?? null,
+    sourceAuthoringEdition: selection.marker,
+    sourceHasLocalPlayExport: selection.localExport,
     importedPlayDependencies: [...importedPlayDependencies.values()].sort(
       (left, right) => left.filePath.localeCompare(right.filePath),
     ),
@@ -2383,6 +2416,10 @@ export type BundlePlayFileOptions = {
   /** Must be `cjs_node20`; retained as an explicit compile-contract assertion. */
   target?: PlayArtifactKind;
   exportName?: string;
+  /** Retain an existing artifact's full contract when changing only source declarations. */
+  compatibility?: PlayArtifactCompatibility;
+  /** Disable local artifact cache writes for inspection-only bundling. */
+  cache?: boolean;
 };
 
 export type BundlePlayFileCoreOptions = BundlePlayFileOptions & {
@@ -2477,13 +2514,32 @@ export async function bundlePlayFile(
   adapter.warnAboutNonDevelopmentBundling?.(absolutePath);
 
   try {
+    const preservedCompatibility =
+      options.compatibility === undefined
+        ? undefined
+        : {
+            ...options.compatibility,
+            authoringContractEdition: normalizePlayContractCompatibility(
+              options.compatibility,
+            ).authoringContractEdition,
+          };
     const analysis = await analyzeSourceGraph(
       absolutePath,
       adapter,
       exportName,
     );
+    const edition = resolvePlaySourceAuthoringContractEdition(
+      analysis.sourceAuthoringEdition,
+      preservedCompatibility?.authoringContractEdition,
+    );
+    const markedSource = analysis.sourceAuthoringEdition.kind === 'value';
+    if (markedSource && !analysis.sourceHasLocalPlayExport) {
+      throw new Error(
+        'Edition 10 source must select a local ESM definePlay export.',
+      );
+    }
     analysis.graphHash = sha256(
-      `${analysis.graphHash}\nentry-export:${exportName}\nauthoring-contract-edition:${PLAY_AUTHORING_CONTRACT_EDITION}`,
+      `${analysis.graphHash}\nentry-export:${exportName}\nauthoring-contract-edition:${edition}${edition >= 10 ? '\nimported-proxy-options:description' : ''}${preservedCompatibility === undefined ? '\ndataset-row-input:current_run' : `\npreserved-compatibility:${JSON.stringify(preservedCompatibility)}`}`,
     );
     const sourceFiles = Object.fromEntries(
       Object.entries(analysis.sourceFiles).map(([sourcePath, sourceCode]) => [
@@ -2555,15 +2611,20 @@ export async function bundlePlayFile(
         success: true,
         artifact: {
           ...cachedArtifact,
+          ...(markedSource ? { exportName } : {}),
           entryFile,
           sourceHash: analysis.sourceHash,
           importPolicy,
-          compatibility: buildPlayContractCompatibility({
-            toolErrorSchemaVersion:
-              analysis.toolErrorSchemaVersion ?? undefined,
-            toolResponseReceiptRevision:
-              analysis.toolResponseReceiptRevision ?? undefined,
-          }),
+          compatibility:
+            preservedCompatibility ??
+            buildPlayContractCompatibility({
+              authoringContractEdition: edition,
+              datasetRowInput: 'current_run',
+              toolErrorSchemaVersion:
+                analysis.toolErrorSchemaVersion ?? undefined,
+              toolResponseReceiptRevision:
+                analysis.toolResponseReceiptRevision ?? undefined,
+            }),
           cacheHit: true,
         },
         sourceCode: analysis.sourceCode,
@@ -2620,6 +2681,7 @@ export async function bundlePlayFile(
     }
 
     const artifact: PlayBundleArtifact = {
+      ...(markedSource ? { exportName } : {}),
       codeFormat: 'cjs_module',
       artifactKind: target,
       entryFile,
@@ -2631,11 +2693,15 @@ export async function bundlePlayFile(
       bundledCode: executableCode,
       sourceMap: normalizedSourceMap,
       importPolicy,
-      compatibility: buildPlayContractCompatibility({
-        toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? undefined,
-        toolResponseReceiptRevision:
-          analysis.toolResponseReceiptRevision ?? undefined,
-      }),
+      compatibility:
+        preservedCompatibility ??
+        buildPlayContractCompatibility({
+          authoringContractEdition: edition,
+          datasetRowInput: 'current_run',
+          toolErrorSchemaVersion: analysis.toolErrorSchemaVersion ?? undefined,
+          toolResponseReceiptRevision:
+            analysis.toolResponseReceiptRevision ?? undefined,
+        }),
       generatedAt: Date.now(),
       cacheHit: false,
     };

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

@@ -49,6 +49,8 @@ export type PlayContractCompatibilitySnapshot = {
   toolResponseReceiptRevision?: string;
   /** Missing preserves Slack HITL's historical parked timeout behavior. */
   slackHitlTimeoutOutcome?: 'error';
+  /** Missing preserves historical dataset output hydration into resolver rows. */
+  datasetRowInput?: 'current_run';
 };
 
 export type NormalizedPlayContractCompatibilitySnapshot =
@@ -93,6 +95,14 @@ export function normalizePlayContractCompatibility(
   }
   const requestedToolErrorSchemaVersion =
     compatibility.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
+  if (
+    compatibility.datasetRowInput !== undefined &&
+    compatibility.datasetRowInput !== 'current_run'
+  ) {
+    throw new InvalidPlayContractCompatibilityError(
+      `Unsupported dataset row input policy ${String(compatibility.datasetRowInput)}.`,
+    );
+  }
   if (
     !SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS.includes(
       requestedToolErrorSchemaVersion,
@@ -137,9 +147,13 @@ export function buildPlayContractCompatibility(input?: {
   authoringContractEdition?: PlayAuthoringContractEdition;
   toolResponseContract?: ToolResponseContract;
   toolResponseReceiptRevision?: string;
+  datasetRowInput?: 'current_run';
 }): PlayContractCompatibilitySnapshot {
   return {
     artifactVersion: PLAY_ARTIFACT_VERSION,
+    ...(input?.datasetRowInput
+      ? { datasetRowInput: input.datasetRowInput }
+      : {}),
     runtimeBackend: input?.runtimeBackend ?? null,
     toolErrorSchemaVersion:
       input?.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION,