deepline 0.2.13 → 0.2.14

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

@@ -98,7 +98,6 @@ import type {
   ToolResultMetadataInput,
 } from '../../shared_libs/play-runtime/tool-result-types.js';
 import type { EmailStatusExtractorConfig } from '../../shared_libs/play-runtime/email-status.js';
-import type { PreviousCell } from '../../shared_libs/play-runtime/cell-staleness.js';
 import type {
   DeeplineClientOptions,
   PlayDetail,
@@ -113,14 +112,64 @@ import type {
   ToolMetadata,
 } from './types.js';
 import type { ToolExecution } from './client.js';
-import type { ToolExecutionErrorSchemaVersion } from '../../shared_libs/tool-execution-error.js';
-
-export type PlayCallExecution = 'inline' | 'child-workflow';
-
-export interface PlayCallOptions {
-  description: string;
-  execution?: PlayCallExecution;
-}
+import type {
+  DurableCallStaleAfterSeconds,
+  PlayAuthoringBindings,
+  PlayAuthoringCallExecution,
+  PlayAuthoringCallOptions,
+  PlayAuthoringColumnResolver,
+  PlayAuthoringColumnMap,
+  PlayAuthoringConditionalStepResolver,
+  PlayAuthoringCsvInput,
+  PlayAuthoringCsvOptions,
+  PlayAuthoringCsvRenameMap,
+  PlayAuthoringDatasetBuilder,
+  PlayAuthoringDatasetColumnDefinition,
+  PlayAuthoringDatasetColumnRunInput,
+  PlayAuthoringDatasetDefinitionOptions,
+  PlayAuthoringDatasetRowKey,
+  PlayAuthoringDatasetRunOptions,
+  PlayAuthoringDefineConfig,
+  PlayAuthoringDefinedPlay,
+  PlayAuthoringInputContract,
+  PlayAuthoringFileInput,
+  PlayAuthoringFetchOptions,
+  PlayAuthoringFetchResponse,
+  PlayAuthoringReferenceLike,
+  PlayAuthoringRunnableStepProgram,
+  PlayAuthoringRuntimeContext,
+  PlayAuthoringRuntimeStepOptions,
+  PlayAuthoringStepOptions,
+  PlayAuthoringStepProgram,
+  PlayAuthoringStepProgramOutput,
+  PlayAuthoringStepProgramResolver,
+  PlayAuthoringStepProgramStep,
+  PlayAuthoringStepResolver,
+  PlayLooseObject,
+  PlayReturnObject as PlayAuthoringReturnObject,
+  PlaySecretAuth,
+  PlaySecretAwareRequestInit,
+  PlaySecretHandle,
+  PlaySqlQuery,
+  PlayReceiptWaitMs,
+  PlayRuntimeTimeoutMs,
+  PlaySqlListenerDeclaration,
+  PlaySqlListenerEvent,
+  PlaySqlListenerFilterOperator,
+  PlaySqlListenerFilterScalar,
+  PlaySqlListenerOperation,
+  PlaySqlListenerWhere,
+  PlayToolExecutionRequest,
+} from '../../shared_libs/plays/authoring-contract.js';
+import { createPlayInputContract } from '../../shared_libs/plays/input-contract-definition.js';
+
+export type PlayCallExecution = PlayAuthoringCallExecution;
+
+export type PlayCallOptions = PlayAuthoringCallOptions;
+
+export type RuntimeStepOptions = PlayAuthoringRuntimeStepOptions;
+export type FetchOptions = PlayAuthoringFetchOptions;
+export type PlayFetchResponse = PlayAuthoringFetchResponse;
 
 /**
  * Optional trigger bindings for a play.
@@ -172,142 +221,21 @@ export interface PlayCallOptions {
  *
  * @sdkReference runtime 030
  */
-export type PlayBindings = {
-  /**
-   * Human-readable one-line description of what this play does.
-   *
-   * New SDK-authored file workflows require this in `plays check`, `plays run
-   * --file`, and `plays publish <file>`. The server API keeps it optional so
-   * older clients can continue to register revisions during the migration.
-   */
-  description?: string;
-  /**
-   * Public behavior that must remain pinned for this play artifact.
-   *
-   * New plays default to typed tool errors (`1`). Set `toolErrorSchemaVersion`
-   * to `0` only while migrating code that depends on legacy error names,
-   * messages, or classes.
-   */
-  compatibility?: {
-    toolErrorSchemaVersion: ToolExecutionErrorSchemaVersion;
-  };
-  /** Allow compilers to bundle this named handler directly without a child run. */
-  inline?: boolean;
-  /** Optional per-run billing controls enforced by the runtime. */
-  billing?: {
-    /** Stop the run before a billed action would push total run credits above this cap. */
-    maxCreditsPerRun?: number;
-  };
-  /** Requested prebuilt sandbox and runtime deadline. */
-  runtime?: {
-    /** Duration such as `"90m"` or `"2h"`. */
-    timeout?: string;
-    /** Deepline-managed prebuilt sandbox size. */
-    size?: 'standard';
-  };
-  /** Webhook trigger with optional HMAC signature verification. */
-  webhook?: {
-    hmac?: {
-      /** Hash algorithm. Currently only `'sha256'` is supported. */
-      algorithm?: 'sha256';
-      /** HTTP header containing the signature (e.g. `'X-Hub-Signature-256'`). */
-      header?: string;
-      /** Environment variable name holding the HMAC secret. */
-      secretEnv: string;
-    };
-  };
-  /** Cron schedule trigger. */
-  cron?: {
-    /** Cron expression (e.g. `'0 9 * * *'` for daily at 9am). */
-    schedule: string;
-    /** IANA timezone (e.g. `'America/New_York'`). Defaults to UTC. */
-    timezone?: string;
-  };
-  /** Customer DB row-change listeners that wake this play when published. */
-  sqlListeners?: SqlListenerDeclaration[];
-  /**
-   * Customer-authored play secrets this play is allowed to use at runtime.
-   * Values are never bundled or exposed by the SDK; access them with
-   * `ctx.secrets.get("NAME")` and approved helpers such as
-   * `ctx.secrets.bearer(handle)`. Secret-authenticated `ctx.fetch` calls
-   * require an https:// URL so customer secrets never leave Deepline over
-   * plaintext HTTP.
-   */
-  secrets?: readonly string[];
-};
-
-export type SqlListenerOperation = 'INSERT' | 'UPDATE' | 'DELETE';
-export type SqlListenerFilterScalar = string | number | boolean | null;
-export type SqlListenerFilterOperator = {
-  eq?: SqlListenerFilterScalar;
-  neq?: SqlListenerFilterScalar;
-  in?: SqlListenerFilterScalar[];
-  notIn?: SqlListenerFilterScalar[];
-  isNull?: true;
-  isNotNull?: true;
-  ilike?: string;
-};
-export type SqlListenerWhere = {
-  before?: Record<string, SqlListenerFilterOperator>;
-  after?: Record<string, SqlListenerFilterOperator>;
-};
-
-export type SqlListenerDeclaration = {
-  /** Short id unique inside this play. Deepline stores it as playName.id. */
-  id: string;
-  /** Modeled monitor tool id, for example "deepline_native.company_radar". */
-  tool: string;
-  /** Stream key exposed by the modeled monitor tool, for example "company_job_openings". */
-  stream: string;
-  /** Row operations that should wake this play. Defaults to INSERT and UPDATE. */
-  operations?: SqlListenerOperation[];
-  /** Optional DB-side row filter over top-level before/after fields. */
-  where?: SqlListenerWhere;
-};
-
-export type SqlListenerEvent<T extends object = Record<string, unknown>> = {
-  tool: string;
-  stream: string;
-  operation: SqlListenerOperation;
-  before: T | null;
-  after: T | null;
-  changedAt: string;
-  metadata: {
-    outboxId: string;
-    listenerId: string;
-    table: string;
-  };
-};
-
-export type SqlQuery = {
-  readonly kind: 'sql.query';
-  readonly text: string;
-  readonly values: readonly unknown[];
-};
-
-declare const SECRET_HANDLE_BRAND: unique symbol;
-
-export type SecretHandle = {
-  readonly [SECRET_HANDLE_BRAND]: never;
-  readonly name: string;
-  toString(): string;
-  toJSON(): never;
-};
-
-export type SecretAuth = {
-  readonly kind: 'bearer' | 'header';
-  readonly secret: SecretHandle;
-  readonly header?: string;
-};
-
-export type SecretAwareRequestInit = Omit<RequestInit, 'headers'> & {
-  headers?: HeadersInit;
-  auth?: SecretAuth;
-};
-
-export type LoosePlayObject = {
-  [key: string]: LoosePlayObject;
-};
+export type PlayBindings = PlayAuthoringBindings;
+export type SqlListenerOperation = PlaySqlListenerOperation;
+export type SqlListenerFilterScalar = PlaySqlListenerFilterScalar;
+export type SqlListenerFilterOperator = PlaySqlListenerFilterOperator;
+export type SqlListenerWhere = PlaySqlListenerWhere;
+export type SqlListenerDeclaration = PlaySqlListenerDeclaration;
+export type SqlListenerEvent<T extends object = Record<string, unknown>> =
+  PlaySqlListenerEvent<T>;
+
+/** @deprecated Pass a SQL string directly to ctx.customerDb.query. */
+export type SqlQuery = PlaySqlQuery;
+export type SecretHandle = PlaySecretHandle;
+export type SecretAuth = PlaySecretAuth;
+export type SecretAwareRequestInit = PlaySecretAwareRequestInit;
+export type LoosePlayObject = PlayLooseObject;
 
 export type {
   ToolExecuteResult,
@@ -344,52 +272,21 @@ export type { PreviousCell } from '../../shared_libs/play-runtime/cell-staleness
  *
  * @sdkReference runtime 160
  */
-export type ToolExecutionRequest = {
-  /** Stable logical id for logs, metadata, and receipt attachment. */
-  id: string;
-  /** Current tool id from `deepline tools search` / `deepline tools describe`. */
-  tool: string;
-  /** JSON-serializable provider/tool input object. */
-  input: Record<string, unknown>;
-  /** Human-readable description for logs and run inspection. */
-  description?: string;
-  /** Recompute this tool call instead of reusing a durable receipt/checkpoint. */
-  force?: boolean;
-  /** Numeric TTL in seconds for this tool checkpoint. */
-  staleAfterSeconds?: number;
-  /** Runtime transport timeout in milliseconds. This is not sent to the provider. */
-  timeoutMs?: number;
-  /** Follower wait budget in milliseconds before a running receipt is reclaimable. */
-  receiptWaitMs?: number;
-};
+export type ToolExecutionRequest = PlayToolExecutionRequest;
 
-export type StepResolver<Row, Value> = (
-  row: Row,
-  ctx: DeeplinePlayRuntimeContext,
-  index: number,
-  previousCell?: PreviousCell<Value>,
-) => Value | Promise<Value>;
+export type StepResolver<Row, Value> = PlayAuthoringStepResolver<
+  Row,
+  Value,
+  DeeplinePlayRuntimeContext
+>;
 
 /**
  * Input object passed to an object-column `run` resolver.
  *
  * @sdkReference runtime 090
  */
-export type DatasetColumnRunInput<Row, Value> = {
-  /** Current row, including previously computed columns. */
-  row: Row;
-  /** Runtime context for tool/play/fetch/log calls. */
-  ctx: DeeplinePlayRuntimeContext;
-  /** Zero-based row index for this dataset run. */
-  index: number;
-  /**
-   * The prior stored value for this exact row+column when the runtime has
-   * decided the cell is due to run again. `previousCell.value` is the same type
-   * this column returns; metadata such as `completedAt` and `staleAt` lives
-   * beside it and is not mixed into the value.
-   */
-  previousCell?: PreviousCell<Value>;
-};
+export type DatasetColumnRunInput<Row, Value> =
+  PlayAuthoringDatasetColumnRunInput<Row, Value, DeeplinePlayRuntimeContext>;
 
 /**
  * Object-column form for `.withColumn(...)`.
@@ -398,96 +295,55 @@ export type DatasetColumnRunInput<Row, Value> = {
  *
  * @sdkReference runtime 100
  */
-export type DatasetColumnDefinition<Row, Value> = {
-  /** Compute one cell value. Receives the previous stored value when rerunning. */
-  run: (input: DatasetColumnRunInput<Row, Value>) => Value | Promise<Value>;
-  /** Optional row-level gate. Skipped rows produce `null` for this column. */
-  readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
-};
+export type DatasetColumnDefinition<Row, Value> =
+  PlayAuthoringDatasetColumnDefinition<Row, Value, DeeplinePlayRuntimeContext>;
 
-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 ConditionalStepResolver<
+  Row,
+  Value,
+  Else = null,
+> = PlayAuthoringConditionalStepResolver<
+  Row,
+  Value,
+  DeeplinePlayRuntimeContext,
+  Else
+>;
 
 /**
  * Options for row-level `.withColumn(...)` and `steps().step(...)` entries.
  *
  * @sdkReference runtime 110
  */
-export type StepOptions<Row, Value = unknown> = {
-  /** Optional row-level gate. Skipped rows produce `null` for this column. */
-  readonly runIf?: (row: Row, index: number) => boolean | Promise<boolean>;
-  /**
-   * Legacy dataset-column recompute flag accepted for older authored plays.
-   *
-   * Prefer putting freshness on the actual reusable call
-   * (`ctx.tools.execute`, `ctx.step`, or `ctx.fetch`).
-   */
-  readonly recompute?: boolean;
-  /** Legacy error-recompute flag accepted for older authored plays. */
-  readonly recomputeOnError?: boolean;
-  /** Legacy cell staleness metadata accepted for older authored plays. */
-  readonly staleAfterSeconds?: number;
-};
+export type StepOptions<Row, Value = unknown> = PlayAuthoringStepOptions<
+  Row,
+  Value
+>;
 
-export type StepProgram<Input, Output, Return = Output> = {
-  readonly kind: 'steps';
-  readonly steps: readonly PlayStepProgramStep[];
-  readonly returnResolver?: StepResolver<Output, Return>;
-  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,
+> = PlayAuthoringStepProgram<Input, Output, DeeplinePlayRuntimeContext, Return>;
 
-export type StepProgramResolver<Input, Return> = {
-  readonly kind: 'steps';
-  readonly steps: readonly PlayStepProgramStep[];
-  readonly returnResolver?: StepResolver<never, Return>;
-  readonly __inputType?: (input: Input) => void;
-};
+export type StepProgramResolver<Input, Return> =
+  PlayAuthoringStepProgramResolver<Input, Return, DeeplinePlayRuntimeContext>;
 
-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 =
+  PlayAuthoringStepProgramStep<DeeplinePlayRuntimeContext>;
 
-export type ColumnResolver<Row, Value> =
-  | StepResolver<Row, Value>
-  | ConditionalStepResolver<Row, Value>
-  | StepProgramResolver<Row, Value>;
+export type ColumnResolver<Row, Value> = PlayAuthoringColumnResolver<
+  Row,
+  Value,
+  DeeplinePlayRuntimeContext
+>;
 
 export type StepProgramOutput<TProgram> =
-  TProgram extends StepProgram<unknown, infer Output, unknown> ? Output : never;
+  PlayAuthoringStepProgramOutput<TProgram>;
 
 export type RunnableStepProgram<TInput, TOutput> = Pick<
-  StepProgram<TInput, never, TOutput>,
-  'kind' | 'steps' | 'returnResolver' | '__inputType'
->;
+  PlayAuthoringRunnableStepProgram<TOutput, DeeplinePlayRuntimeContext>,
+  'kind' | 'steps' | 'returnResolver'
+> & { readonly __inputType?: (input: TInput) => void };
 
 /**
  * Builder returned by `ctx.dataset(...)` for row-level durable columns.
@@ -497,111 +353,26 @@ export type RunnableStepProgram<TInput, TOutput> = Pick<
 export type DatasetBuilder<
   InputRow extends object,
   OutputRow extends object,
-> = {
-  /**
-   * Define one output column for every row in this dataset.
-   *
-   * The `name` becomes a field on each output row. For example,
-   * `.withColumn('contact', ...)` creates `row.contact` in later column resolvers; it does
-   * not spread returned object fields such as `contact.email` into `row.email`.
-   * Add a later column resolver when you want a top-level export field:
-   * `.withColumn('email', row => row.contact?.email ?? null)`.
-   *
-   * @param name - Output column name.
-   * @param resolver - Computes the value for one row.
-   * @returns The same dataset builder with the new column type.
-   */
-  withColumn<Name extends string, Value>(
-    name: Name,
-    resolver: ColumnResolver<OutputRow, Value>,
-  ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
-  /**
-   * Define one output column with object-column authoring and a row gate.
-   *
-   * @param name - Output column name.
-   * @param definition - Object-column definition with required `runIf`.
-   * @returns The same dataset builder with a nullable column type for skipped rows.
-   */
-  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>>;
-  /**
-   * Define one output column with object-column authoring.
-   *
-   * Use this form for typed `previousCell` access.
-   *
-   * @param name - Output column name.
-   * @param definition - Object-column definition.
-   * @returns The same dataset builder with the new column type.
-   */
-  withColumn<Name extends string, Value>(
-    name: Name,
-    definition: DatasetColumnDefinition<OutputRow, Value>,
-  ): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
-  /**
-   * Define one output column with a resolver plus row-level options.
-   *
-   * @param name - Output column name.
-   * @param resolver - Computes the value for one row.
-   * @param options - Row gate options.
-   * @returns The same dataset builder with a nullable column type for skipped rows.
-   */
-  withColumn<Name extends string, Value>(
-    name: Name,
-    resolver:
-      | StepResolver<OutputRow, Value>
-      | StepProgramResolver<OutputRow, 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>>;
-  /** @deprecated Dataset `.step(...)` was replaced by `.withColumn(...)`. */
-  step<Name extends string, Value>(
-    name: Name,
-    resolver: ColumnResolver<OutputRow, Value>,
-  ): never;
-  /**
-   * Execute the row-column program and return a durable dataset handle.
-   *
-   * The returned {@link PlayDataset} preserves one output row per input row,
-   * with original fields merged with the columns produced by `.withColumn(...)`.
-   *
-   * @param options - Run options.
-   * @returns Output rows as a dataset handle.
-   */
-  run(options?: {
-    description?: string;
-    /**
-     * `upsert` (default) returns every input row, reusing persisted work for
-     * existing keys. `net_new` atomically inserts and returns only unseen keys.
-     */
-    mode?: 'upsert' | 'net_new';
-    key?:
-      | (keyof InputRow & string)
-      | readonly (keyof InputRow & string)[]
-      | ((
-          row: InputRow,
-          index: number,
-        ) => string | number | readonly unknown[]);
-  }): Promise<PlayDataset<OutputRow>>;
-};
+> = PlayAuthoringDatasetBuilder<
+  InputRow,
+  OutputRow,
+  DeeplinePlayRuntimeContext
+>;
+
+export type DatasetRowKey<InputRow extends object> =
+  PlayAuthoringDatasetRowKey<InputRow>;
+export type DatasetDefinitionOptions<InputRow extends object> =
+  PlayAuthoringDatasetDefinitionOptions<InputRow>;
+export type DatasetRunOptions<InputRow extends object> =
+  PlayAuthoringDatasetRunOptions<InputRow>;
 
-export type CsvRenameMap = Record<string, string | readonly string[]>;
+export type CsvRenameMap = PlayAuthoringCsvRenameMap;
 
 /**
  * Runtime file-like input. At runtime this is the staged file path/reference
  * string. The type parameter carries static metadata for describe/CLI tooling.
  */
-export type FileInput<TMetadata = unknown> = string & {
-  readonly __deeplineFileInputMetadata?: TMetadata;
-};
+export type FileInput<TMetadata = unknown> = PlayAuthoringFileInput<TMetadata>;
 
 /**
  * CSV file input whose rows are described by `TRow`.
@@ -611,30 +382,16 @@ export type FileInput<TMetadata = unknown> = string & {
  * discovery.
  */
 export type CsvInput<TRow extends object = Record<string, unknown>> =
-  FileInput<{
-    readonly kind: 'csv';
-    readonly row: TRow;
-  }>;
+  PlayAuthoringCsvInput<TRow>;
 
-export type ColumnMap<TRow extends object> = Partial<
-  Record<Extract<keyof TRow, string>, string | readonly string[]>
->;
+export type ColumnMap<TRow extends object> = PlayAuthoringColumnMap<TRow>;
 
 /**
  * Options for loading a staged CSV with `ctx.csv(...)`.
  *
  * @sdkReference runtime 050
  */
-export type CsvOptions = {
-  /** Human-readable description for runtime logs and inspection. */
-  description?: string;
-  /** Canonical field-to-header aliases, e.g. `{ domain: ['domain', 'Company Domain'] }`. */
-  columns?: CsvRenameMap;
-  /** Header rename map; use `columns` for new code. */
-  rename?: CsvRenameMap;
-  /** Canonical fields that must be present after header normalization. */
-  required?: readonly string[];
-};
+export type CsvOptions = PlayAuthoringCsvOptions;
 
 /**
  * Runtime context available inside a play function.
@@ -681,272 +438,7 @@ export type CsvOptions = {
  * });
  * ```
  */
-export interface DeeplinePlayRuntimeContext {
-  /**
-   * Load a staged CSV file as a durable dataset handle.
-   *
-   * Use this when a play receives a CSV path from the CLI or API and row work
-   * should continue through {@link DeeplinePlayRuntimeContext.dataset}. The path is
-   * normally an input field such as `input.csv`, populated by
-   * `deepline plays run my.play.ts --csv rows.csv`. Prefer `input.csv` for row
-   * data so the CLI can run strict CSV preflight before starting a run.
-   * Pass-through flags can also target non-reserved field names. If a play
-   * intentionally calls `ctx.csv(input.file)`, use `--input
-   * '{"file":"rows.csv"}'` because `--file` is reserved for the play source
-   * path.
-   *
-   * Each CSV row becomes an object keyed by canonical column names. Use
-   * `options.columns` / `options.rename` to map user headers such as
-   * `"Company Domain"` to stable code fields such as `domain`.
-   *
-   * @typeParam T - Row type (defaults to `Record<string, unknown>`)
-   * @param path - Staged CSV path.
-   * @param options - CSV load options.
-   *
-   * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.dataset(...)`.
-   *
-   * @sdkReference runtime 040 ctx.csv(path, options)
-   */
-  csv<T = Record<string, unknown>>(
-    path: string,
-    options?: CsvOptions,
-  ): Promise<PlayDataset<T>>;
-
-  /**
-   * Create a persisted row dataset/table from input rows.
-   *
-   * `ctx.dataset` is Deepline's row-work primitive. It records row identity,
-   * progress, retries, table output, and idempotency for a collection of rows.
-   * Use `.withColumn(name, resolver)` on the returned builder to define output
-   * columns, then `.run(...)` to execute the row program.
-   *
-   * The `key` identifies the logical dataset/table. Renaming it is a persistence
-   * migration: existing rows may no longer be reused. Row identity is derived
-   * automatically from input row content unless `.run({ key: ... })` overrides
-   * it with stable business fields such as `domain`, `email`, or `linkedin_url`.
-   *
-   * By default, `ctx.dataset` is row-preserving: one input row produces one output
-   * row, with original fields merged with the columns produced by
-   * `.withColumn(...)`. If one input entity must become many output rows, use the
-   * documented expand/flatten recipe instead of assuming `ctx.dataset` changes
-   * row cardinality.
-   *
-   * @typeParam T - Row type
-   * @param key - Dataset/table name.
-   * @param items - Input rows.
-   * @returns A builder. Calling `.run()` returns a `PlayDataset` of rows plus computed columns.
-   *
-   * @example Single tool per row
-   * ```typescript
-   * const results = await ctx
-   *   .dataset('companies', leads)
-   *   .withColumn('company', (row, ctx) =>
-   *     ctx.tools.execute({
-   *       id: 'company_search',
-   *       tool: 'test_company_search',
-   *       input: { domain: row.domain },
-   *       description: 'Look up company details by domain.',
-   *     }))
-   *   .run({ description: 'Look up companies.' });
-   * // [{ domain: 'stripe.com', company: { name: 'Stripe', ... } }, ...]
-   * ```
-   *
-   * @example Multiple columns with pre/post logic
-   * ```typescript
-   * const results = await ctx
-   *   .dataset('leads', leads)
-   *   .withColumn('company', (row, ctx) =>
-   *     ctx.tools.execute({
-   *       id: 'company_search',
-   *       tool: 'test_company_search',
-   *       input: { domain: row.domain },
-   *       description: 'Look up company details by domain.',
-   *     }))
-   *   .withColumn('score', (row) =>
-   *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
-   *   .run({ description: 'Enrich leads.' });
-   * ```
-   *
-   * @sdkReference runtime 060 ctx.dataset(key, items)
-   */
-  dataset<TSource extends PlayDatasetInput<object>>(
-    key: string,
-    items: TSource,
-  ): DatasetBuilder<
-    PlayDatasetRow<TSource> & object,
-    PlayDatasetRow<TSource> & object
-  >;
-  /**
-   * @deprecated `ctx.map(...)` was replaced by `ctx.dataset(...)`.
-   */
-  map<TSource extends PlayDatasetInput<object>>(
-    key: string,
-    items: TSource,
-  ): never;
-
-  /** Tool execution namespace. */
-  tools: {
-    /**
-     * Execute a single tool with a keyword-style request object.
-     *
-     * @param request - Tool call request.
-     * @returns Tool execution result.
-     *
-     * @sdkReference runtime 150 ctx.tools.execute(request)
-     */
-    execute<TOutput = LoosePlayObject>(
-      request: ToolExecutionRequest,
-    ): Promise<ToolExecuteResult<TOutput>>;
-  };
-  /** Customer DB query namespace for play handlers. */
-  customerDb: {
-    query<TRow extends object = Record<string, unknown>>(
-      statement: SqlQuery | string,
-      options?: {
-        maxRows?: number;
-        timeoutMs?: number;
-      },
-    ): Promise<TRow[]>;
-  };
-  /**
-   * Execute a single tool by stable step key and tool ID.
-   *
-   * Shorthand for `ctx.tools.execute(...)`; this is the preferred spelling in
-   * row-level step programs.
-   */
-  tool<TOutput = LoosePlayObject>(
-    key: string,
-    toolId: string,
-    input: Record<string, unknown>,
-    options?: { description?: string },
-  ): Promise<ToolExecuteResult<TOutput>>;
-  /**
-   * Run a reusable step program against one scalar input object.
-   *
-   * `steps().step(...)` is a composable mini-pipeline. Use `ctx.runSteps(...)`
-   * when that mini-pipeline should execute outside a row dataset. Inside a
-   * `ctx.dataset` column resolver, pass the step program directly to
-   * `.withColumn(name, program)` instead.
-   *
-   * @param program - Step program.
-   * @param input - Program input.
-   * @param options - Run options.
-   * @returns Program output.
-   *
-   * @sdkReference runtime 180 ctx.runSteps(program, input, options)
-   */
-  runSteps<TInput extends Record<string, unknown>, TOutput>(
-    program: RunnableStepProgram<TInput, TOutput>,
-    input: TInput,
-    options?: { description?: string },
-  ): Promise<TOutput>;
-  /**
-   * Create one scalar checkpoint for the whole play run.
-   *
-   * Use `ctx.step` when a value is nondeterministic, expensive, external, or
-   * useful to inspect as a named boundary. The first execution stores the
-   * JSON-serializable output under `id`; replay and retries return the stored
-   * value instead of running `run` again.
-   *
-   * Plain deterministic assignment does not need `ctx.step`. Use
-   * `ctx.dataset(...).withColumn(...)`, not `ctx.step`, when the value should become a
-   * field on each exported row.
-   *
-   * @param id - Checkpoint id.
-   * @param run - Computes the value once.
-   * @param options - Checkpoint options.
-   * @returns Checkpoint value.
-   *
-   * @sdkReference runtime 130 ctx.step(id, fn)
-   */
-  step<T>(
-    id: string,
-    run: () => T | Promise<T>,
-    options?: { staleAfterSeconds?: number },
-  ): Promise<T>;
-  /**
-   * Durable HTTP fetch.
-   *
-   * Use this for non-provider HTTP calls that must replay safely. The response
-   * is recorded under `key` so workflow replay sees the same value. Prefer
-   * `ctx.tools.execute(...)` for Deepline-managed provider APIs because tools
-   * handle auth, retries, rate limits, extraction metadata, and spend tracking.
-   * If `init.auth` comes from `ctx.secrets`, `url` must be https://.
-   *
-   * @param key - Checkpoint id.
-   * @param url - URL to fetch.
-   * @param init - Fetch options.
-   * @returns Recorded response.
-   *
-   * @sdkReference runtime 170 ctx.fetch(key, url, init)
-   */
-  fetch(
-    key: string,
-    url: string | URL,
-    init?: SecretAwareRequestInit,
-    options?: { staleAfterSeconds?: number },
-  ): Promise<{
-    ok: boolean;
-    status: number;
-    statusText: string;
-    url: string;
-    headers: Record<string, string>;
-    bodyText: string;
-    json: unknown | null;
-  }>;
-  secrets: {
-    get(name: string): SecretHandle;
-    bearer(secret: SecretHandle): SecretAuth;
-    header(header: string, secret: SecretHandle): SecretAuth;
-  };
-  /**
-   * Invoke another registered or file-backed play as a child workflow.
-   *
-   * Use this for real composition boundaries, especially when a fitting
-   * scalar prebuilt play already encodes provider order, fallbacks,
-   * normalization, and no-result behavior. Do not invoke plays through
-   * `ctx.tools.execute`; tools and plays are separate namespaces.
-   *
-   * `key` is the stable child-call identity for idempotency and traceability.
-   *
-   * @param key - Stable child-call key.
-   * @param playRef - Registered play name, play handle, or file-backed play reference.
-   * @param input - Input object passed to the child play.
-   * @param options - Child play options.
-   * @returns Child play output.
-   *
-   * @sdkReference runtime 140 ctx.runPlay(key, playRef, input, options)
-   */
-  runPlay<TOutput = unknown>(
-    key: string,
-    playRef: string | PlayReferenceLike,
-    input: Record<string, unknown>,
-    options?: PlayCallOptions,
-  ): Promise<TOutput>;
-
-  /**
-   * Emit a log line visible in `play tail` and the play's progress logs.
-   *
-   * @param message - Log message (plain text)
-   */
-  log(message: string): void;
-
-  /**
-   * Pause play execution for the specified duration.
-   *
-   * Uses Temporal's durable timer — safe across worker restarts.
-   *
-   * @param ms - Duration in milliseconds
-   */
-  sleep(ms: number): Promise<void>;
-
-  /**
-   * @deprecated Read submitted play input from the handler's second argument:
-   * `definePlay('example', async (ctx, input) => ...)`. This legacy field is
-   * not the supported V2 play input API.
-   */
-  readonly input: Record<string, unknown>;
-}
+export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
 
 /**
  * Handle to a running play execution.
@@ -1157,10 +649,7 @@ export type PrebuiltPlayRef = {
   readonly name: string;
 };
 
-export type PlayReferenceLike = {
-  readonly playName?: string;
-  readonly name?: string;
-};
+export type PlayReferenceLike = PlayAuthoringReferenceLike;
 
 export type {
   PlayDataset,
@@ -1168,14 +657,8 @@ export type {
   PlayDatasetRow,
 } from '../../shared_libs/plays/dataset.js';
 
-export type PlayReturnObject = Record<string, unknown> & {
-  readonly _metadata?: never;
-};
-
-export type PlayInputContract<TInput> = {
-  readonly schema: Record<string, unknown>;
-  readonly __inputType?: TInput;
-};
+export type PlayReturnObject = PlayAuthoringReturnObject;
+export type PlayInputContract<TInput> = PlayAuthoringInputContract<TInput>;
 
 /**
  * Object-form play definition accepted by `definePlay(config)`.
@@ -1187,24 +670,10 @@ export type PlayInputContract<TInput> = {
  *
  * @sdkReference runtime 020
  */
-export type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
-  /** Play id/name. */
-  id: string;
-  /** Human-readable one-line description of what this play does. */
-  description?: string;
-  /** Input schema. */
-  input: PlayInputContract<TInput>;
-  /** Play function. */
-  run: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>;
-  /** Trigger bindings. */
-  bindings?: PlayBindings;
-  /** Billing options. */
-  billing?: PlayBindings['billing'];
-  /** Requested prebuilt sandbox and runtime deadline. */
-  runtime?: PlayBindings['runtime'];
-  /** Runtime compatibility override. Omit for the current typed contract. */
-  compatibility?: PlayBindings['compatibility'];
-};
+export type DefinePlayConfig<
+  TInput,
+  TOutput extends PlayReturnObject,
+> = PlayAuthoringDefineConfig<TInput, TOutput, DeeplinePlayRuntimeContext>;
 
 class DeeplineConditionalStepResolver<
   Row,
@@ -1356,20 +825,15 @@ export function runIf<Row, Value>(
  * console.log(myPlay.bindings); // undefined (no cron/webhook)
  * ```
  */
-export type DefinedPlay<TInput, TOutput extends PlayReturnObject> = ((
-  ctx: DeeplinePlayRuntimeContext,
-  input: TInput,
-) => Promise<TOutput>) &
-  DeeplineNamedPlay<TInput, TOutput> & {
-    /** Optional trigger bindings (cron, webhook). */
-    readonly bindings?: PlayBindings;
-    /** Requested prebuilt sandbox and runtime deadline. */
-    readonly runtime?: PlayBindings['runtime'];
-    /** Runtime compatibility explicitly selected by the author. */
-    readonly compatibility?: PlayBindings['compatibility'];
-    /** The play's name (same as `.name`). */
-    readonly playName: string;
-  };
+export type DefinedPlay<
+  TInput,
+  TOutput extends PlayReturnObject,
+> = PlayAuthoringDefinedPlay<
+  TInput,
+  TOutput,
+  DeeplinePlayRuntimeContext,
+  DeeplineNamedPlay<TInput, TOutput>
+>;
 
 type PlayMetadata = {
   name: string;
@@ -2017,12 +1481,7 @@ function toolExecutionEnvelopeToResult(
 export function defineInput<TInput>(
   schema: Record<string, unknown>,
 ): PlayInputContract<TInput> {
-  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-    throw new Error(
-      'defineInput<T>(schema) requires a JSON-schema-like object.',
-    );
-  }
-  return { schema };
+  return createPlayInputContract<TInput>(schema);
 }
 
 /**