@daugasauron/dolly 0.1.4 → 0.1.5

package/src/dollyfile-view.mjs

@@ -0,0 +1,335 @@
+import { hostRequirement, hostRequirements } from "../host/requirements.mjs";
+import { unretainedPath, validName } from "./image-names.mjs";
+
+export const MAX_DOLLYFILE_BYTES = 128 * 1024;
+
+const objectTypes = new Set([
+  "TOOL", "LIB", "ENV", "FILE", "FOLDER", "HEADER",
+]);
+const sha256Pattern = /^[0-9a-f]{64}$/;
+const whitespace = /[ \t\r\n\v\f]/;
+const trim = value => value.replace(/^[ \t\r\n\v\f]+|[ \t\r\n\v\f]+$/g, "");
+const byteLength = value => new TextEncoder().encode(value).byteLength;
+
+function fail(label, line, message) {
+  throw new Error(`${label}:${line}: ${message}`);
+}
+
+function physicalLines(source, label) {
+  if (typeof source !== "string") throw new TypeError(`${label}: Dollyfile must be text`);
+  if (byteLength(source) > MAX_DOLLYFILE_BYTES || source.includes("\0")) {
+    throw new Error(`${label}: invalid Dollyfile text`);
+  }
+  return source.split(/\r\n|\r|\n/);
+}
+
+function stripComment(value) {
+  let quote = "";
+  let escaped = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (escaped) escaped = false;
+    else if (character === "\\" && quote !== "'") escaped = true;
+    else if (quote) {
+      if (character === quote) quote = "";
+    } else if (character === "'" || character === '"') quote = character;
+    else if (character === "#" && (index === 0 || whitespace.test(value[index - 1]))) {
+      return value.slice(0, index);
+    }
+  }
+  return value;
+}
+
+// The words of a row; `ends` receives the offset after each.
+function words(value, label, line, ends = []) {
+  const result = [];
+  let word = "";
+  let quote = "";
+  let escaped = false;
+  let started = false;
+  for (let offset = 0; offset < value.length; offset += 1) {
+    const character = value[offset];
+    if (escaped) {
+      if (quote === '"' && !['$', '`', '"', "\\"].includes(character)) word += "\\";
+      word += character;
+      escaped = false;
+      started = true;
+    } else if (character === "\\" && quote !== "'") {
+      escaped = true;
+      started = true;
+    } else if (quote) {
+      if (character === quote) quote = "";
+      else word += character;
+      started = true;
+    } else if (character === "'" || character === '"') {
+      quote = character;
+      started = true;
+    } else if (whitespace.test(character)) {
+      if (started) {
+        result.push(word);
+        ends.push(offset);
+        word = "";
+        started = false;
+      }
+    } else {
+      word += character;
+      started = true;
+    }
+  }
+  if (escaped || quote) fail(label, line, "unterminated quoted word");
+  if (started) {
+    result.push(word);
+    ends.push(value.length);
+  }
+  return result;
+}
+
+function directives(physical, label) {
+  const result = [];
+  for (let index = 0; index < physical.length; index += 1) {
+    const raw = physical[index];
+    const line = index + 1;
+    let logical = stripComment(raw).replace(/[ \t]+$/, "");
+    while (logical.endsWith("\\")) {
+      logical = logical.slice(0, -1);
+      index += 1;
+      if (index >= physical.length || index === physical.length - 1 && physical[index] === "") {
+        fail(label, line, "unterminated continuation");
+      }
+      logical += `${logical.length ? " " : ""}${stripComment(physical[index]).replace(/[ \t]+$/, "")}`;
+    }
+    if (byteLength(logical) > 64 * 1024) fail(label, line, "logical line is too long");
+    logical = trim(logical);
+    if (logical === "") continue;
+    const match = /^([^ \t\r\n\v\f]+)(?:[ \t\r\n\v\f]+(.*))?$/s.exec(logical);
+    const directive = match[1];
+    const args = match[2] ?? "";
+    let body = null;
+    let endLine = index + 1;
+    if (directive === "FILE") {
+      const bodyLines = [];
+      while (index + 1 < physical.length && physical[index + 1].startsWith("    ")) {
+        index += 1;
+        bodyLines.push(physical[index].slice(4));
+        endLine = index + 1;
+      }
+      if (bodyLines.length) body = bodyLines.join("\n") + "\n";
+    }
+    result.push({ line, endLine, directive, args, body });
+  }
+  return result;
+}
+
+function validAbsolutePath(value) {
+  return value.startsWith("/") && value.length > 1 && byteLength(value) < 4096 &&
+    !/[\\\r\n]/.test(value) && !value.endsWith("/") && !value.includes("//") &&
+    !value.split("/").some((part) => part === "." || part === "..");
+}
+
+// A site path names a file one release of the site publishes: /vX.Y.Z/PATH,
+// without a query. FROM, INSTALL and COPY take one whose file is
+// Dollyfile[-NAME]; SOURCE takes one or an absolute http(s) URL without a
+// fragment.
+const sitePathSyntax = /^\/v\d+\.\d+\.\d+\/[^?#\\ \t\r\n\v\f]+$/;
+const sourceURL = /^https?:\/\/[^/?#\\ \t\r\n\v\f]+(?:[/?][^#\\ \t\r\n\v\f]*)?$/;
+// A URL parser resolves empty, "." and ".." path segments (also spelled with
+// %2e) to another path, so a recipe names only normalized paths.
+function normalizedPath(reference) {
+  const path = reference.split("?")[0].replace(/^https?:\/\/[^/]*/, "");
+  return !path.includes("//") && !path.split("/").some(segment => /^(?:\.|%2e){1,2}$/i.test(segment));
+}
+// The file a recipe's site path names, or "" when the value is not one.
+export const recipeFileName = reference =>
+  sitePathSyntax.test(reference) && normalizedPath(reference) ? reference.slice(reference.lastIndexOf("/") + 1) : "";
+// The image name a file "Dollyfile" or "Dollyfile-NAME" declares, or "".
+export const imageFileName = file => file === "Dollyfile" ? "default" : file.startsWith("Dollyfile-") ? file.slice(10) : "";
+const roles = { APPLICATION: "application", TOOLCHAIN: "toolchain", PACKAGE: "package" };
+
+function assertObject(tokens, label, item, directive) {
+  if (tokens.length < 2 || !objectTypes.has(tokens[0])) {
+    fail(label, item.line, `invalid ${directive}; expected ${directive} <${[...objectTypes].join("|")}> NAME`);
+  }
+  if (tokens[0] === "ENV" && !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(tokens[1])) {
+    fail(label, item.line, `invalid ${directive} environment name`);
+  }
+  if (tokens[0] !== "ENV" && (tokens[1].length > 128 || !/^(?:[a-zA-Z][a-zA-Z0-9._+-]*|\[)$/.test(tokens[1]))) {
+    fail(label, item.line, `invalid ${directive}`);
+  }
+}
+
+// RUN and ENTRY share one argument vector grammar and its record limits.
+function programWords(tokens, label, item) {
+  if (tokens.length === 0 || !validAbsolutePath(tokens[0])) fail(label, item.line, `invalid ${item.directive}`);
+  if (tokens.length > 256 || tokens.some(word => byteLength(word) > 4096) ||
+      tokens.reduce((size, word) => size + 4 + byteLength(word), 16) > 64 * 1024) {
+    fail(label, item.line, `${item.directive} exceeds its record limits`);
+  }
+  return tokens;
+}
+
+function inspectRecipe(source, label, rows) {
+  let role = null;
+  let name = null;
+  let entry = null;
+  const requirements = [];
+  const exports = [];
+  const sources = [];
+  const slops = [];
+  const files = [];
+  const folders = [];
+  const artifacts = [];
+  let from = null;
+  // REQUIRES HOST lines are the image's manifest: they follow the role line.
+  let operations = 0;
+
+  for (const item of rows.slice(1)) {
+    const ends = [];
+    const tokens = words(item.args, label, item.line, ends);
+    // What /bin/dollyfile executes for the row (recipeRows).
+    item.fields = [item.directive, ...tokens];
+    if (role === null && !(item.directive in roles)) {
+      fail(label, item.line, "expected APPLICATION, TOOLCHAIN or PACKAGE");
+    }
+    if (entry) fail(label, item.line, "ENTRY must be the final declaration");
+    switch (item.directive) {
+      case "APPLICATION":
+      case "TOOLCHAIN":
+      case "PACKAGE":
+        if (role || tokens.length !== 1 || !validName(tokens[0])) fail(label, item.line, `invalid ${item.directive}`);
+        role = roles[item.directive];
+        name = tokens[0];
+        break;
+      case "FROM":
+      case "INSTALL":
+      case "USE":
+      case "COPY": {
+        const operation = item.directive.toLowerCase();
+        if (tokens.length !== (operation === "copy" ? 4 : 2) ||
+            !validName(imageFileName(recipeFileName(tokens[0]))) || !sha256Pattern.test(tokens[1]) ||
+            tokens.slice(2).some(path => path !== "/" && !validAbsolutePath(path))) {
+          fail(label, item.line, `invalid ${item.directive}`);
+        }
+        if (operation === "from" && operations !== 0) {
+          fail(label, item.line, "FROM must be the first operation");
+        }
+        if (operation === "use" && role !== "package") {
+          fail(label, item.line, "USE is for a PACKAGE recipe, which keeps nothing it installs");
+        }
+        operations += 1;
+        const artifact = { location: tokens[0], sha256: tokens[1], line: item.line,
+          source: tokens[2] ?? "/", destination: tokens[3] ?? "/", operation };
+        artifacts.push(artifact);
+        if (operation === "from") from = artifact;
+        break;
+      }
+      case "SOURCE":
+        operations += 1;
+        if (tokens.length !== 3 || !(sitePathSyntax.test(tokens[0]) || sourceURL.test(tokens[0])) || !normalizedPath(tokens[0]) ||
+            !sha256Pattern.test(tokens[1]) || !validAbsolutePath(tokens[2])) fail(label, item.line, "invalid SOURCE");
+        sources.push({ location: tokens[0], sha256: tokens[1], destination: tokens[2], line: item.line });
+        break;
+      case "REQUIRES":
+        if (tokens[0] === "HOST") {
+          if (tokens.length !== 2) fail(label, item.line, "invalid REQUIRES HOST; expected REQUIRES HOST NAME@ABI");
+          if (operations !== 0) fail(label, item.line, "REQUIRES HOST lines follow the role line, before every other declaration");
+          try { hostRequirement(tokens[1]); } catch (error) { fail(label, item.line, error.message); }
+        } else {
+          assertObject(tokens, label, item, "REQUIRES");
+          if (!["TOOL", "LIB", "HEADER"].includes(tokens[0])) fail(label, item.line, "REQUIRES takes HOST, TOOL, LIB or HEADER");
+          operations += 1;
+        }
+        if (tokens.length !== 2) fail(label, item.line, "invalid REQUIRES");
+        if (tokens[0] === "TOOL" && tokens[1] === "slop") fail(label, item.line, "SLOP depends on /bin/slop by definition");
+        requirements.push({ type: tokens[0], name: tokens[1], line: item.line });
+        break;
+      case "EXPORTS": {
+        operations += 1;
+        assertObject(tokens, label, item, "EXPORTS");
+        const [type, object, ...details] = tokens;
+        if (type === "TOOL") {
+          if (details.length !== 0) fail(label, item.line, "invalid TOOL export");
+        } else if (type === "ENV") {
+          if (details.length !== 1) {
+            fail(label, item.line, "invalid ENV export");
+          }
+        } else if (details.length !== 1 || !validAbsolutePath(details[0]) || unretainedPath(details[0])) {
+          fail(label, item.line, `invalid ${type} export`);
+        }
+        exports.push({ type, name: object, details, line: item.line });
+        break;
+      }
+      case "FILE":
+        operations += 1;
+        if (tokens.length !== 1 || !validAbsolutePath(tokens[0])) fail(label, item.line, "invalid FILE");
+        if (unretainedPath(tokens[0]) && !tokens[0].startsWith("/tmp/")) {
+          fail(label, item.line, "FILE cannot retain mutable session state");
+        }
+        files.push({ path: tokens[0], body: item.body, line: item.line, endLine: item.endLine });
+        if (item.body !== null) item.fields.push(item.body);
+        break;
+      case "FOLDER":
+        operations += 1;
+        if (tokens.length !== 1 || !validAbsolutePath(tokens[0]) ||
+            unretainedPath(tokens[0])) fail(label, item.line, "invalid FOLDER");
+        folders.push({ path: tokens[0], line: item.line });
+        break;
+      case "RUN":
+      case "SLOP": {
+        operations += 1;
+        let cwd = "/";
+        let command = tokens;
+        if (tokens[0] === "CWD") {
+          if (tokens.length < 3 || (tokens[1] !== "/" && !validAbsolutePath(tokens[1]))) {
+            fail(label, item.line, `invalid ${item.directive} CWD`);
+          }
+          cwd = tokens[1];
+          command = tokens.slice(2);
+        }
+        if (item.directive === "RUN") {
+          item.fields = ["RUN", cwd, ...programWords(command, label, item)];
+        } else {
+          if (!command[0]) fail(label, item.line, "empty SLOP");
+          slops.push({ cwd, command, line: item.line });
+          // Slop reads the command as written, quoting and all.
+          item.fields = ["SLOP", cwd, trim(tokens[0] === "CWD" ? item.args.slice(ends[1]) : item.args)];
+        }
+        break;
+      }
+      case "ENTRY":
+        if (!["application", "toolchain"].includes(role)) fail(label, item.line, "invalid ENTRY");
+        entry = programWords(tokens, label, item);
+        break;
+      case "DOLLY":
+        fail(label, item.line, "DOLLY may only appear on the first line");
+        break;
+      default:
+        fail(label, item.line, `unknown directive ${item.directive}`);
+    }
+  }
+  if (role === null) throw new Error(`${label}: missing APPLICATION, TOOLCHAIN or PACKAGE`);
+  if (role === "application" && !entry) throw new Error(`${label}: APPLICATION is missing ENTRY`);
+  let required;
+  try { required = hostRequirements(requirements.filter(item => item.type === "HOST").map(item => item.name)); }
+  catch (error) { throw new Error(`${label}: ${error.message}`); }
+  return {
+    hostRequirements: required, role, name, image: name, entry,
+    requirements, exports, artifacts, from, sources, slops, files, folders, rows, source,
+  };
+}
+
+// The rows /bin/dollyfile executes, which the page writes to
+// /etc/dolly/recipe.rows: the engine parses no recipe text, so this file is the
+// language's one parser. Every field ends with NUL, which no recipe holds:
+// "DOLLY 7 SHA256" of the recipe's text, then for each row after DOLLY
+// "LINE COUNT" and that many fields, the directive first.
+export const recipeRows = (recipe, sha256) => [`DOLLY 7 ${sha256}`,
+  ...recipe.rows.slice(1).flatMap(row => [`${row.line} ${row.fields.length}`, ...row.fields])]
+  .map(field => `${field}\0`).join("");
+
+export function inspectDollyfile(source, label = "Dollyfile") {
+  const rows = directives(physicalLines(source, label), label);
+  if (rows[0]?.directive !== "DOLLY" || rows[0].args !== "7") {
+    throw new Error(`${label}:${rows[0]?.line ?? 1}: first declaration must be DOLLY 7`);
+  }
+  return inspectRecipe(source, label, rows);
+}

package/src/image-artifact.mjs

@@ -0,0 +1,248 @@
+// Built images in this browser: an artifact's identity read from its own
+// snapshot, and the bounded cache of the images the site builds: each one's
+// snapshot a file of origin-private storage, indexed in IndexedDB.
+//
+// A snapshot is written to its file as it streams out of Wasm memory or out
+// of its packs, and the artifact's bytes is that file. A Blob built from
+// parts in memory is unreadable in Chrome once the parts exceed its
+// in-memory blob space (500 MiB before the browser has been idle after
+// 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 { 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";
+export { sha256 };
+
+const STORE_DIRECTORY = "dolly-images";
+// The store's files this page reads: a build may still read one whose entry
+// was evicted, so it is left for a later sweep.
+const held = new Set();
+
+async function storeDirectory() {
+  try {
+    return await (await navigator.storage.getDirectory()).getDirectoryHandle(STORE_DIRECTORY, { create: true });
+  } catch { return null; }
+}
+
+// A new file of the store, written piece by piece: write(piece), then
+// close() for its File or abort() to delete it. Null without a store.
+async function openStoreFile() {
+  const directory = await storeDirectory();
+  if (!directory) return null;
+  const name = crypto.randomUUID();
+  const handle = await directory.getFileHandle(name, { create: true }), writable = await handle.createWritable();
+  return {
+    write: piece => writable.write(piece),
+    async close() {
+      await writable.close();
+      return handle.getFile();
+    },
+    async abort() {
+      await writable.abort().catch(() => {});
+      await directory.removeEntry(name).catch(() => {});
+    },
+  };
+}
+
+// The File of a store file written through OPENED, which this page then holds.
+async function storeFile(opened) {
+  const file = await opened.close();
+  held.add(file.name);
+  return file;
+}
+
+// An artifact's identity read from its snapshot, SOURCE: a Blob, or the
+// snapshot's bytes in pieces (an iterable of Uint8Array), which become a file
+// of the store (a Blob in memory where the browser has no origin-private
+// storage). The snapshot is digested and checked as it passes; only the
+// identity's files under /etc/dolly are held.
+export async function describeImageArtifact(source, recipeSha256, inputs = []) {
+  const blob = source instanceof Blob ? source : null, hash = new Sha256(), parts = [];
+  const file = blob ? null : await openStoreFile();
+  const pieces = (async function* () {
+    for await (const piece of blob ? blob.stream() : source) {
+      hash.update(piece);
+      if (file) await file.write(piece);
+      else if (!blob) parts.push(new Blob([piece]));
+      yield piece;
+    }
+  })();
+  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");
+    // 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}`);
+      return record.data;
+    }, "Dollyfile");
+    return { buildId: DOLLY_IMAGE_BUILD_ID, recipeSha256, sha256: hash.hex(),
+      inputs: imageInputs(inputs), hostRequirements: graph.root.hostRequirements,
+      byteLength, manifest: [...records.keys()], bytes: blob ?? (file ? await storeFile(file) : new Blob(parts)) };
+  } catch (error) {
+    await file?.abort();
+    throw error;
+  }
+}
+
+async function databaseOperation(mode, operation) {
+  const database = await new Promise((resolve, reject) => {
+    const request = indexedDB.open("dolly-image-artifacts-v3", 3);
+    request.onupgradeneeded = () => {
+      // This database contains rebuildable images, never named user sessions.
+      if (request.result.objectStoreNames.contains("images")) request.result.deleteObjectStore("images");
+      request.result.createObjectStore("images", { keyPath: "id" });
+      // Other runtime versions' pages keep their images' bytes here; this
+      // version's are files of the store, named by their entries.
+      request.result.createObjectStore("payloads");
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+  try {
+    return await new Promise((resolve, reject) => {
+      const transaction = database.transaction(["images", "payloads"], mode);
+      let request;
+      transaction.oncomplete = () => resolve(request.result);
+      transaction.onerror = transaction.onabort = () => reject(transaction.error ?? new Error("image cache transaction aborted"));
+      try { request = operation(transaction.objectStore("images"), transaction.objectStore("payloads")); }
+      catch (error) { transaction.abort(); reject(error); }
+    });
+  } finally { database.close(); }
+}
+
+export async function loadImageArtifactDescriptor(recipeSha256, inputs = []) {
+  try {
+    const id = `${DOLLY_IMAGE_BUILD_ID}:${recipeSha256}`;
+    const record = await databaseOperation("readonly", store => store.get(id));
+    if (record?.id !== id || record.buildId !== DOLLY_IMAGE_BUILD_ID || record.recipeSha256 !== recipeSha256 ||
+        !/^[0-9a-f]{64}$/.test(record.sha256) || !Number.isSafeInteger(record.byteLength) ||
+        record.byteLength <= 0 || record.byteLength > snapshotSizeLimit || typeof record.file !== "string" ||
+        !imageInputsMatch(record.inputs, inputs)) return null;
+    return record;
+  } catch { return null; }
+}
+
+// The cached artifact DESCRIPTOR (its recipe, digest, size and inputs) names,
+// its bytes the entry's file, or null when the entry holds another image or
+// its file is missing or holds other bytes. Loading marks the entry used: the
+// entries a build reads are evicted last.
+export async function loadImageArtifact(descriptor) {
+  try {
+    const id = `${DOLLY_IMAGE_BUILD_ID}:${descriptor.recipeSha256}`;
+    const entry = await databaseOperation("readwrite", store => {
+      const request = store.get(id);
+      request.onsuccess = () => {
+        if (request.result?.sha256 === descriptor.sha256 && request.result.file) store.put({ ...request.result, usedAt: now() });
+      };
+      return request;
+    });
+    if (entry?.sha256 !== descriptor.sha256 || typeof entry.file !== "string") return null;
+    const payload = await (await (await storeDirectory()).getFileHandle(entry.file)).getFile();
+    if (payload.size !== descriptor.byteLength || payload.size <= 0 || payload.size > snapshotSizeLimit) return null;
+    held.add(entry.file);
+    const artifact = await describeImageArtifact(payload, descriptor.recipeSha256, descriptor.inputs);
+    return artifact.sha256 === descriptor.sha256 ? artifact : null;
+  } catch { return null; }
+}
+
+const now = () => performance.timeOrigin + performance.now();
+
+// Rebuildable images only; a bounded cache so builds cannot fill browser storage.
+export const IMAGE_CACHE_MAX_ENTRIES = 32;
+const IMAGE_CACHE_MAX_BYTES = 8 * 1024 ** 3;
+
+// The name of the store's file holding BLOB: its own name when it is one of
+// the store's files, else a new file written from it.
+async function storeFileOf(directory, blob) {
+  if (blob instanceof File && held.has(blob.name)) return blob.name;
+  const file = await openStoreFile();
+  try {
+    for await (const piece of blob.stream()) await file.write(piece);
+    return (await file.close()).name;
+  } catch (error) {
+    await file.abort();
+    throw error;
+  }
+}
+
+export async function saveImageArtifact(artifact, slot = artifact.recipeSha256) {
+  try {
+    if (artifact.buildId !== DOLLY_IMAGE_BUILD_ID || !(artifact.bytes instanceof Blob) ||
+        artifact.bytes.size !== artifact.byteLength || artifact.byteLength <= 0 ||
+        artifact.byteLength > snapshotSizeLimit) return false;
+    const directory = await storeDirectory();
+    if (!directory) return false;
+    const file = await storeFileOf(directory, artifact.bytes);
+    const id = `${DOLLY_IMAGE_BUILD_ID}:${artifact.recipeSha256}`;
+    const { buildId, recipeSha256, sha256, inputs, hostRequirements, byteLength } = artifact;
+    const removed = [];
+    try {
+      await databaseOperation("readwrite", (store, payloads) => {
+        const remove = entry => { store.delete(entry.id); payloads.delete(entry.id); if (entry.file) removed.push(entry.file); };
+        const previous = store.get(id);
+        previous.onsuccess = () => {
+          if (previous.result && previous.result.file !== file) remove(previous.result);
+          store.put({ buildId, recipeSha256, sha256, inputs, hostRequirements, byteLength, slot, id, file, usedAt: now() });
+          // Publish and prune atomically: failed writes preserve the previous
+          // entry, and concurrent writers cannot prune each other's newly
+          // published data. This runtime's previous image in the slot goes
+          // first, then the least recently used images beyond the entry and
+          // byte bounds. Other versions' pages keep their images here too, so
+          // another runtime's are only bounded.
+          const kept = [], cursor = store.openCursor();
+          cursor.onsuccess = () => {
+            const entry = cursor.result?.value;
+            if (entry) {
+              if (entry.id !== id) {
+                if (entry.buildId === DOLLY_IMAGE_BUILD_ID && entry.slot === slot) remove(entry);
+                else kept.push(entry);
+              }
+              cursor.result.continue();
+              return;
+            }
+            kept.sort((left, right) => (right.usedAt ?? right.savedAt ?? 0) - (left.usedAt ?? left.savedAt ?? 0));
+            let total = byteLength;
+            kept.forEach((entry, index) => {
+              total += entry.byteLength;
+              if (index + 1 >= IMAGE_CACHE_MAX_ENTRIES || total > IMAGE_CACHE_MAX_BYTES) remove(entry);
+            });
+          };
+        };
+        return previous;
+      });
+    } catch (error) {
+      if (file !== artifact.bytes.name) await directory.removeEntry(file).catch(() => {});
+      return false;
+    }
+    await deleteStoreFiles(directory, removed.filter(name => !held.has(name)));
+    await sweepStore(directory).catch(() => {});
+    return true;
+  } catch { return false; }
+}
+
+async function deleteStoreFiles(directory, names) {
+  for (const name of names) await directory.removeEntry(name).catch(() => {});
+}
+
+// Files no entry names and this page does not hold, an hour after they were
+// written: what a failed save or a closed page left, and the evicted files
+// pages still read. Chrome lists a file being written under another name.
+const SWEEP_AGE = 60 * 60 * 1000;
+async function sweepStore(directory) {
+  const named = new Set(await databaseOperation("readonly", store => store.getAll()).then(entries => entries.map(entry => entry.file)));
+  for await (const [name, handle] of directory) {
+    if (handle.kind !== "file" || named.has(name) || held.has(name) ||
+        !/^[0-9a-f-]{36}$/.test(name) || (await handle.getFile()).lastModified > now() - SWEEP_AGE) continue;
+    await directory.removeEntry(name).catch(() => {});
+  }
+}

package/src/image-build.mjs

@@ -0,0 +1,89 @@
+import { DOLLY_IMAGES, imageBase, imageDefinition } from "./images.mjs";
+import { loadRecipeGraph } from "./dollyfile-graph.mjs";
+import { imageInputs, imageInputsMatch } from "./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";
+
+
+// A custom recipe builds from this release's published recipes and sources.
+async function customRecipeGraph(customSource, signal) {
+  const graph = await loadRecipeGraph(async reference => {
+    if (reference === "Dollyfile") return new TextEncoder().encode(customSource);
+    const response = await fetch(new URL(sitePath(reference).slice(1), imageBase),
+      { credentials: "same-origin", redirect: "error", signal });
+    if (!response.ok) throw new Error(`${reference}: HTTP ${response.status}; this release does not publish that recipe`);
+    return response.arrayBuffer();
+  }, "Dollyfile");
+  // The broker would refuse another version's path without saying why.
+  for (const { location } of graph.root.sources) sitePath(location);
+  return graph;
+}
+
+// Only explicit image references schedule builds. Modules still execute in
+// order inside their caller's userspace; this traversal makes no input guesses.
+export async function prepareImageArtifacts(image, customSource, build, report, signal) {
+  const artifacts = new Map(), active = new Set();
+  async function materialize(node) {
+    signal?.throwIfAborted();
+    if (node.artifact) return node.artifact;
+    const { definition, descriptor } = node;
+    let artifact = await loadImageArtifact(descriptor);
+    if (artifact) report(`reusing local ${definition.image} artifact`);
+    else {
+      const metadata = node.metadata ?? await loadPackagedSnapshotMetadata(definition.image);
+      // A cache replacement or corruption must not substitute different bytes
+      // after a consumer has already been selected using this descriptor.
+      if (metadata.sha256 !== descriptor.sha256 || !imageInputsMatch(metadata.inputs, descriptor.inputs)) {
+        throw new Error(`${definition.image}: selected image artifact is no longer available; retry the rebuild`);
+      }
+      artifact = await describeImageArtifact(await packagedSystemSnapshot(metadata, signal),
+        definition.sha256, descriptor.inputs);
+      report(`reusing published ${definition.image} artifact`);
+      await saveImageArtifact(artifact, `/${definition.dollyfile}`);
+    }
+    node.artifact = artifact;
+    signal?.throwIfAborted();
+    return artifact;
+  }
+  async function resolve(reference) {
+    signal?.throwIfAborted();
+    if (artifacts.has(reference.sha256)) return artifacts.get(reference.sha256);
+    const definition = DOLLY_IMAGES.find(candidate =>
+      siteReference(candidate.dollyfile) === reference.location && candidate.sha256 === reference.sha256);
+    if (!definition) throw new Error(`${reference.location}: image pin is not present in this release`);
+    if (active.has(definition.image)) throw new Error(`image cycle at ${definition.image}`);
+    active.add(definition.image);
+    const dependencies = new Map();
+    for (const dependency of definition.artifacts) dependencies.set(dependency.sha256, await resolve(dependency));
+    const inputs = imageInputs([...dependencies.values()].map(node => node.descriptor));
+    let descriptor = await loadImageArtifactDescriptor(definition.sha256, inputs);
+    let metadata, artifact;
+    if (!descriptor) {
+      try {
+        metadata = await loadPackagedSnapshotMetadata(definition.image);
+        if (!imageInputsMatch(metadata.inputs, inputs)) throw new Error("published image inputs changed");
+        descriptor = { recipeSha256: definition.sha256, sha256: metadata.sha256,
+          byteLength: metadata.byteLength, inputs };
+      } catch {
+        report(`building missing ${definition.image} artifact`);
+        const loaded = [];
+        for (const dependency of dependencies.values()) loaded.push(await materialize(dependency));
+        artifact = await build(definition.image, loaded);
+        if (!imageInputsMatch(artifact.inputs, inputs)) throw new Error("built image inputs changed");
+        descriptor = artifact;
+      }
+    }
+    signal?.throwIfAborted();
+    active.delete(definition.image);
+    const node = { definition, descriptor, metadata, artifact };
+    artifacts.set(definition.sha256, node);
+    return node;
+  }
+  const references = image === "custom" ? (await customRecipeGraph(customSource, signal)).artifacts : imageDefinition(image).artifacts;
+  const selected = new Map();
+  for (const reference of references) selected.set(reference.sha256, await resolve(reference));
+  const loaded = [];
+  for (const node of selected.values()) loaded.push(await materialize(node));
+  return loaded;
+}