@factoidal/core 0.20.0 → 0.22.0

package/lib/nodes.mjs

@@ -38,6 +38,22 @@
 // {"$nquads": its N-Quads text}. With an older engine, records carry no
 // settings and the evaluator's output wire is the registry's.
 //
+// Graphs (https://github.com/danbri/factoidal/issues/1130, stage 1b):
+// graph({inputs, nodes}) is a pipeline whose nodes read named input ports,
+// each port from a graph input or from the output of an earlier node, so a
+// node can read two values (datasetMerge) and one value can feed two nodes.
+// The engine decides the check (op graphCheckNodes, formal/lean4/Wasm/Ops/
+// GraphNodes.lean, computed by graphIssues of formal/lean4/L4Factoidal/
+// Dataflow/Graph.lean): unknown graph inputs, references to the node itself
+// or to a later node, the number of sources per node, and the wires. graph()
+// refuses a graph with an issue. The engine also gives each node's ports and
+// output wire, the union of the named assumptions (the premises of
+// Graph.guarantee_sound) and the stages with more than one port (node()
+// reads a port stage such as datasetMerge from that op, as stageList has one
+// input wire per stage). PORT_RUNNERS binds a port stage to the package
+// function that runs it; tools/runners-gate.py checks it against the Lean
+// list portStageNames. This file makes no RDF decision and no graph check.
+//
 // ES module, no Node built-ins: the browser loads this file as it is.
 
 import { FactoidalError } from './errors.mjs';
