@milpa/comal 0.2.6 → 0.2.8

package/src/plugin-workbench.mjs

@@ -0,0 +1,675 @@
+import { open, mkdir, writeFile, chmod, lstat, stat, readdir, readlink, realpath, rm, rmdir, symlink, constants } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { inspectPluginModule, pluginId, MAX_CODE_FILES, PLUGIN_SPECIFIERS } from './plugin-config.mjs';
+import { defaultStateDir } from './compat.mjs';
+
+// The plugin workbench's candidate: a private copy of a plugin under
+// <stateDir>/plugin-candidates/<id>/<candidateId>/tree, where a repair is made and tested.
+// The installed files and the user's originals are only ever read.
+//
+// Own files and host modules. Of the files the inspector covers, the plugin's OWN files are
+// those inside the directory of its entry module (recursively): they are copied, and they are
+// all a repair may change or add. Every other covered file is a HOST MODULE (the house's own
+// modules a bundled plugin imports, a workspace file shared with other code): it appears in
+// tree at its relative place as a symbolic link to the installed file's real path, recorded
+// in candidate.json and the seal. Node resolves a linked module to its real path, so the
+// repaired plugin imports the same module instances as the host (its protected paths, its
+// catalogs), never private copies of them.
+//
+// The model writes every byte inside tree, so nothing in the candidate directory is
+// trusted on its own. What later tasks must hold:
+// - the writable root given to the model is exactly `tree`, never `dir` or above, and the file
+//   tools refuse a path under it whose real path leaves it (a write through a host link);
+// - the caller keeps `seal` (from openCandidate) in the session journal and passes it
+//   to readCandidate: candidate.json is only metadata until it hashes to that seal;
+// - verifyCandidate runs immediately before every load of the candidate and again at
+//   promotion, and promotion copies only the files (and hashes) that verification returned
+//   and links exactly the recorded host modules (verifyPlacement checks the result).
+
+const CANDIDATES = 'plugin-candidates';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const SHA = /^[0-9a-f]{64}$/;
+const MAX_FILE_BYTES = 1024 * 1024;        // the inspector's per-file bound
+const MAX_READ_BYTES = 64 * 1024 * 1024;   // all bytes one diff or one verification may read
+const PATCH_LIMIT = 200 * 1024;
+const PATCH_MARKER = '[patch truncated at 200 KB]\n';
+const DIFF_CELLS = 4_000_000;              // above this, a file is summarized instead of diffed
+const CONTEXT = 3;
+// Files Node may load as code: refused when opaque, and scanned for specifiers.
+const CODE = /\.(?:m?js|cjs)$/, OPAQUE_CHECKED = /\.(?:m?js|cjs|json)$/;
+const isCode = file => CODE.test(file) || !path.basename(file).includes('.');
+const isOpaqueChecked = file => OPAQUE_CHECKED.test(file) || !path.basename(file).includes('.');
+// The inspector's literal specifiers, plus CommonJS require: every one must stay inside tree.
+// A module specifier may name no URL scheme but node:; a new URL(…, import.meta.url) only no file:.
+const SPECIFIERS = [/\bfrom\s*['"]([^'"\n]+)['"]/g, /\bimport\s*['"]([^'"\n]+)['"]/g, /\bimport\s*\(\s*['"]([^'"\n]+)['"]\s*[,)]/g,
+  /(?<![.\w$])require\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g].map(pattern => [pattern, true])
+  .concat([[/\bnew\s+URL\s*\(\s*['"]([^'"\n]+)['"]\s*,\s*import\.meta\.url\s*\)/g, false]]);
+// Constructs static inspection cannot follow. Listed for changed files; promotion decides.
+const DYNAMIC = [
+  ['import()', /\bimport\s*\(\s*(?!(['"])[^'"\n]*\1\s*[,)])/],
+  ['createRequire', /\bcreateRequire\b/],
+  ['import.meta.resolve', /\bimport\s*\.\s*meta\s*\.\s*resolve\b/],
+  ['require()', /(?<![.\w$])require\s*\(/],
+  ['process.binding', /\bprocess\s*\.\s*binding\b/],
+  ['eval()', /(?<![.\w$])eval\s*\(/],
+  ['new Function', /(?<![.\w$])Function\s*\(/],
+];
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const posix = relative => relative.split(path.sep).join('/');
+const sorted = values => [...values].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+const plainObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function inside(root, file) {
+  const relative = path.relative(root, file);
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+const stateRoot = (cwd, stateDir) => path.resolve(cwd, stateDir ?? defaultStateDir(cwd));
+
+/**
+ * A reader with a total byte budget. Each read allocates the file's size plus one byte
+ * (to notice growth), refuses non-regular files, and can refuse to follow a final symlink.
+ */
+function reader(total = MAX_READ_BYTES) {
+  let remaining = total;
+  return async function read(file, { limit = Infinity, nofollow = false } = {}) {
+    const handle = await open(file, nofollow ? constants.O_RDONLY | constants.O_NOFOLLOW : 'r');
+    try {
+      const info = await handle.stat();
+      if (!info.isFile()) throw new Error(`Not a regular file: ${file}`);
+      if (info.size > limit) throw new Error(`File larger than ${limit} bytes: ${file}`);
+      if (info.size > remaining) throw fail('PLUGIN_CANDIDATE_TOO_LARGE', `The candidate holds more than ${total} bytes to read (at ${file})`);
+      const buffer = Buffer.alloc(info.size + 1);
+      let offset = 0;
+      while (offset < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+        if (!bytesRead) break;
+        offset += bytesRead;
+      }
+      if (offset > info.size) throw new Error(`File grew while it was read: ${file}`);
+      remaining -= offset;
+      return { bytes: buffer.subarray(0, offset), nlink: info.nlink };
+    } finally { await handle.close(); }
+  };
+}
+
+const boundedRead = async file => (await reader(MAX_FILE_BYTES)(file, { limit: MAX_FILE_BYTES })).bytes;
+
+// A directory of ours: created 0700, or already there as a real directory (never a symlink).
+async function ownDirectory(dir) {
+  try { await mkdir(dir, { mode: 0o700 }); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+  const info = await lstat(dir);
+  if (info.isSymbolicLink() || !info.isDirectory()) throw fail('PLUGIN_CANDIDATE_REFUSED', `Not a plain directory: ${dir}`);
+  await chmod(dir, 0o700);
+}
+
+async function writePrivate(file, bytes) {
+  await writeFile(file, bytes, { flag: 'wx', mode: 0o600 });
+  await chmod(file, 0o600);
+}
+
+function commonDirectory(directories) {
+  const split = directories.map(dir => dir.split(path.sep));
+  let length = split[0].length;
+  for (const parts of split) {
+    let i = 0;
+    while (i < length && i < parts.length && parts[i] === split[0][i]) i++;
+    length = i;
+  }
+  const common = split[0].slice(0, length).join(path.sep);
+  if (!common) {
+    if (split[0][0] === '') return path.sep;
+    throw new Error('The plugin files share no common directory');
+  }
+  return common;
+}
+
+// Node resolves bare specifiers from the first node_modules found walking up from the importer.
+async function nearestNodeModules(start) {
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (path.basename(dir) !== 'node_modules') {
+      const candidate = path.join(dir, 'node_modules');
+      try { if ((await stat(candidate)).isDirectory()) return await realpath(candidate); } catch {}
+    }
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+// The `type` of the nearest package.json: it decides whether a .js file is ESM.
+async function packageType(start) {
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    let bytes = null;
+    try { bytes = await boundedRead(path.join(dir, 'package.json')); } catch {}
+    if (bytes) {
+      try { const type = JSON.parse(bytes.toString('utf8')).type; return typeof type === 'string' ? type : null; }
+      catch { return null; }
+    }
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+function requestedModule(cwd, module) {
+  if (typeof module !== 'string' || !module || path.isAbsolute(module) || /^[a-z][a-z0-9+.-]*:/i.test(module)) return module;
+  return path.resolve(cwd, module);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (plainObject(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value ?? null);
+}
+
+/**
+ * SHA-256 over the canonical JSON of what a candidate's trust rests on: its ids, its entry
+ * inside tree, the base it was copied from, and what open placed beside tree.
+ */
+export function candidateSeal(candidate) {
+  const base = candidate?.base ?? {};
+  return sha256(canonical({
+    id: candidate?.id, candidateId: candidate?.candidateId,
+    entry: typeof candidate?.tree === 'string' && typeof candidate?.module === 'string' ? posix(path.relative(candidate.tree, candidate.module)) : null,
+    base: { module: base.module, fingerprint: base.fingerprint, logical: base.logical ?? null, files: base.files, external: base.external ?? null },
+    host_modules: candidate?.host_modules ?? {},
+    node_modules: candidate?.node_modules ?? null, package_json: candidate?.package_json ?? null,
+  }));
+}
+
+// The inspector's fingerprint formula over a list of { path, sha256 }.
+const fingerprintOf = list => sha256(Buffer.from(JSON.stringify(list.map(({ path: file, sha256: hash }) => ({ path: file, sha256: hash })).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0))));
+
+/**
+ * Where each file the inspector covers sits in the plugin's layout: real path → logical path.
+ * They differ only for a file reached through a link (a host module of a placement that links
+ * them): Node loads the real file, and that file's own relative imports resolve from its real
+ * place, while its logical place is where the importer's specifier points.
+ */
+async function logicalPlaces(entry) {
+  const places = new Map([[entry, entry]]), pending = [entry];
+  while (pending.length) {
+    const real = pending.shift(), at = places.get(real);
+    if (!/\.(?:mjs|js|cjs)$/.test(real)) continue;
+    let source;
+    try { source = (await boundedRead(real)).toString('utf8'); } catch { continue; }
+    for (const pattern of PLUGIN_SPECIFIERS) for (const match of source.matchAll(pattern)) {
+      const specifier = match[1];
+      if (!specifier.startsWith('./') && !specifier.startsWith('../')) continue;
+      const clean = specifier.split(/[?#]/)[0], target = path.resolve(path.dirname(real), clean);
+      let resolved; try { resolved = await realpath(target); } catch (error) { if (error.code !== 'ENOENT') throw error; resolved = target; }
+      if (places.has(resolved)) continue;
+      if (places.size >= MAX_CODE_FILES * 2) throw new Error(`The plugin reaches too many local files: ${entry}`);
+      places.set(resolved, path.resolve(path.dirname(at), clean)); pending.push(resolved);
+    }
+  }
+  return places;
+}
+
+// The recorded host links of a placement: relative place in tree → { target, sha256 }.
+function hostModules(place) {
+  const recorded = place?.host_modules ?? {};
+  if (!plainObject(recorded)) throw fail('PLUGIN_CANDIDATE_INVALID', 'host_modules is not an object');
+  const out = new Map();
+  for (const relative of sorted(Object.keys(recorded))) {
+    const item = recorded[relative];
+    if (!relative || relative.split('/').some(part => !part || part === '.' || part === '..') || !plainObject(item) || typeof item.target !== 'string' || !path.isAbsolute(item.target) || typeof item.sha256 !== 'string' || !SHA.test(item.sha256)) {
+      throw fail('PLUGIN_CANDIDATE_INVALID', `Invalid host module record: ${relative}`);
+    }
+    out.set(relative, { target: item.target, sha256: item.sha256 });
+  }
+  return out;
+}
+
+/**
+ * The code fingerprint of a placement (a tree of own files and host links), naming each covered
+ * file by its place in the layout: the same value wherever the placement lives, and the
+ * inspector's own fingerprint for a plugin that reaches nothing through a link. With `strict`,
+ * a covered file that is neither inside tree nor a recorded host module is an escape.
+ */
+async function placementFingerprint(place, { strict = false } = {}) {
+  const inspection = await inspectPluginModule(place.module), tree = await realpath(place.tree);
+  if (strict && !inside(tree, inspection.module)) throw fail('PLUGIN_CANDIDATE_ESCAPES', `The candidate's entry resolves outside its tree: ${inspection.module}`);
+  const origin = path.dirname(inspection.module), targets = new Map([...hostModules(place)].map(([relative, item]) => [item.target, relative]));
+  const list = [];
+  for (const file of inspection.files) {
+    const real = path.resolve(origin, file.path);
+    if (inside(tree, real)) list.push(file);
+    else if (targets.has(real)) list.push({ path: posix(path.relative(origin, path.join(tree, ...targets.get(real).split('/')))), sha256: file.sha256 });
+    else if (strict) throw fail('PLUGIN_CANDIDATE_ESCAPES', `The candidate reaches a file outside its tree: ${file.path}`);
+    else list.push(file);
+  }
+  return fingerprintOf(list);
+}
+
+/**
+ * Open a fresh candidate of the plugin `entry` names: its own files (those inside the directory
+ * of its entry module) are copied, and every other file the inspector covers is linked to the
+ * installed file as a host module. Each keeps its path relative to the deepest common directory
+ * of the covered set, so every relative import resolves inside tree and an untouched candidate
+ * has the original's code fingerprint (base.logical; base.fingerprint is the inspector's own
+ * fingerprint of the base module, which differs only when the base already links host modules).
+ * Returns the candidate with its `seal`, which the caller keeps; candidate.json holds the rest.
+ */
+export async function openCandidate({ cwd = process.cwd(), stateDir, entry } = {}) {
+  if (!entry || typeof entry !== 'object') throw new TypeError('openCandidate requires the plugins.json entry');
+  pluginId(entry.id);
+  const state = stateRoot(cwd, stateDir);
+  const inspection = await inspectPluginModule(requestedModule(cwd, entry.module));
+  const origin = path.dirname(inspection.module);
+  const layout = () => fail('PLUGIN_CANDIDATE_LAYOUT', `The copy of plugin ${entry.id} does not reproduce its code; it likely reaches files through a symbolic link.`);
+  const places = await logicalPlaces(inspection.module);
+  const own = [], host = [], logical = [], directories = [origin];
+  for (const item of inspection.files) {
+    const real = path.resolve(origin, item.path), at = places.get(real);
+    if (!at) throw layout();
+    logical.push({ path: posix(path.relative(origin, at)), sha256: item.sha256 });
+    const mine = at === real && inside(origin, real);
+    // Referenced-but-missing own files count too: a repair may create them, and they must land inside tree.
+    if (!item.sha256) { if (mine) directories.push(path.dirname(real)); continue; }
+    if (mine) own.push({ file: real, sha256: item.sha256 });
+    else {
+      // A file link is a host module at that place; a file reached through a linked DIRECTORY has no
+      // place of its own in the layout (the inspector records it by real path) and cannot be reproduced.
+      if (at !== real && !(await lstat(at).catch(() => null))?.isSymbolicLink()) throw layout();
+      host.push({ at, target: real, sha256: item.sha256 });
+    }
+    directories.push(path.dirname(at));
+  }
+  const common = commonDirectory(directories);
+
+  await mkdir(state, { recursive: true, mode: 0o700 });
+  const base = path.join(state, CANDIDATES);
+  await ownDirectory(base);
+  await ownDirectory(path.join(base, entry.id));
+  const candidateId = randomUUID();
+  const dir = path.join(base, entry.id, candidateId), tree = path.join(dir, 'tree');
+  await mkdir(dir, { mode: 0o700 });
+  try {
+    await chmod(dir, 0o700);
+    await ownDirectory(tree);
+    const parents = async target => { let parent = tree; for (const part of path.relative(tree, path.dirname(target)).split(path.sep).filter(Boolean)) await ownDirectory(parent = path.join(parent, part)); };
+    const byPath = key => (a, b) => a[key] < b[key] ? -1 : a[key] > b[key] ? 1 : 0;
+    const files = {}, hostModulesRecord = {};
+    for (const { file, sha256: expected } of own.sort(byPath('file'))) {
+      const relative = path.relative(common, file);
+      const bytes = await boundedRead(file);
+      if (sha256(bytes) !== expected) throw new Error(`The plugin changed while it was being copied: ${file}`);
+      const target = path.join(tree, relative);
+      await parents(target);
+      await writePrivate(target, bytes);
+      files[posix(relative)] = expected;
+    }
+    // Host modules: linked to the installed file's real path, never copied.
+    for (const { at, target, sha256: expected } of host.sort(byPath('at'))) {
+      const relative = path.relative(common, at), link = path.join(tree, relative);
+      await parents(link);
+      await symlink(target, link, 'file');
+      hostModulesRecord[posix(relative)] = { target, sha256: expected };
+    }
+    // Beside tree, never inside it: the module type and the packages the original resolves.
+    const type = await packageType(origin);
+    const packageJson = `${JSON.stringify(type ? { type } : {})}\n`;
+    await writePrivate(path.join(dir, 'package.json'), packageJson);
+    const modules = await nearestNodeModules(origin);
+    if (modules) await symlink(modules, path.join(dir, 'node_modules'), 'dir');
+
+    const candidate = {
+      id: entry.id, candidateId, dir, tree,
+      module: path.join(tree, path.relative(common, inspection.module)),
+      base: { module: inspection.module, fingerprint: inspection.code_fingerprint, logical: fingerprintOf(logical), files, external: inspection.external },
+      host_modules: hostModulesRecord,
+      node_modules: modules, package_json: sha256(packageJson),
+      created_at: new Date().toISOString(),
+    };
+    // Same layout, same bytes: anything else means the candidate is not the plugin.
+    if (await placementFingerprint(candidate) !== candidate.base.logical) throw layout();
+    await writePrivate(path.join(dir, 'candidate.json'), `${JSON.stringify(candidate, null, 2)}\n`);
+    return { ...candidate, seal: candidateSeal(candidate) };
+  } catch (error) {
+    await rm(dir, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+/** The candidate as candidate.json describes it, only if that metadata hashes to `seal`. */
+export async function readCandidate({ cwd = process.cwd(), stateDir, id, candidateId, seal } = {}) {
+  pluginId(id);
+  if (typeof seal !== 'string' || !SHA.test(seal)) throw fail('PLUGIN_CANDIDATE_SEAL_REQUIRED', 'readCandidate requires the seal openCandidate returned');
+  const unknown = () => fail('PLUGIN_CANDIDATE_UNKNOWN', `Unknown plugin candidate: ${id}/${candidateId}`);
+  if (typeof candidateId !== 'string' || !UUID.test(candidateId)) throw unknown();
+  const dir = path.join(stateRoot(cwd, stateDir), CANDIDATES, id, candidateId);
+  let stored;
+  try { stored = JSON.parse((await boundedRead(path.join(dir, 'candidate.json'))).toString('utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') throw unknown();
+    throw fail('PLUGIN_CANDIDATE_INVALID', `Unreadable plugin candidate ${id}/${candidateId}: ${error.message}`);
+  }
+  if (!plainObject(stored) || typeof stored.tree !== 'string' || typeof stored.module !== 'string' || !plainObject(stored.base)) {
+    throw fail('PLUGIN_CANDIDATE_INVALID', `Plugin candidate ${id}/${candidateId} has an invalid candidate.json`);
+  }
+  // Paths follow where the candidate is found now (the state directory may have moved).
+  const tree = path.join(dir, 'tree');
+  const { seal: ignored, ...metadata } = stored;
+  const candidate = { ...metadata, dir, tree, module: path.join(tree, path.relative(stored.tree, stored.module)) };
+  if (candidateSeal(candidate) !== seal) throw fail('PLUGIN_CANDIDATE_TAMPERED', `Plugin candidate ${id}/${candidateId} does not match its seal`);
+  if (candidate.id !== id || candidate.candidateId !== candidateId || candidate.module === tree || !inside(tree, candidate.module)
+    || typeof candidate.base.module !== 'string' || typeof candidate.base.fingerprint !== 'string' || !plainObject(candidate.base.files)) {
+    throw fail('PLUGIN_CANDIDATE_INVALID', `Plugin candidate ${id}/${candidateId} has an invalid candidate.json`);
+  }
+  hostModules(candidate);
+  return { ...candidate, seal };
+}
+
+function sealed(candidate) {
+  if (!candidate || typeof candidate.tree !== 'string' || typeof candidate.module !== 'string' || !plainObject(candidate.base)) throw new TypeError('A plugin candidate is required');
+  if (candidateSeal(candidate) !== candidate.seal) throw fail('PLUGIN_CANDIDATE_TAMPERED', `Plugin candidate ${candidate.id}/${candidate.candidateId} does not match its seal`);
+}
+
+// Every entry of tree, by lstat. More files than the inspector covers is an escape.
+async function walkTree(tree) {
+  const files = [], links = [], others = [], modules = [], pending = [tree];
+  let entries = 0;
+  while (pending.length) {
+    const dir = pending.pop();
+    for (const name of await readdir(dir)) {
+      const full = path.join(dir, name);
+      if (++entries > MAX_CODE_FILES * 16) throw fail('PLUGIN_CANDIDATE_ESCAPES', `The candidate tree holds too many entries: ${tree}`);
+      const info = await lstat(full);
+      if (name === 'node_modules') modules.push(full);
+      if (info.isSymbolicLink()) links.push(full);
+      else if (info.isDirectory()) pending.push(full);
+      else if (info.isFile()) {
+        files.push(full);
+        if (files.length > MAX_CODE_FILES) throw fail('PLUGIN_CANDIDATE_ESCAPES', `The candidate tree holds more than ${MAX_CODE_FILES} files: ${tree}`);
+      } else others.push(full);
+    }
+  }
+  return { files: sorted(files), links, others, modules };
+}
+
+function isText(bytes) {
+  if (bytes.includes(0)) return false;
+  try { new TextDecoder('utf-8', { fatal: true }).decode(bytes); return true; } catch { return false; }
+}
+
+// Lines keep their '\n', so a missing final newline is a difference like any other.
+function splitLines(text) {
+  if (!text) return [];
+  const parts = text.split('\n'), last = parts.pop();
+  const lines = parts.map(line => `${line}\n`);
+  if (last !== '') lines.push(last);
+  return lines;
+}
+
+// Edit script by longest common subsequence over the lines between the common prefix and suffix.
+function editScript(a, b) {
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length, endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) { endA--; endB--; }
+  const n = endA - start, m = endB - start;
+  if (n * m > DIFF_CELLS) return null;
+  const ops = [];
+  for (let i = 0; i < start; i++) ops.push([' ', a[i]]);
+  const width = m + 1, table = new Uint32Array((n + 1) * width);
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) {
+    table[i * width + j] = a[start + i] === b[start + j] ? table[(i + 1) * width + j + 1] + 1 : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+  }
+  let i = 0, j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && a[start + i] === b[start + j]) { ops.push([' ', a[start + i]]); i++; j++; }
+    else if (j >= m || (i < n && table[(i + 1) * width + j] >= table[i * width + j + 1])) { ops.push(['-', a[start + i]]); i++; }
+    else { ops.push(['+', b[start + j]]); j++; }
+  }
+  for (let k = endA; k < a.length; k++) ops.push([' ', a[k]]);
+  return ops;
+}
+
+// The unified diff of one file, '' when equal, or null when too large to diff.
+function unifiedDiff(relative, before, after) {
+  const header = `${before === null ? '--- /dev/null' : `--- a/${relative}`}\n+++ b/${relative}\n`;
+  const ops = editScript(splitLines(before), splitLines(after));
+  if (!ops) return null;
+  const oldAt = [], newAt = [];
+  let oldLine = 1, newLine = 1;
+  for (const [kind] of ops) { oldAt.push(oldLine); newAt.push(newLine); if (kind !== '+') oldLine++; if (kind !== '-') newLine++; }
+  const changes = ops.flatMap(([kind], index) => kind === ' ' ? [] : [index]);
+  if (!changes.length) return '';
+  let out = header;
+  for (let c = 0; c < changes.length;) {
+    let last = c;
+    while (last + 1 < changes.length && changes[last + 1] - changes[last] - 1 <= 2 * CONTEXT) last++;
+    const from = Math.max(0, changes[c] - CONTEXT), to = Math.min(ops.length - 1, changes[last] + CONTEXT);
+    const slice = ops.slice(from, to + 1);
+    const oldCount = slice.filter(([kind]) => kind !== '+').length, newCount = slice.filter(([kind]) => kind !== '-').length;
+    out += `@@ -${oldCount ? oldAt[from] : oldAt[from] - 1},${oldCount} +${newCount ? newAt[from] : newAt[from] - 1},${newCount} @@\n`;
+    for (const [kind, line] of slice) out += line.endsWith('\n') ? `${kind}${line}` : `${kind}${line}\n\\n`;
+    c = last + 1;
+  }
+  return out;
+}
+
+/**
+ * What the candidate changed against the own files it was copied from: lists by hash, the
+ * candidate's code fingerprint, and a unified diff of the text files (at most 200 KB). Host
+ * modules are links to the installed files, unchanged by construction: listed apart in
+ * `host_modules` with the hash recorded at open, never in the patch.
+ * Every changed or added file without its full text in `patch` is named there with the hash
+ * of the bytes that will load, and listed in `unreviewed`; `review_complete` is true only
+ * when there is none.
+ */
+export async function candidateDiff(candidate) {
+  sealed(candidate);
+  const read = reader();
+  const baseFiles = candidate.base.files;
+  const current = new Map();
+  for (const file of (await walkTree(candidate.tree)).files) {
+    current.set(posix(path.relative(candidate.tree, file)), (await read(file, { nofollow: true })).bytes);
+  }
+  const changed = [], added = [], removed = [];
+  for (const [relative, bytes] of current) {
+    if (!Object.hasOwn(baseFiles, relative)) added.push(relative);
+    else if (sha256(bytes) !== baseFiles[relative]) changed.push(relative);
+  }
+  for (const relative of Object.keys(baseFiles)) if (!current.has(relative)) removed.push(relative);
+  const fingerprint = await placementFingerprint(candidate);
+  const host_modules = [...hostModules(candidate)].map(([file, item]) => ({ file, sha256: item.sha256 }));
+
+  // The originals sit at the same paths relative to base.module as the copies relative to module.
+  const originRoot = path.resolve(path.dirname(candidate.base.module), path.relative(path.dirname(candidate.module), candidate.tree));
+  const sections = [];
+  let size = 0;
+  for (const relative of sorted([...changed, ...added])) {
+    if (size > PATCH_LIMIT) { sections.push({ file: relative, text: null }); continue; }
+    const after = current.get(relative);
+    let before = null;
+    if (Object.hasOwn(baseFiles, relative)) {
+      try { before = (await read(path.join(originRoot, ...relative.split('/')), { limit: MAX_FILE_BYTES })).bytes; }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    let section;
+    if (!isText(after) || (before && !isText(before))) section = { file: relative, text: `Binary or non-UTF-8 file ${relative} sha256 ${sha256(after)}\n`, reason: 'binary' };
+    else {
+      const text = unifiedDiff(relative, before === null ? null : before.toString('utf8'), after.toString('utf8'));
+      section = text === null
+        ? { file: relative, text: `Too large to diff: ${relative} (${splitLines(after.toString('utf8')).length} lines) sha256 ${sha256(after)}\n`, reason: 'too_large_to_diff' }
+        : { file: relative, text };
+    }
+    sections.push(section);
+    size += Buffer.byteLength(section.text);
+  }
+  let patch = '';
+  const unreviewed = [];
+  if (size <= PATCH_LIMIT) {
+    for (const section of sections) { patch += section.text; if (section.reason) unreviewed.push({ file: section.file, reason: section.reason }); }
+  } else {
+    const room = PATCH_LIMIT - Buffer.byteLength(PATCH_MARKER);
+    let used = 0, full = true;
+    for (const section of sections) {
+      const length = section.text === null ? Infinity : Buffer.byteLength(section.text);
+      if (full && used + length <= room) {
+        patch += section.text; used += length;
+        if (section.reason) unreviewed.push({ file: section.file, reason: section.reason });
+        continue;
+      }
+      if (full && section.text !== null) {
+        // The first section that does not fit is cut at a line boundary.
+        const bytes = Buffer.from(section.text).subarray(0, room - used);
+        patch += bytes.subarray(0, bytes.lastIndexOf(10) + 1).toString('utf8');
+      }
+      full = false;
+      unreviewed.push({ file: section.file, reason: 'patch_truncated' });
+    }
+    patch += PATCH_MARKER;
+  }
+  return { changed: sorted(changed), added: sorted(added), removed: sorted(removed), host_modules, fingerprint, patch, review_complete: unreviewed.length === 0, unreviewed };
+}
+
+// What a placement (a candidate, or an overlay built from one) must be. `baseFiles` are the hashes a
+// file is "unchanged" against; `external` the packages the base already imported (null: not asked).
+async function checkPlacement(place, baseFiles, external) {
+  const escapes = message => fail('PLUGIN_CANDIDATE_ESCAPES', message);
+  const root = await lstat(place.tree);
+  if (root.isSymbolicLink() || !root.isDirectory()) throw escapes(`The candidate tree is not a plain directory: ${place.tree}`);
+  const { files, links, others, modules } = await walkTree(place.tree);
+  const name = file => posix(path.relative(place.tree, file));
+  if (others.length) throw escapes(`The candidate tree holds a special file: ${name(others[0])}`);
+  if (modules.length) throw escapes(`The candidate tree holds node_modules: ${name(modules[0])}`);
+  const tree = await realpath(place.tree), read = reader(), hashes = {}, dynamic = [], packages = [];
+  // Exactly the recorded host links, each still pointing at the installed file recorded at open.
+  const host = hostModules(place), linked = new Set();
+  for (const link of links) {
+    const relative = name(link), recorded = host.get(relative);
+    if (!recorded) throw escapes(`The candidate tree holds a symbolic link: ${relative}`);
+    let target = null, real = null;
+    try { target = await readlink(link); real = await realpath(link); } catch {}
+    if (target !== recorded.target || real !== recorded.target) throw escapes(`The link to a host module was changed: ${relative}`);
+    linked.add(relative);
+  }
+  for (const [relative, recorded] of host) {
+    if (!linked.has(relative)) throw escapes(`A host module is no longer the link to the installed file: ${relative}`);
+    let bytes;
+    try { bytes = (await read(recorded.target, { nofollow: true, limit: MAX_FILE_BYTES })).bytes; }
+    catch (error) { if (error.code === 'PLUGIN_CANDIDATE_TOO_LARGE') throw error; throw fail('PLUGIN_CANDIDATE_BASE_MOVED', `A host module can no longer be read as it was when the candidate was opened: ${relative}`); }
+    if (sha256(bytes) !== recorded.sha256) throw fail('PLUGIN_CANDIDATE_BASE_MOVED', `A host module changed since the candidate was opened: ${relative}`);
+  }
+  // Own files: only inside the directory of the entry module. Anything else in tree would be a private
+  // copy of a host module, or code the plugin does not own.
+  const own = posix(path.relative(place.tree, path.dirname(place.module)));
+  const known = external ? new Set(external) : null;
+  for (const file of files) {
+    const relative = name(file);
+    if (own !== '' && !relative.startsWith(`${own}/`)) throw escapes(`A file outside the plugin's own directory (${own}); host modules are linked, never copied, replaced or added: ${relative}`);
+    const { bytes, nlink } = await read(file, { nofollow: true });
+    if (nlink > 1) throw escapes(`The candidate tree holds a hard link: ${relative}`);
+    const hash = hashes[relative] = sha256(bytes);
+    const changed = baseFiles[relative] !== hash;
+    if (path.basename(file) === 'package.json' && changed) throw escapes(`A package.json in the candidate tree is new or changed: ${relative}`);
+    if (!isOpaqueChecked(file)) continue;
+    if (!isText(bytes)) throw fail('PLUGIN_CANDIDATE_OPAQUE', `A code file in the candidate is not valid UTF-8 text: ${relative}`);
+    if (!isCode(file)) continue;
+    const source = bytes.toString('utf8');
+    for (const [pattern, module] of SPECIFIERS) for (const match of source.matchAll(pattern)) {
+      const specifier = match[1];
+      const scheme = /^[a-z][a-z0-9+.-]*:/i.test(specifier) && (module ? !specifier.startsWith('node:') : /^file:/i.test(specifier));
+      if (path.isAbsolute(specifier) || specifier.startsWith('\\') || scheme) {
+        throw escapes(`The candidate names code outside its tree: ${specifier} in ${relative}`);
+      }
+      const local = specifier.startsWith('./') || specifier.startsWith('../');
+      if (local && !inside(tree, path.resolve(path.dirname(path.join(tree, relative)), specifier.split(/[?#]/)[0]))) {
+        throw escapes(`The candidate reaches outside its tree: ${specifier} in ${relative}`);
+      }
+      // A package the base did not import: code outside the fingerprint that review did not see loading before.
+      if (module && changed && known && !local && !/^[a-z][a-z0-9+.-]*:/i.test(specifier) && !known.has(specifier) && !packages.some(item => item.file === relative && item.specifier === specifier)) packages.push({ file: relative, specifier });
+    }
+    if (changed) for (const [construct, pattern] of DYNAMIC) if (pattern.test(source)) dynamic.push({ file: relative, construct });
+  }
+  // What open placed beside tree, exactly.
+  const besideModules = path.join(place.dir, 'node_modules');
+  let beside = null;
+  try { beside = await lstat(besideModules); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (place.node_modules ? !beside?.isSymbolicLink() || await realpath(besideModules).catch(() => null) !== place.node_modules : beside) {
+    throw escapes(`node_modules beside the candidate tree is not the one recorded at open: ${besideModules}`);
+  }
+  let packageJson = null;
+  try { packageJson = (await read(path.join(place.dir, 'package.json'), { nofollow: true, limit: MAX_FILE_BYTES })).bytes; } catch {}
+  if (!packageJson || sha256(packageJson) !== place.package_json) throw escapes(`package.json beside the candidate tree is not the one written at open: ${place.dir}`);
+  // Everything the inspector reaches from the entry: inside tree, or a recorded host module.
+  const fingerprint = await placementFingerprint(place, { strict: true });
+  return { files: hashes, fingerprint, dynamic, packages, host_modules: [...host].map(([file, item]) => ({ file, sha256: item.sha256 })) };
+}
+
+/**
+ * The candidate is contained and legible. Refused (PLUGIN_CANDIDATE_ESCAPES unless noted):
+ * a symbolic link that is not a recorded host module, or a host link that was removed,
+ * retargeted or replaced by a file; a file outside the plugin's own directory; hard links,
+ * special files or node_modules in tree; more files than the inspector covers; a package.json
+ * in tree that is new or changed; a specifier that is absolute, a URL other than node:, or
+ * relative and leaving tree; code that is not valid UTF-8 text (PLUGIN_CANDIDATE_OPAQUE); a
+ * host module whose installed bytes changed since open (PLUGIN_CANDIDATE_BASE_MOVED);
+ * dir/node_modules or dir/package.json not as open left them; any file the inspector reaches
+ * from the entry that is neither inside tree nor a recorded host module. Returns the hash of
+ * every own file, the candidate's code fingerprint, the host modules, and what static
+ * inspection cannot follow in changed files: `dynamic` constructs and `packages` (bare
+ * specifiers the base did not import).
+ */
+export async function verifyCandidate(candidate) {
+  if (!candidate || typeof candidate.tree !== 'string' || typeof candidate.module !== 'string') throw new TypeError('verifyCandidate requires a candidate');
+  if (candidate.module === candidate.tree || !inside(candidate.tree, candidate.module)) throw fail('PLUGIN_CANDIDATE_ESCAPES', `The candidate's entry is outside its tree: ${candidate.module}`);
+  sealed(candidate);
+  return checkPlacement(candidate, candidate.base.files, Array.isArray(candidate.base.external) ? candidate.base.external : []);
+}
+
+/**
+ * An overlay built from a verified candidate (or found from an earlier repair) is that candidate, whole:
+ * the same own files byte for byte and no other, exactly its host links, the same package.json and
+ * node_modules link beside tree, and the same code fingerprint. Throws PLUGIN_PLACEMENT_MISMATCH otherwise.
+ * place: { dir, tree, module, host_modules, node_modules, package_json }; expected: { files, fingerprint }.
+ */
+export async function verifyPlacement(place, expected) {
+  const mismatch = message => fail('PLUGIN_PLACEMENT_MISMATCH', message);
+  let checked;
+  try {
+    if (!place || typeof place.tree !== 'string' || typeof place.module !== 'string' || place.module === place.tree || !inside(place.tree, place.module)) throw new Error('the entry is outside the tree');
+    checked = await checkPlacement(place, expected.files, null);
+  } catch (error) { throw mismatch(error.message); }
+  for (const relative of sorted(new Set([...Object.keys(expected.files), ...Object.keys(checked.files)]))) {
+    if (checked.files[relative] !== expected.files[relative]) throw mismatch(`${relative} ${Object.hasOwn(checked.files, relative) ? Object.hasOwn(expected.files, relative) ? 'differs' : 'was not verified' : 'is missing'}`);
+  }
+  if (checked.fingerprint !== expected.fingerprint) throw mismatch(`fingerprint ${checked.fingerprint} instead of ${expected.fingerprint}`);
+  return checked;
+}
+
+/**
+ * Remove a candidate directory. Only <stateDir>/plugin-candidates/<id>/<uuid>, reached
+ * without symbolic links below plugin-candidates, is ever removed, by its verified real path.
+ */
+export async function discardCandidate(candidate, { cwd = process.cwd(), stateDir } = {}) {
+  const refuse = message => fail('PLUGIN_CANDIDATE_REFUSED', message);
+  if (!candidate || typeof candidate.dir !== 'string') throw refuse('discardCandidate requires a candidate with its dir');
+  try { pluginId(candidate.id); } catch { throw refuse(`Invalid plugin id: ${candidate.id}`); }
+  if (typeof candidate.candidateId !== 'string' || !UUID.test(candidate.candidateId)) throw refuse(`Invalid candidate id: ${candidate.candidateId}`);
+  const base = path.join(stateRoot(cwd, stateDir), CANDIDATES);
+  const expected = path.join(base, candidate.id, candidate.candidateId);
+  const outside = () => refuse(`Not a candidate directory under ${base}: ${candidate.dir}`);
+  let real;
+  try { real = await realpath(candidate.dir); }
+  catch (error) {
+    if (error.code === 'ENOENT' && path.resolve(candidate.dir) === expected) return;   // already gone
+    throw outside();
+  }
+  for (const dir of [base, path.dirname(expected), expected]) {
+    let info;
+    try { info = await lstat(dir); } catch { throw outside(); }
+    if (info.isSymbolicLink() || !info.isDirectory()) throw refuse(`A symbolic link or non-directory on the way to the candidate: ${dir}`);
+  }
+  const target = path.join(await realpath(base), candidate.id, candidate.candidateId);
+  if (real !== target) throw outside();
+  // Once more, on the very path about to be removed.
+  const final = await lstat(target);
+  if (final.isSymbolicLink() || !final.isDirectory() || await realpath(target) !== target) throw outside();
+  await rm(target, { recursive: true });
+  await rmdir(path.dirname(target)).catch(() => {});   // the plugin's folder, once it holds no candidates
+}