@factoidal/core 0.7.1 → 0.11.0

package/bin/factoidal.mjs

@@ -20,14 +20,14 @@
 // `--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'
-import { loadEngine } from './engine.mjs'
-import { sampleStoreFacts, sampleStorePath } from '../sample-store.mjs'
+import { hexOfBytes, loadEngine } from './engine.mjs'
 import { PackError, packSupported, verifyGeneration } from './pack.mjs'
 import { denoReexec, isStackOverflow, runPack } from './pack-host.mjs'
+import { SAMPLE_TURTLE, sampleStoreFacts } from '../sample-store.mjs'
 import {
   planQueryOnWorker, queryStoreOnWorker, workerRouteAvailable
 } from './store-worker-host.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. */
@@ -91,7 +77,8 @@ function exit (code) {
   else process.exitCode = code
 }
 
-function out (line) { console.log(line) }
+let outSilenced = false
+function out (line) { if (!outSilenced) console.log(line) }
 function err (line) { console.error(line) }
 
 // ---------------------------------------------------------------- usage
@@ -102,13 +89,18 @@ usage: factoidal <command> [options]
 
 commands:
   version                     print the package and engine versions
-  sample-store                print the path of the bundled sample store
+  sample-store [DIR]          pack a small built-in store and print its path
   inspect  STORE              report what the activated manifest commits
   query    STORE [QUERY]      evaluate a SPARQL query against a store
   pack     INPUT OUTPUT       build one immutable generation from an RDF file
   activate STORE GENERATION   make one generation the activated generation
   update   STORE [UPDATE]     apply a SPARQL Update through the delta log
   compact  STORE GENERATION   fold the delta log into a new generation
+  serve    STORE              serve SPARQL 1.1 Protocol, Graph Store and
+                              Service Description over HTTP
+  lws-serve DIR               serve Linked Web Storage 1.0 over HTTP
+  solid-serve DIR             serve the Solid Protocol over HTTP
+  solid-client OP URL         run one Solid client operation
 
 global options:
   -h, --help                  print this text, or a command's own help
@@ -118,33 +110,30 @@ global options:
 exit codes:
   0 success   1 failure   2 usage error   3 not yet wired (${ISSUE})
 
-STORE is a collection root: the directory that holds CURRENT. This package
-carries one, so the first query needs no other download:
+STORE is a collection root: the directory that holds CURRENT. Make one from
+an RDF file with pack and activate, or try a small built-in one:
 
   factoidal query "$(factoidal sample-store)" 'SELECT * WHERE { ?s ?p ?o } LIMIT 5'`
 
 const COMMAND_USAGE = {
-  version: `factoidal version - print the package and engine versions
+  'sample-store': `factoidal sample-store - pack a small built-in store, print its path
 
-usage: factoidal version [--json]
+usage: factoidal sample-store [DIR] [--json]
 
-Prints the npm package version, the Lean engine's WebAssembly digest as
-recorded by its build, and which host-I/O implementation is loaded.`,
+Packs the few triples held in sample-store.mjs (no data file ships) into a
+store under DIR, or under the OS temporary directory, activates it, and
+prints the collection root. A DIR that already holds CURRENT is reused.
 
-  'sample-store': `factoidal sample-store - print the bundled store's path
+  factoidal query "$(factoidal sample-store)" \\
+    'SELECT ?c ?l WHERE { ?c <http://www.w3.org/2004/02/skos/core#prefLabel> ?l }'`,
 
-usage: factoidal sample-store [--json]
+  version: `factoidal version - print the package and engine versions
 
-Prints the collection root of the Shardborough store this package
-carries, so a fresh install can query something at once:
+usage: factoidal version [--json]
 
-  factoidal inspect "$(factoidal sample-store)"
-  factoidal query "$(factoidal sample-store)" \\
-    'SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }'
+Prints the npm package version, the Lean engine's WebAssembly digest as
+recorded by its build, and which host-I/O implementation is loaded.`,
 
-The store holds five IPTC NewsCodes vocabularies (CC BY 4.0; see NOTICE)
-packed into IBK3 predicate blocks. --json adds what was recorded when it
-was packed.`,
 
   inspect: `factoidal inspect - report what a store's manifest commits
 
