@volter/browser-substrate 0.1.103 → 0.1.105

package/dist/cli/main.js

@@ -7,7 +7,8 @@
 import { catalogProvidedPackages } from "../emscripten-catalog.js";
 import { shellPrograms } from "./shell-programs.js";
 import { createHash } from "node:crypto";
-import { homedir } from "node:os";
+import { preparationCacheDirectory, selectedCacheRoot } from "./cache-root.js";
+import { preparationBounded, preparationCheckpoint, preparationMemoryLimit, preparationPhase, withPreparationMemory } from "./preparation-memory.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, watch, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -38,15 +39,18 @@ import { detectSetup, SetupError } from "../setup.js";
 import { carryRegistryTarballs } from "./plan-tarballs.js";
 import { builtForPlan } from "./project-build.js";
 import { TAB_IMAGE_PROGRAMS, TAB_PROVIDED_IMAGES } from "../program-images.js";
+import { formatBrowserProvisionPlan, planBrowserProvisionDemand, readBrowserProvisionDemand } from "./provision-demand.js";
 const USAGE = `Usage:
   browser-substrate dev     [--port <n>] [--no-open] [--no-packs] [--world <dir>] [--dir <sub>] [--build <command>] [settings] [-- <command>]
                             run this folder in a tab, attached to a World; a command after -- is what serves it,
                             run in --dir, the way a developer types it, in place of what the folder's files say;
                             --build is the project's own build, run on this machine at its root, its output carried
-  browser-substrate build   [--out <dir>] [--world <dir>] [--project <id>] [--build-arg <name=value>] [--program <browser-program.json> --programs-dir <dir>] [settings]
+  browser-substrate build   [--out <dir>] [--cache-root <dir>] [--world <dir>] [--project <id>] [--build-arg <name=value>] [--program <browser-program.json> --programs-dir <dir>] [settings]
                             write ./dist: the page and the image; a --program the image's command names
                             is carried in its layers, its archives read from <dir><url>; --world images the
                             World the tab runs the image's command under; --build-arg is a Dockerfile's ARG
+  browser-substrate plan-provisions [--provision-catalog <json>] [--source-pin <commit>] [--definition <file>] [--dependency-plan <json>]
+                            read and report demand without preparing an image or starting compute
   browser-substrate preview [--port <n>] [--out <dir>] [--no-open]  serve ./dist locally with its _headers
   browser-substrate dry-run [--page <url>] [--settle <s>] [--rounds <n>] [--captured <file>] [--steps <file.json>]
                             open the image in Chrome and record every install the tab refuses; what a pack
@@ -59,6 +63,9 @@ Settings, all optional, needed only to serve something yourself:
   --sandbox-origin <origin>   where a playground's sandbox is served (default: sandbox.<host>)
   --relay <origin>            the relay for Git and outbound TCP (default: ours, under its allowance)
   --artifacts <url>           where verified runtime artifacts are fetched from (default: ours)
+  --cache-root <dir>          preparation cache and scratch; overrides BROWSER_SUBSTRATE_CACHE_ROOT
+  --provision-catalog <json>  local publication directory, pinned catalog digest and runtime profile
+  --preparation-memory-mib <n>  build's owned-tree RSS admission; overrides BROWSER_SUBSTRATE_PREPARATION_MEMORY_MIB
   --name <image>              the image name a page opens (default: app)
   --no-packs                  skip preparing packs on this machine; the tab never builds a package, so such an
                               image is refused at the first import that needs one
@@ -69,11 +76,18 @@ export async function main(argv) {
     const cwd = process.cwd();
     switch (args.command) {
         case "dev": return dev(cwd, args);
-        case "build": return build(cwd, args);
+        case "build": return withPreparationMemory(args.preparationMemoryMiB, resolve(cwd, args.out), () => build(cwd, args));
         case "init": return init(cwd);
         case "preview": return preview(cwd, args);
         case "dockerfile": return dockerfile(cwd, args);
         case "dry-run": return dryRunCommand(cwd, args);
+        case "plan-provisions": {
+            const catalog = args.provisionCatalogFile ? JSON.parse(readFileSync(resolve(cwd, args.provisionCatalogFile), "utf8")) : undefined;
+            const demand = readBrowserProvisionDemand(cwd, { abi: catalog?.profile.abi ?? "unselected", ...(args.sourcePin ? { sourcePin: args.sourcePin } : {}), ...(args.definition ? { selectedFile: args.definition } : {}), ...(args.dependencyPlanFile ? { plan: JSON.parse(readFileSync(resolve(cwd, args.dependencyPlanFile), "utf8")) } : {}) });
+            const plan = catalog ? await planBrowserProvisionDemand(demand, catalog) : undefined;
+            process.stdout.write(formatBrowserProvisionPlan(demand, plan));
+            return demand.incomplete.length || demand.items.some((item, index) => item.scope === "selected" && plan?.rows[index]?.status !== "resolved") ? 2 : 0;
+        }
         default:
             process.stdout.write(USAGE);
             return args.command === undefined || args.command === "help" ? 0 : 2;
@@ -115,6 +129,18 @@ function parse(argv) {
         // builds each package itself, which is what it did before it carried any.
         else if (arg === "--no-packs")
             args.packs = false;
+        else if (arg === "--cache-root")
+            args.cacheRoot = value();
+        else if (arg === "--provision-catalog")
+            args.provisionCatalogFile = value();
+        else if (arg === "--source-pin")
+            args.sourcePin = value();
+        else if (arg === "--definition")
+            args.definition = value();
+        else if (arg === "--dependency-plan")
+            args.dependencyPlanFile = value();
+        else if (arg === "--preparation-memory-mib")
+            args.preparationMemoryMiB = preparationMemoryLimit(value());
         else if (arg === "--out")
             args.out = value();
         else if (arg === "--name")
@@ -166,6 +192,18 @@ function parse(argv) {
         throw new Error("--name must be lowercase letters, digits, dots, dashes, or underscores.");
     if (!Number.isInteger(args.port) || args.port < 1 || args.port > 65_535)
         throw new Error("--port must be a port number.");
+    const cacheRoot = selectedCacheRoot(args.cacheRoot);
+    if (cacheRoot)
+        args.cacheRoot = cacheRoot;
+    if (args.command === "build" && args.preparationMemoryMiB === undefined) {
+        const memoryLimit = preparationMemoryLimit();
+        if (memoryLimit !== undefined)
+            args.preparationMemoryMiB = memoryLimit;
+    }
+    if (args.command !== "build" && args.preparationMemoryMiB !== undefined)
+        throw new Error("--preparation-memory-mib applies to build only.");
+    if (args.command !== "plan-provisions" && (args.sourcePin || args.definition || args.dependencyPlanFile))
+        throw new Error("--source-pin, --definition and --dependency-plan apply to plan-provisions only.");
     return args;
 }
 /** What a folder carries, for the setup reader. */
@@ -186,6 +224,12 @@ export async function buildImage(folder, name, settings, project) {
 }
 export async function buildImageWith(folder, name, settings, project, options) {
     assertShell();
+    // Report all static demands before even an archive copy or setup refusal.
+    // Existing families remain on their only current path until their genuine
+    // replacement is published and their atomic consumer/removal cutover lands.
+    const demand = readBrowserProvisionDemand(folder, { abi: options.provisionCatalog?.profile.abi ?? "unselected", ...(options.buildArgs ? { buildArgs: options.buildArgs } : {}) });
+    const provisionPlan = options.provisionCatalog ? await planBrowserProvisionDemand(demand, options.provisionCatalog) : undefined;
+    process.stdout.write(formatBrowserProvisionPlan(demand, provisionPlan));
     let setup;
     try {
         setup = await detectSetup(projectFiles(folder), { ...(options.serve ? { serve: options.serve } : {}), ...(options.directory ? { directory: options.directory } : {}) });
@@ -198,7 +242,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
     if (!setup) {
         throw new Error(`${folder} carries nothing to run: add a Dockerfile with a CMD, or a package.json with a dev script. An empty folder becomes a playground with \`browser-substrate init\`.`);
     }
