@factoidal/core 0.10.0 → 0.12.0

package/bin/ext.mjs

@@ -33,11 +33,12 @@
 // times the physical plan evaluates the expression, and across
 // re-evaluation rounds.
 
-const XSD = 'http://www.w3.org/2001/XMLSchema#'
 
 /** How many evaluation rounds an async resolution may take. */
 export const EXT_MAX_ROUNDS = 25
 
+import { appTermToJson } from '../rdfjs.mjs'
+
 const extFunctions = new Map()
 const extRegistered = new Set()
 let extCache = new Map()
@@ -45,29 +46,24 @@ let extPending = []
 let bridgeInstalled = false
 
 /**
- * Encode one JavaScript answer as an SRJ binding-value object, as a JSON
- * string. `''` means "no value" — the §17.6 error.
+ * Encode one JavaScript answer for Wasm/Ops/ExtFns.lean, as a JSON string:
+ * the value tagged with its JavaScript type ({js, v}; a number as its
+ * Number::toString text), or a term object. The engine chooses the datatype
+ * and the lexical form (L4Factoidal.XSD.JsValue.jsLiteral,
+ * https://github.com/danbri/factoidal/issues/894 item 3). `''` means
+ * "no value", the section 17.6 error.
  */
 function encodeAnswer (out) {
   if (out === null || out === undefined) return ''
-  if (typeof out === 'boolean') {
-    return JSON.stringify({ type: 'literal', value: out ? 'true' : 'false', datatype: XSD + 'boolean' })
-  }
-  if (typeof out === 'number') {
-    if (!Number.isFinite(out)) return ''
-    return Number.isInteger(out)
-      ? JSON.stringify({ type: 'literal', value: String(out), datatype: XSD + 'integer' })
-      : JSON.stringify({ type: 'literal', value: String(out), datatype: XSD + 'double' })
-  }
-  if (typeof out === 'string') {
-    return JSON.stringify({ type: 'literal', value: out })
-  }
-  if (typeof out === 'object' && typeof out.type === 'string') {
-    // Already an SRJ binding-value object (or an RDF/JS-shaped term the
-    // caller built): pass it through and let the Lean decoder judge it.
-    return JSON.stringify(out)
+  switch (typeof out) {
+    case 'boolean': return JSON.stringify({ js: 'boolean', v: out })
+    case 'number': return JSON.stringify({ js: 'number', v: Object.is(out, -0) ? '-0' : String(out) })
+    case 'bigint': return JSON.stringify({ js: 'bigint', v: out.toString() })
+    case 'string': return JSON.stringify({ js: 'string', v: out })
+    case 'object':
+      try { return JSON.stringify(appTermToJson(out)) } catch (_error) { return '' }
+    default: return ''
   }
-  return ''
 }
 
 /** The synchronous bridge the wasm module calls. */

package/bin/factoidal.mjs

@@ -20,7 +20,7 @@
 // `--format turtle` all print documents the engine produced.
 
 import {
-  StoreHostError, atomicReplace, listGeneration, makeDirectory, readWhole,
+  StoreHostError, atomicReplace, listGeneration, makeDirectory, readChunk, readWhole,
   runtime
 } from '../store-host/index.mjs'
 import { fileUrlToPath, joinPath } from '../store-host/paths.mjs'
@@ -46,23 +46,9 @@ const EXIT_NOT_WIRED = 3
 const FEED_PROGRESS = 65536
 
 const PACK_LAYOUTS = ['ibk3', 'ibk4', 'ibk5']
-const PACK_SYNTAXES = ['turtle', 'trig', 'nquads', 'ntriples']
-const PACK_SUFFIXES = [
-  ['.ttl', 'turtle'], ['.turtle', 'turtle'],
-  ['.trig', 'trig'],
-  ['.nq', 'nquads'], ['.nquads', 'nquads'],
-  ['.nt', 'ntriples'], ['.ntriples', 'ntriples']
-]
-
-// Suffixes the engine parses elsewhere but the packer's streaming fold does
-// not read. Naming them is better than "cannot tell the syntax from its
-// name", which sends the reader looking for a --syntax value that does not
-// exist.
-const PACK_UNSUPPORTED_SUFFIXES = [
-  ['.rdf', 'RDF/XML'], ['.owl', 'RDF/XML'], ['.xml', 'RDF/XML'],
-  ['.jsonld', 'JSON-LD'], ['.json', 'JSON-LD'], ['.n3', 'Notation3'],
-  ['.csv', 'CSV'], ['.tsv', 'TSV'], ['.hdt', 'HDT']
-]
+// The syntaxes the packer reads and the file-name suffixes of each are the
+// engine's tables (op engineTables: packSyntaxes, packSuffixes,
+// packUnsupportedSuffixes), https://github.com/danbri/factoidal/issues/894.
 
 /** The parent of a path, and its last component. The `activate` hint
  *  printed after a pack needs both; neither is a format decision. */
@@ -344,43 +330,184 @@ https://www.w3.org/TR/sparql11-service-description/`,
 
   'lws-serve': `factoidal lws-serve - serve Linked Web Storage 1.0 over HTTP
 
-usage: factoidal lws-serve DIR [--port N] [--host ADDRESS]
+usage: factoidal lws-serve DIR (--issuer IRI | --auth-config FILE | --insecure-no-auth)
+                         [--owner WEBID] [--root-acl FILE] [--audience IRI]
+                         [--port N] [--host ADDRESS] [--base IRI] [--page-size N]
+                         [--paginate-always] [--moves all|data|off]
+                         [--no-linkset-put] [--unstable-search-results] [--merkle]
+                         [--controller-inbox URL] [--delivery-limit N]
+                         [--delivery-window SECONDS] [--redirects-max N]
+                         [--storage snapshot|files]
 
 Starts a Node HTTP server that answers every request through the engine's
 lwsStep operation.
 
-DIR names the storage directory. The first slice keeps the resource tree
-in the engine handle, so DIR is not read or written yet; it is the place
-a later snapshot goes (design record, section 2).
+DIR names the storage directory. The storage is kept in the engine
+handle and written to DIR/lws-state.json after every request that
+changed it (temporary file, fsync, rename), and read back on the next
+start. The engine decides the snapshot format and refuses a snapshot
+path with a dot segment or other traversal form
+(formal/lean4/L4Factoidal/LWS/Snapshot.lean).
+
+With --storage files (off by default) a write costs the same whatever the
+size of the storage: DIR holds one file per resource body (DIR/bodies/),
+a journal of metadata changes (DIR/lws-journal) and a metadata file
+(DIR/lws-files.json) that the journal is folded into from time to time.
+A journal record is valid only when it is complete and its SHA-256
+matches; a torn last record is ignored at start. An existing
+DIR/lws-state.json is migrated at the first start and renamed to
+lws-state.json.migrated. The engine decides every file name and every
+byte (formal/lean4/L4Factoidal/LWS/FileLayout.lean); the storage is still
+held in memory while the server runs
+(docs/designissues/2026-10-22-lws-storage-on-disk.md).
+
+Encryption at rest (off by default): when the environment variable
+FACTOIDAL_LWS_KEY holds a 32-byte key (64 hex digits, or 43 characters of
+base64url), the snapshot is sealed with ChaCha20-Poly1305 (HACL*) under a
+new random nonce for every write, and authenticated when the storage is
+opened. A wrong key, a changed or truncated file, a clear-text file with the
+variable set, or a sealed file without it stops the start with a message.
+It protects the file on disk only (formal/lean4/L4Factoidal/LWS/SnapshotSeal.lean).
 
   --port N        the port to bind; 0 takes an ephemeral one (default 3000)
   --host ADDRESS  the address to bind (default 127.0.0.1)
   --base IRI      the absolute IRI the storage root maps to
                   (default: the bound origin)
+  --page-size N   the engine's container page size (config member pageSize;
+                  default 100, 0 turns pagination off)
+  --paginate-always
+                  present every container listing as paginated, also one
+                  that fits on one page (config member paginateAlways;
+                  default off): rel="first" and rel="last", no rel="next"
+  --moves all|data|off
+                  which resources a client may move by changing their up
+                  link (config member moves; default all): data resources
+                  and containers, data resources only (the MoveResource
+                  capability's appliesTo is [DataResource]), or none (no
+                  MoveResource capability; a change of up answers 409)
+  --no-linkset-put
+                  a linkset resource does not accept PUT (config member
+                  linksetPut false): its Allow leaves PUT out and a PUT
+                  answers 405 Method Not Allowed; PATCH still applies
+  --unstable-search-results
+                  ANTICIPATORY AND UNSTABLE, off by default: a QUERY answer
+                  of the type search names a results resource with
+                  Content-Location (RFC 10008 section 2.3). lws10-index
+                  defines no such resource; this is likely to change.
+                  https://github.com/danbri/factoidal/issues/922
+  --merkle        off by default: keep a SHA-256 digest of every resource
+                  and a Merkle root of every container, and show them: an
+                  RFC 9530 Repr-Digest field on GET of a resource, a
+                  Factoidal-Merkle-Root field and listing member on a
+                  container, and the storage root's digest in the storage
+                  description (roots to the storage controller only under
+                  authorization). Entity tags do not change. The hashes are
+                  rebuilt when the storage is opened, not stored.
+                  https://github.com/danbri/factoidal/issues/919
+  --controller-inbox URL
+                  the storage controller's inbox (config member
+                  controllerInbox; default none): each new access request
+                  is announced there with a Create notification. The LWS
+                  draft names no such inbox; this is a server choice.
+                  https://github.com/danbri/factoidal/issues/920
+  --delivery-limit N
+                  the most webhook deliveries one subscription gets in one
+                  window (config member deliveryLimit; default 10, 0 turns
+                  the limit off); the changes over it wait and go in one
+                  batched notification when the window ends
+                  https://github.com/danbri/factoidal/issues/915
+  --delivery-window SECONDS
+                  the length of that window (config member deliveryWindow;
+                  default 60)
+  --redirects-max N
+                  the most previous identifiers of moved resources kept to
+                  answer 301 Moved Permanently (config member redirectsMax;
+                  default 256)
+                  https://github.com/danbri/factoidal/issues/914
+  --storage snapshot|files
+                  how DIR keeps the storage (config member storage;
+                  default the environment variable FACTOIDAL_LWS_STORAGE,
+                  else snapshot): one snapshot file written whole after
+                  each change, or one file per body with a journal, so a
+                  write costs the same whatever the storage size
+                  https://github.com/danbri/factoidal/issues/918
+
+Authorization (LWS editor's draft, section Authorization; one of the three
+is required):
+  --issuer IRI          trust this authorization server; several may be
+                        given separated by commas. Its metadata is read from
+                        IRI/.well-known/lws-configuration and its keys from
+                        the jwks_uri there, when a token first needs them.
+  --auth-config FILE    the engine's "auth" configuration as JSON:
+                        {"issuers":[{"issuer":IRI,"jwks":{...}?}],
+                         "audience":IRI?, "leeway":SECONDS?,
+                         "refreshInterval":SECONDS?}
+  --insecure-no-auth    development only: no authorization at all; every
+                        request is served. Never the default.
+  --owner WEBID         the storage owner: a new storage gets a root ACL
+                        that gives this agent Read, Write and Control
+  --root-acl FILE       a Turtle root ACL for a new storage instead
+  --audience IRI        the aud value tokens must carry (default: the
+                        storage IRI, BASE.well-known/lws-storage, which
+                        every lws#storage link names)
+
+Requests carry an access token as "Authorization: Bearer TOKEN" (RFC 6750).
+The engine verifies its JWS signature (ES256, RS256 or EdDSA, with the
+vendored HACL* code), its iss, aud, exp, nbf and iat, and then decides
+access with Web Access Control over the storage's ACL resources. A
+request without a valid token answers 401 with
+WWW-Authenticate: Bearer resource_metadata="..." (RFC 9728), and the
+metadata document is served at /.well-known/oauth-protected-resource.
 
 The server makes no protocol decision: status codes, Link relations,
-Last-Modified and the PATCH blank-node refusal are all answered by
-formal/lean4/L4Factoidal/LWS/. A WebAssembly module built before those
+Last-Modified, the PATCH blank-node refusal and every authorization
+decision are answered by formal/lean4/L4Factoidal/LWS/. A WebAssembly module built before those
 operations landed makes this command exit 3 and say so.
 
 Specification: https://w3c.github.io/lws-protocol/lws10-core/`,
 
   'solid-serve': `factoidal solid-serve - serve the Solid Protocol over HTTP
 
-usage: factoidal solid-serve DIR [--port N] [--host ADDRESS]
+usage: factoidal solid-serve DIR (--issuer IRI | --auth-config FILE | --insecure-no-auth)
+                           [--owner WEBID] [--port N] [--host ADDRESS] [--base IRI]
 
 Starts a Node HTTP server that answers every request through the engine's
 solidStep operation.
 
-DIR names the storage directory. The first slice keeps the resource tree
-in the engine handle, so DIR is not read or written yet; it is the place
-a later snapshot goes (design record, section 2).
+DIR names the storage directory. The storage is kept in the engine
+handle and written to DIR/lws-state.json after every request that
+changed it (temporary file, fsync, rename), and read back on the next
+start. The engine decides the snapshot format and refuses a snapshot
+path with a dot segment or other traversal form
+(formal/lean4/L4Factoidal/LWS/Snapshot.lean).
+
+Encryption at rest (off by default): when the environment variable
+FACTOIDAL_LWS_KEY holds a 32-byte key (64 hex digits, or 43 characters of
+base64url), the snapshot is sealed with ChaCha20-Poly1305 (HACL*) under a
+new random nonce for every write, and authenticated when the storage is
+opened. A wrong key, a changed or truncated file, a clear-text file with the
+variable set, or a sealed file without it stops the start with a message.
+It protects the file on disk only (formal/lean4/L4Factoidal/LWS/SnapshotSeal.lean).
 
   --port N        the port to bind; 0 takes an ephemeral one (default 3000)
   --host ADDRESS  the address to bind (default 127.0.0.1)
   --base IRI      the absolute IRI the storage root maps to
                   (default: the bound origin)
-  --owner WEBID   the WebID the storage advertises as its owner
+  --owner WEBID   the WebID the storage advertises as its owner; under
+                  authentication it gets acl:Read, acl:Write and
+                  acl:Control on the root (Web Access Control §3.2)
+  --issuer IRI    trust this Solid-OIDC issuer (comma separated for more).
+                  The engine verifies each DPoP-bound access token
+                  (Solid-OIDC §8, §9.3; RFC 9449): signature under the
+                  issuer's keys found by OpenID Connect Discovery, aud
+                  "solid", webid, exp, cnf.jkt bound to the DPoP key,
+                  htm, htu, iat and a jti replay cache, and that the
+                  WebID profile lists the issuer (solid:oidcIssuer).
+  --auth-config FILE  the same as JSON: {"issuers":[{"issuer":IRI,
+                  "jwks":{...}?}], "leeway"?, "iatWindow"?,
+                  "refreshInterval"?, "checkProfileIssuer"?}
+  --insecure-no-auth  development only: no authentication; Web Access
+                  Control is not enforced
 
 The server makes no protocol decision. Storage discovery, containment
 triples, slash semantics, the Allow and Accept-* headers, the PUT/POST/
@@ -469,8 +596,10 @@ const VALUE_OPTIONS = {
   update: new Set(['update', 'file']),
   compact: new Set([]),
   serve: new Set(['port', 'host', 'query-path', 'gsp-path', 'file', 'layout', 'tdb2']),
-  'lws-serve': new Set(['port', 'host', 'base']),
-  'solid-serve': new Set(['port', 'host', 'base', 'owner']),
+  'lws-serve': new Set(['port', 'host', 'base', 'issuer', 'auth-config', 'owner', 'root-acl',
+    'audience', 'page-size', 'moves', 'controller-inbox', 'delivery-limit', 'delivery-window',
+    'redirects-max', 'storage']),
+  'solid-serve': new Set(['port', 'host', 'base', 'owner', 'issuer', 'auth-config']),
   'solid-client': new Set(['body', 'file', 'content-type', 'interpret'])
 }
 
@@ -599,31 +728,28 @@ async function commandVersion (options) {
 /**
  * One graph name as the manifest reports it. `{"kind":"default"}` is the
  * default graph; the operation marks it that way so a host never has to
- * recognise a reserved IRI.
+ * recognise a reserved IRI. The engine writes the N-Triples form of a name
+ * (op termsToNTriples).
  */
-function graphLabel (graph) {
-  if (graph.kind === 'default') return 'default'
-  if (graph.kind === 'iri') return `<${graph.value}>`
-  if (graph.kind === 'bnode') return `_:${graph.value}`
-  return JSON.stringify(graph)
+function graphLabels (engine, graphs) {
+  const terms = graphs.filter((g) => g.kind !== 'default')
+    .map((g) => ({ type: g.kind === 'iri' ? 'uri' : 'bnode', value: g.value }))
+  const tokens = terms.length === 0 ? [] : engine.call('termsToNTriples', [JSON.stringify(terms)]).tokens
+  let k = 0
+  return graphs.map((g) => (g.kind === 'default' ? 'default' : tokens[k++]))
 }
 
 /**
- * One SPARQL Query Results JSON term as a table cell. This is a display,
- * not a serialization: `--format json` prints the engine's own document
- * and `--format nquads` prints the engine's own N-Triples.
+ * The SPARQL Query Results JSON terms of a table, as display cells: the
+ * engine writes each term's canonical N-Triples form (op termsToNTriples).
+ * `--format json` prints the engine's own document.
  */
-function cellOfTerm (term) {
-  if (term === undefined || term === null) return ''
-  if (term.type === 'uri') return `<${term.value}>`
-  if (term.type === 'bnode') return `_:${term.value}`
-  if (term.type === 'literal') {
-    const lang = term['xml:lang']
-    if (typeof lang === 'string' && lang.length > 0) return `"${term.value}"@${lang}`
-    if (typeof term.datatype === 'string') return `"${term.value}"^^<${term.datatype}>`
-    return `"${term.value}"`
-  }
-  return JSON.stringify(term)
+function cellsOfRows (engine, rows) {
+  const terms = []
+  for (const row of rows) for (const t of row) if (t !== undefined && t !== null) terms.push(t)
+  const tokens = terms.length === 0 ? [] : engine.call('termsToNTriples', [JSON.stringify(terms)]).tokens
+  let k = 0
+  return rows.map((row) => row.map((t) => (t === undefined || t === null ? '' : tokens[k++])))
 }
 
 function plural (count, noun) {
@@ -699,7 +825,7 @@ async function commandInspect (positional, options) {
       String(entry.rows),
       String(entry.bytes),
       entry.blockKind,
-      entry.graphs.length === 0 ? '-' : entry.graphs.map(graphLabel).join(' '),
+      entry.graphs.length === 0 ? '-' : graphLabels(engine, entry.graphs).join(' '),
       entry.predicate
     ].concat(zoned
       ? [String((entry.blobRefs ?? []).length), zoneCell(entry.subjectZone)]
@@ -875,7 +1001,7 @@ function renderQueryResult (engine, result, format, limit, quiet) {
       return EXIT_FAILURE
     }
     const shown = limit === null ? bindings : bindings.slice(0, limit)
-    printTable(vars, shown.map((row) => vars.map((name) => cellOfTerm(row[name]))))
+    printTable(vars, cellsOfRows(engine, shown.map((row) => vars.map((name) => row[name]))))
     if (shown.length < bindings.length) {
       err(`showing ${shown.length} of ${bindings.length} rows (--limit ${limit})`)
     } else if (!quiet) {
@@ -914,32 +1040,51 @@ function renderQueryResult (engine, result, format, limit, quiet) {
   return EXIT_FAILURE
 }
 
-/** The syntax tag for an input, from --syntax or from the file name. The
- *  engine is what actually decides how to read the bytes; this only picks
- *  which of its parsers to name. */
-function packSyntax (input, options) {
+/** The first `length` bytes of a file, as text, for content detection. */
+function readHead (path, length) {
+  return new TextDecoder('utf-8', { fatal: false }).decode(readChunk(path, 0, length))
+}
+
+/** The syntax tag for an input: --syntax when given, else the engine's
+ *  suffix table (op engineTables), else the engine's content detection
+ *  (op detectFormat) on the first 64 KiB of the file. */
+function packSyntax (engine, input, options) {
+  const tables = engine.call('engineTables', []).tables
+  const syntaxes = tables.packSyntaxes
   if (typeof options.syntax === 'string') {
     const syntax = options.syntax.toLowerCase()
-    if (PACK_SYNTAXES.indexOf(syntax) >= 0) return syntax
-    throw new UsageError(`--syntax ${options.syntax} is not one of ${PACK_SYNTAXES.join(', ')}`)
+    if (syntaxes.indexOf(syntax) >= 0) return syntax
+    throw new UsageError(`--syntax ${options.syntax} is not one of ${syntaxes.join(', ')}`)
   }
   const lower = input.toLowerCase()
-  for (const [suffix, syntax] of PACK_SUFFIXES) {
+  for (const [suffix, syntax] of Object.entries(tables.packSuffixes)) {
     if (lower.endsWith(suffix)) return syntax
   }
-  for (const [suffix, name] of PACK_UNSUPPORTED_SUFFIXES) {
+  for (const [suffix, name] of Object.entries(tables.packUnsupportedSuffixes)) {
     if (lower.endsWith(suffix)) {
       throw new UsageError(
         `pack does not read ${name}. The packer's streaming fold reads ` +
-        `${PACK_SYNTAXES.join(', ')} only. Convert the file first, for ` +
+        `${syntaxes.join(', ')} only. Convert the file first, for ` +
         "example with: factoidal parse FILE --out nquads")
     }
   }
