@daugasauron/dolly 0.1.5-rc.0 → 0.1.6

package/{src → page}/snapshot-records.mjs

@@ -1,6 +1,11 @@
 import { unretainedPath } from "./image-names.mjs";
-const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
-export const MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024 * 1024;
+import { DOLLY_SNAPSHOT_VERSION, DOLLY_SNAPSHOT_HEADER_BYTES as HEADER_BYTES, DOLLY_SNAPSHOT_RECORD_HEADER_BYTES as RECORD_HEADER_BYTES,
+  DOLLY_SNAPSHOT_RECORD_DIRECTORY as DIRECTORY, DOLLY_SNAPSHOT_RECORD_FILE as FILE, DOLLY_SNAPSHOT_RECORD_SYMLINK as SYMLINK,
+  DOLLY_SNAPSHOT_MAX_PATHS, DOLLY_SNAPSHOT_MAX_MEBIBYTES, DOLLY_SNAPSHOT_PATH_MIN_BYTES, DOLLY_SNAPSHOT_PATH_MAX_BYTES,
+  DOLLY_SNAPSHOT_SYMLINK_MIN_BYTES, DOLLY_SNAPSHOT_SYMLINK_MAX_BYTES } from "../host/runtime/abi.mjs";
+// A snapshot part's layout and limits are abi/dolly-image-0.wat's.
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }), encoder = new TextEncoder();
+export const MAX_SNAPSHOT_BYTES = DOLLY_SNAPSHOT_MAX_MEBIBYTES * 1024 * 1024;
 // Packs average 2 MiB or more (scripts/share-pages-snapshots.mjs): an image of
 // MAX_SNAPSHOT_BYTES needs about 1,024, which this bound leaves room for.
 const MAX_SNAPSHOT_PACKS = MAX_SNAPSHOT_BYTES / (1024 * 1024);
@@ -12,27 +17,46 @@ function compareBytes(left, right) {
   return left.length - right.length;
 }
 
