deepline 0.1.12 → 0.1.20

package/dist/repo/shared_libs/plays/bundling/index.ts

@@ -1,11 +1,9 @@
 import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
 import { mkdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path';
 import { builtinModules, createRequire } from 'node:module';
 import { build, type Message, type Plugin } from 'esbuild';
-import ts from 'typescript';
 import {
   PLAY_ARTIFACT_KINDS,
   type PlayArtifactKind,
@@ -90,7 +88,6 @@ export type PlayBundlingAdapter = {
   workersHarnessEntryFile: string;
   workersHarnessFilesDir: string;
   discoverPackagedLocalFiles(filePath: string): Promise<PlayLocalFileDiscoveryResult>;
-  typecheckSdkTypes?: boolean;
   typecheckPlaySource?(input: {
     sourceCode: string;
     sourcePath: string;
@@ -112,6 +109,7 @@ export type BundledPlayFileSuccess = {
   success: true;
   artifact: PlayBundleArtifact;
   sourceCode: string;
+  sourceFiles: Record<string, string>;
   filePath: string;
   playName: string | null;
   compilerManifest?: PlayCompilerManifest;
@@ -137,6 +135,7 @@ type PackageResolution = {
 
 type SourceGraphAnalysis = {
   sourceCode: string;
+  sourceFiles: Record<string, string>;
   sourceHash: string;
   graphHash: string;
   importPolicy: PlayImportPolicy;
@@ -149,6 +148,13 @@ type PlayWorkspace = {
   rootDir: string;
 };
 
+type SourceImportReference = {
+  specifier: string;
+  line: number;
+  column: number;
+  kind: 'static' | 'require' | 'dynamic-import';
+};
+
 function sha256(value: string): string {
   return createHash('sha256').update(value).digest('hex');
 }
@@ -160,67 +166,6 @@ function formatEsbuildMessage(message: Message): string {
   return location ? `${location} ${message.text}` : message.text;
 }
 
-function formatTypeScriptDiagnostic(diagnostic: ts.Diagnostic): string | null {
-  if (!diagnostic.file) {
-    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').trim();
-    return message || null;
-  }
-  const start = diagnostic.start ?? 0;
-  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(start);
-  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').trim();
-  if (!message) {
-    return null;
-  }
-  return `${diagnostic.file.fileName}:${line + 1}:${character + 1} ${message}`;
-}
-
-function resolveBundledTypeRoots(): string[] {
-  try {
-    return [dirname(dirname(playArtifactRequire.resolve('@types/node/package.json')))];
-  } catch {
-    return [];
-  }
-}
-
-function typecheckPlaySource(
-  input: SourceGraphAnalysis,
-  adapter: PlayBundlingAdapter,
-): string[] {
-  const rootNames = Array.from(
-    new Set([
-      ...input.importPolicy.localFiles,
-      ...input.importedPlayDependencies.map((dependency) => dependency.filePath),
-    ]),
-  );
-  // Resolve `deepline` to SDK source, not ignored dist artifacts. The source
-  // package surface is the canonical local play authoring contract.
-  const sdkTypesPath = adapter.sdkTypesEntryFile ?? adapter.sdkEntryFile;
-  const program = ts.createProgram(rootNames, {
-    target: ts.ScriptTarget.ES2023,
-    // SDK source uses fetch/RequestInit/URL and node-aware config helpers.
-    // The play runtime import policy below still bans Node modules from play
-    // source for workers_edge bundles.
-    lib: ['lib.es2023.d.ts', 'lib.dom.d.ts'],
-    module: ts.ModuleKind.ESNext,
-    moduleResolution: ts.ModuleResolutionKind.Bundler,
-    paths: { deepline: [sdkTypesPath] },
-    strict: true,
-    skipLibCheck: true,
-    noEmit: true,
-    esModuleInterop: true,
-    allowSyntheticDefaultImports: true,
-    allowImportingTsExtensions: true,
-    allowJs: true,
-    resolveJsonModule: true,
-    types: ['node'],
-    typeRoots: resolveBundledTypeRoots(),
-  });
-  return ts
-    .getPreEmitDiagnostics(program)
-    .map(formatTypeScriptDiagnostic)
-    .filter((message): message is string => Boolean(message));
-}
-
 function isLocalSpecifier(specifier: string): boolean {
   return (
     specifier.startsWith('./') ||
@@ -254,18 +199,15 @@ function assertWithinPlayWorkspace(input: {
   specifier: string;
   resolvedPath: string;
   workspace: PlayWorkspace;
-  sourceFile: ts.SourceFile;
-  node: ts.Node;
+  line: number;
+  column: number;
 }): void {
   if (isPathInsideDirectory(input.resolvedPath, input.workspace.rootDir)) {
     return;
   }
 
-  const position = input.sourceFile.getLineAndCharacterOfPosition(
-    input.node.getStart(input.sourceFile),
-  );
   throw new Error(
-    `${input.importer}:${position.line + 1}:${position.character + 1} ` +
+    `${input.importer}:${input.line}:${input.column} ` +
       `Local play imports must stay inside the play workspace (${input.workspace.rootDir}). ` +
       `Import "${input.specifier}" resolved to ${input.resolvedPath}, which crosses into app/backend code. ` +
       'Use the public SDK/API surface or move shared helpers into the play workspace.',
@@ -280,95 +222,156 @@ function getPackageName(specifier: string): string {
   return specifier.split('/')[0] ?? specifier;
 }
 
-function scriptKindForFile(filePath: string): ts.ScriptKind {
-  const extension = extname(filePath).toLowerCase();
-  switch (extension) {
-    case '.tsx':
-      return ts.ScriptKind.TSX;
-    case '.jsx':
-      return ts.ScriptKind.JSX;
-    case '.js':
-    case '.mjs':
-    case '.cjs':
-      return ts.ScriptKind.JS;
-    case '.json':
-      return ts.ScriptKind.JSON;
-    default:
-      return ts.ScriptKind.TS;
+function isPlaySourceFile(filePath: string): boolean {
+  return PLAY_SOURCE_FILE_PATTERN.test(filePath);
+}
+
+function stripCommentsToSpaces(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^:])\/\/.*$/gm, (match, prefix: string) =>
+      prefix + ' '.repeat(Math.max(0, match.length - prefix.length)),
+    );
+}
+
+function lineAndColumnAt(source: string, index: number): { line: number; column: number } {
+  const prefix = source.slice(0, index);
+  const lines = prefix.split('\n');
+  return { line: lines.length, column: lines[lines.length - 1]!.length + 1 };
+}
+
+function findSourceImportReferences(sourceCode: string): SourceImportReference[] {
+  const source = stripCommentsToSpaces(sourceCode);
+  const references: SourceImportReference[] = [];
+  const addReference = (
+    specifier: string | undefined,
+    specifierIndex: number,
+    kind: SourceImportReference['kind'],
+  ) => {
+    if (!specifier) return;
+    const position = lineAndColumnAt(sourceCode, specifierIndex);
+    references.push({
+      specifier,
+      line: position.line,
+      column: position.column,
+      kind,
+    });
+  };
+
+  const staticImportPattern =
+    /\b(?:import|export)\s+(?!type\b)(?:[\s\S]*?\s+from\s*)?(['"])([^'"\n]+)\1/g;
+  for (const match of source.matchAll(staticImportPattern)) {
+    addReference(match[2], match.index! + match[0].lastIndexOf(match[1]!), 'static');
+  }
+
+  const dynamicImportPattern = /\bimport\s*\(\s*(['"])([^'"\n]+)\1/g;
+  for (const match of source.matchAll(dynamicImportPattern)) {
+    addReference(match[2], match.index! + match[0].lastIndexOf(match[1]!), 'dynamic-import');
   }
+
+  const requirePattern = /\brequire\s*\(\s*(['"])([^'"\n]+)\1/g;
+  for (const match of source.matchAll(requirePattern)) {
+    addReference(match[2], match.index! + match[0].lastIndexOf(match[1]!), 'require');
+  }
+
+  const literalDynamicImportIndexes = new Set(
+    [...source.matchAll(dynamicImportPattern)].map((match) => match.index!),
+  );
+  for (const match of source.matchAll(/\bimport\s*\(/g)) {
+    if (literalDynamicImportIndexes.has(match.index!)) continue;
+    const position = lineAndColumnAt(sourceCode, match.index!);
+    throw new Error(
+      `:${position.line}:${position.column} Dynamic import() is not allowed in plays. Use static imports instead.`,
+    );
+  }
+
+  const literalRequireIndexes = new Set(
+    [...source.matchAll(requirePattern)].map((match) => match.index!),
+  );
+  for (const match of source.matchAll(/\brequire\s*\(/g)) {
+    if (literalRequireIndexes.has(match.index!)) continue;
+    const position = lineAndColumnAt(sourceCode, match.index!);
+    throw new Error(
+      `:${position.line}:${position.column} Dynamic require() is not allowed in plays. Use static imports or require("literal") only.`,
+    );
+  }
+
+  return references.sort((left, right) =>
+    left.line === right.line ? left.column - right.column : left.line - right.line,
+  );
 }
 
-function isPlaySourceFile(filePath: string): boolean {
-  return PLAY_SOURCE_FILE_PATTERN.test(filePath);
+function unquoteStringLiteral(literal: string): string | null {
+  const trimmed = literal.trim();
+  const quote = trimmed[0];
+  if ((quote !== '"' && quote !== "'") || trimmed[trimmed.length - 1] !== quote) {
+    return null;
+  }
+  try {
+    return JSON.parse(quote === '"' ? trimmed : `"${trimmed.slice(1, -1).replace(/"/g, '\\"')}"`);
+  } catch {
+    return trimmed.slice(1, -1);
+  }
 }
 
-function extractStringLiteralProperty(
-  objectLiteral: ts.ObjectLiteralExpression,
-  propertyName: string,
-): string | null {
-  for (const property of objectLiteral.properties) {
-    if (!ts.isPropertyAssignment(property)) {
+function findMatchingBrace(source: string, openIndex: number): number {
+  let depth = 0;
+  let quote: string | null = null;
+  let escaped = false;
+  for (let index = openIndex; index < source.length; index += 1) {
+    const char = source[index]!;
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
       continue;
     }
-    const name = property.name;
-    const matches =
-      (ts.isIdentifier(name) && name.text === propertyName) ||
-      (ts.isStringLiteralLike(name) && name.text === propertyName);
-    if (!matches) {
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
       continue;
     }
-    return ts.isStringLiteralLike(property.initializer)
-      ? property.initializer.text.trim()
-      : null;
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
   }
-
-  return null;
+  return -1;
 }
 
 export function extractDefinedPlayName(
   sourceCode: string,
-  filePath: string,
+  _filePath: string,
 ): string | null {
-  const sourceFile = ts.createSourceFile(
-    filePath,
-    sourceCode,
-    ts.ScriptTarget.Latest,
-    true,
-    scriptKindForFile(filePath),
-  );
-  let detectedPlayName: string | null = null;
-
-  const visit = (node: ts.Node) => {
-    if (detectedPlayName) {
-      return;
+  const source = stripCommentsToSpaces(sourceCode);
+  const callPattern = /(?:\b[A-Za-z_$][\w$]*\s*\.\s*)?\b(?:definePlay|defineWorkflow)\s*\(/g;
+  for (const match of source.matchAll(callPattern)) {
+    const openParen = match.index! + match[0].length - 1;
+    const firstArgStart = openParen + 1;
+    const firstNonSpace = source.slice(firstArgStart).search(/\S/);
+    if (firstNonSpace < 0) continue;
+    const argIndex = firstArgStart + firstNonSpace;
+    const quote = source[argIndex];
+    if (quote === '"' || quote === "'") {
+      const literalMatch = source.slice(argIndex).match(/^(['"])(?:\\.|(?!\1)[\s\S])*\1/);
+      const value = literalMatch ? unquoteStringLiteral(literalMatch[0]) : null;
+      if (value?.trim()) return value.trim();
     }
-
-    if (ts.isCallExpression(node)) {
-      const expression = node.expression;
-      const isDefinePlayCall =
-        (ts.isIdentifier(expression) &&
-          (expression.text === 'definePlay' || expression.text === 'defineWorkflow')) ||
-        (ts.isPropertyAccessExpression(expression) &&
-          (expression.name.text === 'definePlay' ||
-            expression.name.text === 'defineWorkflow'));
-      if (isDefinePlayCall) {
-        const firstArgument = node.arguments[0];
-        if (firstArgument && ts.isStringLiteralLike(firstArgument)) {
-          detectedPlayName = firstArgument.text.trim() || null;
-          return;
-        }
-        if (firstArgument && ts.isObjectLiteralExpression(firstArgument)) {
-          detectedPlayName = extractStringLiteralProperty(firstArgument, 'id');
-          return;
-        }
+    if (quote === '{') {
+      const closeBrace = findMatchingBrace(source, argIndex);
+      if (closeBrace < 0) continue;
+      const objectSource = source.slice(argIndex + 1, closeBrace);
+      const idMatch = objectSource.match(/(?:^|[,{\s])(?:id|['"]id['"])\s*:\s*(['"])([\s\S]*?)\1/);
+      if (idMatch?.[2]?.trim()) {
+        return idMatch[2].trim();
       }
     }
-
-    ts.forEachChild(node, visit);
-  };
-
-  visit(sourceFile);
-  return detectedPlayName;
+  }
+  return null;
 }
 
 function getPackageRequireCandidates(fromFile: string) {
@@ -821,23 +824,15 @@ async function analyzeSourceGraph(
       return;
     }
 
-    const sourceFile = ts.createSourceFile(
-      absolutePath,
-      sourceCode,
-      ts.ScriptTarget.Latest,
-      true,
-      scriptKindForFile(absolutePath),
-    );
-
     const handleSpecifier = async (
       specifier: string,
-      node: ts.Node,
+      line: number,
+      column: number,
       kind: 'static' | 'require' | 'dynamic-import',
     ) => {
       if (kind === 'dynamic-import') {
-        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
         throw new Error(
-          `${absolutePath}:${position.line + 1}:${position.character + 1} Dynamic import() is not allowed in plays. Use static imports instead.`,
+          `${absolutePath}:${line}:${column} Dynamic import() is not allowed in plays. Use static imports instead.`,
         );
       }
 
@@ -853,16 +848,15 @@ async function analyzeSourceGraph(
           specifier,
           resolvedPath: resolved,
           workspace,
-          sourceFile,
-          node,
+          line,
+          column,
         });
         if (resolved !== absoluteEntryFile && isPlaySourceFile(resolved)) {
           const importedSource = await readFile(resolved, 'utf-8');
           const importedPlayName = extractDefinedPlayName(importedSource, resolved);
           if (!importedPlayName) {
-            const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
             throw new Error(
-              `${absolutePath}:${position.line + 1}:${position.character + 1} Imported play file "${specifier}" must export definePlay(...) so it can be runtime-composed.`,
+              `${absolutePath}:${line}:${column} Imported play file "${specifier}" must export definePlay(...) so it can be runtime-composed.`,
             );
           }
           importedPlayDependencies.set(resolved, {
@@ -876,9 +870,8 @@ async function analyzeSourceGraph(
       }
 
       if (specifier.includes(':')) {
-        const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
         throw new Error(
-          `${absolutePath}:${position.line + 1}:${position.character + 1} Unsupported import specifier "${specifier}". Allowed imports are relative files, Node builtins, and installed packages.`,
+          `${absolutePath}:${line}:${column} Unsupported import specifier "${specifier}". Allowed imports are relative files, Node builtins, and installed packages.`,
         );
       }
 
@@ -886,48 +879,21 @@ async function analyzeSourceGraph(
       packages.set(packageImport.name, packageImport.version);
     };
 
-    const walk = async (node: ts.Node): Promise<void> => {
-      if (
-        (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
-        node.moduleSpecifier &&
-        !(
-          (ts.isImportDeclaration(node) && node.importClause?.isTypeOnly) ||
-          (ts.isExportDeclaration(node) && node.isTypeOnly)
-        ) &&
-        ts.isStringLiteralLike(node.moduleSpecifier)
-      ) {
-        await handleSpecifier(node.moduleSpecifier.text, node, 'static');
-      }
-
-      if (ts.isCallExpression(node)) {
-        if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-          if (node.arguments.length !== 1 || !ts.isStringLiteralLike(node.arguments[0]!)) {
-            const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-            throw new Error(
-              `${absolutePath}:${position.line + 1}:${position.character + 1} Dynamic import() is not allowed in plays. Use static imports instead.`,
-            );
-          }
-          await handleSpecifier(node.arguments[0]!.text, node, 'dynamic-import');
-        }
-
-        if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
-          const firstArgument = node.arguments[0];
-          if (node.arguments.length !== 1 || !firstArgument || !ts.isStringLiteralLike(firstArgument)) {
-            const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-            throw new Error(
-              `${absolutePath}:${position.line + 1}:${position.character + 1} Dynamic require() is not allowed in plays. Use static imports or require(\"literal\") only.`,
-            );
-          }
-          await handleSpecifier(firstArgument.text, node, 'require');
-        }
+    try {
+      for (const reference of findSourceImportReferences(sourceCode)) {
+        await handleSpecifier(
+          reference.specifier,
+          reference.line,
+          reference.column,
+          reference.kind,
+        );
       }
-
-      for (const child of node.getChildren(sourceFile)) {
-        await walk(child);
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith(':')) {
+        throw new Error(`${absolutePath}${error.message}`);
       }
-    };
-
-    await walk(sourceFile);
+      throw error;
+    }
   };
 
   await visitFile(absoluteEntryFile);
@@ -956,6 +922,11 @@ async function analyzeSourceGraph(
 
   return {
     sourceCode,
+    sourceFiles: Object.fromEntries(
+      [...localFiles.entries()].sort((left, right) =>
+        left[0].localeCompare(right[0]),
+      ),
+    ),
     sourceHash,
     graphHash,
     importPolicy: {
@@ -1067,12 +1038,11 @@ function normalizeSourceMapForRuntime(sourceMapText: string): string {
   return JSON.stringify(parsed);
 }
 
-function getBundleSizeError(
+export function getBundleSizeErrorForBytes(
   filePath: string,
-  bundledCode: string,
+  bundleBytes: number,
   artifactKind: PlayArtifactKind,
 ): string | null {
-  const bundleBytes = Buffer.byteLength(bundledCode, 'utf8');
   if (bundleBytes > MAX_PLAY_BUNDLE_BYTES) {
     return `${filePath} Play bundle exceeds the 30 MiB limit (${bundleBytes} bytes > ${MAX_PLAY_BUNDLE_BYTES} bytes).`;
   }
@@ -1093,6 +1063,18 @@ function getBundleSizeError(
   return null;
 }
 
+function getBundleSizeError(
+  filePath: string,
+  bundledCode: string,
+  artifactKind: PlayArtifactKind,
+): string | null {
+  return getBundleSizeErrorForBytes(
+    filePath,
+    Buffer.byteLength(bundledCode, 'utf8'),
+    artifactKind,
+  );
+}
+
 export type BundlePlayFileOptions = {
   /**
    * Which artifact to produce. Defaults to `cjs_node20` (Daytona / local-process
@@ -1276,14 +1258,27 @@ export async function bundlePlayFile(
         `${analysis.graphHash}\nworkers-harness:${harnessFingerprint}`,
       );
     }
-    // Cache lookup before typecheck/discovery: a cached artifact at this
-    // graphHash is content-addressed by source — it can only exist if the
-    // exact same source already passed typecheckPlaySource on a previous
-    // run (we only write to cache after a successful bundle, which only
-    // runs after a successful typecheck). Re-running ts.createProgram +
-    // getPreEmitDiagnostics costs ~500ms per call and dominates warm
-    // bundle latency, so skipping it on a cache hit is the single biggest
-    // win for `play check` / `play run` startup time.
+    const typecheckErrors = [
+      ...((await adapter.typecheckPlaySource?.({
+        sourceCode: analysis.sourceCode,
+        sourcePath: absolutePath,
+        importedFilePaths: [
+          ...analysis.importPolicy.localFiles,
+          ...analysis.importedPlayDependencies.map((dependency) => dependency.filePath),
+        ],
+      })) ?? []),
+    ];
+    if (typecheckErrors.length > 0) {
+      return {
+        success: false,
+        filePath: absolutePath,
+        errors: typecheckErrors,
+      };
+    }
+
+    // Cache lookup happens after validation because a bundle cache hit is keyed
+    // by source and target, while cloud descriptor typecheck results also depend
+    // on generated tool metadata.
     const cachedArtifact = await readArtifactCache(analysis.graphHash, target, adapter);
     const discoveredFiles = await adapter.discoverPackagedLocalFiles(absolutePath);
     if (cachedArtifact) {
@@ -1304,6 +1299,7 @@ export async function bundlePlayFile(
         success: true,
         artifact: { ...cachedArtifact, cacheHit: true },
         sourceCode: analysis.sourceCode,
+        sourceFiles: analysis.sourceFiles,
         filePath: absolutePath,
         playName: analysis.playName,
         packagedFiles: discoveredFiles.files,
@@ -1312,26 +1308,6 @@ export async function bundlePlayFile(
       };
     }
 
-    const typecheckErrors = [
-      ...(adapter.typecheckSdkTypes === false
-        ? []
-        : typecheckPlaySource(analysis, adapter)),
-      ...((await adapter.typecheckPlaySource?.({
-        sourceCode: analysis.sourceCode,
-        sourcePath: absolutePath,
-        importedFilePaths: [
-          ...analysis.importPolicy.localFiles,
-          ...analysis.importedPlayDependencies.map((dependency) => dependency.filePath),
-        ],
-      })) ?? []),
-    ];
-    if (typecheckErrors.length > 0) {
-      return {
-        success: false,
-        filePath: absolutePath,
-        errors: typecheckErrors,
-      };
-    }
     const buildOutcome =
       target === PLAY_ARTIFACT_KINDS.esmWorkers
         ? await runEsbuildForEsmWorkers(absolutePath, analysis.importedPlayDependencies, adapter, exportName)
@@ -1391,6 +1367,7 @@ export async function bundlePlayFile(
       success: true,
       artifact,
       sourceCode: analysis.sourceCode,
+      sourceFiles: analysis.sourceFiles,
       filePath: absolutePath,
       playName: analysis.playName,
       packagedFiles: discoveredFiles.files,

package/dist/repo/shared_libs/plays/dataset.ts

@@ -19,6 +19,21 @@ export type PlayDatasetBacking =
       file: PlayExecutionFileRef;
     };
 
+export type PlayDatasetWorkProgressSummary = {
+  total: number;
+  executed: number;
+  reused: number;
+  skipped: number;
+  pending: number;
+  failed: number;
+  degraded?: boolean;
+  duplicates?: {
+    exact?: number;
+    semantic?: number;
+    rejected?: number;
+  };
+};
+
 export interface SerializedPlayDataset<T> {
   kind: 'dataset';
   datasetKind: PlayDatasetKind;
@@ -28,6 +43,9 @@ export interface SerializedPlayDataset<T> {
   sourceLabel?: string | null;
   tableNamespace?: string | null;
   columns?: string[];
+  _metadata?: {
+    workProgress?: PlayDatasetWorkProgressSummary;
+  };
   preview: T[];
 }
 
@@ -61,6 +79,9 @@ export interface PlayDataset<T> extends AsyncIterable<T> {
     sourceLabel?: string | null;
     tableNamespace?: string | null;
     columns?: string[];
+    _metadata?: {
+      workProgress?: PlayDatasetWorkProgressSummary;
+    };
     preview: T[];
   };
 }
@@ -136,6 +157,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
   readonly tableNamespace?: string | null;
   private readonly previewRows: readonly T[];
   private readonly previewColumns?: string[];
+  private readonly workProgress?: PlayDatasetWorkProgressSummary;
   private cachedCount: number;
   private readonly resolvers: PlayDatasetResolvers<T>;
 
@@ -147,6 +169,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     previewRows: readonly T[];
     sourceLabel?: string | null;
     tableNamespace?: string | null;
+    workProgress?: PlayDatasetWorkProgressSummary;
     resolvers: PlayDatasetResolvers<T>;
   }) {
     this.datasetKind = input.datasetKind;
@@ -157,6 +180,7 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
     this.previewColumns = inferPreviewColumns(this.previewRows);
     this.sourceLabel = input.sourceLabel ?? null;
     this.tableNamespace = input.tableNamespace ?? null;
+    this.workProgress = input.workProgress;
     this.resolvers = input.resolvers;
   }
 
@@ -212,6 +236,9 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
       ...(this.sourceLabel ? { sourceLabel: this.sourceLabel } : {}),
       ...(this.tableNamespace ? { tableNamespace: this.tableNamespace } : {}),
       ...(this.previewColumns ? { columns: this.previewColumns } : {}),
+      ...(this.workProgress
+        ? { _metadata: { workProgress: this.workProgress } }
+        : {}),
       preview: [...this.previewRows],
     };
   }
@@ -229,6 +256,7 @@ export function createDeferredPlayDataset<T>(input: {
   previewRows?: readonly T[];
   sourceLabel?: string | null;
   tableNamespace?: string | null;
+  workProgress?: PlayDatasetWorkProgressSummary;
   resolvers: PlayDatasetResolvers<T>;
 }): PlayDataset<T> {
   return new DeferredPlayDataset({