+  let head = ''
+  try {
+    head = readHead(input, 65536)
+  } catch (_error) {
+    head = ''
+  }
+  if (head !== '') {
+    const tag = engine.call('detectFormat', [head]).format
+    const syntax = tag.replace(/12$/, '')
+    if (syntaxes.indexOf(syntax) >= 0) return syntax
+  }
   throw new UsageError(
-    `cannot tell the syntax of ${input} from its name; give --syntax ` +
-    `(${PACK_SYNTAXES.join(', ')})`)
+    `cannot tell the syntax of ${input} from its name or its content; give --syntax ` +
+    `(${syntaxes.join(', ')})`)
 }
 
+
 /**
  * The base IRI relative IRIs in the source resolve against.
  *
@@ -970,7 +1115,7 @@ function packLayout (options) {
 async function commandPack (positional, options) {
   if (positional.length !== 2) throw new UsageError('pack needs INPUT and OUTPUT')
   const [input, output] = positional
-  const syntax = packSyntax(input, options)
+  const syntax = packSyntax(await loadEngine(), input, options)
   const layout = packLayout(options)
   // The pack fold needs a bigger call stack than either runtime gives by
   // default (https://github.com/danbri/factoidal/issues/649). Under Node
@@ -1146,6 +1291,20 @@ function servePort (options, fallback) {
   return port
 }
 
+// --page-size N: a CLI number, passed unchanged as the engine config member
+// `pageSize`; what a page holds is decided in L4Factoidal/LWS/Pagination.lean.
+function pageSizeOption (value) {
+  return natOption('page-size', value)
+}
+
+function natOption (flag, value) {
+  const n = Number(value)
+  if (!Number.isInteger(n) || n < 0) {
+    throw new UsageError(`--${flag} must be a non-negative integer, not "${value}"`)
+  }
+  return n
+}
+
 function serveHost (options) {
   if (options.host === undefined) return '127.0.0.1'
   if (typeof options.host !== 'string' || options.host.length === 0) {
@@ -1248,6 +1407,25 @@ async function commandServe (positional, options) {
 async function commandLwsServe (positional, options) {
   if (positional.length !== 1) throw new UsageError('lws-serve needs one DIR')
   const quiet = options.quiet === true
+  const insecure = options['insecure-no-auth'] === true
+  const issuerOption = typeof options.issuer === 'string' ? options.issuer : null
+  const authFile = typeof options['auth-config'] === 'string' ? options['auth-config'] : null
+  if (!insecure && issuerOption === null && authFile === null) {
+    throw new UsageError('lws-serve needs --issuer IRI or --auth-config FILE, ' +
+      'or --insecure-no-auth for development')
+  }
+  if (insecure && (issuerOption !== null || authFile !== null)) {
+    throw new UsageError('--insecure-no-auth cannot be combined with --issuer or --auth-config')
+  }
+  let auth
+  if (authFile !== null) {
+    auth = readJsonFile(authFile)
+  } else if (issuerOption !== null) {
+    auth = { issuers: issuerOption.split(',').filter((v) => v !== '').map((issuer) => ({ issuer })) }
+  }
+  if (auth !== undefined && typeof options.audience === 'string') {
+    auth = { ...auth, audience: options.audience }
+  }
   const { listen, LwsHostError } = await import('../lws/server.mjs')
   let running
   try {
@@ -1255,15 +1433,45 @@ async function commandLwsServe (positional, options) {
       port: servePort(options, 3000),
       host: serveHost(options),
       ...(typeof options.base === 'string' ? { baseIri: options.base } : {}),
-      realClock: true
+      ...(options['page-size'] !== undefined ? { pageSize: pageSizeOption(options['page-size']) } : {}),
+      ...(options['unstable-search-results'] === true ? { searchResults: true } : {}),
+      ...(options.merkle === true ? { merkle: true } : {}),
+      // Passed unread as config members; the engine decides what they mean
+      // and refuses a value it does not know (Wasm/Ops/Lws.lean).
+      ...(options['paginate-always'] === true ? { paginateAlways: true } : {}),
+      ...(typeof options.moves === 'string' ? { moves: options.moves } : {}),
+      ...(options['no-linkset-put'] === true ? { linksetPut: false } : {}),
+      ...(typeof options['controller-inbox'] === 'string' ? { controllerInbox: options['controller-inbox'] } : {}),
+      ...(options['delivery-limit'] !== undefined ? { deliveryLimit: natOption('delivery-limit', options['delivery-limit']) } : {}),
+      ...(options['delivery-window'] !== undefined ? { deliveryWindow: natOption('delivery-window', options['delivery-window']) } : {}),
+      ...(options['redirects-max'] !== undefined ? { redirectsMax: natOption('redirects-max', options['redirects-max']) } : {}),
+      ...(typeof options.storage === 'string' ? { storage: options.storage } : {}),
+      ...(insecure ? { insecureNoAuth: true } : { auth }),
+      ...(typeof options.owner === 'string' ? { owner: options.owner } : {}),
+      ...(typeof options['root-acl'] === 'string'
+        ? { rootAcl: new TextDecoder('utf-8', { fatal: true }).decode(readWhole(options['root-acl'])) }
+        : {}),
+      realClock: true,
+      dir: positional[0]
     })
   } catch (error) {
     if (error instanceof LwsHostError && error.unknownOp) {
       return notWired('lws-serve', error.message)
     }
+    // The engine refused to open the storage (a bad configuration, or a
+    // snapshot it could not read or authenticate, issue 921), or the state
+    // file is not JSON: the message is the whole answer.
+    if (error !== null && typeof error === 'object' &&
+        (error.envelope !== undefined || error.stateFile === true)) {
+      err(`factoidal lws-serve: ${error.envelope !== undefined ? error.envelope.error : error.message}`)
+      return EXIT_FAILURE
+    }
     throw error
   }
-  if (!quiet) err(`lws-serve: listening on ${running.origin} for ${positional[0]}`)
+  if (!quiet) {
+    err(`lws-serve: listening on ${running.origin} for ${positional[0]}`)
+    if (insecure) err('lws-serve: WARNING: --insecure-no-auth: every request is served without authorization')
+  }
   out(running.origin)
   return untilInterrupted(running, quiet)
 }
@@ -1271,6 +1479,24 @@ async function commandLwsServe (positional, options) {
 async function commandSolidServe (positional, options) {
   if (positional.length !== 1) throw new UsageError('solid-serve needs one DIR')
   const quiet = options.quiet === true
+  // The same rule as lws-serve: no start without a trusted issuer unless
+  // the development mode is asked for by name.
+  const insecure = options['insecure-no-auth'] === true
+  const issuerOption = typeof options.issuer === 'string' ? options.issuer : null
+  const authFile = typeof options['auth-config'] === 'string' ? options['auth-config'] : null
+  if (!insecure && issuerOption === null && authFile === null) {
+    throw new UsageError('solid-serve needs --issuer IRI or --auth-config FILE, ' +
+      'or --insecure-no-auth for development')
+  }
+  if (insecure && (issuerOption !== null || authFile !== null)) {
+    throw new UsageError('--insecure-no-auth cannot be combined with --issuer or --auth-config')
+  }
+  let auth
+  if (authFile !== null) {
+    auth = readJsonFile(authFile)
+  } else if (issuerOption !== null) {
+    auth = { issuers: issuerOption.split(',').filter((v) => v !== '').map((issuer) => ({ issuer })) }
+  }
   const { listen, SolidServerHostError } = await import('../solid/server/index.mjs')
   let running
   try {
@@ -1278,16 +1504,29 @@ async function commandSolidServe (positional, options) {
       port: servePort(options, 3000),
       host: serveHost(options),
       ...(typeof options.base === 'string' ? { baseIri: options.base } : {}),
+      ...(insecure ? { insecureNoAuth: true } : { auth }),
       ...(typeof options.owner === 'string' ? { owner: options.owner } : {}),
-      realClock: true
+      realClock: true,
+      dir: positional[0]
     })
   } catch (error) {
     if (error instanceof SolidServerHostError && error.unknownOp) {
       return notWired('solid-serve', error.message)
     }
+    // The engine refused to open the storage (a bad configuration, or a
+    // snapshot it could not read or authenticate, issue 921), or the state
+    // file is not JSON: the message is the whole answer.
+    if (error !== null && typeof error === 'object' &&
+        (error.envelope !== undefined || error.stateFile === true)) {
+      err(`factoidal solid-serve: ${error.envelope !== undefined ? error.envelope.error : error.message}`)
+      return EXIT_FAILURE
+    }
     throw error
   }
-  if (!quiet) err(`solid-serve: listening on ${running.origin} for ${positional[0]}`)
+  if (!quiet) {
+    err(`solid-serve: listening on ${running.origin} for ${positional[0]}`)
+    if (insecure) err('solid-serve: WARNING: --insecure-no-auth: every request is served without authentication')
+  }
   out(running.origin)
   return untilInterrupted(running, quiet)
 }

package/browser.d.ts

@@ -5,6 +5,8 @@
 // system, so a path string rejects.
 
 export type {
+  FactoidalErrorCode,
+  FactoidalErrorPosition,
   NamedNode, BlankNode, Literal, Variable, DefaultGraph, Quad, Term, DataFactory,
   DataFormat, EntailRegime, Bindings, DataInput, QueryInput, ParseOptions,
   QueryOptions, SerializeOptions, StoreReader, OpenStoreOptions,
@@ -19,6 +21,10 @@ export {
   canonicalize,
   graphs,
   canonicalHash,
+  isomorphic,
+  fromQuads,
+  ready,
+  engineTables,
   openDataset,
   closure,
   formats,
@@ -85,9 +91,8 @@ export {
   didKeyResolve,
   capabilities,
   Dataset,
-  DatasetHandle,
   Store,
-  ParseError,
+  FactoidalError,
   dataFactory,
   version,
   engine,

package/browser.js

@@ -67,6 +67,10 @@ export const serialize = api.serialize;
 export const canonicalize = api.canonicalize;
 export const graphs = api.graphs;
 export const canonicalHash = api.canonicalHash;
+export const isomorphic = api.isomorphic;
+export const fromQuads = api.fromQuads;
+export const ready = api.ready;
+export const engineTables = api.engineTables;
 export const openDataset = api.openDataset;
 export const closure = api.closure;
 export const formats = api.formats;
@@ -149,9 +153,8 @@ export const didKeyResolve = api.didKeyResolve;
 // Types, probes and metadata
 export const capabilities = api.capabilities;
 export const Dataset = api.Dataset;
-export const DatasetHandle = api.DatasetHandle;
 export const Store = api.Store;
-export const ParseError = api.ParseError;
+export const FactoidalError = api.FactoidalError;
 export const dataFactory = api.dataFactory;
 export const version = api.version;
 export const engine = api.engine;

package/fn.d.ts

@@ -306,7 +306,7 @@ export function hash(ds: FnDataset): Promise<string>;
 export function equals(a: FnDataset, b: FnDataset): Promise<boolean>;
 
 /** Enumerate named graphs (default graph excluded), first-seen order. */
-export function graphs(ds: FnDataset): Array<[iri: string, graph: FnDataset]>;
+export function graphs(ds: FnDataset): Array<[name: NamedNode | BlankNode, graph: FnDataset]>;
 
 /** A minimal mutable box holding one dataflow input value. */
 export interface Cell<T> {