@@ -49,7 +65,8 @@ import { refusalFor, makeRecord, summarize, unionAssumptions, unionLists } from
  */
 export function buildNodes(deps) {
   const { entry, entryResult, requireEntryFn, Dataset,
-    parse, closure, shaclValidate, query, serialize, canonicalize, canonicalHash, explain, csvwToRdf } = deps;
+    parse, closure, shaclValidate, query, serialize, canonicalize, canonicalHash, explain, csvwToRdf,
+    datasetMerge } = deps;
 
   const reader = (format) => async (wire, params) => {
     if (typeof wire.graph !== 'string') {
@@ -109,12 +126,12 @@ export function buildNodes(deps) {
     // String × String: the canonical N-Quads text and its SHA-256 hex
     // (RdfcContract, Dataflow/PhaseE.lean). canonicalHash is the SHA-256 of
     // the text canonicalize answers (op datasetCanonicalHash).
+    // The input is a Dataset or text (a string or {text, format, baseIRI}:
+    // characters, not bytes; the settings `format` and `baseIRI` read it).
     rdfcStage: async (wire, params) => {
-      if (!(wire.graph instanceof Dataset)) {
-        throw new TypeError(`node rdfcStage: the stage takes a Dataset on its wire (got ${describe(wire.graph)})`);
-      }
+      const isDataset = wire.graph instanceof Dataset;
       const canonical = await canonicalize(wire.graph, params);
-      const sha256 = await canonicalHash(wire.graph);
+      const sha256 = await canonicalHash(wire.graph, isDataset && Object.keys(params).length === 0 ? undefined : params);
       return { graph: [canonical, sha256], artefact: { canonical, sha256 } };
     },
     'CSVW (tabular data to RDF)': async (wire, params) => {
@@ -135,6 +152,23 @@ export function buildNodes(deps) {
     },
   };
 
+  // Port stage name (the Lean list portStageNames, formal/lean4/Wasm/Ops/
+  // GraphNodes.lean) -> the package function that runs it. A runner of a
+  // stage with more than one port gets the values of its ports, in port
+  // order, as the array `wire.graph`.
+  const PORT_RUNNERS = {
+    // RDF 1.1 Semantics section 5.2 merge: the blank nodes of the two
+    // inputs are kept apart (op datasetMerge, theorem mergeDatasets_isMerge).
+    datasetMerge: async (wire) => {
+      const [left, right] = wire.graph;
+      return { graph: await datasetMerge(left, right), artefact: { ports: ['left', 'right'] } };
+    },
+  };
+
+  const hasRunner = (n) => Object.prototype.hasOwnProperty.call(n.ports && n.ports.length > 1
+    ? PORT_RUNNERS : RUNNERS, n.stage);
+  const runnerOf = (n) => (n.ports && n.ports.length > 1 ? PORT_RUNNERS : RUNNERS)[n.stage];
+
   // Whether `value` represents the wire type `wire` (a wire name of the
   // engine's registry, Dataflow/Wire.lean) in this package: a Dataset for the
   // graph wires, text for String, and so on. A wire this table does not name
@@ -232,6 +266,29 @@ export function buildNodes(deps) {
   }
 
   const hasNodeCheck = () => !!engine && typeof engine.pipelineCheckNodes === 'function';
+  const hasGraphCheck = () => !!engine && typeof engine.graphCheckNodes === 'function';
+
+  // The engine's check of a graph request (op graphCheckNodes).
+  function graphCheck(inputs, items) {
+    return entryResult(engine.graphCheckNodes(JSON.stringify({
+      inputs,
+      nodes: items.map((it) => ({ stage: it.node.stage, settings: it.node.settingsWire, from: it.from })),
+    })), 'graph');
+  }
+
+  // A node of a port stage (a stage with more than one input port), read
+  // from the engine's answer for a graph of that one node; null when the
+  // engine has no op graphCheckNodes or no port stage of this name. The
+  // answer's portCount issue (the probe gives no source) is not read.
+  function portNodeInfo(name, settingsWire) {
+    if (!hasGraphCheck()) return null;
+    const r = JSON.parse(engine.graphCheckNodes(JSON.stringify({
+      inputs: [], nodes: [{ stage: name, settings: settingsWire, from: [] }],
+    })));
+    if (!r.ok || !Array.isArray(r.nodes) || r.nodes.length !== 1) return null;
+    const s = r.nodes[0];
+    return s.ports.length > 1 ? s : null;
+  }
 
   // The engine's check of nodes with settings (op pipelineCheckNodes).
   function nodeCheck(items) {
@@ -253,14 +310,38 @@ export function buildNodes(deps) {
       throw new TypeError('node: params must be an object');
     }
     const info = (await stages()).find((s) => s.name === name);
-    if (!info) {
-      throw new FactoidalError(`node: no registered stage named '${name}' (see stages())`,
-        { code: 'option.invalid-value' });
-    }
     // The copy first, then its wire form: the engine checks and digests
     // exactly the settings the node keeps.
     const own = snapshot({ ...(params || {}) });
     const settingsWire = snapshot(marshal(own, 'params'));
+    if (!info) {
+      const p = portNodeInfo(name, settingsWire);
+      if (!p) {
+        throw new FactoidalError(`node: no registered stage named '${name}' (see stages(); ` +
+          'an engine with the op graphCheckNodes also has the stages with more than one port)',
+        { code: 'option.invalid-value' });
+      }
+      return Object.freeze({
+        [NODE]: true,
+        stage: p.name,
+        kind: p.kind,
+        status: p.status,
+        registryStatus: p.registryStatus,
+        contract: p.contract,
+        assumptions: Object.freeze([...p.assumptions]),
+        ports: Object.freeze(p.ports.map((x) => Object.freeze({ ...x }))),
+        wireIn: null,
+        wireOut: p.wireOut,
+        runnable: p.status !== 'missing',
+        bound: Object.prototype.hasOwnProperty.call(PORT_RUNNERS, p.name),
+        params: own,
+        settingsWire,
+        settings: p.settings,
+        settingsDigest: p.settingsDigest,
+        outside: Object.freeze(p.outside.map((o) => Object.freeze({ ...o }))),
+        derived: Object.freeze({ ...p.derived }),
+      });
+    }
     // The engine's reading of the settings, when it has the op.
     let s = null;
     if (hasNodeCheck()) s = nodeCheck([{ stage: info.name, settingsWire }]).stages[0];
@@ -272,6 +353,7 @@ export function buildNodes(deps) {
       registryStatus: info.status,
       contract: info.contract,
       assumptions: info.assumptions,
+      ports: Object.freeze([Object.freeze({ name: 'in', wire: info.wireIn })]),
       wireIn: info.wireIn,
       wireOut: s ? s.wireOut : info.wireOut,
       runnable: info.runnable,
@@ -288,6 +370,10 @@ export function buildNodes(deps) {
   function nodesOf(items, who) {
     const out = [];
     for (const n of items) {
+      if (n && n[NODE] && n.ports && n.ports.length > 1) {
+        throw new TypeError(`${who}: node ${n.stage} has ${n.ports.length} input ports ` +
+          `(${n.ports.map((x) => x.name).join(', ')}); a list pipeline gives each node one input; use graph()`);
+      }
       if (n && n[NODE]) out.push(n);
       else if (n && Array.isArray(n.nodes)) out.push(...nodesOf(n.nodes, who));
       else throw new TypeError(`${who}: expected nodes from node() or pipelines from pipe()`);
@@ -363,9 +449,10 @@ export function buildNodes(deps) {
       throw new TypeError('run: options must be an object');
     }
     const unchecked = !!(options && options.unchecked);
+    if (pipeline && pipeline[GRAPH]) return runGraph(pipeline, input, unchecked);
     const nodes = nodesOf([pipeline], 'run');
     for (const n of nodes) {
-      const why = refusalFor(n, unchecked, Object.prototype.hasOwnProperty.call(RUNNERS, n.stage));
+      const why = refusalFor(n, unchecked, hasRunner(n));
       if (why) throw why;
       assertSettingsUnchanged(n);
     }
@@ -414,5 +501,141 @@ export function buildNodes(deps) {
     };
   }
 
-  return { stages, node, pipe, run };
+  const GRAPH = Symbol('factoidal.graph');
+
+  // The text of one issue of the engine's check (op graphCheckNodes).
+  function issueText(x) {
+    switch (x.kind) {
+      case 'unknownInput':
+        return `node ${x.node} port ${x.port} (${x.portName}) reads graph input ${x.input}, which does not exist`;
+      case 'forwardRef':
+        return `node ${x.node} port ${x.port} (${x.portName}) reads node ${x.ref}, which is not before it ` +
+          '(a cycle or a forward reference)';
+      case 'portCount':
+        return `node ${x.node} has ${x.ports} input ports and ${x.sources} sources`;
+      case 'wireMismatch':
+        return `node ${x.node} port ${x.port} (${x.portName}) reads ${x.portWire}, its source writes ${x.source}`;
+      default:
+        return JSON.stringify(x);
+    }
+  }
+
+  /**
+   * A graph: nodes with named input ports (https://github.com/danbri/factoidal/issues/1130).
+   * `spec.inputs`: the wire of each graph input (a wire label, e.g. 'String';
+   * see stages() wireIn/wireOut). `spec.nodes`: in order, `{ node, from }`,
+   * where `node` comes from node() and `from` has one source per input port of
+   * the node: `{ input: k }` (graph input k) or `{ node: j }` (the output of
+   * node j, which must come before it). The engine's op graphCheckNodes checks
+   * the graph; a graph with an issue is refused (FactoidalError code
+   * op.failed, `err.issues` the engine's list). An engine without the op is
+   * refused with code op.unknown. The last node's output is the graph's output.
+   * @param {{inputs?: string[], nodes: Array<{node: object, from: object[]}>}} spec
+   * @returns {object}
+   */
+  function graph(spec) {
+    if (spec === null || typeof spec !== 'object') throw new TypeError('graph: spec must be an object');
+    const inputs = spec.inputs === undefined ? [] : spec.inputs;
+    if (!Array.isArray(inputs) || !inputs.every((w) => typeof w === 'string')) {
+      throw new TypeError('graph: spec.inputs must be an array of wire labels (strings)');
+    }
+    if (!Array.isArray(spec.nodes) || spec.nodes.length === 0) {
+      throw new TypeError('graph: spec.nodes must be a non-empty array');
+    }
+    const items = spec.nodes.map((it, i) => {
+      if (!it || typeof it !== 'object' || !it.node || !it.node[NODE]) {
+        throw new TypeError(`graph: spec.nodes[${i}].node must be a node from node()`);
+      }
+      if (!Array.isArray(it.from)) throw new TypeError(`graph: spec.nodes[${i}].from must be an array`);
+      return Object.freeze({ node: it.node, from: snapshot(marshal(it.from, `nodes[${i}].from`)) });
+    });
+    requireEntryFn(engine || {}, 'graphCheckNodes', 'graph');
+    const r = graphCheck(inputs, items);
+    if (r.issues.length > 0) {
+      const err = new FactoidalError(`graph: the engine's check (op graphCheckNodes) found ` +
+        `${r.issues.length} issue${r.issues.length === 1 ? '' : 's'}: ${r.issues.map(issueText).join('; ')}`,
+      { code: 'op.failed' });
+      err.issues = Object.freeze(r.issues.map((x) => Object.freeze({ ...x })));
+      throw err;
+    }
+    const check = Object.freeze({
+      issues: Object.freeze([]),
+      wireOut: r.wireOut,
+      assumptions: Object.freeze([...r.assumptions]),
+      contract: Object.freeze({ ...r.contract }),
+      nodes: Object.freeze(r.nodes.map((s) => Object.freeze({
+        ...s,
+        theorems: Object.freeze([...s.theorems]),
+        assumptions: Object.freeze([...s.assumptions]),
+        ports: Object.freeze(s.ports.map((x) => Object.freeze({ ...x }))),
+        outside: Object.freeze(s.outside.map((o) => Object.freeze({ ...o }))),
+      }))),
+    });
+    return Object.freeze({
+      [GRAPH]: true,
+      inputs: Object.freeze([...inputs]),
+      nodes: Object.freeze(items),
+      wireOut: r.wireOut,
+      assumptions: check.assumptions,
+      check,
+    });
+  }
+
+  // run() of a graph: the nodes in order, each on the values of its sources.
+  async function runGraph(g, inputs, unchecked) {
+    if (!Array.isArray(inputs)) {
+      throw new TypeError('run: the input of a graph is an array, one value per graph input');
+    }
+    if (inputs.length !== g.inputs.length) {
+      throw new TypeError(`run: the graph has ${g.inputs.length} inputs, got ${inputs.length} values`);
+    }
+    for (const it of g.nodes) {
+      const why = refusalFor(it.node, unchecked, hasRunner(it.node));
+      if (why) throw why;
+      assertSettingsUnchanged(it.node);
+    }
+    // A graph input given as a wire value {graph, evidence} keeps its records.
+    const prior = [];
+    const inputValues = inputs.map((x, k) => {
+      const v = isWire(x) ? x.graph : x;
+      if (isWire(x)) prior.push(...x.evidence);
+      if (!wireHolds(g.inputs[k], v)) {
+        throw new FactoidalError(`run: graph input ${k} is declared ${g.inputs[k]}, got ${describe(v)}`,
+          { code: 'op.failed' });
+      }
+      return v;
+    });
+    const values = [];
+    const records = [];
+    for (let i = 0; i < g.nodes.length; i++) {
+      const { node: n, from } = g.nodes[i];
+      // graph() refused every graph whose sources are not all before the node.
+      const vals = from.map((src) => (Object.prototype.hasOwnProperty.call(src, 'input')
+        ? inputValues[src.input] : values[src.node]));
+      const wire = { graph: n.ports.length > 1 ? vals : vals[0], evidence: [] };
+      const out = await runnerOf(n)(wire, n.params);
+      const value = out.graph;
+      const wireOut = g.check.nodes[i].wireOut;
+      if (!wireHolds(wireOut, value)) {
+        throw new FactoidalError(`run: node ${i} (${n.stage}) declares the output wire ${wireOut} ` +
+          `but its runner gave ${describe(value)}`, { code: 'op.failed' });
+      }
+      values.push(value);
+      records.push(Object.freeze({ ...makeRecord(n, out.artefact, unchecked), node: i, from }));
+    }
+    const s = summarize(records);
+    return {
+      graph: values[values.length - 1],
+      values,
+      evidence: [...prior, ...records],
+      assumptions: prior.length === 0 ? [...g.check.assumptions]
+        : unionLists([unionAssumptions(prior), g.check.assumptions]),
+      proved: s.proved && summarize(prior).proved,
+      uncheckedSteps: [...summarize(prior).uncheckedSteps, ...s.uncheckedSteps],
+      wellTyped: true,
+      issues: [],
+    };
+  }
+
+  return { stages, node, pipe, graph, run };
 }

package/lib/sbm11.mjs

@@ -121,13 +121,22 @@ export function sbm11Api (loadEngine) {
    * it decodes against the manifest's Merkle roots, and refuses a changed
    * file with its name) or 'none' (lengths only). The engine decides; this
    * file passes the string.
+   *
+   * `options.manifestSha256`: the trust anchor, the SHA-256 of the bytes of
+   * `manifest.sbm11` as 64 hex digits (https://github.com/danbri/factoidal/issues/1105).
+   * The engine computes the digest and refuses the open when it differs;
+   * the error names manifest.sbm11 and both digests. `store.manifestSha256`
+   * is the digest the engine computed, so that a caller can pin it.
    */
   async function openSbm11 (source, options = {}) {
     installBridge()
     if (options.reader) registerSbm11Source(source, options.reader)
     const eng = await loadEngine()
     const openArgs = [String(source)]
-    if (options.verify != null) openArgs.push(JSON.stringify({ verify: String(options.verify) }))
+    const o = {}
+    if (options.verify != null) o.verify = String(options.verify)
+    if (options.manifestSha256 != null) o.manifestSha256 = String(options.manifestSha256)
+    if (Object.keys(o).length > 0) openArgs.push(JSON.stringify(o))
     const opened = envelope(eng.call('sbm11Open', openArgs))
     const handle = opened.handle
     let open = true
@@ -145,6 +154,10 @@ export function sbm11Api (loadEngine) {
       /** how the engine checks reads: 'merkle' or 'none' (undefined from a
        *  wasm module built before the check) */
       verify: opened.verify,
+      /** the SHA-256 of the bytes of manifest.sbm11 (64 lowercase hex
+       *  digits), as the engine computed it at open; undefined from a wasm
+       *  module built before the trust anchor (issue 1105) */
+      manifestSha256: opened.manifestSha256,
       query (sparql, qopts = {}) {
         if (!open) throw new Error('sbm11: the store is closed')
         const o = {}

package/lib/version.mjs

@@ -2,4 +2,4 @@
 // needs import attributes, which not every runtime this package targets
 // reads). test/dts-drift.test.js checks that it equals package.json's
 // `version`.
-export const version = '0.20.0';
+export const version = '0.22.0';

package/lws/README.md

@@ -175,6 +175,15 @@ factoidal lws-serve /tmp/dev --port 3000 --insecure-no-auth
 One of `--issuer`, `--auth-config FILE` or `--insecure-no-auth` is
 required.
 
+With `--insecure-no-auth` every request is served, so the storage answers
+only its own host names (421 for any other `Host`: DNS rebinding), refuses a
+write from another origin (403: a cross-site form or `fetch`), and sends no
+CORS fields unless `--cors-origin ORIGIN` names a page. `--allow-host NAME`
+and `--allow-origin ORIGIN` add names and origins (a reverse proxy, a
+Tailscale name). The engine decides all of this
+(`L4Factoidal/HTTP/LocalGuard.lean`,
+https://github.com/danbri/factoidal/issues/1124).
+
 `--port 0` takes an ephemeral port and the command prints the one it got;
 `--base IRI` sets `baseIri`, which defaults to the bound origin. `DIR`
 names the storage directory, but the first slice keeps the resource tree

package/lws/client.mjs

@@ -148,6 +148,12 @@ export async function lwsClientOpsAvailable (engine) {
  * @param {string} [options.idToken] an OpenID Connect ID Token to exchange
  * @param {object} [options.bearer] `{ token, realm? }`: an access token the
  *   caller already has; with a realm it is sent only under it
+ * @param {boolean} [options.legacyChallenge] follow the 401 challenge
+ *   `Bearer as_uri="…", realm="…"` of the drafts before 2026-10-19 (default
+ *   false: it skips two of the discovery checks of lws10-core)
+ * @param {boolean} [options.requireHttps] send no request to a URL whose
+ *   scheme is not https, in any phase; such an operation fails with code
+ *   `insecureTransport` (default false; the engine decides)
  * @param {object} [options.session] a session from an earlier client
  * @param {number} [options.maxSteps] the loop cap of one operation
  * @returns {Promise<object>} the client
@@ -168,6 +174,11 @@ export async function createLwsClient (options = {}) {
   // Read by the engine's session reader (`Machine.sessionOfJson`), unread here.
   if (options.idToken !== undefined) session.idToken = options.idToken
   if (options.bearer !== undefined) session.bearer = options.bearer
+  // Follow the `Bearer as_uri, realm` challenge of the drafts before
+  // 2026-10-19 (`Machine.on401`); the engine decides, off by default.
+  if (options.legacyChallenge === true) session.legacyChallenge = true
+  // Refuse every request to a URL that is not https (`Machine.enforce`).
+  if (options.requireHttps === true) session.requireHttps = true
 
   function call (op, args) {
     try {
@@ -248,7 +259,9 @@ export async function createLwsClient (options = {}) {
     head: with_('head'),
     /** `create(containerUrl, { body, mediaType, slug, container, types, links })` */
     create: with_('create'),
-    /** `update(url, { body, mediaType, precondition, tag, retry412, links })` */
+    /** `update(url, { body, mediaType, precondition, tag, ifNoneMatchTags, retry412, links })`;
+     *  `ifNoneMatchTags` (entity tags, or field values of them) sends
+     *  `If-None-Match`, alone or with the `If-Match` of `precondition` */
     update: with_('update'),
     patch: with_('patch'),
     /** `delete(url, { recursive, precondition, tag })` */
@@ -267,10 +280,14 @@ export async function createLwsClient (options = {}) {
      *  the service endpoint, `{ onePage: true }` for one page */
     search: with_('search'),
     queryFormats: with_('queryFormats'),
-    /** `subscribe(url, { topics, inbox, expires })` */
+    /** `subscribe(url, { topics, inbox, expires })`, or with `{ endpoint }`
+     *  when the caller has the notification service endpoint: the
+     *  subscription is POSTed to it with no discovery */
     subscribe: with_('subscribe'),
     getSubscription: with_('getSubscription'),
     unsubscribe: with_('unsubscribe'),
+    /** `requestAccess(url, { policies: [{ actions, assignee, targets, constraint }], inbox })`,
+     *  or one policy as `{ actions, assignee, targets, constraint }` */
     requestAccess: with_('requestAccess'),
     grantAccess: with_('grantAccess'),
     getAccess: with_('getAccess'),

package/lws/persist.mjs

@@ -9,6 +9,8 @@
 // This file decides only where the one file lives and how it is written:
 //
 //   DIR/lws-state.json      the snapshot, replaced atomically
+//   DIR/lws.lock            the lock of the one writing process (named by
+//                           the engine, issue 1135; see the end of this file)
 //
 // No request target ever becomes a file name here, so a request cannot
 // address a file outside DIR.
@@ -26,6 +28,7 @@
 
 import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, existsSync } from 'node:fs'
 import { dirname, join, resolve, sep } from 'node:path'
+import { hostname } from 'node:os'
 
 export const STATE_FILE = 'lws-state.json'
 
@@ -323,3 +326,169 @@ export function persistFilesIfChanged (engine, handle, envelope, dir) {
   const answered = engine.callBlobIO('lwsPersist', [handle, JSON.stringify({ seed: seedBase64() })], new Uint8Array(0))
   performPlan(dir, answered.envelope.plan, answered.bytes)
 }
+
+// ---------------------------------------------------------------------------
+// ONE WRITING PROCESS PER STORAGE DIRECTORY
+// (https://github.com/danbri/factoidal/issues/1135)
+//
+// The engine decides the lock file name, its contents and what a start does
+// (`lwsDirLock`, formal/lean4/L4Factoidal/LWS/DirLock.lean). This host does
+// three things only: the exclusive create of the file it names (flag `wx`,
+// O_EXCL), the liveness probe of a process id it names (`kill(pid, 0)`), and
+// the removal of the file at a clean exit. Each result goes back to the
+// engine as data.
+
+/** Random text of this process, drawn once: it tells a lock this process
+ *  wrote from the lock of an earlier process with the same process id. */
+let processToken = null
+function processTokenText () {
+  if (processToken === null) {
+    const bytes = new Uint8Array(18)
+    globalThis.crypto.getRandomValues(bytes)
+    let text = ''
+    for (const b of bytes) text += String.fromCharCode(b)
+    processToken = btoa(text)
+  }
+  return processToken
+}
+
+/** The lock files this process holds: absolute path -> contents. */
+const heldLocks = new Map()
+let exitHookSet = false
+
+/** Remove a lock file this process holds, when it still holds this
+ *  process's contents. Pure I/O. */
+function removeHeldLock (file) {
+  if (!heldLocks.has(file)) return
+  const contents = heldLocks.get(file)
+  heldLocks.delete(file)
+  try {
+    if (readFileSync(file, 'utf8') === contents) unlinkSync(file)
+  } catch (_error) {
+    // Already gone, or not readable: nothing to remove.
+  }
+}
+
+/** At process exit (normal end, `process.exit`, and after a SIGINT or
+ *  SIGTERM handler ends the process), remove every lock still held. */
+function ensureExitHook () {
+  if (exitHookSet || globalThis.process === undefined || typeof globalThis.process.on !== 'function') return
+  exitHookSet = true
+  globalThis.process.on('exit', () => {
+    for (const file of [...heldLocks.keys()]) removeHeldLock(file)
+  })
+}
+
+/** Is process `pid` alive on this host? Pure I/O: `kill(pid, 0)`; EPERM
+ *  means it exists under another user. */
+function processAlive (pid) {
+  try {
+    globalThis.process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error !== null && typeof error === 'object' && error.code === 'EPERM'
+  }
+}
+
+/** Create `file` with O_EXCL and write `contents`; false when it exists. */
+function createExclusive (file, contents) {
+  let fd
+  try {
+    fd = openSync(file, 'wx', 0o600)
+  } catch (error) {
+    if (error.code === 'EEXIST') return false
+    throw error
+  }
+  try {
+    writeSync(fd, contents)
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  return true
+}
+
+/** An error that stops a start because another process holds the storage
+ *  directory. `envelope` carries the engine's message, as for every other
+ *  refusal of a start. */
+export class StorageLockedError extends Error {
+  constructor (message) {
+    super(message)
+    this.name = 'StorageLockedError'
+    this.envelope = { ok: false, error: message }
+  }
+}
+
+/**
+ * Take the lock of storage directory `dir` for `command` (`lws-serve`,
+ * `solid-serve`, `webdav-serve`). Returns `{ file, warning, release }`:
+ * `warning` is the engine's text when it took over a stale lock, else null;
+ * `release()` removes the lock. Throws `StorageLockedError` with the
+ * engine's message when the engine refuses.
+ */
+export function acquireDirLock (engine, dir, command) {
+  const root = resolve(dir)
+  mkdirSync(root, { recursive: true })
+  const base = {
+    dir: root,
+    pid: globalThis.process.pid,
+    command,
+    started: new Date().toISOString(),
+    host: hostname(),
+    token: processTokenText()
+  }
+  let request = { ...base }
+  // Each round is one engine answer; a create that loses to another start
+  // reads the file again and asks again.
+  for (let round = 0; round < 8; round += 1) {
+    const told = engine.call('lwsDirLock', [JSON.stringify(request)])
+    if (told === null || typeof told !== 'object' || told.ok === false) {
+      throw Object.assign(new Error(`lwsDirLock: ${told && told.error ? told.error : 'no answer'}`), { envelope: told })
+    }
+    switch (told.action) {
+      case 'create':
+      case 'replace': {
+        const file = insideDir(root, told.file)
+        if (told.action === 'replace') {
+          try { unlinkSync(file) } catch (error) { if (error.code !== 'ENOENT') throw error }
+        }
+        if (createExclusive(file, told.contents)) {
+          heldLocks.set(file, told.contents)
+          ensureExitHook()
+          return {
+            file,
+            warning: told.action === 'replace' ? told.warning : null,
+            release: () => removeHeldLock(file)
+          }
+        }
+        let present = null
+        try { present = readFileSync(file, 'utf8') } catch (error) { if (error.code !== 'ENOENT') throw error }
+        request = present === null ? { ...base } : { ...base, present }
+        break
+      }
+      case 'probe':
+        request = { ...request, alive: processAlive(Number(told.pid)) }
+        break
+      case 'refuse':
+        throw new StorageLockedError(told.message)
+      default:
+        throw new Error(`lwsDirLock answered an unknown action ${String(told.action)}`)
+    }
+  }
+  throw new Error('lwsDirLock: the lock file changed on every attempt')
+}
+
+/**
+ * The start notice about encryption at rest of the storage in `dir`
+ * (`lwsAtRestNotice`): `{ sealed, keyId?, notice }`. The key text is passed
+ * unread; the engine checks it.
+ */
+export function atRestNotice (engine, dir, storageKey) {
+  const request = { dir: resolve(dir) }
+  if (typeof storageKey === 'string') request.storageKey = storageKey
+  const told = engine.call('lwsAtRestNotice', [JSON.stringify(request)])
+  if (told === null || typeof told !== 'object' || told.ok === false) {
+    throw Object.assign(new Error(`lwsAtRestNotice: ${told && told.error ? told.error : 'no answer'}`), { envelope: told })
+  }
+  return told
+}