@daugasauron/dolly-build 0.0.0-stage → 0.1.5

package/scripts/system-snapshot-format.mjs

@@ -0,0 +1,103 @@
+import { Buffer } from "node:buffer";
+import { parseWasmInterface } from "../src/wasm-interface.mjs";
+import { validateProcessInterface } from "../src/process-abi.mjs";
+import { decodeImageEntry } from "../src/image-entry.mjs";
+import { decodeSnapshotRecords } from "../src/snapshot-records.mjs";
+
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+export function decodeSystemSnapshot(input) {
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  const entries = decodeSnapshotRecords(bytes);
+  const files = new Map();
+  const directories = new Set(["/"]);
+  for (const [path, { kind, data }] of entries) {
+    if (kind === 2) files.set(path, data);
+    if (kind === 1) directories.add(path);
+    for (let slash = path.indexOf("/", 1); slash !== -1; slash = path.indexOf("/", slash + 1)) {
+      directories.add(path.slice(0, slash));
+    }
+  }
+  return { files, entries, directories, manifest: [...entries.keys()] };
+}
+
+// Resolve against retained records only, never the packaging machine's files.
+export function resolveSnapshotFile(snapshot, path) {
+  if (!path.startsWith("/") || path.includes("\0")) throw new Error("invalid snapshot file path");
+  let pending = path.split("/");
+  const resolved = [];
+  let links = 0;
+  while (pending.length) {
+    const part = pending.shift();
+    if (!part || part === ".") continue;
+    if (part === "..") { resolved.pop(); continue; }
+    const current = "/" + [...resolved, part].join("/");
+    const record = snapshot.entries.get(current);
+    if (record?.kind === 3) {
+      if (++links > 40) throw new Error(`snapshot symlink loop: ${path}`);
+      const target = decoder.decode(record.data);
+      if (target.startsWith("/")) resolved.length = 0;
+      pending = [...target.split("/"), ...pending];
+      continue;
+    }
+    if (pending.length && !snapshot.directories.has(current)) {
+      throw new Error(`snapshot parent is missing or not a directory: ${current}`);
+    }
+    if (!pending.length && record?.kind !== 2) {
+      throw new Error(`snapshot file is not retained: ${current}`);
+    }
+    resolved.push(part);
+  }
+  const record = snapshot.entries.get("/" + resolved.join("/"));
+  if (record?.kind !== 2) throw new Error(`snapshot file is not retained: ${path}`);
+  return record.data;
+}
+
+// The ENTRY record, or null for an image that only builds.
+export function validateSnapshotEntry(snapshot, contract, digest) {
+  if (!snapshot.files.has("/etc/dolly/entry")) return null;
+  const entry = decodeImageEntry(snapshot.files.get("/etc/dolly/entry"));
+  validateProcessInterface(contract,
+    parseWasmInterface(resolveSnapshotFile(snapshot, entry[0]), entry[0]), digest);
+  return entry;
+}
+
+
+export function decodeSnapshotEnvironment(bytes) {
+  if (!bytes) throw new Error("snapshot has an invalid environment record");
+  const input = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  if (input.length < 16 ||
+      input.subarray(0, 8).toString("ascii") !== "DOLLYENV" ||
+      input.readUInt32LE(8) !== 1) {
+    throw new Error("snapshot has an invalid environment record");
+  }
+  const count = input.readUInt32LE(12);
+  if (count > 256) throw new Error("snapshot environment has too many entries");
+  let offset = 16;
+  const environment = new Map();
+  for (let index = 0; index < count; index += 1) {
+    if (offset > input.length - 8) {
+      throw new Error("snapshot environment is truncated");
+    }
+    const nameLength = input.readUInt32LE(offset);
+    const valueLength = input.readUInt32LE(offset + 4);
+    offset += 8;
+    if (nameLength === 0 || nameLength > 128 || valueLength > 64 * 1024 ||
+        offset > input.length - nameLength - valueLength) {
+      throw new Error("snapshot environment has an invalid entry");
+    }
+    const name = decoder.decode(input.subarray(offset, offset + nameLength));
+    offset += nameLength;
+    const value = decoder.decode(input.subarray(offset, offset + valueLength));
+    offset += valueLength;
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(name) ||
+        name.includes("\0") || value.includes("\0") || environment.has(name)) {
+      throw new Error("snapshot environment has an invalid name or value");
+    }
+    environment.set(name, value);
+  }
+  if (offset !== input.length) {
+    throw new Error("snapshot environment has trailing data");
+  }
+  return environment;
+}

package/scripts/wasm-interface.mjs

@@ -0,0 +1,7 @@
+import { readFile } from "node:fs/promises";
+import { parseWasmInterface } from "../src/wasm-interface.mjs";
+export * from "../src/wasm-interface.mjs";
+
+export async function readWasmInterface(path) {
+  return parseWasmInterface(await readFile(path), path);
+}

package/src/alphabetical.mjs

