@factoidal/core 0.19.0 → 0.21.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, 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') {
@@ -62,13 +79,18 @@ export function buildNodes(deps) {
     graph: await closure(wire.graph, regime, params),
     artefact: { regime },
   });
-  const writer = (format) => async (wire, params) => ({
-    artefact: { format, text: await serialize(wire.graph, { ...params, format }) },
-  });
+  // A writer's output wire is String: the text goes on the wire, so the next
+  // node (a reader, say) reads it. Before 0.20.0 the input Dataset stayed on
+  // the wire and only the artefact held the text.
+  const writer = (format) => async (wire, params) => {
+    const text = await serialize(wire.graph, { ...params, format });
+    return { graph: text, artefact: { format, text } };
+  };
 
   // Stage name (stageList `name`) -> the package function that runs it.
-  // A runner answers `{ graph?, artefact }`; no `graph` passes the input
-  // graph on unchanged.
+  // A runner answers `{ graph, artefact }`: `graph` is the value of the
+  // node's output wire (FactoidalNode.wireOut, the engine's), which run()
+  // checks (wireHolds); `artefact` goes in the evidence record.
   const RUNNERS = {
     ntriplesDocumentReader: reader('ntriples'),
     nquadsDocumentReader: reader('nquads'),
@@ -83,23 +105,35 @@ export function buildNodes(deps) {
       const { shapes, ...opts } = params;
       if (shapes === undefined) throw new TypeError('node shaclValidator: params.shapes is required');
       const r = await shaclValidate(wire.graph, shapes, opts);
-      return { artefact: { conforms: r.conforms, report: r.report } };
+      const report = { conforms: r.conforms, report: r.report };
+      return { graph: report, artefact: report };
     },
+    // SELECT gives a Table (the rows), ASK an Answer (a boolean), CONSTRUCT
+    // and DESCRIBE a Dataset: the engine picks the wire from the query form
+    // (op pipelineCheckNodes), and the value here follows it.
     shippedEvaluator: async (wire, params) => {
       const { query: sparql, ...opts } = params;
       if (typeof sparql !== 'string') throw new TypeError('node shippedEvaluator: params.query must be a string');
       const answer = await query(wire.graph, sparql, opts);
       return answer instanceof Dataset ? { graph: answer, artefact: { form: 'graph' } }
-        : { artefact: { answer } };
+        : { graph: answer, artefact: { answer } };
     },
     ntriplesDocumentWriter: writer('ntriples'),
     nquadsDocumentWriter: writer('nquads'),
     turtleDocumentWriter: writer('turtle'),
     trigDocumentWriter: writer('trig'),
     rdfxmlDocumentWriter: writer('rdfxml'),
-    rdfcStage: async (wire, params) => ({
-      artefact: { canonical: await canonicalize(wire.graph, params) },
-    }),
+    // 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) => {
+      const isDataset = wire.graph instanceof Dataset;
+      const canonical = await canonicalize(wire.graph, params);
+      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) => {
       if (typeof wire.graph !== 'string') {
         throw new TypeError(`node CSVW: the stage takes CSV text on its wire (got ${typeof wire.graph})`);
@@ -113,10 +147,47 @@ export function buildNodes(deps) {
       if (description === undefined) {
         throw new TypeError('node rdfsExplainGraphStage: params.description is required');
       }
-      return { artefact: await explain(wire.graph, description, { ...opts, profile: 'rdfs' }) };
+      const result = await explain(wire.graph, description, { ...opts, profile: 'rdfs' });
+      return { graph: result, artefact: result };
     },
   };
 
+  // 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
+  // needs a value that is not null or undefined.
+  function wireHolds(wire, value) {
+    switch (wire) {
+      case 'String': return typeof value === 'string';
+      case 'Dataset': case 'Graph': case 'Dataset × PrefixList': return value instanceof Dataset;
+      case 'Answer': return typeof value === 'boolean';
+      case 'Table': return Array.isArray(value);
+      case 'String × String':
+        return Array.isArray(value) && value.length === 2 && value.every((v) => typeof v === 'string');
+      default: return value !== undefined && value !== null;
+    }
+  }
+
+  const describe = (v) => (v instanceof Dataset ? 'a Dataset' : Array.isArray(v) ? 'an array'
+    : v === null ? 'null' : typeof v);
+
   let stageCache = null;
   let engine = null; // the entry stages() loaded; node() calls stages(), so pipe() has it
 
@@ -167,7 +238,57 @@ export function buildNodes(deps) {
     throw new TypeError(`node: setting ${path} must be a JSON value or a Dataset (got ${typeof v})`);
   }
 
+  // The node's own copy of its settings, taken when node() checks them: plain
+  // objects and arrays copied and frozen at every depth, a Dataset cloned. A
+  // later change to the caller's objects does not reach the node, so the
+  // settings that run are the ones the engine checked and digested.
+  function snapshot(v) {
+    if (v instanceof Dataset) return typeof v.clone === 'function' ? v.clone() : v;
+    if (Array.isArray(v)) return Object.freeze(v.map(snapshot));
+    if (v !== null && typeof v === 'object') {
+      const out = {};
+      for (const [k, x] of Object.entries(v)) if (x !== undefined) out[k] = snapshot(x);
+      return Object.freeze(out);
+    }
+    return v;
+  }
+
+  // A node's settings must still be the ones it was checked with: a Dataset
+  // in them (the clone node() made) can still be changed through
+  // node.params. run() refuses such a node instead of running settings that
+  // its evidence record would misdescribe.
+  function assertSettingsUnchanged(n) {
+    const now = JSON.stringify(marshal(n.params, 'params'));
+    if (now !== JSON.stringify(n.settingsWire)) {
+      throw new FactoidalError(`run: the settings of node ${n.stage} changed after node() checked them ` +
+        '(make a new node with node() for new settings)', { code: 'op.failed' });
+    }
+  }
+
   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) {
@@ -189,11 +310,38 @@ export function buildNodes(deps) {
       throw new TypeError('node: params must be an object');
     }
     const info = (await stages()).find((s) => s.name === name);
+    // 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) {
-      throw new FactoidalError(`node: no registered stage named '${name}' (see stages())`,
+      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 }),
+      });
     }
