deepline 0.1.70 → 0.1.71

package/dist/index.d.mts

@@ -19,14 +19,14 @@ interface PlayStaticPipelineSnapshot {
     csvArg?: string;
     hasInlineData?: boolean;
     csvDescription?: string;
-    mapDescription?: string;
+    datasetDescription?: string;
     fields: string[];
     stages?: PlayStaticSubstepSnapshot[];
     substeps: PlayStaticSubstepSnapshot[];
     sheetContract?: PlaySheetContractSnapshot | null;
     sheetContractErrors?: string[];
 }
-type PlaySheetColumnSourceSnapshot = 'input' | 'mapField' | 'waterfallStep' | 'childPlayColumn';
+type PlaySheetColumnSourceSnapshot = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
 interface PlaySheetColumnContractSnapshot {
     id: string;
     sqlName: string;
@@ -63,7 +63,7 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
     callDepth?: number;
     callPath?: string[];
 } | {
-    type: 'map';
+    type: 'dataset';
     field: string;
     name?: string;
     tableNamespace?: string;
@@ -827,7 +827,7 @@ interface PlayDetail {
     deltaCursor: number;
 }
 interface ClearPlayHistoryRequest {
-    /** Optional explicit ctx.map keys to clear. Omit to clear all discovered sheets for the play. */
+    /** Optional explicit ctx.dataset keys to clear. Omit to clear all discovered sheets for the play. */
     tableNamespaces?: string[];
 }
 interface ClearPlayHistoryResult {
@@ -1900,13 +1900,13 @@ type PlayDatasetTransformOptions = {
     sourceLabel?: string | null;
 };
 /**
- * Durable handle for rows produced by `ctx.csv(...)` or `ctx.map(...).run()`.
+ * Durable handle for rows produced by `ctx.csv(...)` or `ctx.dataset(...).run()`.
  *
  * A `PlayDataset` is not a normal in-memory array. It points at runtime-managed
  * rows, usually backed by persisted sheet storage, and carries metadata such as
  * dataset kind, dataset id, table namespace, count, and preview rows.
  *
- * Pass dataset handles directly into later `ctx.map(...)` stages by default so
+ * Pass dataset handles directly into later `ctx.dataset(...)` stages by default so
  * Deepline keeps row progress, retries, memory use, and table output under
  * runtime control. Use `count()` and `peek()` for bounded inspection. Use
  * `materialize(limit)` or async iteration only when the dataset is intentionally
@@ -2161,27 +2161,29 @@ type PlayStepProgramStep = {
     readonly name: string;
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
-type MapStepResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
-type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
+type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
+type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
     /**
-     * Define one output column for every row in this map dataset.
+     * Define one output column for every row in this dataset.
      *
      * The `name` becomes a field on each output row. For example,
-     * `.step('contact', ...)` creates `row.contact` in later map stages; it does
+     * `.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:
-     * `.step('email', row => row.contact?.email ?? null)`.
+     * `.withColumn('email', row => row.contact?.email ?? null)`.
      *
      * @param name - Output column name.
      * @param resolver - Computes the value for one row.
-     * @returns The same map builder with the new column type.
+     * @returns The same dataset builder with the new column type.
      */
-    step<Name extends string, Value>(name: Name, resolver: MapStepResolver<OutputRow, Value>): MapStepBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    /** @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 `.step(...)`.
+     * with original fields merged with the columns produced by `.withColumn(...)`.
      *
      * @param options - Run options.
      * @returns Output rows as a dataset handle.
@@ -2240,10 +2242,10 @@ type CsvOptions = {
  *     description: 'Look up company details by domain.',
  *   });
  *
- *   // Fan-out: process items with named steps
+ *   // Fan-out: process items with named columns
  *   const enriched = await ctx
- *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }])
- *     .step('company', (row, rowCtx) =>
+ *     .dataset('companies', [{ domain: 'a.com' }, { domain: 'b.com' }])
+ *     .withColumn('company', (row, rowCtx) =>
  *       rowCtx.tools.execute({
  *         id: 'company_search',
  *         tool: 'test_company_search',
@@ -2273,7 +2275,7 @@ 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.map}. The path is
+     * 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`.
      *
@@ -2285,15 +2287,15 @@ interface DeeplinePlayRuntimeContext {
      * @param path - Staged CSV path.
      * @param options - CSV load options.
      *
-     * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.map(...)`.
+     * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.dataset(...)`.
      */
     csv<T = Record<string, unknown>>(path: string, options?: CsvOptions): Promise<PlayDataset<T>>;
     /**
      * Create a persisted row dataset/table from input rows.
      *
-     * `ctx.map` is Deepline's row-work primitive. It records row identity,
+     * `ctx.dataset` is Deepline's row-work primitive. It records row identity,
      * progress, retries, table output, and idempotency for a collection of rows.
-     * Use `.step(name, resolver)` on the returned builder to define output
+     * 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
@@ -2301,10 +2303,10 @@ interface DeeplinePlayRuntimeContext {
      * automatically from input row content unless `.run({ key: ... })` overrides
      * it with stable business fields such as `domain`, `email`, or `linkedin_url`.
      *
-     * By default, `ctx.map` is row-preserving: one input row produces one output
+     * By default, `ctx.dataset` is row-preserving: one input row produces one output
      * row, with original fields merged with the columns produced by
-     * `.step(...)`. If one input entity must become many output rows, use the
-     * documented expand/flatten recipe instead of assuming `ctx.map` changes
+     * `.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
@@ -2315,8 +2317,8 @@ interface DeeplinePlayRuntimeContext {
      * @example Single tool per row
      * ```typescript
      * const results = await ctx
-     *   .map('companies', leads)
-     *   .step('company', (row, ctx) =>
+     *   .dataset('companies', leads)
+     *   .withColumn('company', (row, ctx) =>
      *     ctx.tools.execute({
      *       id: 'company_search',
      *       tool: 'test_company_search',
@@ -2330,20 +2332,24 @@ interface DeeplinePlayRuntimeContext {
      * @example Multiple columns with pre/post logic
      * ```typescript
      * const results = await ctx
-     *   .map('leads', leads)
-     *   .step('company', (row, 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.',
      *     }))
-     *   .step('score', (row) =>
+     *   .withColumn('score', (row) =>
      *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
      *   .run({ description: 'Enrich leads.' });
      * ```
      */
-    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): MapStepBuilder<TItem, TItem>;
+    dataset<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): DatasetBuilder<TItem, TItem>;
+    /**
+     * @deprecated `ctx.map(...)` was replaced by `ctx.dataset(...)`.
+     */
+    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): never;
     /** Tool execution namespace. */
     tools: {
         /**
@@ -2370,8 +2376,8 @@ interface DeeplinePlayRuntimeContext {
      *
      * `steps().step(...)` is a composable mini-pipeline. Use `ctx.runSteps(...)`
      * when that mini-pipeline should execute outside a row dataset. Inside a
-     * `ctx.map` column resolver, pass the step program directly to
-     * `.step(name, program)` instead.
+     * `ctx.dataset` column resolver, pass the step program directly to
+     * `.withColumn(name, program)` instead.
      *
      * @param program - Step program.
      * @param input - Program input.
@@ -2390,7 +2396,7 @@ interface DeeplinePlayRuntimeContext {
      * value instead of running `run` again.
      *
      * Plain deterministic assignment does not need `ctx.step`. Use
-     * `ctx.map(...).step(...)`, not `ctx.step`, when the value should become a
+     * `ctx.dataset(...).withColumn(...)`, not `ctx.step`, when the value should become a
      * field on each exported row.
      *
      * @param id - Checkpoint id.
@@ -2425,6 +2431,22 @@ interface DeeplinePlayRuntimeContext {
         bodyText: string;
         json: unknown | null;
     }>;
+    /**
+     * 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.
+     */
     secrets: {
         get(name: string): SecretHandle;
         bearer(secret: SecretHandle): SecretAuth;
@@ -2635,7 +2657,8 @@ type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
     billing?: PlayBindings['billing'];
 };
 declare function steps<TInput>(): StepProgram<TInput, TInput, TInput>;
-declare function when<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): ConditionalStepResolver<Row, Value, null>;
+declare function when<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): never;
+declare function runIf<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): ConditionalStepResolver<Row, Value, null>;
 /**
  * A defined play: both a callable function and a named play handle.
  *
@@ -2824,8 +2847,8 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *   const leads = await ctx.csv(input.csv);
  *   ctx.log(`Processing ${await leads.count()} rows`);
  *   const results = await ctx
- *     .map('companies', leads)
- *     .step('company', (row, ctx) =>
+ *     .dataset('companies', leads)
+ *     .withColumn('company', (row, ctx) =>
  *       ctx.tools.execute({
  *         id: 'company_search',
  *         tool: 'test_company_search',
@@ -3047,4 +3070,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_TOOL_CATEGORIES, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, type MapStepBuilder, type MapStepResolver, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.d.ts

@@ -19,14 +19,14 @@ interface PlayStaticPipelineSnapshot {
     csvArg?: string;
     hasInlineData?: boolean;
     csvDescription?: string;
-    mapDescription?: string;
+    datasetDescription?: string;
     fields: string[];
     stages?: PlayStaticSubstepSnapshot[];
     substeps: PlayStaticSubstepSnapshot[];
     sheetContract?: PlaySheetContractSnapshot | null;
     sheetContractErrors?: string[];
 }
-type PlaySheetColumnSourceSnapshot = 'input' | 'mapField' | 'waterfallStep' | 'childPlayColumn';
+type PlaySheetColumnSourceSnapshot = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
 interface PlaySheetColumnContractSnapshot {
     id: string;
     sqlName: string;
@@ -63,7 +63,7 @@ type PlayStaticSubstepSnapshot = PlayStaticSubstepMetadataSnapshot & ({
     callDepth?: number;
     callPath?: string[];
 } | {
-    type: 'map';
+    type: 'dataset';
     field: string;
     name?: string;
     tableNamespace?: string;
@@ -827,7 +827,7 @@ interface PlayDetail {
     deltaCursor: number;
 }
 interface ClearPlayHistoryRequest {
-    /** Optional explicit ctx.map keys to clear. Omit to clear all discovered sheets for the play. */
+    /** Optional explicit ctx.dataset keys to clear. Omit to clear all discovered sheets for the play. */
     tableNamespaces?: string[];
 }
 interface ClearPlayHistoryResult {
@@ -1900,13 +1900,13 @@ type PlayDatasetTransformOptions = {
     sourceLabel?: string | null;
 };
 /**
- * Durable handle for rows produced by `ctx.csv(...)` or `ctx.map(...).run()`.
+ * Durable handle for rows produced by `ctx.csv(...)` or `ctx.dataset(...).run()`.
  *
  * A `PlayDataset` is not a normal in-memory array. It points at runtime-managed
  * rows, usually backed by persisted sheet storage, and carries metadata such as
  * dataset kind, dataset id, table namespace, count, and preview rows.
  *
- * Pass dataset handles directly into later `ctx.map(...)` stages by default so
+ * Pass dataset handles directly into later `ctx.dataset(...)` stages by default so
  * Deepline keeps row progress, retries, memory use, and table output under
  * runtime control. Use `count()` and `peek()` for bounded inspection. Use
  * `materialize(limit)` or async iteration only when the dataset is intentionally
@@ -2161,27 +2161,29 @@ type PlayStepProgramStep = {
     readonly name: string;
     readonly resolver: StepResolver<Record<string, unknown>, unknown> | ConditionalStepResolver<Record<string, unknown>, unknown> | StepProgramResolver<Record<string, unknown>, unknown>;
 };
-type MapStepResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
-type MapStepBuilder<InputRow extends object, OutputRow extends object> = {
+type ColumnResolver<Row, Value> = StepResolver<Row, Value> | ConditionalStepResolver<Row, Value> | StepProgramResolver<Row, Value>;
+type DatasetBuilder<InputRow extends object, OutputRow extends object> = {
     /**
-     * Define one output column for every row in this map dataset.
+     * Define one output column for every row in this dataset.
      *
      * The `name` becomes a field on each output row. For example,
-     * `.step('contact', ...)` creates `row.contact` in later map stages; it does
+     * `.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:
-     * `.step('email', row => row.contact?.email ?? null)`.
+     * `.withColumn('email', row => row.contact?.email ?? null)`.
      *
      * @param name - Output column name.
      * @param resolver - Computes the value for one row.
-     * @returns The same map builder with the new column type.
+     * @returns The same dataset builder with the new column type.
      */
-    step<Name extends string, Value>(name: Name, resolver: MapStepResolver<OutputRow, Value>): MapStepBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;
+    /** @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 `.step(...)`.
+     * with original fields merged with the columns produced by `.withColumn(...)`.
      *
      * @param options - Run options.
      * @returns Output rows as a dataset handle.
@@ -2240,10 +2242,10 @@ type CsvOptions = {
  *     description: 'Look up company details by domain.',
  *   });
  *
- *   // Fan-out: process items with named steps
+ *   // Fan-out: process items with named columns
  *   const enriched = await ctx
- *     .map('companies', [{ domain: 'a.com' }, { domain: 'b.com' }])
- *     .step('company', (row, rowCtx) =>
+ *     .dataset('companies', [{ domain: 'a.com' }, { domain: 'b.com' }])
+ *     .withColumn('company', (row, rowCtx) =>
  *       rowCtx.tools.execute({
  *         id: 'company_search',
  *         tool: 'test_company_search',
@@ -2273,7 +2275,7 @@ 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.map}. The path is
+     * 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`.
      *
@@ -2285,15 +2287,15 @@ interface DeeplinePlayRuntimeContext {
      * @param path - Staged CSV path.
      * @param options - CSV load options.
      *
-     * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.map(...)`.
+     * @returns A {@link PlayDataset} whose rows should usually flow directly into `ctx.dataset(...)`.
      */
     csv<T = Record<string, unknown>>(path: string, options?: CsvOptions): Promise<PlayDataset<T>>;
     /**
      * Create a persisted row dataset/table from input rows.
      *
-     * `ctx.map` is Deepline's row-work primitive. It records row identity,
+     * `ctx.dataset` is Deepline's row-work primitive. It records row identity,
      * progress, retries, table output, and idempotency for a collection of rows.
-     * Use `.step(name, resolver)` on the returned builder to define output
+     * 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
@@ -2301,10 +2303,10 @@ interface DeeplinePlayRuntimeContext {
      * automatically from input row content unless `.run({ key: ... })` overrides
      * it with stable business fields such as `domain`, `email`, or `linkedin_url`.
      *
-     * By default, `ctx.map` is row-preserving: one input row produces one output
+     * By default, `ctx.dataset` is row-preserving: one input row produces one output
      * row, with original fields merged with the columns produced by
-     * `.step(...)`. If one input entity must become many output rows, use the
-     * documented expand/flatten recipe instead of assuming `ctx.map` changes
+     * `.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
@@ -2315,8 +2317,8 @@ interface DeeplinePlayRuntimeContext {
      * @example Single tool per row
      * ```typescript
      * const results = await ctx
-     *   .map('companies', leads)
-     *   .step('company', (row, ctx) =>
+     *   .dataset('companies', leads)
+     *   .withColumn('company', (row, ctx) =>
      *     ctx.tools.execute({
      *       id: 'company_search',
      *       tool: 'test_company_search',
@@ -2330,20 +2332,24 @@ interface DeeplinePlayRuntimeContext {
      * @example Multiple columns with pre/post logic
      * ```typescript
      * const results = await ctx
-     *   .map('leads', leads)
-     *   .step('company', (row, 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.',
      *     }))
-     *   .step('score', (row) =>
+     *   .withColumn('score', (row) =>
      *     row.company?.employeeCount > 100 ? 'enterprise' : 'smb')
      *   .run({ description: 'Enrich leads.' });
      * ```
      */
-    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): MapStepBuilder<TItem, TItem>;
+    dataset<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): DatasetBuilder<TItem, TItem>;
+    /**
+     * @deprecated `ctx.map(...)` was replaced by `ctx.dataset(...)`.
+     */
+    map<TItem extends object>(key: string, items: PlayDatasetInput<TItem>): never;
     /** Tool execution namespace. */
     tools: {
         /**
@@ -2370,8 +2376,8 @@ interface DeeplinePlayRuntimeContext {
      *
      * `steps().step(...)` is a composable mini-pipeline. Use `ctx.runSteps(...)`
      * when that mini-pipeline should execute outside a row dataset. Inside a
-     * `ctx.map` column resolver, pass the step program directly to
-     * `.step(name, program)` instead.
+     * `ctx.dataset` column resolver, pass the step program directly to
+     * `.withColumn(name, program)` instead.
      *
      * @param program - Step program.
      * @param input - Program input.
@@ -2390,7 +2396,7 @@ interface DeeplinePlayRuntimeContext {
      * value instead of running `run` again.
      *
      * Plain deterministic assignment does not need `ctx.step`. Use
-     * `ctx.map(...).step(...)`, not `ctx.step`, when the value should become a
+     * `ctx.dataset(...).withColumn(...)`, not `ctx.step`, when the value should become a
      * field on each exported row.
      *
      * @param id - Checkpoint id.
@@ -2425,6 +2431,22 @@ interface DeeplinePlayRuntimeContext {
         bodyText: string;
         json: unknown | null;
     }>;
+    /**
+     * 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.
+     */
     secrets: {
         get(name: string): SecretHandle;
         bearer(secret: SecretHandle): SecretAuth;
@@ -2635,7 +2657,8 @@ type DefinePlayConfig<TInput, TOutput extends PlayReturnObject> = {
     billing?: PlayBindings['billing'];
 };
 declare function steps<TInput>(): StepProgram<TInput, TInput, TInput>;
-declare function when<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): ConditionalStepResolver<Row, Value, null>;
+declare function when<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): never;
+declare function runIf<Row, Value>(predicate: (row: Row, index: number) => boolean | Promise<boolean>, resolver: StepResolver<Row, Value>): ConditionalStepResolver<Row, Value, null>;
 /**
  * A defined play: both a callable function and a named play handle.
  *
@@ -2824,8 +2847,8 @@ declare function defineInput<TInput>(schema: Record<string, unknown>): PlayInput
  *   const leads = await ctx.csv(input.csv);
  *   ctx.log(`Processing ${await leads.count()} rows`);
  *   const results = await ctx
- *     .map('companies', leads)
- *     .step('company', (row, ctx) =>
+ *     .dataset('companies', leads)
+ *     .withColumn('company', (row, ctx) =>
  *       ctx.tools.execute({
  *         id: 'company_search',
  *         tool: 'test_company_search',
@@ -3047,4 +3070,4 @@ declare function writeCsvOutputFile(rows: Array<Record<string, unknown>>, stem:
  */
 declare function extractSummaryFields(payload: unknown): Record<string, Scalar>;
 