@@ -0,0 +1,4 @@
+// The one order of every list a visitor reads on the site's pages: by the
+// visible name, ignoring case. Names that differ only in case keep one order.
+const collator = new Intl.Collator("en", { sensitivity: "base" });
+export const alphabetical = (left, right) => collator.compare(left, right) || (left < right ? -1 : left > right ? 1 : 0);

package/src/dollyfile-graph.mjs

@@ -0,0 +1,127 @@
+import { inspectDollyfile, recipeFileName, imageFileName } from "./dollyfile-view.mjs";
+import { sha256 } from "./static-asset.mjs";
+
+const key = object => `${object.type}:${object.name}`;
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+// The recipe graph of one image, as /bin/dollyfile reads it: the root and the
+// FROM/INSTALL/USE/COPY images it imports, each with its own imports. `read(url)`
+// returns a recipe's bytes; this checks every pin. `artifacts` are the images
+// a build of the root reads: its own rows and, before each INSTALL or USE, the rows
+// that package's recipe installs, which the package names and does not hold. It is an inspection graph,
+// not a dependency solver: runtime assertions may resolve against files and
+// environment that recipes do not declare. Pass the same `recipes` cache to
+// reuse parsed recipes across graphs.
+export async function loadRecipeGraph(read, rootLocation, recipes = new Map()) {
+  const records = [], edges = [], artifacts = [];
+  const active = new Set(), images = new Map(), imageNames = new Map();
+
+  function parse(location) {
+    if (!recipes.has(location)) {
+      recipes.set(location, (async () => {
+        const bytes = await read(location);
+        return { ...inspectDollyfile(decoder.decode(bytes), location), sha256: await sha256(bytes) };
+      })());
+    }
+    return recipes.get(location);
+  }
+
+  async function load(location, expected, root) {
+    if (active.has(location)) throw new Error(`${location}: recipe cycle`);
+    const parsed = await parse(location);
+    if (expected && parsed.sha256 !== expected) throw new Error(`${location}: stale recipe pin`);
+    // An uploaded root is labeled "Dollyfile"; every site path names its recipe's file.
+    const file = recipeFileName(location);
+    if (file !== "" && imageFileName(file) !== parsed.name) {
+      throw new Error(`${location}: ${parsed.role.toUpperCase()} ${parsed.name} must match its file name`);
+    }
+    if ((imageNames.get(parsed.name) ?? location) !== location) {
+      throw new Error(`${location}: image ${parsed.name} is already ${imageNames.get(parsed.name)}`);
+    }
+    imageNames.set(parsed.name, location);
+    if (!root && images.has(location)) return images.get(location);
+    active.add(location);
+    const record = { ...parsed, location, dependencies: [], imports: new Map(), artifactTargets: [], installs: [], installTargets: [] };
+    records.push(record);
+    const visible = new Map();
+    const published = new Map();
+    const operations = [
+      ...record.artifacts,
+      ...record.requirements.map(value => ({ ...value, operation: "requirement" })),
+      ...record.exports.map(value => ({ ...value, operation: "export" })),
+    ].sort((a, b) => a.line - b.line);
+    for (const operation of operations) {
+      if (["from", "install", "use", "copy"].includes(operation.operation)) {
+        const target = await load(operation.location, operation.sha256, false);
+        const installs = ["install", "use"].includes(operation.operation);
+        if (operation.operation === "from" ? target.role === "package" : installs && target.role !== "package") {
+          throw new Error(`${location}:${operation.line}: ${target.name} is a ${target.role}: ` +
+            "FROM takes an application or toolchain, INSTALL and USE a package");
+        }
+        // Host requirements are never inherited: a package's must be declared here.
+        if (operation.operation === "install") {
+          const missing = target.hostRequirements.filter(name => !record.hostRequirements.includes(name));
+          if (missing.length) {
+            throw new Error(`${location}:${operation.line}: ${target.name} needs REQUIRES HOST ${missing.join(", ")}`);
+          }
+        }
+        record.artifactTargets.push({ reference: operation, target });
+        if (root && installs) {
+          for (const needed of target.installs) {
+            if (!artifacts.some(held => held.sha256 === needed.sha256)) artifacts.push({ ...needed, line: operation.line });
+          }
+        }
+        // What a package uses is the build's alone: it is not among what arrives with it.
+        if (operation.operation === "install") {
+          const row = { operation: "install", location: operation.location, sha256: operation.sha256, line: operation.line, image: target.image };
+          for (const needed of [...target.installs, row]) {
+            if (!record.installs.some(held => held.sha256 === needed.sha256)) record.installs.push({ ...needed, line: operation.line });
+          }
+          for (const needed of [...target.installTargets, target]) {
+            if (!record.installTargets.includes(needed)) record.installTargets.push(needed);
+          }
+        }
+        if (root) artifacts.push({ ...operation, image: target.image });
+        // A package keeps nothing of its base nor of what it installs; COPY takes files only.
+        const imports = operation.operation !== "copy" && record.role !== "package";
+        const imported = installs ? [...target.installTargets, target]
+          : operation.operation === "from" ? [target] : [];
+        for (const source of imported) {
+          for (const [name, provider] of source.scopeExporters) {
+            visible.set(name, provider);
+            if (imports) published.set(name, provider);
+          }
+        }
+      } else if (operation.operation === "export") {
+        if (operation.details.length !== 0 || !visible.has(key(operation))) {
+          visible.set(key(operation), { module: record, exported: operation });
+        }
+      } else if (operation.operation === "requirement") {
+        const requirement = record.requirements.find(item => item.line === operation.line);
+        const provider = visible.get(key(operation));
+        if (provider) {
+          const edge = { consumer: record, requirement, provider: provider.module, exported: provider.exported };
+          edges.push(edge);
+          record.dependencies.push(edge);
+          record.imports.set(key(operation), provider);
+        }
+      }
+    }
+    // A recipe's own exports describe its completed state and win over imported
+    // ones. Bare TOOL and ENV names resolve against the last provider seen: a
+    // package, an inherited base, or runtime state.
+    for (const exported of record.exports) {
+      const provider = visible.get(key(exported));
+      const resolved = (exported.details.length === 0 || exported.type === "ENV") && provider && provider.module !== record
+        ? { ...exported, details: provider.exported.details } : exported;
+      published.set(key(exported), { module: record, exported: resolved });
+    }
+    record.scopeExporters = published;
+    if (!root) images.set(location, record);
+    active.delete(location);
+    return record;
+  }
+
+  const root = await load(rootLocation, null, true);
+  return { root, records, edges, exporters: root.scopeExporters, artifacts };
+}

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-entry.mjs