-// The 16-byte snapshot header: its record count.
-function decodeHeader(bytes) {
+// A snapshot part's header: its record count.
+export function decodeSnapshotHeader(bytes) {
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  if (bytes.length < 16 || decoder.decode(bytes.subarray(0, 8)) !== "DOLLYSNP" || view.getUint32(8, true) !== 2) {
-    throw new Error("invalid Dolly snapshot header");
-  }
+  if (bytes.length < HEADER_BYTES || decoder.decode(bytes.subarray(0, 8)) !== "DOLLYSNP" ||
+      view.getUint32(8, true) !== DOLLY_SNAPSHOT_VERSION) throw new Error("invalid Dolly snapshot header");
   const count = view.getUint32(12, true);
-  if (count === 0 || count > 100_000) throw new Error("invalid Dolly snapshot record count");
+  if (count === 0 || count > DOLLY_SNAPSHOT_MAX_PATHS) throw new Error("invalid Dolly snapshot record count");
   return count;
 }
 
-// A record's 16-byte header: its kind, path length and data size.
-function decodeRecordHeader(bytes) {
+// A record's header: its kind, path length and data size.
+export function decodeRecordHeader(bytes) {
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   const kind = view.getUint32(0, true), pathLength = view.getUint32(4, true), size = view.getBigUint64(8, true);
-  if (kind < 1 || kind > 3 || pathLength < 2 || pathLength >= 4096 ||
-      size > BigInt(MAX_SNAPSHOT_BYTES) || (kind === 1 && size !== 0n) ||
-      (kind === 3 && (size === 0n || size >= 4096n))) throw new Error("invalid snapshot record size");
+  if (kind < DIRECTORY || kind > SYMLINK || pathLength < DOLLY_SNAPSHOT_PATH_MIN_BYTES || pathLength > DOLLY_SNAPSHOT_PATH_MAX_BYTES ||
+      size > BigInt(MAX_SNAPSHOT_BYTES) || (kind === DIRECTORY && size !== 0n) ||
+      (kind === SYMLINK && (size < BigInt(DOLLY_SNAPSHOT_SYMLINK_MIN_BYTES) || size > BigInt(DOLLY_SNAPSHOT_SYMLINK_MAX_BYTES)))) {
+    throw new Error("invalid snapshot record size");
+  }
   return { kind, pathLength, size: Number(size) };
 }
 
+export function snapshotHeader(count) {
+  const bytes = new Uint8Array(HEADER_BYTES), view = new DataView(bytes.buffer);
+  bytes.set(encoder.encode("DOLLYSNP"));
+  view.setUint32(8, DOLLY_SNAPSHOT_VERSION, true);
+  view.setUint32(12, count, true);
+  return bytes;
+}
+
+// A record's header and its encoded path PATH.
+export function recordHeader(kind, path, size) {
+  const bytes = new Uint8Array(RECORD_HEADER_BYTES + path.length), view = new DataView(bytes.buffer);
+  view.setUint32(0, kind, true);
+  view.setUint32(4, path.length, true);
+  view.setBigUint64(8, BigInt(size), true);
+  bytes.set(path, RECORD_HEADER_BYTES);
+  return bytes;
+}
+
 // The path of PATHBYTES, valid and after PREVIOUS in byte order.
 function decodePath(pathBytes, previous) {
   const path = decoder.decode(pathBytes);
@@ -47,7 +71,7 @@ function checkParents(records) {
   for (const path of records.keys()) {
     for (let slash = path.indexOf("/", 1); slash !== -1; slash = path.indexOf("/", slash + 1)) {
       const parent = records.get(path.slice(0, slash));
-      if (parent && parent.kind !== 1) throw new Error(`snapshot parent is not a directory: ${path}`);
+      if (parent && parent.kind !== DIRECTORY) throw new Error(`snapshot parent is not a directory: ${path}`);
     }
   }
 }
@@ -55,20 +79,20 @@ function checkParents(records) {
 export function decodeSnapshotRecords(input) {
   const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
   if (bytes.length > MAX_SNAPSHOT_BYTES) throw new Error("invalid Dolly snapshot header");
-  const count = decodeHeader(bytes.subarray(0, 16));
+  const count = decodeSnapshotHeader(bytes.subarray(0, HEADER_BYTES));
   const records = new Map();
-  let offset = 16, previous;
+  let offset = HEADER_BYTES, previous;
   for (let index = 0; index < count; index += 1) {
-    if (offset > bytes.length - 16) throw new Error("truncated snapshot record");
-    const { kind, pathLength, size } = decodeRecordHeader(bytes.subarray(offset, offset + 16));
-    offset += 16;
+    if (offset > bytes.length - RECORD_HEADER_BYTES) throw new Error("truncated snapshot record");
+    const { kind, pathLength, size } = decodeRecordHeader(bytes.subarray(offset, offset + RECORD_HEADER_BYTES));
+    offset += RECORD_HEADER_BYTES;
     if (offset > bytes.length - pathLength - size) throw new Error("truncated snapshot record");
     const pathBytes = bytes.subarray(offset, offset + pathLength);
     const path = decodePath(pathBytes, previous);
     previous = pathBytes;
     offset += pathLength;
     const data = bytes.subarray(offset, offset + size);
-    if (kind === 3 && data.includes(0)) throw new Error("invalid snapshot symlink");
+    if (kind === SYMLINK && data.includes(0)) throw new Error("invalid snapshot symlink");
     records.set(path, { kind, data });
     offset += size;
   }
@@ -143,19 +167,19 @@ class PieceReader {
 // snapshot's size.
 export async function scanSnapshotRecords(pieces, keep) {
   const reader = new PieceReader(pieces);
-  const count = decodeHeader(await reader.take(16));
+  const count = decodeSnapshotHeader(await reader.take(HEADER_BYTES));
   const records = new Map();
   let previous;
   for (let index = 0; index < count; index += 1) {
-    const { kind, pathLength, size } = decodeRecordHeader(await reader.take(16));
+    const { kind, pathLength, size } = decodeRecordHeader(await reader.take(RECORD_HEADER_BYTES));
     const pathBytes = await reader.take(pathLength);
     const path = decodePath(pathBytes, previous);
     previous = pathBytes;
     const offset = reader.position;
     let data;
-    if (kind === 3 || (kind === 2 && keep(path))) {
+    if (kind === SYMLINK || (kind === FILE && keep(path))) {
       data = await reader.take(size);
-      if (kind === 3 && data.includes(0)) throw new Error("invalid snapshot symlink");
+      if (kind === SYMLINK && data.includes(0)) throw new Error("invalid snapshot symlink");
     } else await reader.skip(size);
     records.set(path, { kind, data, offset, size });
   }
@@ -165,35 +189,30 @@ export async function scanSnapshotRecords(pieces, keep) {
 }
 
 export function encodeSnapshotRecords(records) {
-  const encoder = new TextEncoder();
   const entries = [...records].map(([path, record]) => ({ path: encoder.encode(path), ...record }))
     .sort((left, right) => compareBytes(left.path, right.path));
-  const size = entries.reduce((sum, record) => sum + 16 + record.path.length + record.data.length, 16);
-  if (size > MAX_SNAPSHOT_BYTES || entries.length === 0 || entries.length > 100_000) throw new Error("snapshot exceeds record limits");
-  const bytes = new Uint8Array(size), view = new DataView(bytes.buffer);
-  bytes.set(encoder.encode("DOLLYSNP"));
-  view.setUint32(8, 2, true);
-  view.setUint32(12, entries.length, true);
-  let offset = 16;
+  const size = entries.reduce((sum, record) => sum + RECORD_HEADER_BYTES + record.path.length + record.data.length, HEADER_BYTES);
+  if (size > MAX_SNAPSHOT_BYTES || entries.length === 0 || entries.length > DOLLY_SNAPSHOT_MAX_PATHS) throw new Error("snapshot exceeds record limits");
+  const bytes = new Uint8Array(size);
+  bytes.set(snapshotHeader(entries.length));
+  let offset = HEADER_BYTES;
   for (const record of entries) {
-    view.setUint32(offset, record.kind, true);
-    view.setUint32(offset + 4, record.path.length, true);
-    view.setBigUint64(offset + 8, BigInt(record.data.length), true);
-    bytes.set(record.path, offset + 16);
-    bytes.set(record.data, offset + 16 + record.path.length);
-    offset += 16 + record.path.length + record.data.length;
+    const header = recordHeader(record.kind, record.path, record.data.length);
+    bytes.set(header, offset);
+    bytes.set(record.data, offset + header.length);
+    offset += header.length + record.data.length;
   }
   return bytes;
 }
 
 export function mergeSnapshotRecords(parts) {
   const records = new Map();
-  let size = 16;
+  let size = HEADER_BYTES;
   for (const part of parts) {
     for (const [path, record] of decodeSnapshotRecords(part)) {
       if (records.has(path)) throw new Error(`duplicate packed snapshot path: ${path}`);
-      size += 16 + new TextEncoder().encode(path).length + record.data.length;
-      if (size > MAX_SNAPSHOT_BYTES || records.size >= 100_000) throw new Error("packed snapshot exceeds limits");
+      size += RECORD_HEADER_BYTES + encoder.encode(path).length + record.data.length;
+      if (size > MAX_SNAPSHOT_BYTES || records.size >= DOLLY_SNAPSHOT_MAX_PATHS) throw new Error("packed snapshot exceeds limits");
       records.set(path, record);
     }
   }
@@ -205,15 +224,15 @@ export function mergeSnapshotRecords(parts) {
 export function validateSnapshotPacks(metadata) {
   if (!Array.isArray(metadata.packs) || metadata.packs.length === 0 || metadata.packs.length > MAX_SNAPSHOT_PACKS) throw new Error("invalid snapshot packs");
   const hashes = new Set();
-  let size = 16;
+  let size = HEADER_BYTES;
   for (const pack of metadata.packs) {
     if (!/^[0-9a-f]{64}$/.test(pack.sha256) || hashes.has(pack.sha256) ||
-        !Number.isSafeInteger(pack.byteLength) || pack.byteLength < 16 || pack.byteLength > MAX_SNAPSHOT_BYTES ||
+        !Number.isSafeInteger(pack.byteLength) || pack.byteLength < HEADER_BYTES || pack.byteLength > MAX_SNAPSHOT_BYTES ||
         !Number.isSafeInteger(pack.encodedByteLength) || pack.encodedByteLength <= 0 || pack.encodedByteLength > MAX_SNAPSHOT_BYTES) {
       throw new Error("invalid snapshot pack descriptor");
     }
     hashes.add(pack.sha256);
-    size += pack.byteLength - 16;
+    size += pack.byteLength - HEADER_BYTES;
     if (size > MAX_SNAPSHOT_BYTES) throw new Error("packed snapshot exceeds size limit");
   }
   if (size !== metadata.byteLength) throw new Error("snapshot pack sizes do not match image");

package/{src → page}/static-asset.mjs

@@ -61,31 +61,47 @@ export async function boundedAssetBody(response, limit, signal) {
 // Pages before v0.1.5 read the X-Dolly-Parts header instead.
 export const PARTS_MANIFEST_START = '{"byteLength":';
 
-// Whether a whole response's body begins as a manifest, read from a copy of it.
-async function isPartsManifest(response) {
-  if (response.status !== 200 || !response.body) return false;
-  const start = new TextEncoder().encode(PARTS_MANIFEST_START), reader = response.clone().body.getReader();
-  const head = new Uint8Array(start.length);
-  let size = 0;
-  try {
-    while (size < start.length) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const taken = value.subarray(0, start.length - size);
-      head.set(taken, size);
-      size += taken.length;
-    }
-  } finally {
-    // Not awaited: cancelling a copy settles only once the response is read too.
-    reader.cancel().catch(() => {});
+// The first `length` bytes of a response's body, and a response whose body is
+// all of it again, those bytes first. It reads the body itself: reading a
+// copy of it and cancelling the copy cost the original its first bytes, in
+// Firefox up to 151 and in Node, when other bodies were read meanwhile.
+async function peeked(response, length) {
+  const reader = response.body.getReader(), chunks = [];
+  let size = 0, ended = false;
+  while (size < length) {
+    const next = await reader.read();
+    if (next.done) { ended = true; break; }
+    chunks.push(next.value);
+    size += next.value.length;
   }
-  return size === start.length && head.every((byte, index) => byte === start[index]);
+  const head = new Uint8Array(Math.min(size, length));
+  for (let offset = 0, index = 0; offset < head.length; ++index) {
+    const taken = chunks[index].subarray(0, head.length - offset);
+    head.set(taken, offset);
+    offset += taken.length;
+  }
+  const body = new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      if (ended) controller.close();
+    },
+    async pull(controller) {
+      const next = await reader.read();
+      if (next.done) controller.close(); else controller.enqueue(next.value);
+    },
+    cancel: reason => reader.cancel(reason),
+  }, { highWaterMark: 0 });
+  const whole = new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+  Object.defineProperty(whole, "url", { value: response.url });
+  return { head, whole };
 }
 
 // Streams verified parts, holding at most one 20 MiB part per request. Each
 // part matches the manifest hash before any of its bytes are delivered.
-export async function decodeStaticAsset(response, target, init, maximumBytes, fetchRequest = globalThis.fetch.bind(globalThis)) {
-  if (!await isPartsManifest(response)) return response;
+export async function decodeStaticAsset(given, target, init, maximumBytes, fetchRequest = globalThis.fetch.bind(globalThis)) {
+  if (given.status !== 200 || !given.body) return given;
+  const start = new TextEncoder().encode(PARTS_MANIFEST_START), { head, whole: response } = await peeked(given, start.length);
+  if (head.length !== start.length || head.some((byte, index) => byte !== start[index])) return response;
   const url = new URL(target);
   if ((init.method ?? "GET") !== "GET" || url.search || url.hash ||
       url.username || url.password || !/^https?:$/.test(url.protocol)) throw new Error("invalid multipart asset request");

package/{src → page}/version.mjs

@@ -1,3 +1,3 @@
 // The version being developed: the release tag vX.Y.Z, the site path /vX.Y.Z/
 // and the prefix of every recipe reference. package.json holds the same value.
-export const DOLLY_VERSION = "0.1.5";
+export const DOLLY_VERSION = "0.1.6";

package/{src → page}/worker-image.mjs

@@ -12,19 +12,29 @@ import { bootFiles } from "../host/runtime/boot-files.mjs";
 const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
 
 // Listen before the host registry loads its manifests: the page's configure
-// message may arrive while that import is still pending.
-const configured = new Promise((resolve, reject) => {
-  const timeout = setTimeout(
-    () => reject(new Error("Dolly boot configuration was not provided")), 10_000,
-  );
+// message may arrive while that import is still pending. The page starts this
+// Worker before its own host modules and configures it once they are up, which
+// a route that builds first takes minutes to be.
+const configured = new Promise(resolve => {
   self.addEventListener("message", function configure(event) {
     if (event.data?.type !== "configure") return;
     self.removeEventListener("message", configure);
-    clearTimeout(timeout);
     resolve(event.data);
   });
 });
-const { hostRegistry } = await import("../host/modules.mjs");
+// The page names its image directory and modules as it starts this Worker: their catalog,
+// manifests and providers load while the page starts its own, and configure finds them loaded.
+const registry = import("../host/modules.mjs");
+self.addEventListener("message", function prepare(event) {
+  if (event.data?.type !== "prepare") return;
+  self.removeEventListener("message", prepare);
+  const { images, modules, hostModules } = event.data;
+  void (async () => {
+    await loadImages(images);
+    (await (await registry).hostRegistry(modules)).load(hostModules);
+  })().catch(() => {});
+});
+const { hostRegistry } = await registry;
 
 // The runtime's own files: the kernel and the contracts beside this module.
 const runtimeBase = new URL("../", import.meta.url);
@@ -78,7 +88,8 @@ export async function runImage(image) {
     host = await (await hostRegistry(config.modules)).createHost("worker", config.hostModules, {
       send: (message, transfers = []) => self.postMessage(message, transfers),
       configuration: config.hostConfiguration,
-      resources: { runtimeBase },
+      // The image directory reaches the modules here: one the bundle holds is not theirs.
+      resources: { runtimeBase, images: new URL(config.images) },
     });
     const steps = await image(config, host);
     stage("creating wasm64 userspace kernel...");
@@ -101,7 +112,7 @@ export async function runImage(image) {
     const supervisor = restored.supervisor ?? await host.kernel.supervisor(kernel);
     await steps.finish?.({ kernel, stage });
 
-    await host.imageRestored({ kernel, supervisor, stage, files, image: steps.name });
+    await host.imageRestored({ kernel, memory, supervisor, stage, files, image: steps.name });
     if (kernel.dolly_bootstrap_environment() !== 0) throw new Error("Dolly image environment is invalid");
     await host.start("image", { kernel, memory });
     const runtimeImage = decoder.decode(files.read("/etc/dolly/image", 256));

package/{src → site}/build-worker.mjs

@@ -1,18 +1,18 @@
 // The site's runtime Worker (worker-image.mjs): it builds an image from its
-// recipe, from the compiler seed or the base image the page hands it, caches
-// it and runs it, telling the page its identity, or, for the image builder,
-// hands the page the cached artifact (buildOnly); or it restores a custom
-// image the site built before. Images cross to and from Wasm memory a piece
-// at a time: the page holds them as Blobs, never in a JS heap.
-import { DOLLY_IMAGE_BUILD_ID } from "../dist/dolly-image-build-id.mjs";
-import { imageBase, imageDefinition } from "./images.mjs";
-import { scanSnapshotRecords, MAX_SNAPSHOT_BYTES as snapshotSizeLimit } from "./snapshot-records.mjs";
+// recipe, from the base image or the engine package the page hands it or from
+// the compiler seed, caches it and runs it, telling the page its identity, or,
+// for the image builder, hands the page the cached artifact (buildOnly); or it
+// restores a custom image the site built before. Images cross to and from Wasm
+// memory a piece at a time: the page holds them as Blobs, never in a JS heap.
+import { DOLLY_IMAGE_BUILD_ID } from "../page/generated.mjs";
+import { imageBase, imageDefinition } from "../page/images.mjs";
+import { scanSnapshotRecords, MAX_SNAPSHOT_BYTES as snapshotSizeLimit } from "../page/snapshot-records.mjs";
 import { describeImageArtifact, saveImageArtifact, sha256 } from "./image-artifact.mjs";
-import { imageInputs } from "./image-inputs.mjs";
-import { inspectDollyfile, MAX_DOLLYFILE_BYTES, recipeRows } from "./dollyfile-view.mjs";
+import { imageInputs } from "../page/image-inputs.mjs";
+import { imageFileName, inspectDollyfile, MAX_DOLLYFILE_BYTES, recipeFileName, recipeRows } from "./dollyfile-view.mjs";
 import { checkedCustomArtifact } from "./custom-image.mjs";
-import { siteReference, decodeStaticAsset } from "./static-asset.mjs";
-import { checkedMemoryRange, kernelArtifact, runImage } from "./worker-image.mjs";
+import { siteReference, decodeStaticAsset } from "../page/static-asset.mjs";
+import { checkedMemoryRange, kernelArtifact, runImage } from "../page/worker-image.mjs";
 
 const encoder = new TextEncoder();
 const PIECE = 8 * 1024 * 1024;
@@ -69,17 +69,21 @@ await runImage(async (config, host) => {
     return range.size;
   };
   if (mode === "snapshot") {
-    const artifact = await checkedCustomArtifact(customSource, config.customArtifact);
+    // A saved session is the whole filesystem: it needs the recipe, not the image.
+    const artifact = config.customArtifact === undefined ? null : await checkedCustomArtifact(customSource, config.customArtifact);
     config.customArtifact = undefined;
-    host.require(artifact.hostRequirements);
-    host.admit(artifact.hostRequirements);
+    const hosts = artifact?.hostRequirements ?? recipe.hostRequirements;
+    host.require(hosts);
+    await host.admit(hosts);
     return {
       name: image,
       prepare({ files }) {
         prepareRecipe(files);
-        files.write("/etc/dolly/image.manifest", `${artifact.manifest.join("\n")}\n`);
+        if (artifact) files.write("/etc/dolly/image.manifest", `${artifact.manifest.join("\n")}\n`);
       },
       async restore({ kernel, memory, stage }) {
+        if (await host.restoreFilesystem({ kernel, memory, stage })) return { status: 0 };
+        if (!artifact) throw new Error("invalid Dolly image selection");
         stage("loading precompiled userspace snapshot...");
         const size = await stageSnapshot(kernel, memory, artifact.bytes);
         artifact.bytes = undefined;
@@ -93,6 +97,10 @@ await runImage(async (config, host) => {
   // /bin/dollyfile executes the rows this page's parser compiles.
   const rows = recipeRows(custom ? recipe : await catalogRecipe(definition), recipeSha256);
   const baseReference = custom ? recipe.from : definition.artifacts.find(reference => reference.operation === "from");
+  // A root build that installs the recipe engine's package starts from that package's
+  // /bin/dollyfile, as a FROM build starts from its base's; any other from the compiler seed.
+  const engineReference = baseReference ? null : (custom ? recipe : definition).artifacts.find(reference =>
+    reference.operation === "install" && imageFileName(recipeFileName(reference.location)) === "dollyfile");
   const artifacts = new Map();
   if (config.artifacts !== undefined && (!Array.isArray(config.artifacts) || config.artifacts.length > 256)) {
     throw new Error("invalid build artifacts");
@@ -108,16 +116,19 @@ await runImage(async (config, host) => {
   // A build runs the engine and its tools with the build host's modules, and
   // the programs of the images it reads with their modules: one the build host
   // does not enable answers ENOSYS.
-  host.admit([...declared, ...host.enabled, ...[...artifacts.values()].flatMap(artifact => artifact.hostRequirements)]);
+  await host.admit([...declared, ...host.enabled, ...[...artifacts.values()].flatMap(artifact => artifact.hostRequirements)]);
   const inputs = imageInputs([...artifacts.values()]);
   const base = baseReference ? artifacts.get(baseReference.sha256) : null;
   if (baseReference && !base) throw new Error("base image artifact was not provided");
+  const engine = engineReference ? artifacts.get(engineReference.sha256) : null;
+  if (engineReference && !engine) throw new Error("dollyfile package artifact was not provided");
+  const builder = base ?? engine, builderReference = baseReference ?? engineReference;
   let seed = null, built = false;
   return {
     name: image,
     async prepare({ files, stage }) {
-      // A root build starts from the compiler seed, a snapshot like any image.
-      if (!base) {
+      // A root build without the engine starts from the compiler seed, a snapshot like any image.
+      if (!builder) {
         stage("loading root compiler seed...");
         // Static hosts may serve the seed as verified parts.
         const url = kernelArtifact("dolly.data");
@@ -129,15 +140,15 @@ await runImage(async (config, host) => {
       [...artifacts.values()].forEach((artifact, input) =>
         files.input(`/etc/dolly/artifacts/${artifact.recipeSha256}.snapshot`, input, artifact.bytes.size));
       // The kernel restores a snapshot against the list of its paths.
-      const manifest = base?.manifest ?? [...(await scanSnapshotRecords(seed.stream(), () => false)).records.keys()];
+      const manifest = builder?.manifest ?? [...(await scanSnapshotRecords(seed.stream(), () => false)).records.keys()];
       files.write("/etc/dolly/image.manifest", `${manifest.join("\n")}\n`);
     },
     async restore({ kernel, memory, files, stage }) {
       stage("building userspace from the Dollyfile...");
       let status;
-      if (base) {
-        stage(`loading builder from ${baseReference.location}...`);
-        status = kernel.dolly_process_bootstrap_resume_prepare(BigInt(await stageSnapshot(kernel, memory, base.bytes)), 1);
+      if (builder) {
+        stage(`loading builder from ${builderReference.location}...`);
+        status = kernel.dolly_process_bootstrap_resume_prepare(BigInt(await stageSnapshot(kernel, memory, builder.bytes)), 1);
       } else {
         status = kernel.dolly_process_bootstrap_prepare(BigInt(await stageSnapshot(kernel, memory, seed)));
         seed = null;
@@ -145,7 +156,7 @@ await runImage(async (config, host) => {
       let supervisor;
       if (status === 0) {
         supervisor = await host.kernel.supervisor(kernel);
-        status = (await supervisor.spawn(base ? ["/bin/dollyfile", locator] : ["/usr/libexec/dolly/process-bin/bootstrap"])).status;
+        status = (await supervisor.spawn(builder ? ["/bin/dollyfile", locator] : ["/usr/libexec/dolly/process-bin/bootstrap"])).status;
       }
       for (const artifact of artifacts.values()) files.remove(`/etc/dolly/artifacts/${artifact.recipeSha256}.snapshot`);
       artifacts.clear();
@@ -166,7 +177,7 @@ await runImage(async (config, host) => {
       // The image runs here with its own modules. The page keeps its identity,
       // which a session saved on it names, not its bytes.
       host.require(artifact.hostRequirements);
-      host.admit(artifact.hostRequirements);
+      await host.admit(artifact.hostRequirements);
       const { buildId, sha256: digest, byteLength } = artifact;
       self.postMessage({ type: "image-built", artifact: { buildId, recipeSha256, sha256: digest, byteLength, inputs: artifact.inputs } });
       built = true;

package/{src → site}/custom-image.mjs

@@ -1,5 +1,5 @@
-import { DOLLY_IMAGE_BUILD_ID } from "../dist/dolly-image-build-id.mjs";
-import { describeImageArtifact, loadImageArtifact, loadImageArtifactDescriptor, sha256 } from "./image-artifact.mjs";
+import { DOLLY_IMAGE_BUILD_ID } from "../page/generated.mjs";
+import { describeImageArtifact, loadImageArtifact, sha256 } from "./image-artifact.mjs";
 import { inspectDollyfile } from "./dollyfile-view.mjs";
 
 export async function loadCustomImage(source, descriptor) {
@@ -13,14 +13,6 @@ export async function loadCustomImage(source, descriptor) {
   return artifact;
 }
 
-// Whether this browser's image cache still records the completed custom image
-// ARTIFACT (its descriptor): a session saved on it can then be restored, which
-// checks the image's bytes.
-export async function customImageCached(artifact) {
-  const cached = await loadImageArtifactDescriptor(artifact.recipeSha256, artifact.inputs);
-  return cached?.sha256 === artifact.sha256 && cached.byteLength === artifact.byteLength;
-}
-
 export async function checkedCustomArtifact(source, candidate) {
   inspectDollyfile(source);
   if (candidate?.buildId !== DOLLY_IMAGE_BUILD_ID || !(candidate.bytes instanceof Blob) ||

package/{src → site}/dollyfile-graph.mjs

@@ -1,5 +1,5 @@
 import { inspectDollyfile, recipeFileName, imageFileName } from "./dollyfile-view.mjs";
-import { sha256 } from "./static-asset.mjs";
+import { sha256 } from "../page/static-asset.mjs";
 
 const key = object => `${object.type}:${object.name}`;
 const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });

package/{src → site}/dollyfile-view.mjs

@@ -1,5 +1,5 @@
 import { hostRequirement, hostRequirements } from "../host/requirements.mjs";
-import { unretainedPath, validName } from "./image-names.mjs";
+import { unretainedPath, validName } from "../page/image-names.mjs";
 
 export const MAX_DOLLYFILE_BYTES = 128 * 1024;
 

package/{src → site}/image-artifact.mjs

@@ -9,13 +9,14 @@
 // starting, whatever the machine), a file is not. A file is deleted when its
 // entry is replaced or evicted; a page that still holds the file then reads
 // nothing, so an entry's bytes are read only for a build the entry outlives.
-import { DOLLY_IMAGE_BUILD_ID } from "../dist/dolly-image-build-id.mjs";
-import { imageInputs, imageInputsMatch } from "./image-inputs.mjs";
+import { DOLLY_IMAGE_BUILD_ID } from "../page/generated.mjs";
+import { imageInputs, imageInputsMatch } from "../page/image-inputs.mjs";
 import { loadRecipeGraph } from "./dollyfile-graph.mjs";
 import { recipeFileName } from "./dollyfile-view.mjs";
-import { sha256 } from "./static-asset.mjs";
-import { Sha256 } from "./sha256.mjs";
-import { scanSnapshotRecords, MAX_SNAPSHOT_BYTES as snapshotSizeLimit } from "./snapshot-records.mjs";
+import { sha256 } from "../page/static-asset.mjs";
+import { Sha256 } from "../page/sha256.mjs";
+import { scanSnapshotRecords, MAX_SNAPSHOT_BYTES as snapshotSizeLimit } from "../page/snapshot-records.mjs";
+import { DOLLY_SNAPSHOT_RECORD_FILE } from "../host/runtime/abi.mjs";
 export { sha256 };
 
 const STORE_DIRECTORY = "dolly-images";
@@ -75,14 +76,14 @@ export async function describeImageArtifact(source, recipeSha256, inputs = []) {
   try {
     const { records, byteLength } = await scanSnapshotRecords(pieces, path => path.startsWith("/etc/dolly/"));
     const recipe = records.get("/etc/dolly/Dollyfile");
-    if (recipe?.kind !== 2 || await sha256(recipe.data) !== recipeSha256 ||
-        records.get("/etc/dolly/artifact")?.kind !== 2) throw new Error("artifact recipe identity mismatch");
+    if (recipe?.kind !== DOLLY_SNAPSHOT_RECORD_FILE || await sha256(recipe.data) !== recipeSha256 ||
+        records.get("/etc/dolly/artifact")?.kind !== DOLLY_SNAPSHOT_RECORD_FILE) throw new Error("artifact recipe identity mismatch");
     // The artifact retains every recipe it was built from, by file name.
     const graph = await loadRecipeGraph(reference => {
       if (reference === "Dollyfile") return recipe.data;
       const path = `/etc/dolly/recipes/${recipeFileName(reference)}`;
       const record = records.get(path);
-      if (record?.kind !== 2) throw new Error(`artifact does not retain recipe ${reference}`);
+      if (record?.kind !== DOLLY_SNAPSHOT_RECORD_FILE) throw new Error(`artifact does not retain recipe ${reference}`);
       return record.data;
     }, "Dollyfile");
     return { buildId: DOLLY_IMAGE_BUILD_ID, recipeSha256, sha256: hash.hex(),

package/{src → site}/image-build.mjs

@@ -1,9 +1,9 @@
-import { DOLLY_IMAGES, imageBase, imageDefinition } from "./images.mjs";
+import { DOLLY_IMAGES, imageBase, imageDefinition } from "../page/images.mjs";
 import { loadRecipeGraph } from "./dollyfile-graph.mjs";
-import { imageInputs, imageInputsMatch } from "./image-inputs.mjs";
+import { imageInputs, imageInputsMatch } from "../page/image-inputs.mjs";
 import { describeImageArtifact, loadImageArtifactDescriptor, loadImageArtifact, saveImageArtifact } from "./image-artifact.mjs";
-import { loadPackagedSnapshotMetadata, packagedSystemSnapshot } from "./packaged-snapshot.mjs";
-import { siteReference, sitePath } from "./static-asset.mjs";
+import { loadPackagedSnapshotMetadata, packagedSystemSnapshot } from "../page/packaged-snapshot.mjs";
+import { siteReference, sitePath } from "../page/static-asset.mjs";
 
 
 // A custom recipe builds from this release's published recipes and sources.

package/{src → site}/image-builder.mjs

@@ -1,6 +1,6 @@
-import { buildHost, hostRegistry } from "../host/modules.mjs";
+import { hostRegistry } from "../host/modules.mjs";
 import { hostRequirement } from "../host/requirements.mjs";
-import { imageBase, imageDefinition } from "./images.mjs";
+import { imageBase, imageDefinition } from "../page/images.mjs";
 import { inspectDollyfile } from "./dollyfile-view.mjs";
 
 // Disposable Wasm userspace on the runtime the image declares, with the build
@@ -19,9 +19,10 @@ export async function buildImage(image, artifacts, configuration, report, { modu
   // inputs declare: it enables only the runtime and the build host, but a step
   // may run a program linked against a declared module's client (transfer's
   // download --help), which the Worker admits by that module's ABI.
-  const needed = new Set([...buildHost, ...declared, ...artifacts.flatMap(artifact => artifact.hostRequirements)]
-    .map(value => hostRequirement(value).name));
   const manifests = await Promise.all(modules.map(async url => ({ url, ...(await import(url, { with: { type: "json" } })).default })));
+  const needed = new Set([...declared, ...artifacts.flatMap(artifact => artifact.hostRequirements)]
+    .map(value => hostRequirement(value).name));
+  for (const { name, build } of manifests) if (build) needed.add(name);
   const registry = await hostRegistry(manifests.filter(({ name }) => needed.has(name)).map(({ url }) => url));
   const host = await registry.createHost("browser", registry.buildHostFor(declared),
     { send: message => worker.postMessage(message), configuration });

package/site/offline.mjs

@@ -0,0 +1,53 @@
+// The site's runtime kept in this browser, so that a saved session opens when
+// the network fails: the files dist/dolly-offline.json lists (the pages of a
+// session, the page's and the Workers' code, the host modules and the kernel),
+// in a cache named by the site and that list's digest. The service worker
+// answers from it only when a request fails (coi-serviceworker.js). The page
+// alone writes it, each file checked against the list's SHA-256 for it; nothing
+// of the guest reaches it. A cache is complete once it holds the list itself.
+import { sha256 } from "../page/static-asset.mjs";
+
+const prefix = site => `dolly-offline ${new URL(site).href} `;
+const listUrl = site => new URL("dist/dolly-offline.json", site).href;
+
+async function keptCaches(site) {
+  return (await caches.keys()).filter(name => name.startsWith(prefix(site)));
+}
+
+// Whether SITE's runtime is kept whole.
+export async function runtimeKept(site) {
+  for (const name of await keptCaches(site)) if (await (await caches.open(name)).match(listUrl(site))) return true;
+  return false;
+}
+
+// Keeps SITE's runtime as its server gives it now, and removes what was kept of
+// another. Rejects where the browser refuses the page a service worker or a
+// cache, or a file is not the one the list names.
+export async function keepRuntime(site) {
+  await navigator.serviceWorker.register(new URL("coi-serviceworker.js", site), { scope: new URL(site).pathname });
+  const listed = await fetch(listUrl(site), { cache: "no-cache" });
+  if (!listed.ok) throw new Error("this site lists no runtime to keep");
+  const list = await listed.clone().text(), name = prefix(site) + await sha256(new TextEncoder().encode(list));
+  const cache = await caches.open(name);
+  if (!await cache.match(listUrl(site))) {
+    try {
+      await Promise.all(JSON.parse(list).map(async ([path, digest]) => {
+        const url = new URL(path, site).href;
+        const response = await fetch(url, { cache: "no-cache" }), copy = response.clone();
+        if (!response.ok || await sha256(await response.arrayBuffer()) !== digest) throw new Error(`${path} is not the file this site lists`);
+        await cache.put(url, copy);
+      }));
+      await cache.put(listUrl(site), listed);
+    } catch (error) {
+      // A part of a runtime opens nothing and takes room the saves may need.
+      await caches.delete(name);
+      throw error;
+    }
+  }
+  for (const other of await keptCaches(site)) if (other !== name) await caches.delete(other);
+}
+
+// Removes what is kept of SITE's runtime.
+export async function clearRuntime(site) {
+  for (const name of await keptCaches(site)) await caches.delete(name);
+}