@@ -200,14 +189,16 @@ every later query from what it retained.
 
 formats:
   table    a human display of the engine's SPARQL Query Results JSON;
-           ASK prints true or false, CONSTRUCT prints its N-Triples
+           ASK prints true or false, CONSTRUCT and DESCRIBE print their
+           N-Triples
   json     SELECT prints the engine's SPARQL 1.1 Query Results JSON
-           document; ASK and CONSTRUCT print the operation's envelope,
-           because the operation answers those two with a boolean and a
-           serialized graph rather than with a results document
-  nquads   CONSTRUCT only: the graph the engine serialized
-  turtle   CONSTRUCT only: that graph through the engine's own Turtle
-           writer, which flattens named graphs into the default graph
+           document; ASK, CONSTRUCT and DESCRIBE print the operation's
+           envelope, because the operation answers those with a boolean
+           or a serialized graph rather than with a results document
+  nquads   CONSTRUCT and DESCRIBE only: the graph the engine serialized
+  turtle   CONSTRUCT and DESCRIBE only: that graph through the engine's
+           own Turtle writer, which flattens named graphs into the default
+           graph
 
 not available, and why:
   --base IRI         the store query operation takes no base argument;
@@ -215,8 +206,6 @@ not available, and why:
   xml, csv, tsv      the engine has no operation that writes the SPARQL
                      Results XML, CSV or TSV documents, and writing one
                      here would be a second serializer (iron rule 7)
-  DESCRIBE           the engine answers "DESCRIBE is not supported by the
-                     npm entry yet"
 
 A store carrying a non-empty delta log is not served by this path: the
 operation reads the manifest's committed artifacts only. Use the native
@@ -279,7 +268,186 @@ compacted epoch. It does not activate unless --activate is given.
 
 options:
   --activate         activate the new generation when it verifies
