deepline 0.1.69 → 0.1.71

package/README.md

@@ -212,8 +212,8 @@ export default definePlay('rate-limit-repro', async (ctx) => {
     row_number: i + 1,
   }));
 
-  const results = await ctx.map('rate_limit_probes', items)
-  .step("result", (row, ctx) =>
+  const results = await ctx.dataset('rate_limit_probes', items)
+  .withColumn("result", (row, ctx) =>
       ctx.tools.execute({
         id: 'rate_limit_probe',
         tool: 'test_rate_limit',
@@ -242,12 +242,12 @@ deepline play run --file rate-limit-repro.play.ts --watch
 
 ### 4. Fallback variant (multi-step with rate limits)
 
-Use `steps()` and `when()` to express row-level fallback sequences. Skipped
+Use `steps()` and `runIf()` to express row-level fallback sequences. Skipped
 conditional steps yield `null`.
 
 ```bash
 cat > rate-limit-waterfall.play.ts << 'TS'
-import { definePlay, steps, when } from 'deepline';
+import { definePlay, runIf, steps } from 'deepline';
 
 export default definePlay('rate-limit-waterfall', async (ctx) => {
   const leads = Array.from({ length: 24 }, (_, i) => ({
@@ -267,7 +267,7 @@ export default definePlay('rate-limit-waterfall', async (ctx) => {
         },
         description: 'Exercise primary rate-limit behavior.',
       }))
-    .step("backup_probe", when(
+    .step("backup_probe", runIf(
       (row) => !row.primary_probe,
       (row, ctx) =>
         ctx.tools.execute({
@@ -284,8 +284,8 @@ export default definePlay('rate-limit-waterfall', async (ctx) => {
     .return((row) => row.primary_probe ?? row.backup_probe ?? null);
 
   // Fan out over leads — each gets a row-level fallback sequence
-  const results = await ctx.map('leads', leads)
-    .step("probe", probeFallback)
+  const results = await ctx.dataset('leads', leads)
+    .withColumn("probe", probeFallback)
     .run();
 
   return results;

package/dist/cli/index.js

@@ -229,10 +229,10 @@ var import_node_path2 = require("path");
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.69",
-  apiContract: "2026-05-play-bootstrap-dataset-summary",
+  version: "0.1.71",
+  apiContract: "2026-06-dataset-column-syntax-cutover",
   supportPolicy: {
-    latest: "0.1.69",
+    latest: "0.1.71",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -1037,6 +1037,7 @@ var DeeplineClient = class {
       ...request.inputFile ? { inputFile: request.inputFile } : {},
       ...request.packagedFiles?.length ? { packagedFiles: request.packagedFiles } : {},
       ...request.force ? { force: true } : {},
+      ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
       ...request.profile ? { profile: request.profile } : {}
     };
     for await (const event of this.http.streamSse(
@@ -6884,7 +6885,7 @@ function playInspectionComments(playRef, indent) {
 function accessorExpression(base, field) {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field) ? `${base}.${field}` : `${base}[${jsString(field)}]`;
 }
-function needsWhenImport(options) {
+function needsRunIfImport(options) {
   return stageProviders(options.email).length > 1 || stageProviders(options.phone).length > 1;
 }
 function sourceCollectionTypeName(entity) {
@@ -7186,7 +7187,7 @@ function generateFinderPlayStep(input2) {
     "        ",
     input2.stage.value
   );
-  return `.step(${jsString(outputField)}, async (row, rowCtx) => {
+  return `.withColumn(${jsString(outputField)}, async (row, rowCtx) => {
       const ${input2.aggregateStepName}Input = ${payload};
       throw new Error(${jsString(`TODO: map ${input2.aggregateStepName}Input for ${input2.stage.value}, then delete this throw.`)});
       const ${input2.aggregateStepName}Result = await rowCtx.runPlay<${resultTypeName}>(
@@ -7232,12 +7233,12 @@ function generateFinderProviderStep(input2) {
   const stepName = input2.stepNames[input2.index];
   switch (input2.index) {
     case 0:
-      return `.step(${jsString(stepName)}, ${input2.resolver})`;
+      return `.withColumn(${jsString(stepName)}, ${input2.resolver})`;
     default: {
       const priorCandidates = input2.stepNames.slice(0, input2.index).map((name) => `row.${name}`).join(", ");
-      return `.step(
+      return `.withColumn(
       ${jsString(stepName)},
-      when(
+      runIf(
         (row) => ![${priorCandidates}].some((candidate) => ${optionalFinderValueExpression("candidate", input2.outputField)}),
         ${input2.resolver},
       ),
@@ -7271,9 +7272,9 @@ function generateFinderProviderWaterfall(input2) {
   );
   const candidateNames = stepNames.map((name) => `row.${name}`).join(", ");
   return `// ${input2.aggregateStepName} provider waterfall. Each provider leg is active once its TODO throw is removed;
-    // delete or comment out legs you do not want before running. Later legs are gated with when(...).
+    // delete or comment out legs you do not want before running. Later legs are gated with runIf(...).
     ${providerSteps.join("\n    ")}
-    .step(${jsString(input2.aggregateStepName)}, (row) => {
+    .withColumn(${jsString(input2.aggregateStepName)}, (row) => {
       const candidates = [${candidateNames}];
       const match = candidates.find((candidate) => ${optionalFinderValueExpression("candidate", input2.outputField)});
       return ${optionalFinderValueExpression("match", input2.outputField)} ?? null;
@@ -7328,7 +7329,7 @@ function generateBootstrapPlaySource(input2) {
     rowTypeDefinitions,
     finderPlayResultTypes
   ].filter((definition) => definition.trim().length > 0).join("\n\n");
-  const importNames = needsWhenImport(input2.options) ? "definePlay, when" : "definePlay";
+  const importNames = needsRunIfImport(input2.options) ? "definePlay, runIf" : "definePlay";
   return `import { ${importNames} } from 'deepline';
 
 ${typeDefinitions}
@@ -7347,7 +7348,7 @@ export default definePlay(${jsString(input2.options.name)}, async (ctx, input: I
   }
 
   const rows = await ctx
-    .map('bootstrap_rows', rowsToProcess)${mapSteps}
+    .dataset('bootstrap_rows', rowsToProcess)${mapSteps}
     .run({
       key: (_row, index) => index,
       description: ${jsString(`Bootstrap ${input2.options.template}: seed source rows, run requested stages, then return the mapped rows.`)},
@@ -7857,7 +7858,7 @@ function normalizePlayNameForSheet(value) {
 function normalizeTableNamespace(value) {
   return validateIdentifierPart(
     value,
-    "ctx.map() key",
+    "ctx.dataset() key",
     MAP_KEY_NAMESPACE_MAX_LENGTH
   );
 }
@@ -7867,7 +7868,7 @@ function validatePlaySheetTableName(playName, tableNamespace) {
   const resolved = `${playSegment}_${keySegment}`;
   if (resolved.length > POSTGRES_IDENTIFIER_MAX_LENGTH) {
     throw new Error(
-      `Play sheet table name is too long after normalization (${resolved.length}/63). Shorten the play name or ctx.map() key. Resolved table name: "${resolved}".`
+      `Play sheet table name is too long after normalization (${resolved.length}/63). Shorten the play name or ctx.dataset() key. Resolved table name: "${resolved}".`
     );
   }
   return resolved;
@@ -7947,6 +7948,7 @@ ${EXTRACTED_GETTER_ERROR_HINT}`;
 }
 
 // src/cli/commands/play.ts
+var PLAY_START_STREAM_FAST_COMPLETION_WAIT_MS = 2500;
 var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--json",
   "--wait",
@@ -8889,6 +8891,10 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   let eventCount = 0;
   let firstRunIdMs = null;
   let lastPhase = null;
+  const startRequest = {
+    ...input2.request,
+    waitForCompletionMs: typeof input2.request.waitForCompletionMs === "number" ? input2.request.waitForCompletionMs : PLAY_START_STREAM_FAST_COMPLETION_WAIT_MS
+  };
   const timeout = input2.waitTimeoutMs === null ? null : setTimeout(
     () => {
       timedOut = true;
@@ -8897,7 +8903,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
     Math.max(1, input2.waitTimeoutMs)
   );
   try {
-    for await (const event of input2.client.startPlayRunStream(input2.request, {
+    for await (const event of input2.client.startPlayRunStream(startRequest, {
       signal: controller.signal
     })) {
       eventCount += 1;
@@ -10105,10 +10111,66 @@ function formatActiveRunConflictError(input2) {
   lines.push(`  rerun: add --force to the same deepline plays run command`);
   return lines.join("\n");
 }
+var PLAY_SYNTAX_MIGRATION_ERROR_MARKERS = [
+  "ctx.map(...) has been replaced by ctx.dataset(...)",
+  "Dataset .step(...) has been replaced by .withColumn(...)"
+];
+function stringArrayField(record, key) {
+  const value = record[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string");
+}
+function extractPlayValidationErrors(value) {
+  if (value instanceof DeeplineError) {
+    return extractPlayValidationErrors(value.details);
+  }
+  if (!isRecord4(value)) {
+    return [];
+  }
+  const directErrors = stringArrayField(value, "errors");
+  if (directErrors.length > 0) {
+    return directErrors;
+  }
+  for (const key of ["response", "error", "details"]) {
+    const nestedErrors = extractPlayValidationErrors(value[key]);
+    if (nestedErrors.length > 0) {
+      return nestedErrors;
+    }
+  }
+  return [];
+}
+function orderPlayValidationErrors(errors) {
+  const uniqueErrors = [...new Set(errors)];
+  const migrationErrors = uniqueErrors.filter(
+    (error) => PLAY_SYNTAX_MIGRATION_ERROR_MARKERS.some(
+      (marker) => error.includes(marker)
+    )
+  );
+  const remainingErrors = uniqueErrors.filter(
+    (error) => !migrationErrors.includes(error)
+  );
+  return [...migrationErrors, ...remainingErrors];
+}
+function normalizePlayValidationError(error) {
+  const validationErrors = extractPlayValidationErrors(error);
+  if (validationErrors.length === 0) {
+    return error;
+  }
+  const message = orderPlayValidationErrors(validationErrors).join("\n");
+  if (!message.trim()) {
+    return error;
+  }
+  return new DeeplineError(
+    message,
+    error instanceof DeeplineError ? error.statusCode : void 0,
+    error instanceof DeeplineError ? error.code : "PLAY_VALIDATION_ERROR",
+    error instanceof DeeplineError ? error.details : void 0
+  );
+}
 function normalizePlayStartError(error, playName) {
   const activeRuns = extractActiveRunsFromError(error);
   if (activeRuns.length === 0) {
-    return error;
+    return normalizePlayValidationError(error);
   }
   return new DeeplineError(
     formatActiveRunConflictError({ playName, activeRuns }),
@@ -10271,7 +10333,7 @@ function writeStartedPlayRun(input2) {
   );
 }
 function parsePlayRunOptions(args) {
-  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--full] [--<input> value]\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
+  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--full] [--<input> value]\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.dataset guidance.";
   let filePath = null;
   let playName = null;
   let input2 = null;
@@ -10634,7 +10696,10 @@ async function handleFileBackedRun(options) {
     progress.phase("compiled play");
   } catch (error) {
     progress.fail();
-    console.error(error instanceof Error ? error.message : String(error));
+    const normalizedError = normalizePlayValidationError(error);
+    console.error(
+      normalizedError instanceof Error ? normalizedError.message : String(normalizedError)
+    );
     return 1;
   }
   const bundleResult = graph.root;
@@ -11777,7 +11842,7 @@ function registerPlayCommands(program) {
 Concepts:
   Plays are durable cloud workflows.
   Stable ctx.tools.execute({ id, tool, input }) calls are replay-safe.
-  ctx.map adds row keys and row progress.
+  ctx.dataset adds row keys and row progress.
   Named play runs use the live revision unless --latest or --revision-id is set.
   Running a local file does not make it live; use set-live/publish explicitly.
 
@@ -11830,19 +11895,19 @@ Idempotent execution:
 
     await ctx.tools.execute({ id: 'company_lookup', tool, input });
 
-  For rows, use ctx.map plus a stable row key:
+  For rows, use ctx.dataset plus a stable row key:
 
     const rows = await ctx
-      .map('companies_v1', companies)
-      .step('cto', (row, ctx) => ctx.tools.execute({
+      .dataset('companies_v1', companies)
+      .withColumn('cto', (row, ctx) => ctx.tools.execute({
         id: 'find_cto',
         tool: 'apollo_search_people_with_match',
         input: { q_organization_domains_list: [row.domain], per_page: 1 },
       }))
       .run({ key: 'domain' });
 
-  Reuse needs the same play, tool id, map name, row key, and compatible logic.
-  To refresh, change the id/map key or set staleAfterSeconds:
+  Reuse needs the same play, tool id, dataset name, row key, and compatible logic.
+  To refresh, change the id/dataset key or set staleAfterSeconds:
 
     .run({ key: 'domain', staleAfterSeconds: 86400 })
 
@@ -13997,11 +14062,11 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   const rows = (list?.get() ?? []).slice(0, 100);
   // ${sampleRows}
   // columns: ${columns}
-  // .step('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
-  // .step('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
-  // ctx.map is idempotent by map key + row key; reruns reuse completed rows.
+  // .withColumn('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
+  // .withColumn('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
+  // ctx.dataset is idempotent by dataset key + row key; reruns reuse completed rows.
   const enrichedData = await ctx
-    .map('enriched_data', rows)
+    .dataset('enriched_data', rows)
     .run({
       key: ${rowKey},
       description: 'Enrich seeded rows.',
@@ -14815,8 +14880,8 @@ async function runPlayRunnerHealthCheck() {
         "",
         "export default definePlay('health-check', async (ctx) => {",
         "  const rows = await ctx",
-        "    .map('health_rows', [{ id: 'a' }, { id: 'b' }])",
-        "    .step('echo', (row) => ({ ok: true, id: row.id }))",
+        "    .dataset('health_rows', [{ id: 'a' }, { id: 'b' }])",
+        "    .withColumn('echo', (row) => ({ ok: true, id: row.id }))",
         "    .run({ key: 'id' });",
         "  return { ok: true, rows, source: 'deepline health --play-runner' };",
         "});",

package/dist/cli/index.mjs

@@ -206,10 +206,10 @@ import { join as join2 } from "path";
 
 // src/release.ts
 var SDK_RELEASE = {
-  version: "0.1.69",
-  apiContract: "2026-05-play-bootstrap-dataset-summary",
+  version: "0.1.71",
+  apiContract: "2026-06-dataset-column-syntax-cutover",
   supportPolicy: {
-    latest: "0.1.69",
+    latest: "0.1.71",
     minimumSupported: "0.1.53",
     deprecatedBelow: "0.1.53"
   }
@@ -1014,6 +1014,7 @@ var DeeplineClient = class {
       ...request.inputFile ? { inputFile: request.inputFile } : {},
       ...request.packagedFiles?.length ? { packagedFiles: request.packagedFiles } : {},
       ...request.force ? { force: true } : {},
+      ...typeof request.waitForCompletionMs === "number" ? { waitForCompletionMs: request.waitForCompletionMs } : {},
       ...request.profile ? { profile: request.profile } : {}
     };
     for await (const event of this.http.streamSse(
@@ -6887,7 +6888,7 @@ function playInspectionComments(playRef, indent) {
 function accessorExpression(base, field) {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field) ? `${base}.${field}` : `${base}[${jsString(field)}]`;
 }
-function needsWhenImport(options) {
+function needsRunIfImport(options) {
   return stageProviders(options.email).length > 1 || stageProviders(options.phone).length > 1;
 }
 function sourceCollectionTypeName(entity) {
@@ -7189,7 +7190,7 @@ function generateFinderPlayStep(input2) {
     "        ",
     input2.stage.value
   );
-  return `.step(${jsString(outputField)}, async (row, rowCtx) => {
+  return `.withColumn(${jsString(outputField)}, async (row, rowCtx) => {
       const ${input2.aggregateStepName}Input = ${payload};
       throw new Error(${jsString(`TODO: map ${input2.aggregateStepName}Input for ${input2.stage.value}, then delete this throw.`)});
       const ${input2.aggregateStepName}Result = await rowCtx.runPlay<${resultTypeName}>(
@@ -7235,12 +7236,12 @@ function generateFinderProviderStep(input2) {
   const stepName = input2.stepNames[input2.index];
   switch (input2.index) {
     case 0:
-      return `.step(${jsString(stepName)}, ${input2.resolver})`;
+      return `.withColumn(${jsString(stepName)}, ${input2.resolver})`;
     default: {
       const priorCandidates = input2.stepNames.slice(0, input2.index).map((name) => `row.${name}`).join(", ");
-      return `.step(
+      return `.withColumn(
       ${jsString(stepName)},
-      when(
+      runIf(
         (row) => ![${priorCandidates}].some((candidate) => ${optionalFinderValueExpression("candidate", input2.outputField)}),
         ${input2.resolver},
       ),
@@ -7274,9 +7275,9 @@ function generateFinderProviderWaterfall(input2) {
   );
   const candidateNames = stepNames.map((name) => `row.${name}`).join(", ");
   return `// ${input2.aggregateStepName} provider waterfall. Each provider leg is active once its TODO throw is removed;
-    // delete or comment out legs you do not want before running. Later legs are gated with when(...).
+    // delete or comment out legs you do not want before running. Later legs are gated with runIf(...).
     ${providerSteps.join("\n    ")}
-    .step(${jsString(input2.aggregateStepName)}, (row) => {
+    .withColumn(${jsString(input2.aggregateStepName)}, (row) => {
       const candidates = [${candidateNames}];
       const match = candidates.find((candidate) => ${optionalFinderValueExpression("candidate", input2.outputField)});
       return ${optionalFinderValueExpression("match", input2.outputField)} ?? null;
@@ -7331,7 +7332,7 @@ function generateBootstrapPlaySource(input2) {
     rowTypeDefinitions,
     finderPlayResultTypes
   ].filter((definition) => definition.trim().length > 0).join("\n\n");
-  const importNames = needsWhenImport(input2.options) ? "definePlay, when" : "definePlay";
+  const importNames = needsRunIfImport(input2.options) ? "definePlay, runIf" : "definePlay";
   return `import { ${importNames} } from 'deepline';
 
 ${typeDefinitions}
@@ -7350,7 +7351,7 @@ export default definePlay(${jsString(input2.options.name)}, async (ctx, input: I
   }
 
   const rows = await ctx
-    .map('bootstrap_rows', rowsToProcess)${mapSteps}
+    .dataset('bootstrap_rows', rowsToProcess)${mapSteps}
     .run({
       key: (_row, index) => index,
       description: ${jsString(`Bootstrap ${input2.options.template}: seed source rows, run requested stages, then return the mapped rows.`)},
@@ -7860,7 +7861,7 @@ function normalizePlayNameForSheet(value) {
 function normalizeTableNamespace(value) {
   return validateIdentifierPart(
     value,
-    "ctx.map() key",
+    "ctx.dataset() key",
     MAP_KEY_NAMESPACE_MAX_LENGTH
   );
 }
@@ -7870,7 +7871,7 @@ function validatePlaySheetTableName(playName, tableNamespace) {
   const resolved = `${playSegment}_${keySegment}`;
   if (resolved.length > POSTGRES_IDENTIFIER_MAX_LENGTH) {
     throw new Error(
-      `Play sheet table name is too long after normalization (${resolved.length}/63). Shorten the play name or ctx.map() key. Resolved table name: "${resolved}".`
+      `Play sheet table name is too long after normalization (${resolved.length}/63). Shorten the play name or ctx.dataset() key. Resolved table name: "${resolved}".`
     );
   }
   return resolved;
@@ -7950,6 +7951,7 @@ ${EXTRACTED_GETTER_ERROR_HINT}`;
 }
 
 // src/cli/commands/play.ts
+var PLAY_START_STREAM_FAST_COMPLETION_WAIT_MS = 2500;
 var PLAY_RUN_RESERVED_BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--json",
   "--wait",
@@ -8892,6 +8894,10 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
   let eventCount = 0;
   let firstRunIdMs = null;
   let lastPhase = null;
+  const startRequest = {
+    ...input2.request,
+    waitForCompletionMs: typeof input2.request.waitForCompletionMs === "number" ? input2.request.waitForCompletionMs : PLAY_START_STREAM_FAST_COMPLETION_WAIT_MS
+  };
   const timeout = input2.waitTimeoutMs === null ? null : setTimeout(
     () => {
       timedOut = true;
@@ -8900,7 +8906,7 @@ async function startAndWaitForPlayCompletionByStreamOnce(input2) {
     Math.max(1, input2.waitTimeoutMs)
   );
   try {
-    for await (const event of input2.client.startPlayRunStream(input2.request, {
+    for await (const event of input2.client.startPlayRunStream(startRequest, {
       signal: controller.signal
     })) {
       eventCount += 1;
@@ -10108,10 +10114,66 @@ function formatActiveRunConflictError(input2) {
   lines.push(`  rerun: add --force to the same deepline plays run command`);
   return lines.join("\n");
 }
+var PLAY_SYNTAX_MIGRATION_ERROR_MARKERS = [
+  "ctx.map(...) has been replaced by ctx.dataset(...)",
+  "Dataset .step(...) has been replaced by .withColumn(...)"
+];
+function stringArrayField(record, key) {
+  const value = record[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === "string");
+}
+function extractPlayValidationErrors(value) {
+  if (value instanceof DeeplineError) {
+    return extractPlayValidationErrors(value.details);
+  }
+  if (!isRecord4(value)) {
+    return [];
+  }
+  const directErrors = stringArrayField(value, "errors");
+  if (directErrors.length > 0) {
+    return directErrors;
+  }
+  for (const key of ["response", "error", "details"]) {
+    const nestedErrors = extractPlayValidationErrors(value[key]);
+    if (nestedErrors.length > 0) {
+      return nestedErrors;
+    }
+  }
+  return [];
+}
+function orderPlayValidationErrors(errors) {
+  const uniqueErrors = [...new Set(errors)];
+  const migrationErrors = uniqueErrors.filter(
+    (error) => PLAY_SYNTAX_MIGRATION_ERROR_MARKERS.some(
+      (marker) => error.includes(marker)
+    )
+  );
+  const remainingErrors = uniqueErrors.filter(
+    (error) => !migrationErrors.includes(error)
+  );
+  return [...migrationErrors, ...remainingErrors];
+}
+function normalizePlayValidationError(error) {
+  const validationErrors = extractPlayValidationErrors(error);
+  if (validationErrors.length === 0) {
+    return error;
+  }
+  const message = orderPlayValidationErrors(validationErrors).join("\n");
+  if (!message.trim()) {
+    return error;
+  }
+  return new DeeplineError(
+    message,
+    error instanceof DeeplineError ? error.statusCode : void 0,
+    error instanceof DeeplineError ? error.code : "PLAY_VALIDATION_ERROR",
+    error instanceof DeeplineError ? error.details : void 0
+  );
+}
 function normalizePlayStartError(error, playName) {
   const activeRuns = extractActiveRunsFromError(error);
   if (activeRuns.length === 0) {
-    return error;
+    return normalizePlayValidationError(error);
   }
   return new DeeplineError(
     formatActiveRunConflictError({ playName, activeRuns }),
@@ -10274,7 +10336,7 @@ function writeStartedPlayRun(input2) {
   );
 }
 function parsePlayRunOptions(args) {
-  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--full] [--<input> value]\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.map guidance.";
+  const usage = "Usage: deepline plays run <play-name> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --file <play-file.ts> [--input '{...}'] [--no-wait] [--tail-timeout-ms 30000] [--force] [--full] [--<input> value]\n       deepline plays run --name <name> [--input '{...}'] [--live|--latest|--revision-id <id>] [--no-wait] [--tail-timeout-ms 30000] [--force] [--no-open] [--json] [--full] [--<input> value]\n       Unknown --<input> value flags, such as --limit 5, are passed into play input.\nRun `deepline plays run --help` for idempotency, tool call id, and ctx.dataset guidance.";
   let filePath = null;
   let playName = null;
   let input2 = null;
@@ -10637,7 +10699,10 @@ async function handleFileBackedRun(options) {
     progress.phase("compiled play");
   } catch (error) {
     progress.fail();
-    console.error(error instanceof Error ? error.message : String(error));
+    const normalizedError = normalizePlayValidationError(error);
+    console.error(
+      normalizedError instanceof Error ? normalizedError.message : String(normalizedError)
+    );
     return 1;
   }
   const bundleResult = graph.root;
@@ -11780,7 +11845,7 @@ function registerPlayCommands(program) {
 Concepts:
   Plays are durable cloud workflows.
   Stable ctx.tools.execute({ id, tool, input }) calls are replay-safe.
-  ctx.map adds row keys and row progress.
+  ctx.dataset adds row keys and row progress.
   Named play runs use the live revision unless --latest or --revision-id is set.
   Running a local file does not make it live; use set-live/publish explicitly.
 
@@ -11833,19 +11898,19 @@ Idempotent execution:
 
     await ctx.tools.execute({ id: 'company_lookup', tool, input });
 
-  For rows, use ctx.map plus a stable row key:
+  For rows, use ctx.dataset plus a stable row key:
 
     const rows = await ctx
-      .map('companies_v1', companies)
-      .step('cto', (row, ctx) => ctx.tools.execute({
+      .dataset('companies_v1', companies)
+      .withColumn('cto', (row, ctx) => ctx.tools.execute({
         id: 'find_cto',
         tool: 'apollo_search_people_with_match',
         input: { q_organization_domains_list: [row.domain], per_page: 1 },
       }))
       .run({ key: 'domain' });
 
-  Reuse needs the same play, tool id, map name, row key, and compatible logic.
-  To refresh, change the id/map key or set staleAfterSeconds:
+  Reuse needs the same play, tool id, dataset name, row key, and compatible logic.
+  To refresh, change the id/dataset key or set staleAfterSeconds:
 
     .run({ key: 'domain', staleAfterSeconds: 86400 })
 
@@ -14000,11 +14065,11 @@ export default definePlay(${JSON.stringify(playName)}, async (ctx) => {
   const rows = (list?.get() ?? []).slice(0, 100);
   // ${sampleRows}
   // columns: ${columns}
-  // .step('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
-  // .step('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
-  // ctx.map is idempotent by map key + row key; reruns reuse completed rows.
+  // .withColumn('email_waterfall', (row, rowCtx) => rowCtx.runPlay('name_domain_email', 'name-and-domain-to-email', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), domain: String(row.domain ?? '') }, { description: 'Resolve email.' }))
+  // .withColumn('phone_waterfall', (row, rowCtx) => rowCtx.runPlay('contact_phone', 'contact-to-phone', { first_name: String(row.first_name ?? ''), last_name: String(row.last_name ?? ''), email: String(row.email ?? '') }, { description: 'Resolve phone.' }))
+  // ctx.dataset is idempotent by dataset key + row key; reruns reuse completed rows.
   const enrichedData = await ctx
-    .map('enriched_data', rows)
+    .dataset('enriched_data', rows)
     .run({
       key: ${rowKey},
       description: 'Enrich seeded rows.',
@@ -14825,8 +14890,8 @@ async function runPlayRunnerHealthCheck() {
         "",
         "export default definePlay('health-check', async (ctx) => {",
         "  const rows = await ctx",
-        "    .map('health_rows', [{ id: 'a' }, { id: 'b' }])",
-        "    .step('echo', (row) => ({ ok: true, id: row.id }))",
+        "    .dataset('health_rows', [{ id: 'a' }, { id: 'b' }])",
+        "    .withColumn('echo', (row) => ({ ok: true, id: row.id }))",
         "    .run({ key: 'id' });",
         "  return { ok: true, rows, source: 'deepline health --play-runner' };",
         "});",