-export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_TOOL_CATEGORIES, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, type MapStepBuilder, type MapStepResolver, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };
+export { AuthError, type ClearPlayHistoryRequest, type ClearPlayHistoryResult, type ColumnMap, type ColumnResolver, type ConditionalStepResolver, ConfigError, type CsvInput, DEEPLINE_TOOL_CATEGORIES, type DatasetBuilder, Deepline, DeeplineClient, type DeeplineClientOptions, DeeplineContext, DeeplineError, type DeeplineNamedPlay, type DeeplinePlayRuntimeContext, type DeeplineToolCategory, type DefinePlayConfig, type DefinedPlay, type FileInput, type LiveEventEnvelope, PLAY_BOOTSTRAP_COMPANY_FIELDS, PLAY_BOOTSTRAP_COMPANY_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_CONTACT_FIELDS, PLAY_BOOTSTRAP_FINDER_KINDS, PLAY_BOOTSTRAP_OUTPUT_FIELD_BY_FINDER, PLAY_BOOTSTRAP_PEOPLE_PROVIDER_CATEGORY, PLAY_BOOTSTRAP_PROVIDER_CATEGORY_BY_FINDER, PLAY_BOOTSTRAP_SOURCE_KINDS, PLAY_BOOTSTRAP_STAGE_KINDS, PLAY_BOOTSTRAP_TEMPLATES, PROD_URL, type PlayBindings, type PlayBootstrapEntityKind, type PlayBootstrapFinderKind, type PlayDataset, type PlayDatasetInput, type PlayInputContract, type PlayJob, type PlayListItem, type PlayLiveEvent, type PlayRevisionSummary, type PlayRunResult, type PlayRunStart, type PlayStatus, type PlayStepProgramStep, type PrebuiltPlayRef, type PublishPlayVersionRequest, type PublishPlayVersionResult, RateLimitError, type ResolvedConfig, SDK_API_CONTRACT, SDK_VERSION, type StartPlayRunRequest, type StepProgram, type StepProgramResolver, type StepResolver, type ToolDefinition, type ToolExecuteResult, type ToolExecution, type ToolMetadata, defineInput, definePlay, defineWorkflow, extractSummaryFields, formatPlayBootstrapFinderKinds, formatPlayBootstrapFinderKindsForSentence, formatPlayBootstrapTemplates, getDefinedPlayMetadata, isPlayBootstrapFinderKind, isPlayBootstrapTemplate, resolveConfig, runIf, steps, tryConvertToList, when, writeCsvOutputFile, writeJsonOutputFile };