@@ -0,0 +1,29 @@
+// Shared by packaging and browser admission; empty arguments are valid.
+export function decodeImageEntry(bytes) {
+  if (!(bytes instanceof Uint8Array) || bytes.byteLength < 16 || bytes.byteLength > 64 * 1024) {
+    throw new TypeError("invalid image ENTRY record");
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (decoder.decode(bytes.subarray(0, 8)) !== "DOLLYENT" || view.getUint32(8, true) !== 1) {
+    throw new TypeError("invalid image ENTRY version");
+  }
+  const count = view.getUint32(12, true);
+  if (count === 0 || count > 256) throw new TypeError("invalid image ENTRY count");
+  let offset = 16;
+  const arguments_ = [];
+  for (let index = 0; index < count; ++index) {
+    if (offset > bytes.byteLength - 4) throw new TypeError("truncated image ENTRY");
+    const size = view.getUint32(offset, true);
+    offset += 4;
+    if (size > 4096 || offset > bytes.byteLength - size) throw new TypeError("invalid image ENTRY argument");
+    const value = decoder.decode(bytes.subarray(offset, offset + size));
+    if (value.includes("\0")) throw new TypeError("image ENTRY has a NUL argument");
+    arguments_.push(value);
+    offset += size;
+  }
+  if (offset !== bytes.byteLength || !arguments_[0].startsWith("/")) {
+    throw new TypeError("invalid image ENTRY payload");
+  }
+  return arguments_;
+}

package/src/image-inputs.mjs

@@ -0,0 +1,20 @@
+// Recipe pins identify instructions; artifact digests identify their results.
+export function imageInputs(artifacts = []) {
+  if (!Array.isArray(artifacts) || artifacts.length > 256) throw new Error("invalid image inputs");
+  const inputs = new Map();
+  for (const artifact of artifacts) {
+    const { recipeSha256, sha256 } = artifact ?? {};
+    if (!/^[0-9a-f]{64}$/.test(recipeSha256) || !/^[0-9a-f]{64}$/.test(sha256)) {
+      throw new Error("invalid image input digest");
+    }
+    if (inputs.has(recipeSha256) && inputs.get(recipeSha256).sha256 !== sha256) {
+      throw new Error("conflicting image inputs");
+    }
+    inputs.set(recipeSha256, { recipeSha256, sha256 });
+  }
+  return [...inputs.values()].sort((a, b) => a.recipeSha256.localeCompare(b.recipeSha256));
+}
+
+export function imageInputsMatch(actual, expected) {
+  return JSON.stringify(imageInputs(actual)) === JSON.stringify(imageInputs(expected));
+}

package/src/image-names.mjs

@@ -0,0 +1,11 @@
+// What a recipe may name: an image, and the paths no image retains.
+
+// Image names: [a-z][a-z0-9]*(-[a-z0-9]+|\.[0-9]+)*, at most 32 bytes. A dot
+// starts a run of version digits, so a documentation copy such as
+// Dollyfile-example.txt is never a recipe.
+export const validName = name => /^[a-z][a-z0-9]*(?:-[a-z0-9]+|\.[0-9]+)*$/.test(name) && name.length <= 32;
+
+// No image retains scratch space.
+export function unretainedPath(value) {
+  return ["/tmp", "/workspace"].some((prefix) => value === prefix || value.startsWith(`${prefix}/`));
+}