-  --json             emit one JSON object`
+  --json             emit one JSON object`,
+
+  serve: `factoidal serve - a SPARQL 1.1 endpoint over an activated store
+
+usage: factoidal serve STORE [--port N] [--host ADDRESS] [options]
+       factoidal serve --file DATA /DATASET [--port N] [options]
+       factoidal serve --tdb2 DIR /DATASET [--port N] [options]
+
+The second form matches fuseki-server --file DATA /DATASET: DATA is packed
+into a temporary collection (layout ibk5 unless --layout is given), served
+at /DATASET/sparql (also /DATASET/query and /DATASET/update) and
+/DATASET/data (also /DATASET/get, read only). Updates are lost on exit.
+
+The third form matches fuseki-server --loc DIR /DATASET for an Apache Jena
+TDB2 database: DIR is read in place, read only. SPARQL query and Graph Store
+GET work; an update or a Graph Store write answers 501 with a message. The
+current Data-NNNN generation is served; a database whose journal.jrnl is not
+empty (Jena has not replayed it) is refused. The Lean decoder reads the
+indexes and node table (formal/lean4/L4Factoidal/Tdb2/Read.lean); every
+quad is held in memory while the server runs.
+
+Serves the activated generation of STORE, with its delta log, over HTTP:
+
+  GET/POST /sparql   SPARQL 1.1 Protocol query and update
+                     (GET /sparql with no query string: the SPARQL 1.1
+                     Service Description of the endpoint)
+  /data, /data/...   SPARQL 1.1 Graph Store HTTP Protocol (?default,
+                     ?graph=IRI, or a path under /data naming the graph)
+
+options:
+  --port N           the port to bind; 0 takes an ephemeral one (default 3030)
+  --host ADDRESS     the address to bind (default 127.0.0.1)
+  --query-path PATH  the query and update endpoint (default /sparql)
+  --gsp-path PATH    the Graph Store endpoint (default /data)
+  --file DATA        pack and serve an RDF file (see the second form)
+  --tdb2 DIR         serve a Jena TDB2 database read only (third form)
+  --layout LAYOUT    with --file: ibk3, ibk4 or ibk5 (default ibk5)
+  --no-worker        serve on this thread instead of a worker thread with a
+                     raised call stack (large collections need the worker)
+  --quiet            print the origin only
+
+An update, or a Graph Store PUT, POST or DELETE, is appended to the
+activated generation's delta log as one batch before the response is sent,
+and is visible to the next request. An IBK3 (triples) generation accepts
+changes to the default graph only, because its delta log is replayed and
+compacted for that graph only; a change to a named graph answers 501. A
+quad generation (ibk4, ibk5) accepts every graph. Fold the log into a new
+generation with l4block-shard-compact, activate it, and restart the server.
+
+The server makes no protocol decision: the request framing, routing,
+status codes, content negotiation, evaluation and the delta-log batch are
+decided by formal/lean4/L4Factoidal/HTTP/Wire.lean and
+formal/lean4/L4Factoidal/SPARQL/StoreEndpoint.lean through the
+storeServe operations. A WebAssembly module built before those operations
+landed makes this command exit 3 and say so.
+
+Specifications: https://www.w3.org/TR/sparql11-protocol/
+https://www.w3.org/TR/sparql11-http-rdf-update/
+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 (--issuer IRI | --auth-config FILE | --insecure-no-auth)
+                         [--owner WEBID] [--root-acl FILE] [--audience IRI]
+                         [--port N] [--host ADDRESS] [--base IRI]
+
+Starts a Node HTTP server that answers every request through the engine's
+lwsStep operation.
+
+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).
+
+  --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)
+
+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 root IRI)
+
+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, 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 (--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 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).
+
+  --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; 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/
+PATCH/DELETE rules, the acl and describedby lifecycle, N3 Patch, Web
+Access Control, CORS and the LDN inbox are answered by
+formal/lean4/L4Factoidal/Solid/Server/. A WebAssembly module built before
+those operations landed makes this command exit 3 and say so.
+
+Specification: https://solidproject.org/TR/protocol`,
+
+  'solid-client': `factoidal solid-client - run one Solid client operation
+
+usage: factoidal solid-client <get|put|post|delete|discover> URL [options]
+
+Every request is built by the engine's solidClientRequest operation and
+every response is read by solidClientResponse. This command supplies a
+socket and prints what the engine answered.
+
+The five verbs are aliases for the operation kinds of the wasm ABI; the
+kind names are accepted directly as well.
+
+  get       read              put     replace          post   create
+  delete    delete            discover discoverStorage
+  (also: patch, readProfile)
+
+  --body TEXT       the request body for put, post and patch
+  --file PATH       read the request body from a file
+  --content-type M  the body's media type
+  --interpret KIND  one of storage, containment, auxiliaries, profile,
+                    wacAllow, used when the engine names none
+
+Specification: https://solidproject.org/TR/protocol`
 }
 
 // ------------------------------------------------------------- arguments
@@ -334,7 +502,12 @@ const VALUE_OPTIONS = {
   pack: new Set(['layout', 'syntax', 'chunk-bytes', 'base', 'batch-bytes']),
   activate: new Set([]),
   update: new Set(['update', 'file']),
-  compact: new Set([])
+  compact: new Set([]),
+  serve: new Set(['port', 'host', 'query-path', 'gsp-path', 'file', 'layout', 'tdb2']),
+  'lws-serve': new Set(['port', 'host', 'base', 'issuer', 'auth-config', 'owner', 'root-acl',
+    'audience']),
+  'solid-serve': new Set(['port', 'host', 'base', 'owner', 'issuer', 'auth-config']),
+  'solid-client': new Set(['body', 'file', 'content-type', 'interpret'])
 }
 
 // ------------------------------------------------------------- commands
@@ -348,85 +521,142 @@ function readJsonFile (path) {
   return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
 }
 