package/dist/index.js

@@ -52,6 +52,7 @@ __export(src_exports, {
   isPlayBootstrapFinderKind: () => isPlayBootstrapFinderKind,
   isPlayBootstrapTemplate: () => isPlayBootstrapTemplate,
   resolveConfig: () => resolveConfig,
+  runIf: () => runIf,
   steps: () => steps,
   tryConvertToList: () => tryConvertToList,
   when: () => when,
@@ -241,10 +242,10 @@ var import_node_path2 = require("path");
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.70",
-  apiContract: "2026-05-play-bootstrap-dataset-summary",
+  version: "0.1.71",
+  apiContract: "2026-06-dataset-column-syntax-cutover",
   supportPolicy: {
-    latest: "0.1.70",
+    latest: "0.1.71",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -2435,6 +2436,13 @@ function steps() {
   return new DeeplineStepProgram([]);
 }
 function when(predicate, resolver) {
+  void predicate;
+  void resolver;
+  throw new Error(
+    "when(...) has been replaced by runIf(...). Use runIf(predicate, resolver)."
+  );
+}
+function runIf(predicate, resolver) {
   return new DeeplineConditionalStepResolver(predicate, resolver, null);
 }
 var PLAY_METADATA_SYMBOL = /* @__PURE__ */ Symbol.for("deepline.play.metadata");
@@ -3011,6 +3019,7 @@ function extractSummaryFields(payload) {
   isPlayBootstrapFinderKind,
   isPlayBootstrapTemplate,
   resolveConfig,
+  runIf,
   steps,
   tryConvertToList,
   when,

package/dist/index.mjs

@@ -179,10 +179,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.70",
-  apiContract: "2026-05-play-bootstrap-dataset-summary",
+  version: "0.1.71",
+  apiContract: "2026-06-dataset-column-syntax-cutover",
   supportPolicy: {
-    latest: "0.1.70",
+    latest: "0.1.71",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -2373,6 +2373,13 @@ function steps() {
   return new DeeplineStepProgram([]);
 }
 function when(predicate, resolver) {
+  void predicate;
+  void resolver;
+  throw new Error(
+    "when(...) has been replaced by runIf(...). Use runIf(predicate, resolver)."
+  );
+}
+function runIf(predicate, resolver) {
   return new DeeplineConditionalStepResolver(predicate, resolver, null);
 }
 var PLAY_METADATA_SYMBOL = /* @__PURE__ */ Symbol.for("deepline.play.metadata");
@@ -2948,6 +2955,7 @@ export {
   isPlayBootstrapFinderKind,
   isPlayBootstrapTemplate,
   resolveConfig,
+  runIf,
   steps,
   tryConvertToList,
   when,