deepline 0.0.1 → 0.1.1

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

@@ -0,0 +1,1346 @@
+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,
+} from '../../play-runtime/backend.js';
+import type { PlayCompilerManifest } from '../compiler-manifest.js';
+import type {
+  PlayArtifactCompatibility,
+  PlayBundleArtifact,
+  PlayImportPolicy,
+  PlayPackageImport,
+  PlayRuntimeFeature,
+} from '../artifact-types.js';
+import { buildPlayContractCompatibility } from '../contracts.js';
+
+const playArtifactRequire = createRequire(import.meta.url);
+const PLAY_BUNDLE_CACHE_VERSION = 24;
+const MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
+// workerd local-mode (`wrangler dev` Worker Loader) silently fails to
+// instantiate per-graphHash play Workers when the bundled code passes a
+// threshold somewhere between 1.04 MiB (44-package-imports — works) and
+// 1.18 MiB (the same play with date-fns added — hangs forever). The
+// workflow body never runs, no error is logged anywhere, and the run
+// hangs indefinitely. We surface this as a hard bundle failure so the
+// user gets an actionable message at submit time instead of a 5-minute
+// silent timeout. Real CF (workers.dev) accepts much larger bundles, but
+// `dev:v2 cloudflare` is the regression entrypoint so the local limit is
+// the binding one.
+const MAX_ESM_WORKERS_BUNDLE_BYTES = 1_150_000;
+const PLAY_ARTIFACT_CACHE_DIR = join(
+  tmpdir(),
+  `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`,
+);
+const PLAY_PROXY_NAMESPACE = 'deepline-play-runtime-ref';
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json'];
+const WORKERS_PLAY_ENTRY_VIRTUAL = 'deepline-play-entry';
+const PLAY_SOURCE_FILE_PATTERN = /\.play\.(?:[cm]?[jt]sx?)$/i;
+const NODE_BUILTIN_SET = new Set(
+  builtinModules.flatMap((name) => (name.startsWith('node:') ? [name, name.slice(5)] : [name, `node:${name}`])),
+);
+
+export type {
+  PlayArtifactCompatibility,
+  PlayBundleArtifact,
+  PlayImportPolicy,
+  PlayPackageImport,
+  PlayRuntimeFeature,
+};
+
+export type ImportedPlayDependency = {
+  filePath: string;
+  playName: string;
+};
+
+export type PlayLocalFileReference = {
+  sourceFragment: string;
+  logicalPath: string;
+  absolutePath: string;
+  bytes: number;
+  contentHash: string;
+  contentType: string;
+};
+
+export type PlayLocalFileDiscoveryError = {
+  sourceFragment: string;
+  message: string;
+};
+
+export type PlayLocalFileDiscoveryResult = {
+  files: PlayLocalFileReference[];
+  unresolved: PlayLocalFileDiscoveryError[];
+};
+
+export type PlayBundlingAdapter = {
+  projectRoot: string;
+  nodeModulesDir: string;
+  cacheDir?: string;
+  sdkSourceRoot: string;
+  sdkPackageJson: string;
+  sdkEntryFile: string;
+  sdkTypesEntryFile?: string;
+  sdkWorkersEntryFile: string;
+  workersHarnessEntryFile: string;
+  workersHarnessFilesDir: string;
+  discoverPackagedLocalFiles(filePath: string): Promise<PlayLocalFileDiscoveryResult>;
+  typecheckSdkTypes?: boolean;
+  typecheckPlaySource?(input: {
+    sourceCode: string;
+    sourcePath: string;
+    importedFilePaths: string[];
+  }): Promise<string[]> | string[];
+  warnAboutNonDevelopmentBundling?(filePath: string): void;
+};
+
+export type BundledPlayFileSuccess = {
+  success: true;
+  artifact: PlayBundleArtifact;
+  sourceCode: string;
+  filePath: string;
+  playName: string | null;
+  compilerManifest?: PlayCompilerManifest;
+  packagedFiles: PlayLocalFileReference[];
+  unresolvedFileReferences: PlayLocalFileDiscoveryError[];
+  importedPlayDependencies: ImportedPlayDependency[];
+};
+
+export type BundledPlayFileFailure = {
+  success: false;
+  errors: string[];
+  filePath: string;
+};
+
+export type BundledPlayFileResult =
+  | BundledPlayFileSuccess
+  | BundledPlayFileFailure;
+
+type PackageResolution = {
+  name: string;
+  version: string | null;
+};
+
+type SourceGraphAnalysis = {
+  sourceCode: string;
+  sourceHash: string;
+  graphHash: string;
+  importPolicy: PlayImportPolicy;
+  playName: string | null;
+  importedPlayDependencies: ImportedPlayDependency[];
+};
+
+type PlayWorkspace = {
+  entryFile: string;
+  rootDir: string;
+};
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function formatEsbuildMessage(message: Message): string {
+  const location = message.location
+    ? `${message.location.file}:${message.location.line}:${message.location.column}`
+    : null;
+  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 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'],
+  });
+  return ts
+    .getPreEmitDiagnostics(program)
+    .map(formatTypeScriptDiagnostic)
+    .filter((message): message is string => Boolean(message));
+}
+
+function isLocalSpecifier(specifier: string): boolean {
+  return (
+    specifier.startsWith('./') ||
+    specifier.startsWith('../') ||
+    specifier.startsWith('/') ||
+    specifier.startsWith('file:')
+  );
+}
+
+async function normalizeLocalPath(filePath: string): Promise<string> {
+  try {
+    return await realpath(filePath);
+  } catch {
+    return resolve(filePath);
+  }
+}
+
+function createPlayWorkspace(entryFile: string): PlayWorkspace {
+  return {
+    entryFile,
+    rootDir: dirname(entryFile),
+  };
+}
+
+function isPathInsideDirectory(filePath: string, directory: string): boolean {
+  return filePath === directory || filePath.startsWith(`${directory}/`);
+}
+
+function assertWithinPlayWorkspace(input: {
+  importer: string;
+  specifier: string;
+  resolvedPath: string;
+  workspace: PlayWorkspace;
+  sourceFile: ts.SourceFile;
+  node: ts.Node;
+}): 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} ` +
+      `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.',
+  );
+}
+
+function getPackageName(specifier: string): string {
+  if (specifier.startsWith('@')) {
+    const [scope, name] = specifier.split('/');
+    return scope && name ? `${scope}/${name}` : specifier;
+  }
+  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 extractStringLiteralProperty(
+  objectLiteral: ts.ObjectLiteralExpression,
+  propertyName: string,
+): string | null {
+  for (const property of objectLiteral.properties) {
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    const name = property.name;
+    const matches =
+      (ts.isIdentifier(name) && name.text === propertyName) ||
+      (ts.isStringLiteralLike(name) && name.text === propertyName);
+    if (!matches) {
+      continue;
+    }
+    return ts.isStringLiteralLike(property.initializer)
+      ? property.initializer.text.trim()
+      : null;
+  }
+
+  return null;
+}
+
+export function extractDefinedPlayName(
+  sourceCode: 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;
+    }
+
+    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;
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return detectedPlayName;
+}
+
+function getPackageRequireCandidates(fromFile: string) {
+  const candidates = [
+    createRequire(fromFile),
+    createRequire(join(process.cwd(), 'package.json')),
+    playArtifactRequire,
+  ];
+  return candidates;
+}
+
+function localSdkAliasPlugin(
+  adapter: PlayBundlingAdapter,
+  options?: { workersRuntime?: boolean },
+): Plugin | null {
+  const entryFile = options?.workersRuntime
+    ? adapter.sdkWorkersEntryFile
+    : adapter.sdkEntryFile;
+  if (!playArtifactRequire('node:fs').existsSync(entryFile)) {
+    return null;
+  }
+
+  return {
+    name: 'deepline-sdk-local-alias',
+    setup(buildContext) {
+      buildContext.onResolve({ filter: /^deepline$/ }, () => ({
+        path: entryFile,
+      }));
+    },
+  };
+}
+
+/**
+ * Resolves the virtual `deepline-play-entry` import (used by the Workers
+ * harness) to the user's play source file. Lets the harness statically import
+ * the play without the bundler needing to know its path ahead of time.
+ */
+function workersPlayEntryAliasPlugin(playFilePath: string): Plugin {
+  return {
+    name: 'deepline-workers-play-entry-alias',
+    setup(buildContext) {
+      buildContext.onResolve(
+        { filter: new RegExp(`^${WORKERS_PLAY_ENTRY_VIRTUAL}$`) },
+        () => ({ path: playFilePath }),
+      );
+    },
+  };
+}
+
+/**
+ * Cloudflare Workers' `nodejs_compat` flag covers most node builtins (path,
+ * crypto, buffer, async_hooks, ...) but NOT `node:fs` / `node:fs/promises` /
+ * `node:os` (no filesystem, no OS in a V8 isolate). The SDK's config-loading
+ * and tool-output utilities reference these even when the play never invokes
+ * them — which is the case for plays that don't read CLI config at runtime.
+ *
+ * This plugin substitutes those specific imports with a tiny stub module that
+ * has no top-level side effects and throws clearly if anything actually calls
+ * into them. That lets the deploy validation pass while still surfacing a
+ * loud error if a play unexpectedly depends on a node-only API.
+ */
+function workersNodeBuiltinStubPlugin(): Plugin {
+  // These are the node builtins NOT exposed by Cloudflare's nodejs_compat.
+  // Keep this list narrow — anything supported (path, crypto, etc.) should
+  // pass through as `external: ['node:*']` in the build config.
+  const UNSUPPORTED = new Set(['node:fs', 'node:fs/promises', 'node:os', 'node:child_process']);
+  return {
+    name: 'deepline-workers-node-builtin-stub',
+    setup(buildContext) {
+      buildContext.onResolve({ filter: /^node:/ }, (args) => {
+        if (!UNSUPPORTED.has(args.path)) return null;
+        return { path: args.path, namespace: 'deepline-workers-node-stub' };
+      });
+      buildContext.onLoad(
+        { filter: /.*/, namespace: 'deepline-workers-node-stub' },
+        (args) => {
+          const builtinName = args.path;
+          // CommonJS module.exports = Proxy. esbuild's CJS↔ESM interop maps
+          // any named import (e.g. `import { readFileSync } from 'node:fs'`)
+          // to a property access on this Proxy. Property access returns a
+          // function-like Proxy that throws on call. So:
+          //   - import resolves at bundle time (deploy validation passes)
+          //   - import binding evaluates to a no-arg-throw function
+          //   - calling it gives a clear error
+          const stubSource = `
+const message = ${JSON.stringify(
+            `Workers backend: ${builtinName} is not available in Cloudflare Workers ` +
+              '(no filesystem / no OS). Run this play on Daytona or local-process backend ' +
+              'if it needs node builtins.',
+          )};
+function makeThrower(name) {
+  return new Proxy(function() { throw new Error(message + ' (called: ' + name + ')'); }, {
+    get(_t, prop) {
+      if (prop === '__esModule') return true;
+      if (typeof prop === 'symbol') return undefined;
+      return makeThrower(name + '.' + String(prop));
+    },
+    apply() { throw new Error(message + ' (called: ' + name + ')'); },
+    construct() { throw new Error(message + ' (constructed: ' + name + ')'); },
+  });
+}
+module.exports = makeThrower(${JSON.stringify(builtinName)});
+`;
+          return { contents: stubSource, loader: 'js' };
+        },
+      );
+    },
+  };
+}
+
+/**
+ * Stub every `zod/v4/locales/<lang>.js` module EXCEPT English with an
+ * empty default export so non-English locale strings don't get bundled
+ * into per-play Workers.
+ *
+ * Why this exists:
+ *   `zod/v4/core/index.js` does `export * as locales from "../locales/index.js"`
+ *   and `zod/v4/locales/index.js` re-exports every individual locale
+ *   module (he, ru, ta, th, be, km, ka, uk, hy, bg, ur, ar, mk, fa, ps,
+ *   lt, …). esbuild follows the static re-exports and bundles every
+ *   locale, ~5–9 KB each. A bundle audit (`scripts/audit-play-bundle.ts`)
+ *   on `03-tool-basic.play.ts` showed ~22 of these locale modules
+ *   present, totaling ~150–200 KB of dead weight.
+ *
+ *   Plays only ever surface English error messages to user/CLI. The
+ *   non-English locale data is unreachable in our codepath, but
+ *   esbuild's tree-shaking can't prove that across `export * as`
+ *   re-exports. So we stub each non-English locale at load time with
+ *   an empty default export. zod's runtime falls back to its built-in
+ *   English messages when a requested locale's data is missing or
+ *   empty.
+ *
+ * What this saves (measured, fresh per-play bundle):
+ *   ~150–200 KB → cold V8 compile time drops proportionally
+ *   (~50–70 ms on CF edge per cold play).
+ *
+ * Safety:
+ *   - English (`en.js`) is NEVER stubbed — that's the language zod
+ *     and our error surfaces actually use.
+ *   - The locales/index.js wrapper is left intact; its re-exports
+ *     resolve to empty `{}` modules but the import shape stays
+ *     stable for any code that does `import { locales } from "zod"`.
+ *   - If a future codepath needs a non-English locale, this plugin
+ *     would silently swallow the data; that would be a real bug, so
+ *     we log a one-time warning at bundle time when a non-English
+ *     locale is stubbed (only emitted to stderr in dev to keep CI
+ *     output clean).
+ */
+function zodNonEnglishLocaleStubPlugin(): Plugin {
+  // Match any zod v4 locale module path EXCEPT en + en variants.
+  // The filter uses a coarse regex; the namespace handler then
+  // double-checks with a precise basename test before stubbing.
+  const LOCALE_PATH_FILTER = /[\\/]zod[\\/]v4[\\/]locales[\\/][^\\/]+\.(?:c?js|mjs)$/;
+  const NAMESPACE = 'deepline-zod-locale-stub';
+  return {
+    name: 'deepline-zod-non-english-locale-stub',
+    setup(buildContext) {
+      buildContext.onResolve({ filter: LOCALE_PATH_FILTER }, (args) => {
+        // Resolve relatively first (esbuild needs an absolute path), then
+        // decide whether to stub. We do this in onResolve so we can check
+        // the filename and let `en` flow through unmodified.
+        const norm = args.path.replace(/\\/g, '/');
+        const file = norm.slice(norm.lastIndexOf('/') + 1);
+        // Allow English variants — `en.js`, `en.cjs`, future `en-US.js`, etc.
+        if (/^en(?:[-_][A-Za-z]+)?\.(?:c?js|mjs)$/.test(file)) {
+          return null;
+        }
+        // Anything else: stub with an empty default export.
+        return { path: args.path, namespace: NAMESPACE };
+      });
+      buildContext.onLoad(
+        { filter: /.*/, namespace: NAMESPACE },
+        () => ({
+          // zod locales export a default object literal. Empty object is
+          // structurally compatible — accessing any locale key returns
+          // undefined and zod falls back to its built-in English.
+          contents: 'export default {};',
+          loader: 'js',
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Hard banlist of `node:*` modules whose presence in a workers_edge bundle
+ * would either escape the V8 isolate boundary (filesystem, network sockets,
+ * subprocess control) or open up confused-deputy paths (vm/repl/worker
+ * threads). These are blocked at bundle time so the per-graphHash CF Worker
+ * never sees code that could attempt to call them.
+ *
+ * `nodejs_compat` covers the supported subset (crypto, stream, buffer, util,
+ * path, url, http, https) — those imports continue to pass through and
+ * resolve to workerd-shimmed implementations.
+ */
+const WORKERS_BANNED_NODE_MODULES = new Set([
+  'node:fs',
+  'node:fs/promises',
+  'node:net',
+  'node:child_process',
+  'node:cluster',
+  'node:tls',
+  'node:dgram',
+  'node:dns',
+  'node:dns/promises',
+  'node:repl',
+  'node:vm',
+  'node:worker_threads',
+]);
+
+function workersNodeImportBanlistPlugin(adapter: PlayBundlingAdapter): Plugin {
+  return {
+    name: 'deepline-workers-node-import-banlist',
+    setup(buildContext) {
+      buildContext.onResolve({ filter: /^node:/ }, (args) => {
+        if (!WORKERS_BANNED_NODE_MODULES.has(args.path)) return null;
+        // SDK internals (sdk/src/*.ts) intentionally reference a small set
+        // of node builtins (e.g. config loaders, tool-output writers) that
+        // never run in the V8 isolate path; they're substituted by the
+        // workersNodeBuiltinStubPlugin's throwing stub. Only reject when
+        // the import comes from outside the SDK source tree -- i.e. user
+        // play code or third-party deps that the play pulls in.
+        const importer = args.importer ?? '';
+        if (importer.startsWith(adapter.sdkSourceRoot)) {
+          return null;
+        }
+        return {
+          errors: [
+            {
+              text: `Module "${args.path}" is not allowed in workers_edge plays. See AGENTS.md for the V8 isolate boundary.`,
+              detail: { importer: args.importer, kind: args.kind },
+            },
+          ],
+        };
+      });
+    },
+  };
+}
+
+function buildImportedPlayProxyModule(playName: string): string {
+  const serializedName = JSON.stringify(playName);
+  return `
+const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
+const importedPlayRef = async function importedPlayRef(ctx, input) {
+  return ctx.runPlay(${JSON.stringify(`imported_${playName.replace(/[^A-Za-z0-9_]+/g, '_')}`)}, importedPlayRef, input, {
+    description: 'Run the imported Deepline play dependency.',
+  });
+};
+Object.defineProperty(importedPlayRef, 'playName', {
+  value: ${serializedName},
+  enumerable: true,
+  configurable: false,
+  writable: false,
+});
+Object.defineProperty(importedPlayRef, PLAY_METADATA_SYMBOL, {
+  value: { name: ${serializedName} },
+  enumerable: false,
+  configurable: false,
+  writable: false,
+});
+export const playName = ${serializedName};
+export const name = ${serializedName};
+export default importedPlayRef;
+`;
+}
+
+function importedPlayProxyPlugin(
+  importedPlayDependencies: ImportedPlayDependency[],
+): Plugin | null {
+  if (importedPlayDependencies.length === 0) {
+    return null;
+  }
+
+  const dependenciesByPath = new Map(
+    importedPlayDependencies.map((dependency) => [dependency.filePath, dependency]),
+  );
+
+  return {
+    name: 'deepline-imported-play-proxy',
+    setup(buildContext) {
+      buildContext.onResolve({ filter: /.*/ }, async (args) => {
+        if (!args.importer || !isLocalSpecifier(args.path)) {
+          return null;
+        }
+
+        const resolvedPath = await resolveLocalImport(args.importer, args.path);
+        const dependency = dependenciesByPath.get(resolvedPath);
+        if (!dependency) {
+          return null;
+        }
+
+        return {
+          path: dependency.filePath,
+          namespace: PLAY_PROXY_NAMESPACE,
+          pluginData: dependency,
+        };
+      });
+
+      buildContext.onLoad({ filter: /.*/, namespace: PLAY_PROXY_NAMESPACE }, async (args) => {
+        const dependency = (args.pluginData as ImportedPlayDependency | undefined)
+          ?? dependenciesByPath.get(args.path);
+        if (!dependency) {
+          return null;
+        }
+
+        return {
+          contents: buildImportedPlayProxyModule(dependency.playName),
+          loader: 'ts',
+          resolveDir: dirname(args.path),
+        };
+      });
+    },
+  };
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveLocalImport(fromFile: string, specifier: string): Promise<string> {
+  if (specifier.startsWith('file:')) {
+    return normalizeLocalPath(new URL(specifier).pathname);
+  }
+
+  const base = isAbsolute(specifier) ? resolve(specifier) : resolve(dirname(fromFile), specifier);
+  const candidates: string[] = [base];
+  const explicitExtension = extname(base).toLowerCase();
+
+  if (!explicitExtension) {
+    candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`));
+    candidates.push(...SOURCE_EXTENSIONS.map((extension) => join(base, `index${extension}`)));
+  } else if (['.js', '.jsx', '.mjs', '.cjs'].includes(explicitExtension)) {
+    const stem = base.slice(0, -explicitExtension.length);
+    candidates.push(...SOURCE_EXTENSIONS.map((extension) => `${stem}${extension}`));
+  }
+
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) {
+      return normalizeLocalPath(candidate);
+    }
+  }
+
+  throw new Error(`Could not resolve local import "${specifier}" from ${fromFile}`);
+}
+
+function resolvePackageImport(
+  specifier: string,
+  fromFile: string,
+  adapter: PlayBundlingAdapter,
+): PackageResolution {
+  const packageName = getPackageName(specifier);
+  if (packageName === 'deepline' && playArtifactRequire('node:fs').existsSync(adapter.sdkPackageJson)) {
+    const packageJson = JSON.parse(
+      playArtifactRequire('node:fs').readFileSync(adapter.sdkPackageJson, 'utf-8'),
+    ) as { version?: string };
+    return {
+      name: 'deepline',
+      version: packageJson.version ?? null,
+    };
+  }
+  const candidateRequires = getPackageRequireCandidates(fromFile);
+  let resolved = false;
+
+  for (const candidateRequire of candidateRequires) {
+    try {
+      candidateRequire.resolve(specifier);
+      resolved = true;
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  if (!resolved) {
+    throw new Error(`Could not resolve "${specifier}" from ${fromFile}`);
+  }
+
+  let version: string | null = null;
+
+  for (const candidateRequire of candidateRequires) {
+    try {
+      const packageJsonPath = candidateRequire.resolve(`${packageName}/package.json`);
+      const packageJson = JSON.parse(
+        playArtifactRequire('node:fs').readFileSync(packageJsonPath, 'utf-8'),
+      ) as { version?: string };
+      version = packageJson.version ?? null;
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  return { name: packageName, version };
+}
+
+async function analyzeSourceGraph(
+  entryFile: string,
+  adapter: PlayBundlingAdapter,
+): Promise<SourceGraphAnalysis> {
+  const absoluteEntryFile = await normalizeLocalPath(entryFile);
+  const workspace = createPlayWorkspace(absoluteEntryFile);
+  const localFiles = new Map<string, string>();
+  const nodeBuiltins = new Set<string>();
+  const packages = new Map<string, string | null>();
+  const importedPlayDependencies = new Map<string, ImportedPlayDependency>();
+  const visited = new Set<string>();
+
+  const visitFile = async (filePath: string) => {
+    const absolutePath = await normalizeLocalPath(filePath);
+    if (visited.has(absolutePath)) {
+      return;
+    }
+    visited.add(absolutePath);
+
+    const sourceCode = await readFile(absolutePath, 'utf-8');
+    localFiles.set(absolutePath, sourceCode);
+
+    if (extname(absolutePath).toLowerCase() === '.json') {
+      return;
+    }
+
+    const sourceFile = ts.createSourceFile(
+      absolutePath,
+      sourceCode,
+      ts.ScriptTarget.Latest,
+      true,
+      scriptKindForFile(absolutePath),
+    );
+
+    const handleSpecifier = async (
+      specifier: string,
+      node: ts.Node,
+      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.`,
+        );
+      }
+
+      if (NODE_BUILTIN_SET.has(specifier)) {
+        nodeBuiltins.add(specifier.startsWith('node:') ? specifier : `node:${specifier}`);
+        return;
+      }
+
+      if (isLocalSpecifier(specifier)) {
+        const resolved = await resolveLocalImport(absolutePath, specifier);
+        assertWithinPlayWorkspace({
+          importer: absolutePath,
+          specifier,
+          resolvedPath: resolved,
+          workspace,
+          sourceFile,
+          node,
+        });
+        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.`,
+            );
+          }
+          importedPlayDependencies.set(resolved, {
+            filePath: resolved,
+            playName: importedPlayName,
+          });
+          return;
+        }
+        await visitFile(resolved);
+        return;
+      }
+
+      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.`,
+        );
+      }
+
+      const packageImport = resolvePackageImport(specifier, absolutePath, adapter);
+      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');
+        }
+      }
+
+      for (const child of node.getChildren(sourceFile)) {
+        await walk(child);
+      }
+    };
+
+    await walk(sourceFile);
+  };
+
+  await visitFile(absoluteEntryFile);
+
+  const sourceCode = localFiles.get(absoluteEntryFile) ?? '';
+  const sourceHash = sha256(sourceCode);
+  const graphHash = sha256(
+    JSON.stringify({
+      entryFile: absoluteEntryFile,
+      localFiles: [...localFiles.entries()]
+        .map(([filePath, contents]) => ({ filePath, hash: sha256(contents) }))
+        .sort((left, right) => left.filePath.localeCompare(right.filePath)),
+      nodeBuiltins: [...nodeBuiltins].sort(),
+      packages: [...packages.entries()]
+        .map(([name, version]) => ({ name, version }))
+        .sort((left, right) => left.name.localeCompare(right.name)),
+      importedPlayDependencies: [...importedPlayDependencies.values()]
+        .map((dependency) => ({
+          filePath: dependency.filePath,
+          playName: dependency.playName,
+        }))
+        .sort((left, right) => left.filePath.localeCompare(right.filePath)),
+    }),
+  );
+  const playName = extractDefinedPlayName(sourceCode, absoluteEntryFile);
+
+  return {
+    sourceCode,
+    sourceHash,
+    graphHash,
+    importPolicy: {
+      localFiles: [...localFiles.keys()].sort(),
+      nodeBuiltins: [...nodeBuiltins].sort(),
+      packages: [...packages.entries()]
+        .map(([name, version]) => ({ name, version }))
+        .sort((left, right) => left.name.localeCompare(right.name)),
+    },
+    playName,
+    importedPlayDependencies: [...importedPlayDependencies.values()]
+      .sort((left, right) => left.filePath.localeCompare(right.filePath)),
+  };
+}
+
+/**
+ * Fingerprint of every TypeScript file in the Workers harness source dir.
+ * The harness gets bundled INTO every esm_workers play artifact, so any
+ * harness edit must invalidate the bundle cache and force a fresh CF
+ * deploy. Computed fresh on every bundle call so dev edits to entry.ts (or
+ * its peer DO files) are picked up on the next `play run` without
+ * restarting the dev server. (4 small files = sub-millisecond.) No
+ * caching: that's deliberate — caching the fingerprint is exactly the
+ * stale-state bug this exists to prevent.
+ */
+async function computeWorkersHarnessFingerprintWithAdapter(
+  adapter: PlayBundlingAdapter,
+): Promise<string> {
+  const { readdir } = await import('node:fs/promises');
+  const entries = await readdir(adapter.workersHarnessFilesDir, { withFileTypes: true });
+  const tsFiles = entries
+    .filter((e) => e.isFile() && /\.[cm]?ts$/.test(e.name))
+    .map((e) => e.name)
+    .sort();
+  const parts: Array<{ name: string; hash: string }> = [];
+  for (const name of tsFiles) {
+    const contents = await readFile(join(adapter.workersHarnessFilesDir, name), 'utf-8');
+    parts.push({ name, hash: sha256(contents) });
+  }
+  return sha256(JSON.stringify(parts));
+}
+
+function artifactCachePath(
+  graphHash: string,
+  artifactKind: PlayArtifactKind,
+  adapter: PlayBundlingAdapter,
+): string {
+  // Cache key includes artifactKind so a play can have both cjs_node20 and
+  // esm_workers builds cached side-by-side without one stomping on the other.
+  return join(
+    adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR,
+    `${graphHash}.${artifactKind}.json`,
+  );
+}
+
+async function readArtifactCache(
+  graphHash: string,
+  artifactKind: PlayArtifactKind,
+  adapter: PlayBundlingAdapter,
+): Promise<PlayBundleArtifact | null> {
+  try {
+    const serialized = await readFile(
+      artifactCachePath(graphHash, artifactKind, adapter),
+      'utf-8',
+    );
+    return JSON.parse(serialized) as PlayBundleArtifact;
+  } catch {
+    return null;
+  }
+}
+
+async function writeArtifactCache(
+  artifact: PlayBundleArtifact,
+  adapter: PlayBundlingAdapter,
+): Promise<void> {
+  const cacheDir = adapter.cacheDir ?? PLAY_ARTIFACT_CACHE_DIR;
+  await mkdir(cacheDir, { recursive: true });
+  await writeFile(
+    artifactCachePath(
+      artifact.graphHash,
+      artifact.artifactKind ?? PLAY_ARTIFACT_KINDS.cjsNode20,
+      adapter,
+    ),
+    JSON.stringify(artifact),
+    'utf-8',
+  );
+}
+
+function normalizeSourceMapForRuntime(sourceMapText: string): string {
+  const parsed = JSON.parse(sourceMapText) as {
+    sourceRoot?: string;
+    sources?: string[];
+  };
+
+  parsed.sources = (parsed.sources ?? []).map((sourcePath) => {
+    if (
+      sourcePath.startsWith('data:') ||
+      sourcePath.startsWith('node:') ||
+      sourcePath.startsWith('/') ||
+      /^[a-zA-Z]+:\/\//.test(sourcePath)
+    ) {
+      return sourcePath;
+    }
+
+    return resolve(process.cwd(), sourcePath);
+  });
+  parsed.sourceRoot = undefined;
+
+  return JSON.stringify(parsed);
+}
+
+function getBundleSizeError(
+  filePath: string,
+  bundledCode: string,
+  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).`;
+  }
+  if (
+    artifactKind === PLAY_ARTIFACT_KINDS.esmWorkers &&
+    bundleBytes > MAX_ESM_WORKERS_BUNDLE_BYTES
+  ) {
+    const mib = (bundleBytes / 1024 / 1024).toFixed(2);
+    const limitMib = (MAX_ESM_WORKERS_BUNDLE_BYTES / 1024 / 1024).toFixed(2);
+    return (
+      `${filePath} Cloudflare Workers bundle is ${mib} MiB, above the workerd ` +
+      `local-mode threshold of ${limitMib} MiB. Bundles past this size silently ` +
+      `hang without executing the workflow body. Reduce dependencies (top ` +
+      `offenders are usually date-fns, lodash, large schema libs) or split the ` +
+      `play into smaller pieces with ctx.runPlay.`
+    );
+  }
+  return null;
+}
+
+export type BundlePlayFileOptions = {
+  /**
+   * Which artifact to produce. Defaults to `cjs_node20` (Daytona / local-process
+   * runner). Pass `esm_workers` to produce a Cloudflare Worker bundle that
+   * combines the play with the Workers harness.
+   *
+   * The CLI selects this from the execution profile or an explicit flag. Each
+   * kind is cached independently on disk.
+   */
+  target?: PlayArtifactKind;
+};
+
+export type BundlePlayFileCoreOptions = BundlePlayFileOptions & {
+  adapter: PlayBundlingAdapter;
+};
+
+type EsbuildBundleOutput = {
+  bundledCode: string;
+  sourceMapText: string;
+  outputExtension: 'cjs' | 'mjs';
+};
+
+async function runEsbuildForCjsNode(
+  entryFile: string,
+  importedPlayDependencies: ImportedPlayDependency[],
+  adapter: PlayBundlingAdapter,
+): Promise<EsbuildBundleOutput | string[]> {
+  const sdkAliasPlugin = localSdkAliasPlugin(adapter);
+  const playProxyPlugin = importedPlayProxyPlugin(importedPlayDependencies);
+  const result = await build({
+    entryPoints: [entryFile],
+    absWorkingDir: adapter.projectRoot,
+    bundle: true,
+    format: 'cjs',
+    nodePaths: [adapter.nodeModulesDir],
+    platform: 'node',
+    target: ['node20'],
+    outfile: 'play-artifact.cjs',
+    write: false,
+    sourcemap: 'external',
+    sourcesContent: false,
+    logLevel: 'silent',
+    legalComments: 'none',
+    plugins: [sdkAliasPlugin, playProxyPlugin].filter(
+      (plugin): plugin is Plugin => plugin != null,
+    ),
+  });
+  const codeFile = result.outputFiles?.find((f) => f.path.endsWith('.cjs'));
+  const mapFile = result.outputFiles?.find((f) => f.path.endsWith('.cjs.map'));
+  if (!codeFile?.text || !mapFile?.text) {
+    return ['Play bundling produced incomplete output.'];
+  }
+  return {
+    bundledCode: codeFile.text,
+    sourceMapText: mapFile.text,
+    outputExtension: 'cjs',
+  };
+}
+
+async function runEsbuildForEsmWorkers(
+  playEntryFile: string,
+  importedPlayDependencies: ImportedPlayDependency[],
+  adapter: PlayBundlingAdapter,
+): Promise<EsbuildBundleOutput | string[]> {
+  const sdkAliasPlugin = localSdkAliasPlugin(adapter, { workersRuntime: true });
+  const playProxyPlugin = importedPlayProxyPlugin(importedPlayDependencies);
+  const playEntryAlias = workersPlayEntryAliasPlugin(playEntryFile);
+  const result = await build({
+    // Entry is the Workers harness; it imports the play via the virtual
+    // `deepline-play-entry` alias resolved by workersPlayEntryAliasPlugin.
+    entryPoints: [adapter.workersHarnessEntryFile],
+    absWorkingDir: adapter.projectRoot,
+    bundle: true,
+    format: 'esm',
+    nodePaths: [adapter.nodeModulesDir],
+    // Browser platform with workerd + worker conditions matches Cloudflare's
+    // V8-isolate runtime. Avoids accidentally pulling node-only branches of
+    // dual-publish packages.
+    platform: 'browser',
+    conditions: ['workerd', 'worker', 'browser', 'import', 'default'],
+    mainFields: ['module', 'main'],
+    target: ['es2022'],
+    outfile: 'play-worker.mjs',
+    write: false,
+    sourcemap: 'external',
+    sourcesContent: false,
+    logLevel: 'silent',
+    legalComments: 'none',
+    // Aggressive minify + treeshake: a tiny play (<1KB source) was producing
+    // an ~870KB bundle, dominated by zod's locale files (~260KB unused) and
+    // dead-code branches across `shared_libs/play-runtime/*` and the SDK.
+    // Both DCE on with these flags. workerd compiles each unique-graphHash
+    // bundle on first dispatch, so bundle bytes translate ~linearly into
+    // per-play cold latency on workers_edge. External sourcemap remains
+    // unchanged (`sourcemap: 'external'`), so debugging is unaffected.
+    minify: true,
+    treeShaking: true,
+    // Most node:* builtins are provided by Cloudflare's `nodejs_compat` flag.
+    // The unsupported subset (fs, fs/promises, os, child_process) gets
+    // replaced with throwing stubs by workersNodeBuiltinStubPlugin so deploy
+    // validation passes; anything supported (path, crypto, buffer, etc.) is
+    // marked external and resolved at runtime by the Workers runtime.
+    external: ['node:*', 'cloudflare:workers'],
+    plugins: [
+      // Banlist runs first so a forbidden import errors out before any other
+      // resolver (esp. the workersNodeBuiltinStubPlugin which would silently
+      // turn it into a throwing-stub).
+      workersNodeImportBanlistPlugin(adapter),
+      sdkAliasPlugin,
+      playProxyPlugin,
+      playEntryAlias,
+      workersNodeBuiltinStubPlugin(),
+      // Strip non-English zod locale data from the bundle. zod's locales
+      // are re-exported as a static namespace from `zod/v4/core`, so
+      // tree-shaking can't drop them; this plugin replaces each
+      // non-English locale module with an empty default export at bundle
+      // time. ~150–200 KB savings on every per-play bundle, with no
+      // behavior change (we only surface English messages anyway).
+      // If the bundle suddenly grows back, check whether a new dep added
+      // its own zod copy or whether zod's locale layout changed.
+      zodNonEnglishLocaleStubPlugin(),
+    ].filter((plugin): plugin is Plugin => plugin != null),
+  });
+  const codeFile = result.outputFiles?.find((f) => f.path.endsWith('.mjs'));
+  const mapFile = result.outputFiles?.find((f) => f.path.endsWith('.mjs.map'));
+  if (!codeFile?.text || !mapFile?.text) {
+    return ['Workers play bundling produced incomplete output.'];
+  }
+  return {
+    bundledCode: codeFile.text,
+    sourceMapText: mapFile.text,
+    outputExtension: 'mjs',
+  };
+}
+
+export async function bundlePlayFile(
+  filePath: string,
+  options: BundlePlayFileCoreOptions,
+): Promise<BundledPlayFileResult> {
+  const adapter = options.adapter;
+  const target: PlayArtifactKind = options.target ?? PLAY_ARTIFACT_KINDS.cjsNode20;
+  const absolutePath = await normalizeLocalPath(filePath);
+  adapter.warnAboutNonDevelopmentBundling?.(absolutePath);
+
+  try {
+    const analysis = await analyzeSourceGraph(absolutePath, adapter);
+    // For esm_workers builds, the harness source files (entry.ts +
+    // peer DO/coordinator types it imports) are bundled INTO every play
+    // artifact. So any harness edit must produce a different graphHash so
+    // (a) the bundle cache misses, (b) the per-graphHash CF Worker name
+    // changes and gets a fresh deploy. This is the file-watcher-equivalent
+    // for hot-reload of the harness: editing entry.ts → next play run
+    // re-bundles + redeploys automatically.
+    if (target === PLAY_ARTIFACT_KINDS.esmWorkers) {
+      const harnessFingerprint = await computeWorkersHarnessFingerprintWithAdapter(adapter);
+      analysis.graphHash = sha256(
+        `${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 cachedArtifact = await readArtifactCache(analysis.graphHash, target, adapter);
+    const discoveredFiles = await adapter.discoverPackagedLocalFiles(absolutePath);
+    if (cachedArtifact) {
+      const cachedArtifactSizeError = getBundleSizeError(
+        absolutePath,
+        cachedArtifact.bundledCode,
+        target,
+      );
+      if (cachedArtifactSizeError) {
+        return {
+          success: false,
+          filePath: absolutePath,
+          errors: [cachedArtifactSizeError],
+        };
+      }
+
+      return {
+        success: true,
+        artifact: { ...cachedArtifact, cacheHit: true },
+        sourceCode: analysis.sourceCode,
+        filePath: absolutePath,
+        playName: analysis.playName,
+        packagedFiles: discoveredFiles.files,
+        unresolvedFileReferences: discoveredFiles.unresolved,
+        importedPlayDependencies: analysis.importedPlayDependencies,
+      };
+    }
+
+    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)
+        : await runEsbuildForCjsNode(absolutePath, analysis.importedPlayDependencies, adapter);
+    if (Array.isArray(buildOutcome)) {
+      return {
+        success: false,
+        filePath: absolutePath,
+        errors: buildOutcome,
+      };
+    }
+    const { bundledCode, sourceMapText, outputExtension } = buildOutcome;
+
+    const normalizedSourceMap = normalizeSourceMapForRuntime(sourceMapText);
+    const virtualFilename = `/virtual/deepline-plays/${analysis.graphHash}/${basename(absolutePath).replace(/\.[^.]+$/, '')}.${outputExtension}`;
+    const executableCode = `${bundledCode}\n//# sourceMappingURL=${basename(virtualFilename)}.map\n`;
+    const bundleSizeError = getBundleSizeError(
+      absolutePath,
+      executableCode,
+      target,
+    );
+    if (bundleSizeError) {
+      return {
+        success: false,
+        filePath: absolutePath,
+        errors: [bundleSizeError],
+      };
+    }
+
+    const codeFormat: PlayBundleArtifact['codeFormat'] =
+      target === PLAY_ARTIFACT_KINDS.esmWorkers ? 'esm_module' : 'cjs_module';
+
+    const artifact: PlayBundleArtifact = {
+      codeFormat,
+      artifactKind: target,
+      entryFile: absolutePath,
+      virtualFilename,
+      sourceHash: analysis.sourceHash,
+      graphHash: analysis.graphHash,
+      artifactHash: sha256(executableCode),
+      sourceMapHash: sha256(normalizedSourceMap),
+      bundledCode: executableCode,
+      sourceMap: normalizedSourceMap,
+      importPolicy: analysis.importPolicy,
+      compatibility: buildPlayContractCompatibility(),
+      generatedAt: Date.now(),
+      cacheHit: false,
+    };
+
+    await writeArtifactCache(artifact, adapter);
+
+    return {
+      success: true,
+      artifact,
+      sourceCode: analysis.sourceCode,
+      filePath: absolutePath,
+      playName: analysis.playName,
+      packagedFiles: discoveredFiles.files,
+      unresolvedFileReferences: discoveredFiles.unresolved,
+      importedPlayDependencies: analysis.importedPlayDependencies,
+    };
+  } catch (error) {
+    if (error && typeof error === 'object' && 'errors' in error) {
+      const errors = Array.isArray((error as { errors?: Message[] }).errors)
+        ? ((error as { errors: Message[] }).errors).map(formatEsbuildMessage)
+        : ['Play bundling failed.'];
+      return {
+        success: false,
+        filePath: absolutePath,
+        errors,
+      };
+    }
+
+    return {
+      success: false,
+      filePath: absolutePath,
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+}