-    const settingsWire = marshal({ ...(params || {}) }, 'params');
     // 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];
@@ -205,11 +353,12 @@ 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,
       bound: info.bound,
-      params: Object.freeze({ ...(params || {}) }),
+      params: own,
       settingsWire,
       settings: s ? s.settings : null,
       settingsDigest: s ? s.settingsDigest : null,
@@ -221,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()`);
@@ -296,10 +449,12 @@ 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);
     }
     const c = check(nodes);
     if (c && !c.wellTyped && !unchecked) {
@@ -314,6 +469,16 @@ export function buildNodes(deps) {
     let owned = null; // a Dataset an earlier node of this run made
     for (const n of nodes) {
       const out = await RUNNERS[n.stage](wire, n.params);
+      // The value on the output wire must be one of the node's wireOut, the
+      // wire the engine's check typed: a well-typed pipeline then cannot fail
+      // between nodes for want of the value the next node reads. The output
+      // wires per setting are the engine's when it has op pipelineCheckNodes;
+      // with an older engine the registry wire is generic, so not checked.
+      const value = out.graph === undefined ? wire.graph : out.graph;
+      if (hasNodeCheck() && !wireHolds(n.wireOut, value)) {
+        throw new FactoidalError(`run: node ${n.stage} declares the output wire ${n.wireOut} ` +
+          `but its runner gave ${describe(value)}`, { code: 'op.failed' });
+      }
       const record = makeRecord(n, out.artefact, unchecked);
       let graph = wire.graph;
       if (out.graph !== undefined && out.graph !== wire.graph) {
@@ -336,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-lws.mjs

@@ -17,8 +17,10 @@
 // representation: it is kept in memory and every later read of that file is
 // cut from it, with no further request. A changed entity tag between two
 // reads of one file refuses the read (the bytes of two versions are never
-// mixed). Limits: no Merkle check here (the engine's Verify.none path), no
-// eviction of the in-memory copies, no retry.
+// mixed). The engine checks every byte it decodes against the manifest's
+// Merkle roots (openSbm11's default `verify: 'merkle'`), so it asks for whole
+// 65,536-byte chunks and the `.merkle` sidecars; this file does no check.
+// Limits: no eviction of the in-memory copies, no retry.
 //
 // EVIDENCE
 // `evidence()` lists each resource read: { resource, etag, lastModified,

package/lib/sbm11.mjs

@@ -111,17 +111,33 @@ function envelope (raw) {
 export function sbm11Api (loadEngine) {
   /**
    * Open an SBM11 generation (a generation directory, or a collection root
-   * whose CURRENT file names one). Returns { generation, terms, query(sparql,
-   * options), close() }. `query` answers { path, rows, format, result, json }:
-   * `result` is the text `l4sbm11 query` writes (SPARQL JSON for SELECT and
-   * ASK, N-Triples for CONSTRUCT and DESCRIBE), `json` its parse for
-   * SELECT and ASK.
+   * whose CURRENT file names one). Returns { generation, terms, verify,
+   * query(sparql, options), close() }. `query` answers { path, rows, format,
+   * result, json }: `result` is the text `l4sbm11 query` writes (SPARQL JSON
+   * for SELECT and ASK, N-Triples for CONSTRUCT and DESCRIBE), `json` its
+   * parse for SELECT and ASK.
+   *
+   * `options.verify`: 'merkle' (the default: the engine checks every byte
+   * 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 opened = envelope(eng.call('sbm11Open', [String(source)]))
+    const openArgs = [String(source)]
+    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
     const reader = options.reader || readers.get(String(source))
@@ -135,6 +151,13 @@ export function sbm11Api (loadEngine) {
       },
       generation: opened.generation,
       terms: Number(opened.terms),
+      /** 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.19.0';
+export const version = '0.21.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'),