deepline 0.3.88 → 0.3.89

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

@@ -7,10 +7,10 @@ import type { ToolExecutionErrorSchemaVersion } from './tool-execution-error';
 import type { PlayDataset, PlayDatasetInput, PlayDatasetRow } from './dataset';
 
 export const LEGACY_PLAY_AUTHORING_CONTRACT_EDITION = 1 as const;
-export const PLAY_AUTHORING_CONTRACT_EDITION = 6 as const;
+export const PLAY_AUTHORING_CONTRACT_EDITION = 7 as const;
 export const PLAY_AUTHORING_INPUT_SCHEMA_SNAPSHOT_EDITION = 3 as const;
 export const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS = [
-  1, 2, 3, 4, 5, 6,
+  1, 2, 3, 4, 5, 6, 7,
 ] as const;
 
 export type PlayAuthoringContractEdition =
@@ -67,6 +67,14 @@ export const PLAY_AUTHORING_CONTRACT_CHANGELOG = [
     newWritesEnd: null,
     readerRemoval: null,
   },
+  {
+    edition: 7,
+    changed:
+      'Slack HITL calls that omit timeout wait one week. Editions 1–6 retain the historical 24-hour default.',
+    compatibilityOwner: 'Plays Runtime',
+    newWritesEnd: null,
+    readerRemoval: null,
+  },
 ] as const;
 
 /**
@@ -276,6 +284,308 @@ export function normalizeAdmittedSqlListenerWhere(
   }
   return normalized;
 }
+export type PlaySqlListenerValidationIssue = {
+  severity: 'error' | 'warning';
+  code: string;
+  path: string;
+  message: string;
+  expected?: unknown;
+  received?: unknown;
+  suggestion?: string;
+  entity_type?:
+    | 'monitor'
+    | 'action'
+    | 'trigger'
+    | 'bundle'
+    | 'play'
+    | 'listener'
+    | 'table'
+    | 'tool'
+    | 'workflow';
+  entity_key?: string;
+  docs_ref?: string;
+};
+
+function sqlListenerIssue(
+  issue: Omit<PlaySqlListenerValidationIssue, 'severity'> & {
+    severity?: PlaySqlListenerValidationIssue['severity'];
+  },
+): PlaySqlListenerValidationIssue {
+  return { severity: issue.severity ?? 'error', ...issue };
+}
+
+const PLAY_SQL_LISTENER_OPERATIONS = new Set<string>([
+  'INSERT',
+  'UPDATE',
+  'DELETE',
+]);
+
+function validateAdmittedSqlListenerWhere(
+  input: { where: unknown; path: string; listenerKey: string },
+  issues: PlaySqlListenerValidationIssue[],
+): void {
+  if (input.where === undefined) return;
+  if (!isPlainRecord(input.where)) {
+    issues.push(
+      sqlListenerIssue({
+        code: 'invalid_sql_listener_filter_shape',
+        path: input.path,
+        message:
+          'SQL listener where must be a literal object with before and/or after filters.',
+        expected:
+          '{ before?: Record<string, operators>, after?: Record<string, operators> }',
+        received: input.where,
+        entity_type: 'listener',
+        entity_key: input.listenerKey,
+        docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+      }),
+    );
+    return;
+  }
+  for (const [scope, scopeValue] of Object.entries(input.where)) {
+    const scopePath = `${input.path}.${scope}`;
+    if (scope !== 'before' && scope !== 'after') {
+      issues.push(
+        sqlListenerIssue({
+          code: 'unsupported_sql_listener_filter_scope',
+          path: scopePath,
+          message: 'SQL listener filters only support before and after scopes.',
+          expected: ['before', 'after'],
+          received: scope,
+          entity_type: 'listener',
+          entity_key: input.listenerKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+      continue;
+    }
+    if (!isPlainRecord(scopeValue)) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'invalid_sql_listener_filter_scope',
+          path: scopePath,
+          message: `SQL listener where.${scope} must be an object keyed by top-level row field.`,
+          expected: 'Record<field, operators>',
+          received: scopeValue,
+          entity_type: 'listener',
+          entity_key: input.listenerKey,
+          docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+        }),
+      );
+      continue;
+    }
+    for (const [field, operators] of Object.entries(scopeValue)) {
+      const fieldPath = `${scopePath}.${field}`;
+      if (!PLAY_SQL_LISTENER_FIELD_PATTERN.test(field)) {
+        issues.push(
+          sqlListenerIssue({
+            code: 'invalid_sql_listener_filter_field',
+            path: fieldPath,
+            message:
+              'SQL listener filters only support top-level row fields with plain identifier names.',
+            expected: PLAY_SQL_LISTENER_FIELD_PATTERN.source,
+            received: field,
+            suggestion:
+              'Use a top-level column key such as "country" instead of a path expression.',
+            entity_type: 'listener',
+            entity_key: input.listenerKey,
+            docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+          }),
+        );
+      }
+      if (!isPlainRecord(operators)) {
+        issues.push(
+          sqlListenerIssue({
+            code: 'invalid_sql_listener_filter_condition',
+            path: fieldPath,
+            message:
+              'SQL listener field filters must be an object keyed by a supported operator, e.g. { eq: <value> } — got a bare value.',
+            expected: PLAY_SQL_LISTENER_WHERE_OPERATORS,
+            received: operators,
+            entity_type: 'listener',
+            entity_key: input.listenerKey,
+            docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+          }),
+        );
+        continue;
+      }
+      if (Object.keys(operators).length === 0) {
+        issues.push(
+          sqlListenerIssue({
+            code: 'empty_sql_listener_filter_condition',
+            path: fieldPath,
+            message:
+              'SQL listener field filters must contain at least one operator.',
+            expected: PLAY_SQL_LISTENER_WHERE_OPERATORS,
+            received: operators,
+            entity_type: 'listener',
+            entity_key: input.listenerKey,
+            docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+          }),
+        );
+      }
+      for (const [operator, value] of Object.entries(operators)) {
+        const operatorPath = `${fieldPath}.${operator}`;
+        if (!PLAY_SQL_LISTENER_WHERE_OPERATOR_SET.has(operator)) {
+          issues.push(
+            sqlListenerIssue({
+              code: 'unsupported_sql_listener_filter_operator',
+              path: operatorPath,
+              message: `SQL listener filter operator "${operator}" is not supported.`,
+              expected: PLAY_SQL_LISTENER_WHERE_OPERATORS,
+              received: operator,
+              suggestion: `Use ${PLAY_SQL_LISTENER_WHERE_OPERATORS.slice(0, -1).join(', ')}, or ${PLAY_SQL_LISTENER_WHERE_OPERATORS.at(-1)}.`,
+              entity_type: 'listener',
+              entity_key: input.listenerKey,
+              docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+            }),
+          );
+          continue;
+        }
+        const valid =
+          ((operator === 'in' || operator === 'notIn') &&
+            Array.isArray(value) &&
+            value.length > 0 &&
+            value.every(isPlaySqlListenerFilterScalar)) ||
+          ((operator === 'isNull' || operator === 'isNotNull') &&
+            value === true) ||
+          (operator === 'ilike' &&
+            typeof value === 'string' &&
+            value.length > 0) ||
+          ((operator === 'eq' || operator === 'neq') &&
+            isPlaySqlListenerFilterScalar(value));
+        if (!valid) {
+          issues.push(
+            sqlListenerIssue({
+              code: 'invalid_sql_listener_filter_value',
+              path: operatorPath,
+              message: `SQL listener filter operator "${operator}" has an invalid value.`,
+              received: value,
+              entity_type: 'listener',
+              entity_key: input.listenerKey,
+              docs_ref: 'docs/monitor-sdk-architecture-plan.html#v2',
+            }),
+          );
+        }
+      }
+    }
+  }
+}
+
+/** Validate only a stored binding snapshot that already crossed admission. */
+export function validateAdmittedSqlListenerBindings(
+  bindings: PlayAuthoringAstBindings | null | undefined,
+  input: { playName?: string; pathPrefix?: string } = {},
+): PlaySqlListenerValidationIssue[] {
+  const issues: PlaySqlListenerValidationIssue[] = [];
+  const listeners = bindings?.sqlListeners;
+  if (!listeners) return issues;
+  const seen = new Set<string>();
+  listeners.forEach((listener, index) => {
+    const path = `${input.pathPrefix ?? 'sqlListeners'}[${index}]`;
+    const listenerKey = input.playName
+      ? `${input.playName}.${listener.id}`
+      : listener.id;
+    if (!listener.id || !PLAY_SQL_LISTENER_ID_PATTERN.test(listener.id)) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'invalid_sql_listener_id',
+          path: `${path}.id`,
+          message:
+            'SQL listener id must start with a letter and contain only letters, numbers, underscores, or hyphens.',
+          expected: PLAY_SQL_LISTENER_ID_PATTERN.source,
+          received: listener.id,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+    if (seen.has(listener.id)) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'duplicate_sql_listener_id',
+          path: `${path}.id`,
+          message: `SQL listener id "${listener.id}" is already used in this play.`,
+          received: listener.id,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+    seen.add(listener.id);
+    if (!listener.tool || !PLAY_SQL_LISTENER_TOOL_PATTERN.test(listener.tool)) {
+      issues.push(
+        sqlListenerIssue({
+          code: listener.tool
+            ? 'invalid_sql_listener_tool'
+            : 'missing_sql_listener_tool',
+          path: `${path}.tool`,
+          message: 'SQL listener tool must use provider.tool syntax.',
+          expected: PLAY_SQL_LISTENER_TOOL_PATTERN.source,
+          received: listener.tool,
+          entity_type: 'tool',
+          entity_key: listener.tool || listenerKey,
+        }),
+      );
+    }
+    if (
+      !listener.stream ||
+      !PLAY_SQL_LISTENER_ID_PATTERN.test(listener.stream)
+    ) {
+      issues.push(
+        sqlListenerIssue({
+          code: listener.stream
+            ? 'invalid_sql_listener_stream'
+            : 'missing_sql_listener_stream',
+          path: `${path}.stream`,
+          message:
+            'SQL listener stream keys must start with a letter and contain only letters, numbers, underscores, or hyphens.',
+          expected: PLAY_SQL_LISTENER_ID_PATTERN.source,
+          received: listener.stream,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+    validateAdmittedSqlListenerWhere(
+      { where: listener.where, path: `${path}.where`, listenerKey },
+      issues,
+    );
+    if (
+      !Array.isArray(listener.operations) ||
+      listener.operations.length === 0
+    ) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'empty_sql_listener_operations',
+          path: `${path}.operations`,
+          message: 'SQL listener operations must not be empty.',
+          expected: [...PLAY_SQL_LISTENER_OPERATIONS],
+          received: listener.operations,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    } else if (
+      listener.operations.some(
+        (operation) => !PLAY_SQL_LISTENER_OPERATIONS.has(operation),
+      )
+    ) {
+      issues.push(
+        sqlListenerIssue({
+          code: 'invalid_sql_listener_operation',
+          path: `${path}.operations`,
+          message: 'SQL listener operations must be INSERT, UPDATE, or DELETE.',
+          expected: [...PLAY_SQL_LISTENER_OPERATIONS],
+          received: listener.operations,
+          entity_type: 'listener',
+          entity_key: listenerKey,
+        }),
+      );
+    }
+  });
+  return issues;
+}
 export type PlaySqlListenerDeclaration = {
   id: string;
   tool: string;
@@ -615,6 +925,8 @@ export type PlayAuthoringDefinedPlay<
     readonly runtime?: PlayAuthoringBindings<TInput>['runtime'];
     readonly compatibility?: PlayAuthoringBindings<TInput>['compatibility'];
     readonly playName: string;
+    /** Type-only input carrier used by typed Play-reference consumers. */
+    readonly __inputType?: TInput;
   };
 
 /** Canonical resolver shape for a customer-authored durable step. */
@@ -851,20 +1163,14 @@ export type PlayAuthoringDatasetBuilder<
     TContext
   >;
   /** Add all columns declared by one reusable step program. */
-  withColumns<
-    Program extends PlayAuthoringStepProgram<
+  withColumns<ProgramOutput extends OutputRow, Return>(
+    program: PlayAuthoringStepProgram<
       OutputRow,
-      object,
+      ProgramOutput,
       TContext,
-      unknown
+      Return
     >,
-  >(
-    program: Program,
-  ): PlayAuthoringDatasetBuilder<
-    InputRow,
-    PlayAuthoringStepProgramOutput<Program>,
-    TContext
-  >;
+  ): PlayAuthoringDatasetBuilder<InputRow, ProgramOutput, TContext>;
   /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
   step<Name extends string, Value>(
     name: Name,
@@ -881,9 +1187,34 @@ export type PlayAuthoringDatasetBuilder<
   ): Promise<PlayDataset<OutputRow>>;
 };
 
-export type PlayAuthoringReferenceLike =
+export type PlayAuthoringReferenceLike<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+> = (
   | { readonly playName: string; readonly name?: string }
-  | { readonly name: string; readonly playName?: string };
+  | { readonly name: string; readonly playName?: string }
+) & {
+  /** Type-only input carrier used by ctx.runPlayAsync. */
+  readonly __inputType?: TInput;
+};
+
+declare const PLAY_RUN_ID_BRAND: unique symbol;
+
+/** Branded run identity returned inside {@link AsyncPlayRunRef}. */
+export type PlayRunId = string & {
+  readonly [PLAY_RUN_ID_BRAND]: 'PlayRunId';
+};
+
+/**
+ * Serializable reference returned after an async child Run is durable.
+ * @sdkReference runtime 143 AsyncPlayRunRef
+ */
+export type AsyncPlayRunRef = Readonly<{
+  runId: PlayRunId;
+}>;
+
+export type PlayAuthoringAsyncCallOptions = Readonly<{
+  description: string;
+}>;
 
 /** Discoverable, non-deprecated Runtime Context members shown to Play authors. */
 export const PLAY_AUTHORING_RUNTIME_CONTEXT_MEMBERS = [
@@ -894,6 +1225,7 @@ export const PLAY_AUTHORING_RUNTIME_CONTEXT_MEMBERS = [
   'log',
   'run',
   'runPlay',
+  'runPlayAsync',
   'runSteps',
   'secrets',
   'sleep',
@@ -1239,6 +1571,27 @@ export interface PlayAuthoringRuntimeContext {
     options: PlayAuthoringCallOptions,
   ): Promise<TOutput>;
 
+  /**
+   * Admit an independent scalar Play Run and return its durable identity after scheduler admission, before child completion.
+   * @sdkReference runtime 141 ctx.runPlayAsync(key, playRef, input, options)
+   */
+  runPlayAsync<TInput extends Record<string, unknown>>(
+    /** Replay-stable identity for this launch site and row scope. */
+    key: string,
+    /** Independently published Play name or definePlay handle carrying its input type. */
+    playRef: PlayAuthoringReferenceLike<TInput>,
+    /** Input checked against the referenced definePlay handle when available. */
+    input: NoInfer<TInput>,
+    /** Human-readable launch purpose recorded in the parent's step history. */
+    options: PlayAuthoringAsyncCallOptions,
+  ): Promise<AsyncPlayRunRef>;
+  runPlayAsync(
+    key: string,
+    playRef: string,
+    input: Record<string, unknown>,
+    options: PlayAuthoringAsyncCallOptions,
+  ): Promise<AsyncPlayRunRef>;
+
   /**
    * Write a customer-safe line to the durable Run Log Stream. Omitting level
    * preserves the historical info-level behavior.
@@ -2298,6 +2651,84 @@ export const PLAY_AUTHORING_FIELD_REGISTRY = {
     errorMessage:
       'ctx.runPlay timeoutMs is unsupported because child Plays execute inline.',
   },
+  'ctx.runPlayAsync.key': {
+    schema: Type.String({ minLength: 1 }),
+    fixtures: {
+      valid: 'request-approval',
+      invalid: '',
+      absent: undefined,
+      unresolved: { expression: 'callKey' },
+      edition1: 'request-approval',
+    },
+    referenceType: 'string',
+    required: true,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_run_play_option_invalid',
+    description: 'Stable identity for one independent child Play Run.',
+    errorMessage: 'ctx.runPlayAsync key must be a non-empty string.',
+  },
+  'ctx.runPlayAsync.playRef': {
+    schema: Type.Union([
+      Type.String({ minLength: 1 }),
+      Type.Union([
+        Type.Object(
+          { playName: Type.String({ minLength: 1 }) },
+          { additionalProperties: true },
+        ),
+        Type.Object(
+          { name: Type.String({ minLength: 1 }) },
+          { additionalProperties: true },
+        ),
+      ]),
+    ]),
+    fixtures: {
+      valid: 'request-approval',
+      invalid: {},
+      absent: undefined,
+      unresolved: { expression: 'playRef' },
+      edition1: 'request-approval',
+    },
+    referenceType: 'string | PlayReferenceLike',
+    required: true,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_run_play_option_invalid',
+    description:
+      'Independently published scalar child Play name or strongly typed definition handle.',
+    errorMessage:
+      'ctx.runPlayAsync playRef must be a non-empty Play name or definition handle.',
+  },
+  'ctx.runPlayAsync.input': {
+    schema: Type.Record(Type.String(), Type.Unknown()),
+    fixtures: {
+      valid: { draftId: 'draft-1' },
+      invalid: 'draft-1',
+      absent: undefined,
+      unresolved: 'childInput',
+      edition1: {},
+    },
+    referenceType: 'Record<string, unknown>',
+    required: true,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_run_play_option_invalid',
+    description: 'Scalar input object submitted to the independent child Run.',
+    errorMessage: 'ctx.runPlayAsync input must be an object.',
+  },
+  'ctx.runPlayAsync.options.description': {
+    schema: Type.String({ minLength: 1 }),
+    fixtures: {
+      valid: 'Request approval.',
+      invalid: '',
+      absent: undefined,
+      unresolved: { expression: 'description' },
+      edition1: 'Request approval.',
+    },
+    referenceType: 'string',
+    required: true,
+    resolution: 'runtime-dynamic',
+    issueCode: 'play_authoring_run_play_option_invalid',
+    description: 'Non-empty purpose for one independent child Play Run.',
+    errorMessage: 'ctx.runPlayAsync options.description must be non-empty.',
+  },
   'runtime.timeout': {
     schema: Type.String({ pattern: '^\\d+\\s*[mh]$' }),
     fixtures: {
@@ -2747,6 +3178,10 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   `export type CsvOptions = { description?: ${cloudReferenceType('ctx.csv.options.description')}; columns?: ${cloudReferenceType('ctx.csv.options.columns')}; rename?: ${cloudReferenceType('ctx.csv.options.rename')}; required?: ${cloudReferenceType('ctx.csv.options.required')} };`,
   "export type PlayCallExecution = 'inline';",
   `export type PlayCallOptions = { description: ${cloudReferenceType('ctx.runPlay.options.description')}; execution?: ${cloudReferenceType('ctx.runPlay.options.execution')}; timeoutMs?: ${cloudReferenceType('ctx.runPlay.options.timeoutMs')} };`,
+  `export type PlayAsyncCallOptions = { description: ${cloudReferenceType('ctx.runPlayAsync.options.description')} };`,
+  'declare const PLAY_RUN_ID_BRAND: unique symbol;',
+  "export type PlayRunId = string & { readonly [PLAY_RUN_ID_BRAND]: 'PlayRunId' };",
+  '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 };',
@@ -2772,11 +3207,11 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   '  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>>;',
   '  withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;',
   '  withColumn<Name extends string, Value>(name: Name, resolver: StepResolver<OutputRow, Value> | RunnableColumnStepProgram<Value>, options: StepOptions<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;',
-  '  withColumns<Program extends StepProgram<OutputRow, object, unknown>>(program: Program): DatasetBuilder<InputRow, StepProgramOutput<Program>>;',
+  '  withColumns<ProgramOutput extends OutputRow, Return>(program: StepProgram<OutputRow, ProgramOutput, Return>): DatasetBuilder<InputRow, ProgramOutput>;',
   '  step<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): never;',
   '  run(options?: DatasetRunOptions<InputRow>): Promise<PlayDataset<OutputRow>>;',
   '};',
-  'export type PlayReferenceLike = { readonly playName: string; readonly name?: string } | { readonly name: string; readonly playName?: string };',
+  'export type PlayReferenceLike<TInput extends Record<string, unknown> = Record<string, unknown>> = ({ readonly playName: string; readonly name?: string } | { readonly name: string; readonly playName?: string }) & { readonly __inputType?: TInput };',
   'export interface DeeplinePlayRuntimeContext {',
   '  csv<T = Record<string, unknown>>(path: string | CsvInput<T & object>, options?: CsvOptions): Promise<PlayDataset<T>>;',
   '  dataset<TSource extends PlayDatasetInput<object>>(key: string, items: TSource): DatasetBuilder<PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object>;',
@@ -2790,6 +3225,8 @@ export const PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "  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 };',
   `  runPlay<TOutput = unknown>(key: string, playRef: ${cloudReferenceType('ctx.runPlay.playRef')}, input: ${cloudReferenceType('ctx.runPlay.input')}, options: PlayCallOptions): Promise<TOutput>;`,
+  '  runPlayAsync<TInput extends Record<string, unknown>>(key: string, playRef: PlayReferenceLike<TInput>, input: NoInfer<TInput>, options: PlayAsyncCallOptions): Promise<AsyncPlayRunRef>;',
+  '  runPlayAsync(key: string, playRef: string, input: Record<string, unknown>, options: PlayAsyncCallOptions): Promise<AsyncPlayRunRef>;',
   "  log(message: string, options?: { level?: 'debug' | 'info' | 'warn' | 'error' }): void;",
   `  sleep(ms: ${cloudReferenceType('ctx.sleep.ms')}): Promise<void>;`,
   '}',

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

@@ -63,7 +63,7 @@ import { PLAY_AUTHORING_CONTRACT_EDITION } from '../authoring-contract';
 // of the artifact bytes. Do not reuse a local bundle cached before either
 // compatibility selection or docflow instrumentation entered graph analysis.
 // Keep this aligned with the app and SDK adapters' cache namespace.
-const PLAY_BUNDLE_CACHE_VERSION = 36;
+const PLAY_BUNDLE_CACHE_VERSION = 37;
 const PLAY_ARTIFACT_CACHE_DIR = join(
   tmpdir(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,
@@ -122,7 +122,12 @@ export type PlayLocalFileDiscoveryResult = {
 
 export type PlayBundlingAdapter = {
   projectRoot: string;
-  /** Optional root used only to make source-graph identity independent of temporary absolute paths. */
+  /**
+   * Optional root that makes the artifact independent of where it was built:
+   * source paths in the graph hash and esbuild's working directory (which it
+   * writes into every module-header comment, and so into `artifactHash`) are
+   * both taken relative to it instead of to the build's absolute location.
+   */
   sourceIdentityRoot?: string;
   nodeModulesDir: string;
   cacheDir?: string;
@@ -2247,6 +2252,7 @@ async function runEsbuildForCjsNode(
   importedPlayDependencies: ImportedPlayDependency[],
   adapter: PlayBundlingAdapter,
   exportName: string,
+  bundleRoot: string,
 ): Promise<EsbuildBundleOutput | string[]> {
   const sdkAliasPlugin = localSdkAliasPlugin(adapter);
   const playProxyPlugin = importedPlayProxyPlugin(importedPlayDependencies);
@@ -2269,7 +2275,14 @@ async function runEsbuildForCjsNode(
           },
         }
       : { entryPoints: [entryFile] }),
-    absWorkingDir: adapter.projectRoot,
+    // esbuild writes `// <path relative to absWorkingDir>` above every module
+    // it inlines, and artifactHash is sha256 of those bytes. Rooting the build
+    // at the identity root keeps the customer's own files repo-relative, so a
+    // deploy worker building the same commit in a fresh temp directory each
+    // time produces the same bytes. Files outside the root (the SDK on the
+    // worker image) come out as a `..`-prefixed path whose shape depends only
+    // on the image's layout, which is fixed, not on the build's name.
+    absWorkingDir: bundleRoot,
     bundle: true,
     format: 'cjs',
     nodePaths: [adapter.nodeModulesDir],
@@ -2416,12 +2429,14 @@ export async function bundlePlayFile(
       };
     }
 
+    const bundleRoot = resolve(sourceIdentityRoot ?? adapter.projectRoot);
     const buildOutcome = await runEsbuildForCjsNode(
       absolutePath,
       analysis.importPolicy.localFiles,
       analysis.importedPlayDependencies,
       adapter,
       exportName,
+      bundleRoot,
     );
     if (Array.isArray(buildOutcome)) {
       return {
@@ -2434,7 +2449,7 @@ export async function bundlePlayFile(
 
     const normalizedSourceMap = normalizeSourceMapForRuntime(
       sourceMapText,
-      resolve(adapter.projectRoot),
+      bundleRoot,
     );
     const virtualBaseName =
       exportName === 'default'

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

@@ -28,21 +28,16 @@ export type PlayRuntimeFeature =
   | 'durable_sleep'
   | 'packaged_files';
 
-export const PLAY_PUBLIC_API_VERSION = 1;
 export const PLAY_ARTIFACT_VERSION = CURRENT_PLAY_ARTIFACT_CONTRACT_VERSION;
-export const PLAY_MIN_RUNNER_VERSION = 1;
-export const PLAY_RUNTIME_FEATURES: PlayRuntimeFeature[] = [
-  'artifact_storage',
-  'checkpoint_resume',
-  'durable_sleep',
-  'packaged_files',
-];
 
 export type PlayContractCompatibilitySnapshot = {
-  apiVersion: number;
+  /** Historical marker. Nothing admits, gates, or branches on it. */
+  apiVersion?: number;
   artifactVersion: number;
-  minRunnerVersion: number;
-  runtimeFeatures: PlayRuntimeFeature[];
+  /** Historical marker. Every runner reads every artifact. */
+  minRunnerVersion?: number;
+  /** Historical marker. Capabilities are named per operation, not listed here. */
+  runtimeFeatures?: PlayRuntimeFeature[];
   runtimeBackend?: string | null;
   /** Every Play run uses the structured tool-error contract. */
   toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
@@ -142,10 +137,7 @@ export function buildPlayContractCompatibility(input?: {
   toolResponseReceiptRevision?: string;
 }): PlayContractCompatibilitySnapshot {
   return {
-    apiVersion: PLAY_PUBLIC_API_VERSION,
     artifactVersion: PLAY_ARTIFACT_VERSION,
-    minRunnerVersion: PLAY_MIN_RUNNER_VERSION,
-    runtimeFeatures: [...PLAY_RUNTIME_FEATURES],
     runtimeBackend: input?.runtimeBackend ?? null,
     toolErrorSchemaVersion:
       input?.toolErrorSchemaVersion ?? TOOL_EXECUTION_ERROR_SCHEMA_VERSION,