-    let archive = archiveFolder(folder);
+    let archive = archiveFolder(folder, options.cacheRoot ? { cacheRoot: options.cacheRoot } : {});
     let preparation = { location: "none" };
     if (setup.kind === "dockerfile") {
         // A Dockerfile has two halves. The tab builds and runs a file it can take
@@ -224,6 +268,8 @@ export async function buildImageWith(folder, name, settings, project, options) {
         // the tab receives what it made.
         const runSteps = parseContainerFile(dockerfile).stages.flatMap((stage) => stage.instructions.filter((instruction) => instruction.kind === "run").map((instruction) => instruction.line));
         if (report.phases.build.verdict !== "native" || runSteps.length > 0) {
+            if (preparationBounded())
+                throw new Error("Bounded preparation refuses container RUN backends: their external/runtime tasks lack complete owned native-process cancellation/RSS coverage. No fallback was started.");
             process.stdout.write(report.phases.build.verdict !== "native"
                 ? `  the build half needs more than the tab has (${report.phases.build.blocking.map((b) => `line ${b.line}`).join(", ")}); building it here\n`
                 : `  the build half runs ${runSteps.length} RUN step${runSteps.length === 1 ? "" : "s"} (line${runSteps.length === 1 ? "" : "s"} ${runSteps.join(", ")}); building it here, where setup runs\n`);
@@ -237,6 +283,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
                 if (options.buildArgs)
                     throw new Error(`Build arguments (${Object.keys(options.buildArgs).join(", ")}) are read by Docker`);
                 built = await buildOnHost(folder, dockerfile, (text) => process.stdout.write(text), {
+                    ...(options.cacheRoot ? { cacheRoot: options.cacheRoot } : {}),
                     ...(setup.target ? { target: setup.target } : {}),
                     ...(setup.context ? { context: setup.context } : {}),
                 });
@@ -254,6 +301,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
                     ...(externalBase(report) ? { base: externalBase(report) } : {}),
                     programs: tabLaneTable().programs,
                     ...(options.buildArgs ? { buildArgs: options.buildArgs } : {}),
+                    ...(options.cacheRoot ? { cacheRoot: options.cacheRoot } : {}),
                     ...(setup.target ? { target: setup.target } : {}),
                     ...(setup.context ? { context: setup.context } : {}),
                 });
@@ -274,7 +322,9 @@ export async function buildImageWith(folder, name, settings, project, options) {
     let rolldown;
     const tarballs = new Map();
     if (options.dependencies !== false && setup.kind === "manifests" && setup.install) {
+        preparationPhase("plan");
         const resolved = await resolveDependencyPlan(folder, setup.install, {
+            ...(options.cacheRoot ? { cacheRoot: options.cacheRoot } : {}),
             ...(options.packagesDirectory ? { packagesDirectory: options.packagesDirectory } : {}),
             onOutput: (text) => process.stdout.write(text),
             // What the tab's copy of the project holds is the archive, not the
@@ -300,7 +350,8 @@ export async function buildImageWith(folder, name, settings, project, options) {
             if (options.packagesDirectory)
                 servePlanTarballsFromOrigin(plan, options.packagesDirectory);
             // What the project's toolchain needs in the tab beyond its lockfile.
-            const companions = await addCompanionPackages(plan, (text) => process.stdout.write(text));
+            preparationPhase("generate");
+            const companions = await addCompanionPackages(plan, (text) => process.stdout.write(text), options.cacheRoot);
             // The companions are part of what the tab links, so they are part of the
             // plan's key: a workspace linked from an image without them, whose key
             // was the same, kept its tree and never received them.
@@ -316,6 +367,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
             // was the same, would keep its tree and never receive it.
             const generated = await generatedForPlan(folder, plan, setup.install, {
                 imageName: name,
+                ...(options.cacheRoot ? { cacheRoot: options.cacheRoot } : {}),
                 ...(options.packagesDirectory ? { packagesDirectory: options.packagesDirectory } : {}),
                 onOutput: (text) => process.stdout.write(text),
             });
@@ -332,12 +384,14 @@ export async function buildImageWith(folder, name, settings, project, options) {
             if (captured.packs.length > 0)
                 process.stdout.write(`  captured: ${captured.packs.length} packs an earlier dry run asked for\n`);
             if (options.build) {
+                preparationPhase("product build");
                 const built = await builtForPlan(folder, plan, setup.install, options.build, {
                     imageName: name,
                     sourcesDigest: archive.integrity,
                     holds: (path) => archive.files.has(path),
                     ...(options.buildEnv ? { env: options.buildEnv } : {}),
                     ...(options.buildWorld ? { world: options.buildWorld } : {}),
+                    ...(options.cacheRoot ? { cacheRoot: options.cacheRoot } : {}),
                     ...(options.packagesDirectory ? { packagesDirectory: options.packagesDirectory } : {}),
                     onOutput: (text) => process.stdout.write(text),
                 });
@@ -357,7 +411,8 @@ export async function buildImageWith(folder, name, settings, project, options) {
             if (plan.entries.length > 0)
                 plan.key = `${plan.key}-${createHash("sha256").update(plan.entries.map((entry) => `${entry.path}\0${entry.content}`).join("\n")).digest("hex").slice(0, 12)}`;
             // The project's own Rolldown binding, where its version is not the shell's.
-            const binding = await rolldownBindingForPlan(plan, imageRolldownPath(name, plan.packages.find((entry) => entry.name === "rolldown")?.version ?? ""), (text) => process.stdout.write(text));
+            preparationPhase("generate");
+            const binding = await rolldownBindingForPlan(plan, imageRolldownPath(name, plan.packages.find((entry) => entry.name === "rolldown")?.version ?? ""), (text) => process.stdout.write(text), options.cacheRoot);
             if (binding) {
                 for (const [served, source] of binding.files)
                     tarballs.set(served, source);
@@ -367,11 +422,12 @@ export async function buildImageWith(folder, name, settings, project, options) {
             // Every registry package the plan names travels with the image, the
             // companions included: the tab never reaches a registry, and refuses a
             // plan that names one.
-            const carried = await carryRegistryTarballs(plan, name);
+            preparationPhase("package archives");
+            const carried = await carryRegistryTarballs(plan, name, options.cacheRoot ? { cacheRoot: options.cacheRoot } : {});
             process.stdout.write(`  carried: ${carried.files.size} registry packages, ${formatBytes(carried.bytes)}, ${carried.fetched} fetched here, ${carried.cached} from the cache\n`);
             // What travels is each package's pack, its tree laid out here; the tab
             // never reads a tarball (Article 1), so the tarballs stay on this machine.
-            const planPacks = await packPlan(plan, name, carried.files, tarballs, options.packagesDirectory ?? join(folder, PACKAGES_DIRECTORY));
+            const planPacks = await packPlan(plan, name, carried.files, tarballs, options.packagesDirectory ?? join(folder, PACKAGES_DIRECTORY), options.cacheRoot);
             for (const [served, source] of planPacks.files)
                 tarballs.set(served, source);
             // The packs are what a warm open links; another set of them is another plan.
@@ -379,9 +435,10 @@ export async function buildImageWith(folder, name, settings, project, options) {
             process.stdout.write(`  packages as packs: ${planPacks.files.size} archives, ${formatBytes(planPacks.bytes)}\n`);
             // Each package's browser build, made here under the key the tab
             // computes for it. The tab links what is carried and builds the rest.
-            const moduleWorld = options.moduleWorld ? await buildWorldImage(options.moduleWorld, name) : undefined;
+            const moduleWorld = options.moduleWorld ? await buildWorldImage(options.moduleWorld, name, options.cacheRoot) : undefined;
             let builtForLayers;
             if (options.packs !== false) {
+                preparationPhase("bundles");
                 const built = await packsForPlan(folder, plan, setup.install, {
                     moduleSourcesKey: `${archive.integrity}|${moduleWorld?.world.archive.integrity ?? ""}`,
                     ...(options.moduleWorld ? { moduleSourceTrees: [options.moduleWorld] } : {}),
@@ -392,6 +449,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
                             throw new Error(`No carried module pack for ${entry.name}@${entry.version}`);
                         return { file, artifact: pack.artifact };
                     }),
+                    ...(options.cacheRoot ? { cacheRoot: options.cacheRoot } : {}),
                     ...(options.packagesDirectory ? { packagesDirectory: options.packagesDirectory } : {}),
                     // What the image's dry run captured last time is prepared too (ADR-0043).
                     ...(prebundled.length > 0 || captured.packs.length > 0 ? { extra: [...prebundled, ...captured.packs] } : {}),
@@ -404,7 +462,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
                     const have = new Set(built.modules.map((body) => body.key));
                     let carried = 0;
                     for (const key of captured.prepared) {
-                        const file = join(preparedBodiesDirectory(captured.cache), key);
+                        const file = join(preparedBodiesDirectory(captured.cache, options.cacheRoot), key);
                         if (have.has(key) || !existsSync(file))
                             continue;
                         built.modules.push({ key, file, bytes: statSync(file).size });
@@ -439,6 +497,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
             // What all of that puts in the origin's shared store, laid out as the
             // store keeps it, in parts the tab appends whole (ADR-0045).
             if (options.layers !== false) {
+                preparationPhase("layers");
                 const startedAt = Date.now();
                 // World packages enter the same content-addressed store before its links
                 // are placed. Leaving them out makes every cold tab expand them again.
@@ -450,7 +509,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
                     { root: "/workspace/app", tree: treeUnit(archive.bytes, archive.blobs) },
                     ...(moduleWorld ? [{ root: `/workspace/worlds/${moduleWorld.world.name}`, tree: treeUnit(moduleWorld.archive, moduleWorld.blobs) }] : []),
                 ].flatMap(({ root, tree }) => tree ? [{ root, ...tree }] : []);
-                layers = await buildImageLayers(name, withTrees(layerUnits(layerPlan, layerFiles, builtForLayers, options.programs ?? [], options.programsDirectory), trees.map(({ unit }) => unit)), 0, undefined, {
+                layers = await buildImageLayers(name, withTrees(layerUnits(layerPlan, layerFiles, builtForLayers, options.programs ?? [], options.programsDirectory), trees.map(({ unit }) => unit)), 0, preparationCacheDirectory("layer-parts", options.cacheRoot), {
                     plans: [{ root: "/workspace/app", plan }, ...(moduleWorld?.plan ? [{ root: `/workspace/worlds/${moduleWorld.world.name}`, plan: moduleWorld.plan }] : [])],
                     trees: trees.map(({ root, unit, integrity, mtimes }) => ({ root, unit: unit.root, integrity, mtimes })),
                 });
@@ -465,8 +524,8 @@ export async function buildImageWith(folder, name, settings, project, options) {
     // packs is another pre-bundle, which the tab would serve as this one.
     const captureKey = readCaptured(options.capturedFile ?? join(folder, PACKAGES_DIRECTORY, "..", CAPTURED_FILE)).cache;
     const packsDigest = packs ? createHash("sha256").update(JSON.stringify(packs.document)).digest("hex").slice(0, 16) : undefined;
-    const warmRecord = captureKey ? readWarmRecord(warmDirectory(captureKey)) : undefined;
-    const warm = captureKey && warmRecord && packsDigest && warmRecord.packs?.digest === packsDigest ? warmFiles(join(warmDirectory(captureKey), "files")) : undefined;
+    const warmRecord = captureKey ? readWarmRecord(warmDirectory(captureKey, options.cacheRoot)) : undefined;
+    const warm = captureKey && warmRecord && packsDigest && warmRecord.packs?.digest === packsDigest ? warmFiles(join(warmDirectory(captureKey, options.cacheRoot), "files")) : undefined;
     for (const file of warm?.files ?? [])
         archive.blobs.set(file.integrity, file.source);
     if (warm)
@@ -501,7 +560,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
     // The origin's Cache Storage the dry run left (an engine's artifacts, the
     // service worker's copies of the project's servers' cacheable answers):
     // a first open puts each back before anything asks for it.
-    const caches = captureKey ? capturedCaches(name, cachesDirectory(captureKey)) : undefined;
+    const caches = captureKey ? capturedCaches(name, cachesDirectory(captureKey, options.cacheRoot)) : undefined;
     if (caches) {
         const bytes = caches.entries.reduce((total, entry) => total + entry.bytes, 0);
         manifest.caches = { url: `/substrate/${name}.caches.json`, entries: caches.entries.length, bytes };
@@ -510,7 +569,7 @@ export async function buildImageWith(folder, name, settings, project, options) {
     const startup = readStartupRecord(folder);
     let startupStreams;
     if (startup) {
-        const streams = layers ? writeStartupStreams(name, startup.digests, layers.files) : undefined;
+        const streams = layers ? writeStartupStreams(name, startup.digests, layers.files, options.cacheRoot) : undefined;
         startupStreams = streams?.files;
         manifest.startup = { url: imageStartupPath(name), ranges: startup.ranges, ...(streams ? { streams: streams.streams } : {}) };
         process.stdout.write(`  startup: ${startup.ranges} image ranges a first boot read, from ${STARTUP_RECORD}${streams ? `, as ${streams.streams.length} streams of ${formatBytes(streams.streams.reduce((total, stream) => total + stream.bytes, 0))}` : ""}\n`);
@@ -754,7 +813,7 @@ function decodeBase64Content(value) {
  * files, or the project's own in its packages directory, which the plan names
  * at the origin's registry path.
  */
-function packPlan(plan, imageName, carried, local, packagesDirectory) {
+function packPlan(plan, imageName, carried, local, packagesDirectory, cacheRoot) {
     const own = packagesDirectory ? readOriginRegistry(packagesDirectory) : undefined;
     return preparePlanPacks(plan, imageName, (entry) => {
         // A registry package carried here; a tarball the image names under its
@@ -764,7 +823,7 @@ function packPlan(plan, imageName, carried, local, packagesDirectory) {
             return fromRegistry;
         const file = entry.tarball.startsWith(`${REGISTRY_PATH}/`) ? own?.get(entry.name)?.get(entry.version)?.file : undefined;
         return file && packagesDirectory ? join(packagesDirectory, file) : undefined;
-    });
+    }, cacheRoot);
 }
 /** Every file of the image and its World by the path it is served at, and where the folder holds it. */
 export function imageBlobs(image) {
@@ -802,11 +861,11 @@ const STARTUP_STREAMS = 2;
  * its served length and its served bytes. One request per helper instead of
  * one per range: 830 requests took 0.85 s on localhost to deliver 43 MB.
  */
-function writeStartupStreams(name, digests, layerFiles) {
+function writeStartupStreams(name, digests, layerFiles, cacheRoot) {
     const held = [...new Set(digests)].filter((digest) => layerFiles.has(`/substrate/${name}.layers/${digest}.bin`));
     if (held.length === 0)
         return undefined;
-    const directory = join(homedir(), ".cache", "browser-substrate", "startup-streams");
+    const directory = preparationCacheDirectory("startup-streams", cacheRoot);
     mkdirSync(directory, { recursive: true });
     const streams = [];
     const files = new Map();
@@ -872,7 +931,7 @@ export function imageFiles(image) {
  * directory is the World's, outside any project; the World's own runtime
  * runs from it in the tab.
  */
-export async function buildWorldImage(directory, imageName) {
+export async function buildWorldImage(directory, imageName, cacheRoot) {
     const folder = resolve(directory);
     const config = ["world.json"].find((name) => existsSync(join(folder, name)));
     if (!config)
@@ -883,18 +942,18 @@ export async function buildWorldImage(directory, imageName) {
     // What travels is the World's state, its data; a runtime's bookkeeping of
     // one instance, its pids, logs, receipts, session keys and proxy, is that
     // runtime's and stays where it ran.
-    const archive = archiveFolder(folder, { exclude: new Set([...EXCLUDED_NAMES, ...WORLD_RUNTIME_NAMES]) });
+    const archive = archiveFolder(folder, { ...(cacheRoot ? { cacheRoot } : {}), exclude: new Set([...EXCLUDED_NAMES, ...WORLD_RUNTIME_NAMES]) });
     const packagesDirectory = join(folder, PACKAGES_DIRECTORY);
     const tarballs = new Map();
     let plan;
     if (existsSync(join(folder, "package.json"))) {
-        const resolved = await resolveDependencyPlan(folder, installCommandOf(folder), { packagesDirectory, onOutput: (text) => process.stdout.write(text), holds: (path) => archive.files.has(path) });
+        const resolved = await resolveDependencyPlan(folder, installCommandOf(folder), { ...(cacheRoot ? { cacheRoot } : {}), packagesDirectory, onOutput: (text) => process.stdout.write(text), holds: (path) => archive.files.has(path) });
         if (resolved) {
             plan = resolved.plan;
             servePlanTarballsFromOrigin(plan, packagesDirectory);
             process.stdout.write(`  world ${name}: ${plan.packages.length} packages at ${plan.links.length} paths, resolved with ${plan.resolver}${resolved.cached ? ", from the cache" : ` in ${resolved.durationMs} ms`}\n`);
-            const carried = await carryRegistryTarballs(plan, imageName);
-            for (const [served, source] of (await packPlan(plan, imageName, carried.files, tarballs, packagesDirectory)).files)
+            const carried = await carryRegistryTarballs(plan, imageName, cacheRoot ? { cacheRoot } : {});
+            for (const [served, source] of (await packPlan(plan, imageName, carried.files, tarballs, packagesDirectory, cacheRoot)).files)
                 tarballs.set(served, source);
             plan.key = `${plan.key}-p${createHash("sha256").update(plan.packages.map((entry) => `${entry.pack?.artifact.digest ?? ""}:${entry.linuxX64}`).join("\n")).digest("hex").slice(0, 12)}`;
             if (carried.files.size > 0)
@@ -924,7 +983,9 @@ export async function buildWorldImage(directory, imageName) {
 /** What a command's arguments ask of an image. */
 function imageOptions(args, packagesDirectory) {
     return {
+        ...(args.provisionCatalogFile ? { provisionCatalog: JSON.parse(readFileSync(resolve(args.provisionCatalogFile), "utf8")) } : {}),
         ...(packagesDirectory ? { packagesDirectory } : {}),
+        ...(args.cacheRoot ? { cacheRoot: args.cacheRoot } : {}),
         packs: args.packs,
         ...(args.world ? { moduleWorld: args.world } : {}),
         ...(Object.keys(args.buildArgs).length > 0 ? { buildArgs: args.buildArgs } : {}),
@@ -974,7 +1035,7 @@ async function dev(cwd, args) {
     // The app's image first: its build may run attached to the World and leave
     // the data it read in the World's directory, which the World's image carries.
     let image = await buildImageWith(cwd, args.name, args.settings, project, imageOptions(args, packages));
-    const world = args.world ? await buildWorldImage(args.world, args.name) : undefined;
+    const world = args.world ? await buildWorldImage(args.world, args.name, args.cacheRoot) : undefined;
     const attach = (image) => {
         if (!world)
             return;
@@ -991,7 +1052,7 @@ async function dev(cwd, args) {
     // is written beside its packages and carried by every image built from it,
     // and a rebuilt image whose ranges did not change keeps it (ADR-0078).
     const startup = { path: imageStartupPath(image.manifest.name), file: join(cwd, STARTUP_RECORD) };
-    const server = await serve({ shell: SHELL_DIRECTORY, files, blobs: (pathname) => blobs.get(pathname), port: args.port, registry: world ? [packages, world.packagesDirectory] : packages, startup });
+    const server = await serve({ shell: SHELL_DIRECTORY, manifest: image.manifest, files, blobs: (pathname) => blobs.get(pathname), port: args.port, registry: world ? [packages, world.packagesDirectory] : packages, startup });
     const summary = `${image.manifest.setup.kind === "dockerfile" ? "Dockerfile" : image.manifest.setup.source}, ${image.manifest.archive.entries} entries, ${formatBytes(image.manifest.archive.fileBytes)}${world ? `; World ${world.world.name} from ${args.world}, ${world.world.archive.entries} entries` : ""}`;
     const carried = image.manifest.registry
         ? `\n  ${PACKAGES_DIRECTORY}: this origin is the registry for ${[...image.manifest.registry.scopes, ...image.manifest.registry.names].join(", ")}`
@@ -1117,14 +1178,16 @@ async function build(cwd, args) {
         throw new Error(`--build-arg ${Object.keys(args.buildArgs).join(", ")} applies to a Dockerfile whose build half runs here (a RUN step); this one's setup is ${image.manifest.setup.kind}, built in the tab with its ARG defaults`);
     }
     if (args.world) {
-        const world = await buildWorldImage(args.world, args.name);
+        const world = await buildWorldImage(args.world, args.name, args.cacheRoot);
         image.manifest.world = world.world;
         image.world = { archive: world.archive, blobs: world.blobs, ...(world.plan ? { plan: world.plan } : {}) };
         for (const [served, source] of world.tarballs)
             image.tarballs.set(served, source);
     }
     const out = resolve(cwd, args.out);
+    preparationPhase("final copy");
     const written = writeBuild({ shell: SHELL_DIRECTORY, files: imageFiles(image), blobs: imageBlobs(image), out, manifest: image.manifest });
+    preparationCheckpoint();
     process.stdout.write(`\n  browser-substrate build\n\n  ${out}\n  ${written.files} files, ${formatBytes(written.bytes)}\n  ${image.manifest.setup.playground
         ? `a playground: deploy on your page's origin and on ${image.manifest.settings.sandboxOrigin ?? "a sandbox. subdomain of it"}`
         : "one origin, static; _headers carries the isolation headers"}\n\n`);
@@ -1157,34 +1220,34 @@ async function dryRunCommand(cwd, args) {
             const index = originRegistryIndex(packages);
             if (index)
                 image.manifest.registry = index;
-            server = await serve({ shell: SHELL_DIRECTORY, files: new Map(imageFiles(image)), blobs: ((blobs) => (pathname) => blobs.get(pathname))(imageBlobs(image)), port: 0, registry: packages });
+            server = await serve({ shell: SHELL_DIRECTORY, manifest: image.manifest, files: new Map(imageFiles(image)), blobs: ((blobs) => (pathname) => blobs.get(pathname))(imageBlobs(image)), port: 0, registry: packages });
             url = server.url;
         }
         try {
             say(`\n  browser-substrate dry-run, round ${round}\n`);
             const captureKey = captureKeyFor(file);
-            const warmBefore = warmSignature(warmDirectory(captureKey));
-            const cachesBefore = warmSignature(join(cachesDirectory(captureKey), "files"));
+            const warmBefore = warmSignature(warmDirectory(captureKey, args.cacheRoot));
+            const cachesBefore = warmSignature(join(cachesDirectory(captureKey, args.cacheRoot), "files"));
             const steps = args.steps ? JSON.parse(readFileSync(args.steps, "utf8")) : undefined;
-            const result = await dryRun(url, { settleMs: settle * 1000, onOutput: say, ...(steps ? { steps } : {}), preparedInto: preparedBodiesDirectory(captureKey), warmInto: warmDirectory(captureKey), cachesInto: cachesDirectory(captureKey) });
+            const result = await dryRun(url, { settleMs: settle * 1000, onOutput: say, ...(steps ? { steps } : {}), preparedInto: preparedBodiesDirectory(captureKey, args.cacheRoot), warmInto: warmDirectory(captureKey, args.cacheRoot), cachesInto: cachesDirectory(captureKey, args.cacheRoot) });
             const captured = readCaptured(file);
             const { added: packsAdded, uncapturable } = capture(result.records, captured);
             // The bodies the engine prepared in the tab are the image's next time:
             // a first open compiles nothing the dry run saw it compile.
-            const bodiesAdded = capturePrepared(result.prepared, captured, preparedBodiesDirectory(captureKey));
+            const bodiesAdded = capturePrepared(result.prepared, captured, preparedBodiesDirectory(captureKey, args.cacheRoot));
             // Caches captured for the first time are built into the next image. Later
             // captures replace them on disk for whatever build comes next, without a
             // round of their own: a cache may differ run to run and never settle.
             // And caches the image did not carry (never captured, or assembled from
             // packs an earlier round's capture changed): the next build carries them.
-            const warmChanged = result.warm > 0 && (!result.warmCarried || warmBefore === EMPTY_WARM || captured.cache !== captureKey) && warmSignature(warmDirectory(captureKey)) !== EMPTY_WARM ? 1 : 0;
+            const warmChanged = result.warm > 0 && (!result.warmCarried || warmBefore === EMPTY_WARM || captured.cache !== captureKey) && warmSignature(warmDirectory(captureKey, args.cacheRoot)) !== EMPTY_WARM ? 1 : 0;
             if (result.warm > 0 || bodiesAdded > 0)
                 captured.cache = captureKey;
             if (warmChanged)
                 say(`  captured the project's caches anew (${result.warm} files)\n`);
             // Cache Storage whose bodies are new to this machine is built into the
             // next image; the same bodies again (their headers carry a time) are not.
-            const cachesChanged = result.caches > 0 && warmSignature(join(cachesDirectory(captureKey), "files")) !== cachesBefore ? 1 : 0;
+            const cachesChanged = result.caches > 0 && warmSignature(join(cachesDirectory(captureKey, args.cacheRoot), "files")) !== cachesBefore ? 1 : 0;
             if (cachesChanged)
                 say(`  captured the origin's Cache Storage anew (${result.caches} entries)\n`);
             if (result.caches > 0)