@factoidal/core 0.16.0 → 0.18.0

package/bin/store.mjs

@@ -123,7 +123,7 @@ export const STACK_REMEDY = {
 export function openStore (root, generationName = null) {
   if (typeof generationName !== 'string') {
     const opened = openCollection(root)
-    return { ...opened, manifestHex: hexOfBytes(opened.manifest), activated: true }
+    return withManifestHex({ ...opened, activated: true })
   }
   const generationDir = joinPath(root, generationName)
   for (const manifestName of MANIFEST_NAMES) {
@@ -133,23 +133,67 @@ export function openStore (root, generationName = null) {
     } catch (_error) {
       continue
     }
-    return {
+    return withManifestHex({
       root,
       generation: generationName,
       generationDir,
       manifestName,
       manifest,
-      manifestHex: hexOfBytes(manifest),
       activated: false
-    }
+    })
   }
   throw new StoreOperationError(
     `${generationDir} has none of ${MANIFEST_NAMES.join(', ')}`)
 }
 
+/**
+ * `store.manifestHex`, the hexadecimal the older manifest ops take, computed
+ * on first read. The byte ops (`hasManifestBytesOps`) do not read it, so a
+ * store opened for them never builds the 1.5 million digits of a large
+ * manifest (https://github.com/danbri/factoidal/issues/1039).
+ */
+function withManifestHex (store) {
+  let hex = null
+  return Object.defineProperty(store, 'manifestHex', {
+    enumerable: true,
+    get () {
+      if (hex === null) hex = hexOfBytes(store.manifest)
+      return hex
+    }
+  })
+}
+
+/** The byte forms of the manifest ops (formal/lean4/Wasm/Ops/StoreHandles.lean). */
+const MANIFEST_BYTES_OPS = ['storeManifestInspectBytes', 'storeQueryPlanBytes', 'storeOpenBytes']
+const manifestBytesSupport = new WeakMap()
+
+/**
+ * Whether the engine serves the byte forms of the manifest ops. They take
+ * the manifest as the byte region, not as hexadecimal inside the JSON
+ * arguments, and the engine decodes it once for a plan and the open that
+ * follows. An engine built before them has only the hexadecimal ops, and
+ * this host then uses those, as before.
+ */
+function hasManifestBytesOps (engine) {
+  let known = manifestBytesSupport.get(engine)
+  if (known === undefined) {
+    known = false
+    if (typeof engine.callBlobIO === 'function') {
+      const reflection = engine.call('ops', [])
+      const blobIoOps = Array.isArray(reflection && reflection.blobIoOps) ? reflection.blobIoOps : []
+      known = MANIFEST_BYTES_OPS.every((op) => blobIoOps.includes(op))
+    }
+    manifestBytesSupport.set(engine, known)
+  }
+  return known
+}
+
 /** `storeManifestInspect` — decode one manifest. */
 export function inspectManifest (engine, store) {
   try {
+    if (hasManifestBytesOps(engine)) {
+      return engine.callBlobIO('storeManifestInspectBytes', [], store.manifest).envelope
+    }
     return engine.call('storeManifestInspect', [store.manifestHex])
   } catch (error) {
     throw asStoreError(error)
@@ -159,6 +203,9 @@ export function inspectManifest (engine, store) {
 /** `storeQueryPlan` — the artifact keys this query needs, and the mode. */
 export function planQuery (engine, store, sparql) {
   try {
+    if (hasManifestBytesOps(engine)) {
+      return engine.callBlobIO('storeQueryPlanBytes', [sparql], store.manifest).envelope
+    }
     return engine.call('storeQueryPlan', [store.manifestHex, sparql])
   } catch (error) {
     throw asStoreError(error)
@@ -194,16 +241,20 @@ function capDecision (engine, store, sparql) {
   }
 }
 
-/** Read the named artifacts and concatenate them into one region. */
-function regionOf (store, keys) {
+/** Read the named artifacts and concatenate them into one region. With a
+ *  `prefix` (the manifest, for `storeOpenBytes`) the region starts with it,
+ *  and the windows still count from the first artifact byte. */
+function regionOf (store, keys, prefix = null) {
   const chunks = keys.map((key) => readWhole(joinPath(store.generationDir, key)))
+  const start = prefix ? prefix.length : 0
   let total = 0
   for (const chunk of chunks) total += chunk.length
-  const blob = new Uint8Array(total)
+  const blob = new Uint8Array(start + total)
+  if (prefix) blob.set(prefix, 0)
   const artifacts = []
   let offset = 0
   for (let index = 0; index < chunks.length; index += 1) {
-    blob.set(chunks[index], offset)
+    blob.set(chunks[index], start + offset)
     artifacts.push({ key: keys[index], offset, len: chunks[index].length })
     offset += chunks[index].length
   }
@@ -374,11 +425,16 @@ export function openStoreHandle (engine, store, options = {}) {
   } else {
     keys = manifestKeys(engine, store)
   }
-  const { blob, artifacts } = regionOf(store, keys)
+  const bytesOps = hasManifestBytesOps(engine)
+  // The byte op takes the manifest as the first bytes of the region.
+  const { blob, artifacts } = regionOf(store, keys, bytesOps ? store.manifest : null)
   let envelope
   try {
-    envelope = engine.callBlobIO('storeOpen',
-      [store.manifestHex, JSON.stringify(artifacts)], blob).envelope
+    envelope = bytesOps
+      ? engine.callBlobIO('storeOpenBytes',
+        [String(store.manifest.length), JSON.stringify(artifacts)], blob).envelope
+      : engine.callBlobIO('storeOpen',
+        [store.manifestHex, JSON.stringify(artifacts)], blob).envelope
   } catch (error) {
     throw asStoreError(error)
   }

package/index.d.ts

@@ -212,6 +212,9 @@ export interface WriteOptions {
   useRdfType?: boolean;
   /** 'jsonld' only. */
   rdfDirection?: string;
+  /** 'jsonld' only: write RDF 1.2 triple terms as JSON-LD-star (`@triple`,
+   *  `@reifies`, `@annotation`). Without it a triple term is refused. */
+  rdfstar?: boolean;
 }
 
 export type WriteFormat =
@@ -529,14 +532,15 @@ export function canonicalize(
 export function graphs(dataset: Dataset): Array<[name: NamedNode | BlankNode, graph: Dataset]>;
 
 /**
- * RDFC-1.0 canonical form of a single graph -- the graph-scoped
- * sibling of canonicalize(). It returns the canonical N-Quads TEXT, not
- * a digest: hash the string yourself (for example `vcSha256Hex`) when a
- * fixed-length value is needed. Every quad's graph component is dropped
- * before canonicalizing, so isomorphic graphs (including under
- * blank-node relabeling) give the same string regardless of what
- * graph name they were extracted from. Typically called with one
- * entry of graphs()'s output.
+ * The RDFC-1.0 canonical hash of a single graph: the SHA-256 of its
+ * canonical N-Quads document, as 64 lowercase hexadecimal digits (RDF
+ * Dataset Canonicalization 1.0, section 4.4 note 2). The engine computes
+ * the canonical form and the digest. Every quad's graph component is
+ * dropped first, so isomorphic graphs (including under blank-node
+ * relabeling) give the same hash whatever graph name they were extracted
+ * from. Typically called with one entry of graphs()'s output. For the
+ * canonical text, use canonicalize(). Rejects when the input holds an
+ * RDF 1.2 triple term or the section 4.4 call budget is exceeded.
  */
 export function canonicalHash(datasetOrGraph: Dataset): Promise<string>;
 
@@ -1010,6 +1014,9 @@ export interface JsonLdOptions {
   rdfDirection?: string;
   expandContext?: string;
   processingMode?: string;
+  /** JSON-LD-star: read `@triple`, `@reifies`, `@annotation` as RDF 1.2
+   *  triple terms and reifiers. */
+  rdfstar?: boolean;
 }
 
 /**
@@ -1026,6 +1033,9 @@ export function jsonldToRdf(
 export interface JsonLdFromRdfOptions {
   useNativeTypes?: boolean;
   useRdfType?: boolean;
+  /** JSON-LD-star: write RDF 1.2 triple terms (`@triple`, `@reifies`,
+   *  `@annotation`). Without it a triple term is refused. */
+  rdfstar?: boolean;
   format?: DataFormat;
 }
 

package/l4-assets/l4factoidal.js

@@ -37,7 +37,7 @@
 // bytes change.
 
 // Stamped by formal/lean4/Wasm/build-wasm.sh step 9 -- do not hand-edit.
-const WASM_VERSION = "1b10444e4416";
+const WASM_VERSION = "925f357453db";
 
 import createModule from './l4factoidal.mjs';
 

package/l4-assets/version.json

@@ -2,17 +2,17 @@
   "engine": "lean4",
   "note": "The Lean 4 (L4Factoidal) engine build provenance and claims: the only engine of @factoidal/core since 0.9.0 (issue 713). This committed file is a placeholder. tools/fetch-builds.sh --set web (through tools/stamp-l4-version.mjs) writes the provenance members from the danbri/factoidal-builds release that built the wasm; formal/lean4/Wasm/build-wasm.sh step 9 writes them for a local build. Do not commit a stamped copy.",
   "stamped": true,
-  "release": "danbri/factoidal-builds build-0069da82efd7-web",
-  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40281606727",
-  "gitSha": "0069da82efd75cc3bfe10785ef8853bd84931957",
-  "builtAt": "2026-10-26T08:11:18Z",
+  "release": "danbri/factoidal-builds build-788ee43aec79-web",
+  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40457275423",
+  "gitSha": "788ee43aec79c4d29592c5e82cc7ab350f0d05dd",
+  "builtAt": "2026-10-27T06:36:59Z",
   "leanToolchain": "leanprover/lean4:v4.33.1",
   "emscripten": "6.0.8",
   "abiVersion": "1",
   "engineVersion": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
   "version": "l4factoidal-wasm 0.2.0 (dispatch: RDF parse/serialize, SPARQL query+update, RDFS/OWL-RL closures, RDFC-1.0, CL/IKL)",
-  "wasmSha256": "1b10444e44160b8689ebd5375c074509196930b1927ce4c9fbc829a73d9b58ac",
-  "wasmBytes": 17034490,
+  "wasmSha256": "925f357453dbb71d087bef70fd428b054999756d7c967a806403d3d8ee875a57",
+  "wasmBytes": 17565361,
   "claims": {
     "source": "formal/lean4 (L4Factoidal): no sorry, no user axioms, no native_decide; W3C behaviour pinned by build-time #guard",
     "suitesAtBuildSha": "see docs/test-results and formal/lean4/PORT_NOTES.md at gitSha"

package/lib/api.mjs

@@ -182,11 +182,10 @@ function utf16Diagnostics(text, diagnostics) {
 // is never one of a partial generation.
 // ---------------------------------------------------------------------
 class Store {
-  constructor(e, env, gen, manifestHex, fromNQuads, withExtensionRounds) {
+  constructor(e, env, gen, fromNQuads, withExtensionRounds) {
     this._e = e;
     this._env = env;
     this._gen = gen;
-    this._manifestHex = manifestHex;
     this._closed = false;
     this._fromNQuads = fromNQuads;
     this._withExtensionRounds = withExtensionRounds;
@@ -236,7 +235,9 @@ class Store {
 
   /** The manifest, decoded by the engine (op storeManifestInspect). */
   async inspect() {
-    const r = entryResult(this._e.storeManifestInspect(this._manifestHex), 'Store.inspect');
+    const r = entryResult(typeof this._e.storeManifestInspectBytes === 'function'
+      ? this._e.storeManifestInspectBytes(this._gen.manifest)
+      : this._e.storeManifestInspect(hexOfBytes(this._gen.manifest)), 'Store.inspect');
     const { ok: _ok, ...rest } = r;
     return rest;
   }
@@ -841,7 +842,7 @@ function buildApi(driver) {
    * @param {Dataset|string|Array} data
    * @param {{format?: string, version?: '1.1'|'1.2', prefixes?: object,
    *   literalShorthand?: boolean, useNativeTypes?: boolean,
-   *   useRdfType?: boolean, rdfDirection?: string,
+   *   useRdfType?: boolean, rdfDirection?: string, rdfstar?: boolean,
    *   inputFormat?: string, baseIRI?: string}} [options]
    *   format: nquads (default), ntriples, turtle, trig, rdfxml, jsonld,
    *   rdfc. inputFormat and baseIRI read text `data`.
@@ -884,9 +885,12 @@ function buildApi(driver) {
   }
 
   /**
-   * RDFC-1.0 canonical N-Quads of one graph: every quad's graph name is
-   * dropped first (op datasetGraphAsDefault with the union of the graphs).
-   * Text, not a digest.
+   * The RDFC-1.0 canonical hash of one graph: the SHA-256, as 64 lowercase
+   * hexadecimal digits, of the canonical N-Quads document (RDF Dataset
+   * Canonicalization 1.0, section 4.4 note 2). Every quad's graph name is
+   * dropped first (op datasetGraphAsDefault with the union of the graphs);
+   * then op datasetCanonicalHash computes the canonical form and the digest
+   * in Lean. canonicalize() answers the canonical text.
    * @param {Dataset} datasetOrGraph
    * @returns {Promise<string>}
    */
@@ -897,10 +901,11 @@ function buildApi(driver) {
     datasetOrGraph.size; // throws the disposed error
     const c = datasetOrGraph._ctx;
     requireEntryFn(c.e, 'datasetGraphAsDefault', 'canonicalHash');
+    requireEntryFn(c.e, 'datasetCanonicalHash', 'canonicalHash');
     const merged = c.wrap(entryResult(c.e.datasetGraphAsDefault(datasetOrGraph.handle,
       JSON.stringify({ type: 'union' })), 'canonicalHash'), {});
     try {
-      return merged.toString('rdfc');
+      return entryResult(c.e.datasetCanonicalHash(merged.handle), 'canonicalHash').hash;
     } finally {
       merged.dispose();
     }
@@ -1206,7 +1211,9 @@ function buildApi(driver) {
    * A remote `@context` is not fetched.
    * @param {string} jsonldText
    * @param {{base?: string, rdfDirection?: string, expandContext?: string,
-   *   processingMode?: string}} [options]
+   *   processingMode?: string, rdfstar?: boolean}} [options]
+   *   rdfstar: JSON-LD-star (`@triple`, `@reifies`, `@annotation` as RDF 1.2
+   *   triple terms and reifiers).
    * @returns {Promise<Dataset>}
    */
   async function jsonldToRdf(jsonldText, options) {
@@ -1219,6 +1226,7 @@ function buildApi(driver) {
       ...(opts.rdfDirection ? { rdfDirection: opts.rdfDirection } : {}),
       ...(opts.expandContext ? { expandContext: opts.expandContext } : {}),
       ...(opts.processingMode ? { processingMode: opts.processingMode } : {}),
+      ...(opts.rdfstar ? { rdfstar: true } : {}),
     });
     return c.wrap(entryResult(c.e.datasetFromJsonLd(jsonldText, optionsJson), 'jsonldToRdf'), {},
       { format: 'jsonld', formatInferred: false });
@@ -1246,7 +1254,8 @@ function buildApi(driver) {
    * The text form is `serialize(data, {format: 'jsonld'})`.
    * @param {Dataset|string|Array} data
    * @param {{useNativeTypes?: boolean, useRdfType?: boolean,
-   *   rdfDirection?: string, format?: string, baseIRI?: string}} [options]
+   *   rdfDirection?: string, rdfstar?: boolean, format?: string,
+   *   baseIRI?: string}} [options]
    * @returns {Promise<any>}
    */
   async function jsonldFromRdf(data, options) {
@@ -1903,20 +1912,30 @@ function buildApi(driver) {
     const e = await entry();
     requireEntryFn(e, 'storeOpen', 'openStore (storeOpen)');
     const gen = await openGeneration(reader, opts.generation);
-    const manifestHex = hexOfBytes(gen.manifest);
+    // The byte ops when the engine has them (issue 1039): the manifest
+    // crosses as bytes and is decoded once for the plan and the open. An
+    // older engine gets the hexadecimal ops, as before.
+    const bytesOps = typeof e.storeOpenBytes === 'function';
+    const manifestHex = bytesOps ? null : hexOfBytes(gen.manifest);
     let keys;
     if (Array.isArray(opts.keys)) {
       keys = opts.keys.map(String);
     } else if (typeof opts.sparql === 'string') {
-      const plan = entryResult(e.storeQueryPlan(manifestHex, opts.sparql), 'openStore(plan)');
+      const plan = entryResult(bytesOps
+        ? e.storeQueryPlanBytes(gen.manifest, opts.sparql)
+        : e.storeQueryPlan(manifestHex, opts.sparql), 'openStore(plan)');
       keys = plan.keys.concat(plan.sidecarKeys || [], plan.blobKeys || []);
     } else {
-      keys = manifestKeys(entryResult(e.storeManifestInspect(manifestHex), 'openStore(inspect)'));
+      keys = manifestKeys(entryResult(bytesOps
+        ? e.storeManifestInspectBytes(gen.manifest)
+        : e.storeManifestInspect(manifestHex), 'openStore(inspect)'));
     }
     const { blob, artifacts } = await readRegion(reader, gen.generation, keys);
-    const env = entryResult(e.storeOpen(manifestHex, JSON.stringify(artifacts), blob), 'openStore');
+    const env = entryResult(bytesOps
+      ? e.storeOpenBytes(gen.manifest, JSON.stringify(artifacts), blob)
+      : e.storeOpen(manifestHex, JSON.stringify(artifacts), blob), 'openStore');
     const c = await ctx();
-    return new Store(e, env, gen, manifestHex, (nq) => c.fromNQuads(nq, {}), withExtensionRounds);
+    return new Store(e, env, gen, (nq) => c.fromNQuads(nq, {}), withExtensionRounds);
   }
 
   /**

package/lib/dataset.mjs

@@ -279,7 +279,7 @@ class Dataset {
    * The dataset as a document.
    * @param {{format?: string, version?: '1.1'|'1.2', prefixes?: object,
    *   literalShorthand?: boolean, useNativeTypes?: boolean,
-   *   useRdfType?: boolean, rdfDirection?: string}} [options]
+   *   useRdfType?: boolean, rdfDirection?: string, rdfstar?: boolean}} [options]
    *   format: nquads (default), ntriples, turtle, trig, rdfxml, jsonld,
    *   rdfc (RDFC-1.0 canonical N-Quads).
    * @returns {Promise<string>}
@@ -315,6 +315,7 @@ class Dataset {
         ...(opts.useNativeTypes ? { useNativeTypes: true } : {}),
         ...(opts.useRdfType ? { useRdfType: true } : {}),
         ...(opts.rdfDirection ? { rdfDirection: String(opts.rdfDirection) } : {}),
+        ...(opts.rdfstar ? { rdfstar: true } : {}),
         ...(suffix ? { version: String(opts.version) } : {}),
       })), 'serialize');
       return r.jsonld;

package/lib/lean-entry.mjs

@@ -125,6 +125,9 @@ function installExtensionBridge(eng, entry) {
   };
 }
 
+/** The byte forms of the manifest ops (Wasm/Ops/StoreHandles.lean). */
+const MANIFEST_BYTES_OPS = ['storeManifestInspectBytes', 'storeQueryPlanBytes', 'storeOpenBytes'];
+
 /**
  * Build the entry object lib/api.mjs drives, from a loaded engine handle.
  *
@@ -199,9 +202,45 @@ export function entryFromEngine(eng) {
       }
     };
   }
+  const blobIoOps = Array.isArray(reflection.blobIoOps) ? reflection.blobIoOps : [];
+  // The byte forms of the manifest ops (https://github.com/danbri/factoidal/issues/1039):
+  // the manifest crosses as the byte region, not as hexadecimal inside the
+  // JSON arguments, and the engine decodes it once for a plan and the open
+  // that follows. An engine without them has only the hexadecimal ops; the
+  // methods are then absent and lib/api.mjs uses the hexadecimal ops.
+  if (typeof eng.callBlobIO === 'function' &&
+      MANIFEST_BYTES_OPS.every((op) => blobIoOps.includes(op))) {
+    entry.storeManifestInspectBytes = (manifestBytes) => {
+      try {
+        return JSON.stringify(eng.callBlobIO('storeManifestInspectBytes', [], manifestBytes).envelope);
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+    entry.storeQueryPlanBytes = (manifestBytes, sparql) => {
+      try {
+        return JSON.stringify(
+          eng.callBlobIO('storeQueryPlanBytes', [String(sparql)], manifestBytes).envelope);
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+    entry.storeOpenBytes = (manifestBytes, artifactsJson, bytes) => {
+      try {
+        const region = new Uint8Array(manifestBytes.length + bytes.length);
+        region.set(manifestBytes, 0);
+        region.set(bytes, manifestBytes.length);
+        return JSON.stringify(eng.callBlobIO('storeOpenBytes',
+          [String(manifestBytes.length), String(artifactsJson)], region).envelope);
+      } catch (err) {
+        return failEnvelope(err);
+      }
+    };
+  } else {
+    for (const op of MANIFEST_BYTES_OPS) delete entry[op];
+  }
   // datasetQuadsBin answers a byte region (formal/lean4/L4Factoidal/RDF/QuadsBin.lean):
   // this method answers {envelope, bytes} and throws on a refusal.
-  const blobIoOps = Array.isArray(reflection.blobIoOps) ? reflection.blobIoOps : [];
   if (typeof eng.callBlobIO === 'function' && blobIoOps.includes('datasetQuadsBin')) {
     entry.datasetQuadsBin = (handle, optsJson) => {
       try {

package/lib/store.mjs

@@ -99,16 +99,18 @@ export function manifestKeys(inspectEnvelope) {
   return keys;
 }
 
-const HEX = (() => {
-  const t = new Array(256);
-  for (let b = 0; b < 256; b += 1) t[b] = b.toString(16).padStart(2, '0');
-  return t;
-})();
+const HEX_DIGIT = Uint8Array.from('0123456789abcdef', (c) => c.charCodeAt(0));
+const HEX_DECODER = new TextDecoder();
 
 /** Lowercase hexadecimal: the transport the manifest argument of the store
  *  ops takes. Artifact bytes never take this path. */
 export function hexOfBytes(bytes) {
-  const parts = new Array(bytes.length);
-  for (let i = 0; i < bytes.length; i += 1) parts[i] = HEX[bytes[i]];
-  return parts.join('');
+  // One byte buffer of ASCII digits, decoded once (issue 1039; see
+  // bin/engine.mjs hexOfBytes).
+  const out = new Uint8Array(bytes.length * 2);
+  for (let i = 0, at = 0; i < bytes.length; i += 1, at += 2) {
+    out[at] = HEX_DIGIT[bytes[i] >> 4];
+    out[at + 1] = HEX_DIGIT[bytes[i] & 15];
+  }
+  return HEX_DECODER.decode(out);
 }

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.16.0';
+export const version = '0.18.0';

package/lws/client.mjs

@@ -38,14 +38,15 @@ import { loadEngine } from '../bin/engine.mjs'
 import { FactoidalError } from '../lib/errors.mjs'
 
 /** The ops this host needs from the engine. */
-export const LWS_CLIENT_OPS = ['lwsClientStart', 'lwsClientStep']
+export const LWS_CLIENT_OPS = ['lwsClientStart', 'lwsClientStep', 'lwsClientNewKey']
 
 /** The operation kinds of the ABI. Listed so a caller can be checked
  *  against the contract; this host attaches no meaning to any of them. */
 export const LWS_CLIENT_KINDS = [
-  'discover', 'read', 'head', 'create', 'update', 'patch', 'delete', 'readLinkset',
-  'updateLinkset', 'move', 'list', 'typeIndex', 'search', 'subscribe', 'unsubscribe',
-  'requestAccess', 'grantAccess', 'getAccess', 'revokeAccess', 'verifyNotification'
+  'discover', 'describe', 'read', 'readPage', 'head', 'create', 'update', 'patch', 'delete',
+  'findLinkset', 'readLinkset', 'updateLinkset', 'putLinkset', 'move', 'list', 'typeIndex',
+  'search', 'queryFormats', 'subscribe', 'getSubscription', 'unsubscribe', 'requestAccess',
+  'grantAccess', 'getAccess', 'revokeAccess', 'verifyNotification'
 ]
 
 /** The error an operation ends with. `reason` is the engine's code
@@ -58,6 +59,9 @@ export class LwsClientError extends FactoidalError {
     this.name = 'LwsClientError'
     this.reason = reason
     this.detail = fail
+    // The engine's name for the failure in the lws-driver/1 adapter
+    // protocol ({ kind, message, ... }), as the engine wrote it.
+    this.report = fail && typeof fail.report === 'object' ? fail.report : undefined
     this.unknownOp = extra.unknownOp === true
   }
 }
@@ -138,8 +142,12 @@ export async function lwsClientOpsAvailable (engine) {
  * @param {string} [options.subjectToken] the authentication credential to
  *   exchange for access tokens (RFC 8693 subject_token)
  * @param {string} [options.subjectTokenType] its token type URI
- * @param {object} [options.selfIssued] `{ subject, keyId, jwk }`: a P-256 key
- *   to sign self-issued credentials with, instead of a subject token
+ * @param {object} [options.selfIssued] `{ subject, keyId, jwk }`: a P-256 or
+ *   Ed25519 key to sign self-issued credentials with, instead of a subject
+ *   token (`createDidKey` makes one)
+ * @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 {object} [options.session] a session from an earlier client
  * @param {number} [options.maxSteps] the loop cap of one operation
  * @returns {Promise<object>} the client
@@ -157,6 +165,9 @@ export async function createLwsClient (options = {}) {
   // `{ subject, keyId, jwk }`: a P-256 key the engine signs self-issued
   // credentials with (lws10-authn-ssi-cid), passed through unread.
   if (options.selfIssued !== undefined) session.selfIssued = options.selfIssued
+  // 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
 
   function call (op, args) {
     try {
@@ -230,7 +241,10 @@ export async function createLwsClient (options = {}) {
     /** The session (access tokens and subject token), for a later client. */
     session: () => ({ ...session }),
     discover: with_('discover'),
+    describe: with_('describe'),
+    /** `read(url, { accept, rangeStart, rangeEnd, ifNoneMatch, prefer })` */
     read: with_('read'),
+    readPage: with_('readPage'),
     head: with_('head'),
     /** `create(containerUrl, { body, mediaType, slug, container, types, links })` */
     create: with_('create'),
@@ -239,26 +253,54 @@ export async function createLwsClient (options = {}) {
     patch: with_('patch'),
     /** `delete(url, { recursive, precondition, tag })` */
     delete: with_('delete'),
+    findLinkset: with_('findLinkset'),
     readLinkset: with_('readLinkset'),
+    /** `updateLinkset(resourceUrl, { body })`, or with `{ linksetUrl, body }`
+     *  when the caller has the linkset resource. */
     updateLinkset: with_('updateLinkset'),
+    putLinkset: with_('putLinkset'),
     /** `move(url, { destination })` */
     move: with_('move'),
     list: with_('list'),
     typeIndex: with_('typeIndex'),
-    /** `search(anyUrlInTheStorage, { query })` */
+    /** `search(anyUrlInTheStorage, { query })`, or `{ endpoint, query }` with
+     *  the service endpoint, `{ onePage: true }` for one page */
     search: with_('search'),
+    queryFormats: with_('queryFormats'),
+    /** `subscribe(url, { topics, inbox, expires })` */
     subscribe: with_('subscribe'),
+    getSubscription: with_('getSubscription'),
     unsubscribe: with_('unsubscribe'),
     requestAccess: with_('requestAccess'),
     grantAccess: with_('grantAccess'),
     getAccess: with_('getAccess'),
     revokeAccess: with_('revokeAccess'),
-    /** `verifyNotification(baseUrl, { requestTarget, method, headers, body })`:
+    /** `verifyNotification(baseUrl, { requestTarget, method, headers, body, trustedStorages })`:
      *  the engine's verdict `{ accept, status, reason? }`. */
     verifyNotification: with_('verifyNotification')
   }
 }
 
+/**
+ * A new `did:key` agent: the engine makes the key pair and the identifier from
+ * 64 random bytes of this host's random source. The host reads none of it.
+ *
+ * @param {object} [options]
+ * @param {object} [options.engine] an engine handle to reuse
+ * @param {string} [options.algorithm] the engine's name of the algorithm
+ *   (default `ES256`, a P-256 key; `EdDSA` makes an Ed25519 key)
+ * @returns {Promise<{agent: string, kid: string, selfIssued: object}>}
+ *   `selfIssued` is the `createLwsClient` option of that name
+ */
+export async function createDidKey (options = {}) {
+  const engine = options.engine !== undefined ? options.engine : await loadEngine()
+  const algorithm = typeof options.algorithm === 'string' ? options.algorithm : 'ES256'
+  const random = new Uint8Array(64)
+  globalThis.crypto.getRandomValues(random)
+  const answer = engine.call('lwsClientNewKey', [algorithm, base64OfBytes(random)])
+  return answer.key
+}
+
 /**
  * An HTTP receiver for webhook notifications. For each request it asks the
  * engine (`verifyNotification`) and answers with the status of the

package/lws/server.mjs

@@ -584,11 +584,33 @@ export async function createLwsServer (options = {}) {
   let settings = { ...options }
   let opening = null
   let opened = null
+  let authz = null
 
-  /** The storage handle, opened once. */
+  /** The storage handle, opened once. With `authz` (an object of
+   *  `openAuthorizationServer` options), an authorization server that shares
+   *  the storage's issuer is opened first, on `mountedOn: baseIri`; the
+   *  storage then trusts that issuer with the JWK Set the engine published
+   *  (L4Factoidal/Authz/Mount.lean). */
   function storage () {
     if (opening === null) {
-      opening = openLwsStorage(settings).then((value) => { opened = value; return value })
+      opening = (async () => {
+        let storageSettings = settings
+        if (settings.authz !== undefined && settings.authz !== null) {
+          if (typeof settings.baseIri !== 'string') throw new LwsHostError('authz needs baseIri')
+          const { openAuthorizationServer } = await import('../authz/server.mjs')
+          authz = await openAuthorizationServer({
+            ...settings.authz,
+            ...(settings.engine !== undefined ? { engine: settings.engine } : {}),
+            ...(settings.auth && typeof settings.auth.audience === 'string' ? { audience: settings.auth.audience } : {}),
+            mountedOn: settings.baseIri
+          })
+          const issuers = [{ issuer: authz.issuer, jwks: authz.jwks }]
+          const prior = settings.auth && Array.isArray(settings.auth.issuers) ? settings.auth.issuers : []
+          storageSettings = { ...settings, auth: { ...(settings.auth || {}), issuers: issuers.concat(prior) } }
+        }
+        opened = await openLwsStorage(storageSettings)
+        return opened
+      })()
     }
     return opening
   }
@@ -610,7 +632,13 @@ export async function createLwsServer (options = {}) {
     }
     let answer
     try {
-      answer = await (await storage()).step(record)
+      const store = await storage()
+      // One port for both servers: the engine names the authorization
+      // server's paths (L4Factoidal.Authz.owns); every other request is the
+      // storage's. The token request body is form text.
+      answer = authz !== null && authz.owns(record.target)
+        ? await authz.step({ ...record, body: new TextDecoder('utf-8').decode(record.body) })
+        : await store.step(record)
     } catch (error) {
       // A failure of this host or of the engine, not a protocol answer.
       // The engine's own words are kept; nothing is invented.
@@ -627,6 +655,8 @@ export async function createLwsServer (options = {}) {
   return {
     server,
     storage,
+    /** The authorization server sharing the storage's issuer, or null. */
+    authz () { return authz },
     /** Set the storage root's absolute IRI, before the first request. */
     setBaseIri (value) {
       if (opening !== null) {
@@ -646,6 +676,7 @@ export async function createLwsServer (options = {}) {
       return new Promise((resolve) => {
         server.close(() => {
           if (opened !== null) opened.close()
+          if (authz !== null) authz.close()
           resolve()
         })
       })