-function commandVersion (options) {
+async function sha256Hex (bytes) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return hexOfBytes(new Uint8Array(digest))
+}
+
+// `factoidal version`: what l4-assets/version.json says (the release stamp,
+// written by tools/fetch-builds.sh --set web from the factoidal-builds
+// release that built the wasm), what the installed wasm files hash to, and
+// the loaded engine's own version(). A stamp whose sha256 differs from the
+// installed wasm is an error (exit 1): the stamp then describes another
+// build. A source checkout carries the unstamped placeholder.
+async function commandVersion (options) {
   const root = packageDirectory()
   const own = readJsonFile(joinPath(root, 'package.json'))
-  let engine = null
+  let stamp = null
   try {
-    engine = readJsonFile(joinPath(root, 'l4-assets/version.json'))
+    stamp = readJsonFile(joinPath(root, 'l4-assets/version.json'))
   } catch (_error) {
-    engine = null
+    stamp = null
+  }
+  const stamped = stamp !== null && stamp.stamped === true
+  const installed = {}
+  for (const [key, file] of [['wasm', 'l4factoidal.wasm']]) {
+    try {
+      const bytes = readWhole(joinPath(root, `l4-assets/${file}`))
+      installed[key] = { sha256: await sha256Hex(bytes), bytes: bytes.length }
+    } catch (_error) {
+      installed[key] = null
+    }
+  }
+  let engineVersion = null
+  let engineError = null
+  if (installed.wasm !== null) {
+    try {
+      engineVersion = (await loadEngine()).version()
+    } catch (error) {
+      engineError = String(error && error.message ? error.message : error)
+    }
+  }
+  const mismatches = []
+  if (stamped) {
+    for (const [key, shaKey, bytesKey] of [['wasm', 'wasmSha256', 'wasmBytes']]) {
+      if (installed[key] === null) continue
+      if (stamp[shaKey] !== installed[key].sha256 || stamp[bytesKey] !== installed[key].bytes) {
+        mismatches.push(`${key}: version.json says sha256 ${stamp[shaKey]} (${stamp[bytesKey]} bytes), ` +
+          `installed file is ${installed[key].sha256} (${installed[key].bytes} bytes)`)
+      }
+    }
+    if (engineVersion !== null && typeof stamp.engineVersion === 'string' &&
+        stamp.engineVersion !== engineVersion) {
+      mismatches.push(`engine: version.json says ${stamp.engineVersion}, the loaded wasm says ${engineVersion}`)
+    }
   }
   const report = {
     package: own.name,
     version: own.version,
     host: runtime,
-    engine: engine === null
+    stamp: stamp === null
       ? null
-      : {
-          engine: engine.engine,
-          version: engine.version,
-          gitSha: engine.gitSha,
-          leanToolchain: engine.leanToolchain,
-          wasmSha256: engine.wasmSha256,
-          wasmBytes: engine.wasmBytes
-        }
+      : stamped
+        ? {
+            stamped: true,
+            engineVersion: stamp.engineVersion,
+            gitSha: stamp.gitSha,
+            builtAt: stamp.builtAt,
+            release: stamp.release,
+            leanToolchain: stamp.leanToolchain,
+            wasmSha256: stamp.wasmSha256,
+            wasmBytes: stamp.wasmBytes
+          }
+        : { stamped: false, status: stamp.status || 'stamped at release' },
+    installed,
+    engineVersion,
+    engineError,
+    mismatches
   }
   if (options.json) {
     out(JSON.stringify(report, null, 2))
-    return EXIT_OK
-  }
-  out(`${report.package} ${report.version}`)
-  out(`host-io ${report.host}`)
-  if (report.engine !== null) {
-    out(`engine ${report.engine.engine} ${report.engine.version} (${report.engine.leanToolchain})`)
-    out(`wasm sha256 ${report.engine.wasmSha256} (${report.engine.wasmBytes} bytes)`)
   } else {
-    out('engine (no l4-assets/version.json in this install)')
+    out(`${report.package} ${report.version}`)
+    out(`host-io ${report.host}`)
+    if (stamp === null) {
+      out('stamp: no l4-assets/version.json in this install')
+    } else if (!stamped) {
+      out('stamp: not stamped (l4-assets/version.json is the source placeholder; ' +
+        'it is stamped at release by tools/fetch-builds.sh --set web)')
+    } else {
+      out(`stamp: built from ${stamp.gitSha} at ${stamp.builtAt}` +
+        (stamp.release ? ` (${stamp.release})` : ''))
+      out(`stamp: engine ${stamp.engineVersion} (${stamp.leanToolchain})`)
+      out(`stamp: wasm sha256 ${stamp.wasmSha256} (${stamp.wasmBytes} bytes)`)
+    }
+    for (const [key, label] of [['wasm', 'wasm']]) {
+      out(installed[key] === null
+        ? `installed ${label}: absent`
+        : `installed ${label} sha256 ${installed[key].sha256} (${installed[key].bytes} bytes)`)
+    }
+    out(engineVersion !== null
+      ? `engine version() ${engineVersion}`
+      : `engine version() unavailable${engineError ? ': ' + engineError : ''}`)
   }
-  return EXIT_OK
-}
-
-function commandSampleStore (options) {
-  const path = sampleStorePath()
-  if (options.json === true) {
-    out(JSON.stringify({ path, ...sampleStoreFacts }, null, 2))
-    return EXIT_OK
+  if (mismatches.length > 0) {
+    for (const m of mismatches) err(`factoidal version: STAMP MISMATCH ${m}`)
+    return EXIT_FAILURE
   }
-  out(path)
   return EXIT_OK
 }
 
+
 // ------------------------------------------------------------ rendering
 
 /**
  * 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) {
@@ -502,7 +732,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)]
@@ -674,11 +904,11 @@ function renderQueryResult (engine, result, format, limit, quiet) {
       return EXIT_OK
     }
     if (format !== 'table') {
-      err(`factoidal query: --format ${format} needs a CONSTRUCT query; this one is a SELECT`)
+      err(`factoidal query: --format ${format} needs a CONSTRUCT or DESCRIBE query; this one is a SELECT`)
       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) {
@@ -694,13 +924,13 @@ function renderQueryResult (engine, result, format, limit, quiet) {
       return EXIT_OK
     }
     if (format !== 'table') {
-      err(`factoidal query: --format ${format} needs a CONSTRUCT query; this one is an ASK`)
+      err(`factoidal query: --format ${format} needs a CONSTRUCT or DESCRIBE query; this one is an ASK`)
       return EXIT_FAILURE
     }
     out(result.boolean ? 'true' : 'false')
     return EXIT_OK
   }
-  if (result.kind === 'construct') {
+  if (result.kind === 'construct' || result.kind === 'describe') {
     if (format === 'json') {
       out(JSON.stringify(result, null, 2))
       return EXIT_OK
@@ -717,32 +947,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.
  *
@@ -773,7 +1022,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
@@ -835,6 +1084,34 @@ async function commandPack (positional, options) {
   return EXIT_OK
 }
 
+async function commandSampleStore (positional, options) {
+  if (positional.length > 1) throw new UsageError('sample-store takes at most one DIR')
+  const { mkdtempSync, writeFileSync, existsSync } = await import('node:fs')
+  const { tmpdir } = await import('node:os')
+  const root = positional.length === 1
+    ? positional[0]
+    : mkdtempSync(joinPath(tmpdir(), 'factoidal-sample-store-'))
+  if (!existsSync(joinPath(root, 'CURRENT'))) {
+    makeDirectory(joinPath(root, 'gen-1'))
+    const source = joinPath(root, 'sample.ttl')
+    writeFileSync(source, SAMPLE_TURTLE)
+    outSilenced = true
+    try {
+      let code = await commandPack([source, joinPath(root, 'gen-1')], { quiet: true })
+      if (code === EXIT_OK) code = await commandActivate([root, 'gen-1'], { quiet: true })
+      if (code !== EXIT_OK) return code
+    } finally {
+      outSilenced = false
+    }
+  }
+  if (options.json === true) {
+    out(JSON.stringify({ path: root, ...sampleStoreFacts }, null, 2))
+  } else {
+    out(root)
+  }
+  return EXIT_OK
+}
+
 async function commandActivate (positional, options) {
   if (positional.length !== 2) throw new UsageError('activate needs STORE and GENERATION')
   const [root, generation] = positional
@@ -906,15 +1183,287 @@ function commandCompact (positional, _options) {
   return notWired('compact', 'Compaction is stage 4 of the milestone.')
 }
 
+// ------------------------------------------------- the protocol servers
+// These commands hand a socket to a host module and print where it is
+// listening. They decide nothing about the protocol they serve; see
+// npm/factoidal/lws/README.md and npm/factoidal/solid/*/README.md.
+// https://github.com/danbri/factoidal/issues/659
+
+function servePort (options, fallback) {
+  if (options.port === undefined) return fallback
+  const port = Number(options.port)
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new UsageError(`--port must be an integer from 0 to 65535, not "${options.port}"`)
+  }
+  return port
+}
+
+function serveHost (options) {
+  if (options.host === undefined) return '127.0.0.1'
+  if (typeof options.host !== 'string' || options.host.length === 0) {
+    throw new UsageError('--host needs an address')
+  }
+  return options.host
+}
+
+/** Keep the process alive until the runtime is interrupted. */
+function untilInterrupted (running, quiet) {
+  return new Promise((resolve) => {
+    const stop = async () => {
+      if (!quiet) err('')
+      await running.close()
+      resolve(EXIT_OK)
+    }
+    if (isDeno) {
+      globalThis.Deno.addSignalListener('SIGINT', stop)
+    } else {
+      process.on('SIGINT', stop)
+      process.on('SIGTERM', stop)
+    }
+  })
+}
+
+async function commandServe (positional, options) {
+  const quiet = options.quiet === true
+  // The Apache Jena Fuseki form: `serve --file DATA /ds`. The file is
+  // packed into a new collection in a temporary directory (ibk5 unless
+  // --layout says otherwise, so every graph accepts writes), activated, and
+  // served at /ds/sparql and /ds/data; /ds/query, /ds/update and /ds/get
+  // are answered too (StoreEndpoint.datasetPrefix). Updates go to that
+  // temporary collection and are lost when the process ends, as with
+  // fuseki-server --file. docs/fuseki-replacement.md.
+  if (typeof options.file === 'string') {
+    if (positional.length !== 1 || !positional[0].startsWith('/')) {
+      throw new UsageError('serve --file DATA needs one dataset name, such as /ds')
+    }
+    const dsName = positional[0].replace(/\/+$/, '')
+    const { mkdtempSync } = await import('node:fs')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const root = mkdtempSync(join(tmpdir(), 'factoidal-serve-'))
+    const packOptions = { quiet: true, layout: typeof options.layout === 'string' ? options.layout : 'ibk5' }
+    let rc = await commandPack([options.file, join(root, 'gen-1')], packOptions)
+    if (rc !== 0) return rc
+    rc = await commandActivate([root, 'gen-1'], { quiet: true })
+    if (rc !== 0) return rc
+    if (!quiet) err(`serve: packed ${options.file} into ${root} (temporary; updates are lost on exit)`)
+    positional = [root]
+    options = { ...options, 'query-path': `${dsName}/sparql`, 'gsp-path': `${dsName}/data` }
+  }
+  // The Apache Jena Fuseki form: `serve --tdb2 DIR /ds`, a TDB2 database
+  // read in place and read only (https://github.com/danbri/factoidal/issues/834).
+  const tdb2 = typeof options.tdb2 === 'string'
+  if (tdb2) {
+    if (positional.length !== 1 || !positional[0].startsWith('/')) {
+      throw new UsageError('serve --tdb2 DIR needs one dataset name, such as /ds')
+    }
+    const dsName = positional[0].replace(/\/+$/, '')
+    positional = [options.tdb2]
+    options = { ...options, 'query-path': `${dsName}/sparql`, 'gsp-path': `${dsName}/data` }
+  }
+  if (positional.length !== 1) throw new UsageError('serve needs one STORE')
+  const { listen, listenOnWorker, ServeHostError } = await import('./serve.mjs')
+  const serveOptions = {
+    port: servePort(options, 3030),
+    host: serveHost(options),
+    ...(tdb2 ? { tdb2: true } : {}),
+    ...(typeof options['query-path'] === 'string' ? { queryPath: options['query-path'] } : {}),
+    ...(typeof options['gsp-path'] === 'string' ? { gspPath: options['gsp-path'] } : {})
+  }
+  const onWorker = options['no-worker'] !== true && workerRouteAvailable()
+  let running
+  try {
+    running = onWorker
+      ? await listenOnWorker(positional[0], serveOptions)
+      : await listen(positional[0], serveOptions)
+  } catch (error) {
+    if (error instanceof ServeHostError && error.unknownOp) {
+      return notWired('serve', error.message)
+    }
+    if (error instanceof Error && typeof error.message === 'string') {
+      err(`factoidal serve: ${error.message.replace(/^l4factoidal:\s*/, '')}`)
+      return EXIT_FAILURE
+    }
+    throw error
+  }
+  const info = onWorker ? running.info : running.served.info
+  if (!quiet) {
+    err(`serve: listening on ${running.origin} for ${positional[0]} ` +
+      `(layout ${info.layout}, ${plural(info.rows, 'row')}, ` +
+      `delta batches replayed: ${info.deltaBatches}, write scope ${info.writeScope})`)
+    err(`serve: query ${running.origin}${info.queryPath}, graph store ${running.origin}${info.gspPath}`)
+  }
+  out(running.origin)
+  return untilInterrupted(running, quiet)
+}
+
+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 {
+    running = await listen({
+      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 } : {}),
+      ...(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)
+    }
+    throw error
+  }
+  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)
+}
+
+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 {
+    running = await listen({
+      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,
+      dir: positional[0]
+    })
+  } catch (error) {
+    if (error instanceof SolidServerHostError && error.unknownOp) {
+      return notWired('solid-serve', error.message)
+    }
+    throw error
+  }
+  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)
+}
+
+// The command's verbs, as aliases for the wasm ABI's request kinds. A
+// kind name is accepted directly too, so this table adds a spelling and
+// hides nothing.
+const SOLID_CLIENT_ALIASES = {
+  get: 'read',
+  put: 'replace',
+  post: 'create',
+  delete: 'delete',
+  discover: 'discoverStorage'
+}
+
+async function commandSolidClient (positional, options) {
+  if (positional.length !== 2) {
+    throw new UsageError('solid-client needs an operation and a URL')
+  }
+  const [verb, target] = positional
+  const { createSolidClient, SolidClientHostError, SOLID_REQUEST_KINDS } =
+    await import('../solid/client/index.mjs')
+  const kind = Object.prototype.hasOwnProperty.call(SOLID_CLIENT_ALIASES, verb)
+    ? SOLID_CLIENT_ALIASES[verb]
+    : verb
+  if (!SOLID_REQUEST_KINDS.includes(kind)) {
+    throw new UsageError(
+      `unknown operation "${verb}"; one of ` +
+      `${Object.keys(SOLID_CLIENT_ALIASES).join(', ')} or ` +
+      `${SOLID_REQUEST_KINDS.join(', ')}`)
+  }
+  const args = { target }
+  if (typeof options.file === 'string') {
+    args.body = new TextDecoder('utf-8', { fatal: true }).decode(readWhole(options.file))
+  } else if (typeof options.body === 'string') {
+    args.body = options.body
+  }
+  if (typeof options['content-type'] === 'string') {
+    args.contentType = options['content-type']
+  }
+  if (['create', 'replace', 'patch'].includes(kind) && args.body === undefined) {
+    throw new UsageError(`${verb} needs --body or --file`)
+  }
+  const extra = typeof options.interpret === 'string'
+    ? { interpret: options.interpret }
+    : {}
+  let answer
+  try {
+    const client = await createSolidClient()
+    answer = await client.run(kind, args, extra)
+  } catch (error) {
+    if (error instanceof SolidClientHostError && error.unknownOp) {
+      return notWired('solid-client', error.message)
+    }
+    throw error
+  }
+  out(JSON.stringify(answer, null, 2))
+  return EXIT_OK
+}
+
 const COMMANDS = {
   version: (positional, options) => commandVersion(options),
-  'sample-store': (positional, options) => commandSampleStore(options),
+  'sample-store': (positional, options) => commandSampleStore(positional, options),
   inspect: commandInspect,
   query: commandQuery,
   pack: commandPack,
   activate: commandActivate,
   update: commandUpdate,
-  compact: commandCompact
+  compact: commandCompact,
+  serve: commandServe,
+  'lws-serve': commandLwsServe,
+  'solid-serve': commandSolidServe,
+  'solid-client': commandSolidClient
 }
 
 // ----------------------------------------------------------------- main