@factoidal/core 0.19.0 → 0.21.0

package/lib/api.mjs

@@ -26,10 +26,12 @@ import { dataFactory, termFromSrj, termToJson, quadToJson, _setTextEngine } from
 import { Dataset, INTERNAL, checkOptions, makeRegistry, WRITER_TAGS } from './dataset.mjs';
 import { version as packageVersion } from './version.mjs';
 import { openGeneration, readRegion, manifestKeys, hexOfBytes } from './store.mjs';
-import { fullEngineMessage } from './lean-entry.mjs';
+import { fullEngineMessage, encodeJsValue } from './lean-entry.mjs';
 import { memoryDeltaLogStore } from './delta-log-hosts.mjs';
 import { FactoidalError, errorFromEnvelope, envelopeResult } from './errors.mjs';
 import { buildNodes } from './nodes.mjs';
+import { runWithCipher } from './cipher-host.mjs';
+import { cidFunctions } from './cid.mjs';
 
 // The format names, regimes and query outputs are the engine's tables (op
 // engineTables, formal/lean4/Wasm/Ops/Handles.lean), read once per engine:
@@ -265,6 +267,10 @@ class Store {
  *        Where the deltaLog* functions keep their records
  *        (lib/delta-log-hosts.mjs): IndexedDB in the browser entries. The
  *        default keeps them in the memory of this process.
+ * @param {object} [driver.cidHost]
+ *        Name resolution and the GET of cidRetrieveVerificationMethod
+ *        (lib/cid-node.mjs under Node and Deno). The default is the browser
+ *        host of lib/cid.mjs: the page's fetch, no name resolution.
  */
 function buildApi(driver) {
   let entryPromise; // memoized; a failed load is retried on the next call
@@ -655,6 +661,17 @@ function buildApi(driver) {
     const entail = opts.entail || 'none';
     const sparql12 = opts.sparql12 === true || String(opts.version || '') === '1.2';
     const e = c.e;
+    if (sparql12 && entail !== 'none' && opts.output === undefined) {
+      // SPARQL 1.2 under an entailment regime: the engine closes the stored
+      // dataset and runs the SPARQL 1.2 evaluator (op datasetQuery12Entail,
+      // https://github.com/danbri/factoidal/issues/1109).
+      requireEntryFn(e, 'datasetQuery12Entail', 'query {sparql12, entail}');
+      const r = await withExtensionRounds(() => entryResult(
+        e.datasetQuery12Entail(ds.handle, sparql, entail), 'query', sparql));
+      if (r.kind === 'ask') return r.boolean;
+      if (r.kind === 'construct' || r.kind === 'describe') return c.fromNQuads(r.nquads, ds.prefixes);
+      return bindingsFromSrj(r.srj);
+    }
     if (entail !== 'none' || opts.output !== undefined) {
       // queryRaw over the stored dataset: an entailment regime, or a
       // results format (SPARQL 1.1 Query Results JSON, XML, CSV, TSV).
@@ -664,15 +681,18 @@ function buildApi(driver) {
       requireEntryFn(e, 'datasetQueryRaw', `query {entail/output}`);
       if (opts.output === undefined) {
         // An entailment regime with the default answer shape.
-        const r = entryResult(e.datasetQueryRaw(ds.handle, sparql, JSON.stringify({
-          entail, output: graphForm ? 'ntriples' : 'json' })), 'query', sparql);
+        // withExtensionRounds: a registered async extension function
+        // (SPARQL 1.1 §17.6) is resolved here as in datasetQuery
+        // (https://github.com/danbri/factoidal/issues/1090).
+        const r = await withExtensionRounds(() => entryResult(e.datasetQueryRaw(ds.handle, sparql,
+          JSON.stringify({ entail, output: graphForm ? 'ntriples' : 'json' })), 'query', sparql));
         if (graphForm) return c.fromNQuads(r.text, ds.prefixes);
         const srj = JSON.parse(r.text);
         if (typeof srj.boolean === 'boolean') return srj.boolean;
         return bindingsFromSrj(srj);
       }
-      const r = entryResult(e.datasetQueryRaw(ds.handle, sparql,
-        JSON.stringify({ entail, output })), 'query', sparql);
+      const r = await withExtensionRounds(() => entryResult(e.datasetQueryRaw(ds.handle, sparql,
+        JSON.stringify({ entail, output })), 'query', sparql));
       return output === 'json' && !graphForm ? JSON.parse(r.text) : r.text;
     }
     const fn = sparql12 ? e.datasetQuery12 : e.datasetQuery;
@@ -735,16 +755,33 @@ function buildApi(driver) {
    * skipped statement in `dataset.diagnostics`
    * (https://github.com/danbri/factoidal/issues/716); `maxErrors: n` stops
    * after n diagnostics. With no `format` the engine infers one
-   * (`dataset.format`, `dataset.formatInferred`).
+   * (`dataset.format`, `dataset.formatInferred`). `{rdfstar:true}` reads
+   * JSON-LD as JSON-LD-star (`@triple`, `@reifies`, `@annotation`), as
+   * jsonldToRdf() does; it applies to format 'jsonld' only.
    * @param {string} text
    * @param {{format?: string, baseIRI?: string, lenient?: boolean,
-   *   maxErrors?: number}} [options]
+   *   maxErrors?: number, rdfstar?: boolean}} [options]
    * @returns {Promise<Dataset>}
    */
   async function parse(text, options) {
     if (typeof text !== 'string') throw new TypeError('parse: text must be a string');
     const opts = await checkedOptions('parse', optionsOf('parse', options));
     const c = await ctx();
+    if (opts.rdfstar) {
+      const { tag, inferred } = formatTagOf(c, text, opts.format, 'parse');
+      if (tag !== 'jsonld') {
+        throw new FactoidalError(
+          `parse: rdfstar applies to format 'jsonld' only (format '${tag}'${inferred ? ', inferred' : ''})`,
+          { code: 'option.conflict' });
+      }
+      requireEntryFn(c.e, 'datasetFromJsonLd', 'parse {rdfstar:true} (datasetFromJsonLd)');
+      const optionsJson = JSON.stringify({
+        ...(opts.baseIRI ? { base: opts.baseIRI } : {}),
+        rdfstar: true,
+      });
+      return c.wrap(entryResult(c.e.datasetFromJsonLd(text, optionsJson), 'parse'), {},
+        { format: tag, formatInferred: inferred });
+    }
     if (opts.lenient) {
       const { tag, inferred } = formatTagOf(c, text, opts.format, 'parse');
       requireEntryFn(c.e, 'parseDocument', 'parse {lenient:true} (parseDocument)');
@@ -885,30 +922,54 @@ function buildApi(driver) {
   }
 
   /**
-   * 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
+   * The RDFC-1.0 canonical hash of a dataset: the SHA-256, as 64 lowercase
+   * hexadecimal digits, of the canonical N-Quads document that canonicalize()
+   * answers (RDF Dataset Canonicalization 1.0, section 4.4 note 2), graph
+   * names included. Op datasetCanonicalHash computes the canonical form and
+   * the digest in Lean. Since 0.20.0; 0.17.0 to 0.19.x dropped every graph
+   * name first, so datasets that differ only in their graph names got the
+   * same hash. To hash a graph whatever its name, use
+   * canonicalHash(asDefaultGraph(g)).
+   *
+   * The input is what canonicalize() takes: a Dataset, or text (a string,
+   * or {text, format, baseIRI}), with the options {format, baseIRI}. Text is
+   * a JavaScript string: characters, not bytes. Decode bytes first (the RDF
+   * text syntaxes are UTF-8: `new TextDecoder('utf-8', { fatal: true })`);
+   * a Uint8Array is refused.
+   * @param {Dataset|string|{text: string, format?: string, baseIRI?: string}} data
+   * @param {{format?: string, baseIRI?: string}} [options]
    * @returns {Promise<string>}
    */
-  async function canonicalHash(datasetOrGraph) {
-    if (!(datasetOrGraph instanceof Dataset)) {
-      throw new TypeError('canonicalHash: expected a Dataset (e.g. one entry of graphs())');
+  async function canonicalHash(data, options) {
+    const hashOf = (e, ds) => {
+      requireEntryFn(e, 'datasetCanonicalHash', 'canonicalHash');
+      return entryResult(e.datasetCanonicalHash(ds.handle), 'canonicalHash').hash;
+    };
+    if (data instanceof Dataset && options === undefined) {
+      data.size; // throws the disposed error
+      return hashOf(data._ctx.e, data);
     }
-    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 entryResult(c.e.datasetCanonicalHash(merged.handle), 'canonicalHash').hash;
-    } finally {
-      merged.dispose();
+    // The options are canonicalize()'s, checked by the engine's table for it.
+    const opts = await checkedOptions('canonicalize', optionsOf('canonicalize', options));
+    return withDataset(data, opts, 'canonicalHash', (c, ds) => hashOf(c.e, ds));
+  }
+
+  /**
+   * A new Dataset that holds the triples of every graph of `dataset`, all in
+   * the default graph (op datasetGraphAsDefault with the union of the
+   * graphs). With one entry of graphs(), it is that graph without its name.
+   * @param {Dataset} dataset
+   * @returns {Dataset}
+   */
+  function asDefaultGraph(dataset) {
+    if (!(dataset instanceof Dataset)) {
+      throw new TypeError('asDefaultGraph: expected a Dataset');
     }
+    dataset.size; // throws the disposed error
+    const c = dataset._ctx;
+    requireEntryFn(c.e, 'datasetGraphAsDefault', 'asDefaultGraph');
+    return c.wrap(entryResult(c.e.datasetGraphAsDefault(dataset.handle,
+      JSON.stringify({ type: 'union' })), 'asDefaultGraph'), {});
   }
 
   /**
@@ -930,6 +991,30 @@ function buildApi(driver) {
       }));
   }
 
+  /**
+   * The RDF merge of two datasets (RDF 1.1 Semantics section 5.2): a new
+   * Dataset that holds the quads of both, with the blank nodes of each input
+   * kept apart, so `_:b` in `a` and `_:b` in `b` are two blank nodes. The
+   * engine computes it (op datasetMerge, formal/lean4/Wasm/Ops/GraphNodes.lean,
+   * theorem mergeDatasets_isMerge); the prefixes are those of `a`, then those
+   * of `b` whose label `a` does not declare. A text argument is read as by
+   * parse() (`options.format`, `options.baseIRI`), in its own blank-node
+   * scope. Since 0.21.0 (https://github.com/danbri/factoidal/issues/1130).
+   * @param {Dataset|string|Array} a
+   * @param {Dataset|string|Array} b
+   * @param {{format?: string, baseIRI?: string}} [options] read text arguments
+   * @returns {Promise<Dataset>}
+   */
+  async function datasetMerge(a, b, options) {
+    // An engine built before the op refuses with op.unknown before the
+    // options are read (its option table has no row for this function).
+    requireEntryFn((await ctx()).e, 'datasetMerge', 'datasetMerge');
+    const opts = await checkedOptions('datasetMerge', optionsOf('datasetMerge', options));
+    return withDataset(a, opts, 'datasetMerge', (c, da) =>
+      withDataset(b, opts, 'datasetMerge', (_c, db) =>
+        c.wrap(entryResult(c.e.datasetMerge(da.handle, db.handle), 'datasetMerge'))));
+  }
+
   /**
    * A Dataset holding RDF/JS quads (op datasetFromQuadsJson). Each term is
    * sent as its components; the engine reads no text.
@@ -949,6 +1034,95 @@ function buildApi(driver) {
     await ctx();
   }
 
+  // The synchronous term functions (sameValue, syntaxFor, splitIri, ...) call
+  // the loaded engine: `await ready()`, or any other call, loads it first.
+  function loadedCtx(who, op = who) {
+    if (!ctxCache) {
+      throw new FactoidalError(
+        `${who}: the engine is not loaded yet. Await any @factoidal/core call first ` +
+        '(for example `await ready()`).', { code: 'op.unknown' });
+    }
+    requireEntryFn(ctxCache.e, op, who);
+    return ctxCache;
+  }
+
+  /**
+   * SPARQL 1.1 `=` on two RDF terms (sections 17.3 and 17.4.1.7), decided by
+   * the engine (L4Factoidal.SPARQL.sameValue;
+   * https://github.com/danbri/factoidal/issues/1052).
+   * @param {object|string} a an RDF/JS term or an N-Triples term string
+   * @param {object|string} b
+   * @returns {boolean|null} true: the same value; false: different values;
+   *   null: incomparable (the operator's type error)
+   */
+  function sameValue(a, b) {
+    const c = loadedCtx('sameValue');
+    const r = entryResult(c.e.sameValue(JSON.stringify(termToJson(a)),
+      JSON.stringify(termToJson(b))), 'sameValue');
+    return r.sameValue === 'true' ? true : (r.sameValue === 'false' ? false : null);
+  }
+
+  const iriText = (iri) => (typeof iri === 'string' ? iri : (iri && iri.value) || '');
+
+  /**
+   * The syntax of a document by its file name (or IRI path) and its media
+   * type, from the engine's table of W3C registrations
+   * (L4Factoidal.RDF.syntaxOfNames; https://github.com/danbri/factoidal/issues/1053).
+   * The media type wins when it is given; an unknown media type does not fall
+   * back to the name.
+   * @param {string|{fileName?: string, mediaType?: string}} what a file name or IRI,
+   *   or both names
+   * @returns {string|null} a syntax name of formats(), or null
+   */
+  function syntaxFor(what) {
+    const c = loadedCtx('syntaxFor');
+    const o = (typeof what === 'string') ? { fileName: what } : (what || {});
+    const r = entryResult(c.e.syntaxFor(String(o.fileName ?? ''), String(o.mediaType ?? '')), 'syntaxFor');
+    return r.syntax ?? null;
+  }
+
+  /**
+   * An IRI as a namespace and a local name: the local name is the longest
+   * suffix that is an XML NCName, '' when there is none
+   * (L4Factoidal.RDF.splitIriXml; https://github.com/danbri/factoidal/issues/1051 item 4).
+   * @param {string|{value: string}} iri
+   * @returns {{namespace: string, localName: string}}
+   */
+  function splitIri(iri) {
+    const c = loadedCtx('splitIri');
+    const r = entryResult(c.e.splitIri(iriText(iri)), 'splitIri');
+    return { namespace: r.namespace, localName: r.localName };
+  }
+
+  /** Is the text an XML NCName (Namespaces in XML 1.0, production [4])? */
+  function isNCName(text) {
+    const c = loadedCtx('isNCName');
+    return entryResult(c.e.isNCName(String(text)), 'isNCName').ncName === true;
+  }
+
+  /**
+   * The engine's vocabulary table: prefix, namespace and term local names of
+   * rdf, rdfs, xsd and owl, and the namespaces of foaf, dcterms, dc and schema
+   * (L4Factoidal.RDF.vocabularyTable; https://github.com/danbri/factoidal/issues/1051 item 5).
+   * @returns {Array<{prefix: string, namespace: string, terms: string[]}>}
+   */
+  function vocabularies() {
+    const c = loadedCtx('vocabularies');
+    return entryResult(c.e.vocabularies(), 'vocabularies').vocabularies;
+  }
+
+  /** The container membership property rdf:_n, n >= 1, as a NamedNode. */
+  function memberIri(n) {
+    const c = loadedCtx('memberIri');
+    return dataFactory.namedNode(entryResult(c.e.memberIri(String(n)), 'memberIri').iri);
+  }
+
+  /** The n of rdf:_n, or null for any other IRI. */
+  function memberOrdinal(iri) {
+    const c = loadedCtx('memberOrdinal');
+    return entryResult(c.e.memberOrdinal(iriText(iri)), 'memberOrdinal').ordinal ?? null;
+  }
+
   /** The engine's name tables (formats, regimes, query outputs, pack syntaxes). */
   async function engineTables() {
     return (await ctx()).tables();
@@ -1001,6 +1175,28 @@ function buildApi(driver) {
     return withDataset(data, opts, 'closure', (c, ds) => closureOnHandle(c, ds, regime));
   }
 
+  /**
+   * SPARQL 1.2 RL (SPARQL-RL) infer: apply a rule set to the default graph
+   * of `data` and answer the inference graph (the triples the rules derive,
+   * the rule set's DATA blocks included, that are not in `data`) as a new
+   * Dataset. The rule set is SPARQL-RL text (https://w3c.github.io/data-shapes/sparql12-rl/).
+   * A rule set that is not well-formed, not stratifiable, or has IMPORTS is
+   * refused. Engine op: datasetSparqlRlInfer.
+   * @param {Dataset|string|Array} data
+   * @param {string} rules
+   * @param {{format?: string, baseIRI?: string}} [options]
+   * @returns {Promise<Dataset>}
+   */
+  async function sparqlRlInfer(data, rules, options) {
+    const opts = await checkedOptions('sparqlRlInfer', optionsOf('sparqlRlInfer', options));
+    if (typeof rules !== 'string') throw new TypeError('sparqlRlInfer: rules must be a string');
+    return withDataset(data, opts, 'sparqlRlInfer(data)', (c, ds) => {
+      requireEntryFn(c.e, 'datasetSparqlRlInfer', 'sparqlRlInfer');
+      const r = entryResult(c.e.datasetSparqlRlInfer(ds.handle, rules), 'sparqlRlInfer');
+      return c.wrap(r, ds.prefixes);
+    });
+  }
+
   /**
    * RDFS or OWL 2 RL closure of the default graph, as a new Dataset.
    * @param {Dataset|string|Array} data
@@ -1533,6 +1729,136 @@ function buildApi(driver) {
       e.vcEd25519Verify(publicKeyHex, messageHex, signatureHex), 'vcEd25519Verify').valid;
   }
 
+  // -----------------------------------------------------------------
+  // XML Encryption 1.1 and JWE (https://github.com/danbri/factoidal/issues/1084,
+  // https://github.com/danbri/factoidal/issues/1085). Every decision is in
+  // Lean (formal/lean4/Wasm/Ops/XmlEnc.lean, Wasm/Ops/Jwe.lean); RSA, P-256
+  // and X25519 run in the wasm (HACL*). AES runs in this host's WebCrypto:
+  // runWithCipher (lib/cipher-host.mjs) answers each request the engine
+  // makes and calls the op again. This code converts bytes to base64 and
+  // draws random bytes; it reads no document and chooses nothing.
+  // -----------------------------------------------------------------
+
+  // The most random octets any of these ops reads (Jwe.randomBytesNeeded is
+  // at most 112; xmlEncrypt reads at most 76).
+  const CIPHER_RANDOM_BYTES = 112;
+
+  function bytesToBase64(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+      bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(bin);
+  }
+
+  function base64ToBytes(text) {
+    const bin = atob(text);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+
+  function randomBase64(n) {
+    const b = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(b);
+    return bytesToBase64(b);
+  }
+
+  // One op that may ask for AES: the engine's envelope after every request
+  // is answered; a refusal throws a FactoidalError.
+  async function cipherOp(fnName, what, args) {
+    const e = await entry();
+    requireEntryFn(e, fnName, what);
+    const res = await runWithCipher((a) => JSON.parse(e[fnName](JSON.stringify(a))), args);
+    return entryResult(JSON.stringify(res), fnName);
+  }
+
+  function checkKeys(fnName, keys) {
+    if (!Array.isArray(keys) || !keys.every((k) => k !== null && typeof k === 'object')) {
+      throw new TypeError(`${fnName}: keys must be an array of JWK objects`);
+    }
+  }
+
+  /**
+   * Decrypt every xenc:EncryptedData of an XML document (XML Encryption 1.1).
+   * Allowlist and key forms: API.md "XML Encryption and JWE".
+   * @param {string} document the XML document
+   * @param {{keys: object[], allowCbc?: boolean}} options private JWKs
+   *   (`kid` is the ds:KeyName); `allowCbc` admits aes128-cbc and aes256-cbc
+   * @returns {Promise<{document: string, canonical: string}>}
+   */
+  async function xmlDecrypt(document, options) {
+    if (typeof document !== 'string') throw new TypeError('xmlDecrypt: document must be a string');
+    const o = options || {};
+    checkKeys('xmlDecrypt', o.keys);
+    const r = await cipherOp('xmlDecrypt', 'XML decryption',
+      { document, keys: o.keys, allowCbc: o.allowCbc === true });
+    return { document: r.document, canonical: r.canonical };
+  }
+
+  /**
+   * Encrypt the document element (or, with `content`, its content) of an XML
+   * document for one recipient (XML Encryption 1.1, AES-GCM content).
+   * @param {string} document the XML document
+   * @param {{recipient: object, algorithm?: 'aes128-gcm'|'aes256-gcm',
+   *   keyTransport?: 'rsa-oaep-mgf1p'|'rsa-oaep-sha256', keyWrap?: 'kw-aes128'|'kw-aes256',
+   *   content?: boolean, saml?: boolean}} options `recipient` is a public JWK
+   *   (RSA, EC P-256, OKP X25519) or an `oct` key; `saml` wraps the result in
+   *   saml:EncryptedAssertion
+   * @returns {Promise<{document: string, canonical: string}>}
+   */
+  async function xmlEncrypt(document, options) {
+    if (typeof document !== 'string') throw new TypeError('xmlEncrypt: document must be a string');
+    const o = options || {};
+    if (o.recipient === null || typeof o.recipient !== 'object') {
+      throw new TypeError('xmlEncrypt: options.recipient must be a JWK object');
+    }
+    const args = { document, recipient: o.recipient, random: randomBase64(CIPHER_RANDOM_BYTES) };
+    for (const k of ['algorithm', 'keyTransport', 'keyWrap']) if (o[k] !== undefined) args[k] = o[k];
+    if (o.content === true) args.content = true;
+    if (o.saml === true) args.saml = true;
+    const r = await cipherOp('xmlEncrypt', 'XML encryption', args);
+    return { document: r.document, canonical: r.canonical };
+  }
+
+  /**
+   * Decrypt a JWE in the Compact Serialization (RFC 7516).
+   * @param {string} token the compact JWE
+   * @param {{jwk: object}} options the recipient's private JWK
+   * @returns {Promise<{header: object, plaintext: Uint8Array}>}
+   */
+  async function jweDecrypt(token, options) {
+    if (typeof token !== 'string') throw new TypeError('jweDecrypt: token must be a string');
+    const o = options || {};
+    if (o.jwk === null || typeof o.jwk !== 'object') throw new TypeError('jweDecrypt: options.jwk must be a JWK object');
+    const r = await cipherOp('jweDecrypt', 'JWE decryption', { token, jwk: o.jwk });
+    return { header: r.header, plaintext: base64ToBytes(r.plaintext) };
+  }
+
+  /**
+   * Encrypt to a JWE in the Compact Serialization (RFC 7516).
+   * @param {Uint8Array|string} plaintext bytes, or text written as UTF-8
+   * @param {{alg: string, enc: string, jwk: object, header?: object}} options
+   *   the recipient's public JWK (or the `oct` key for A128KW, A256KW, dir);
+   *   `header`: more protected header members
+   * @returns {Promise<string>} the compact JWE
+   */
+  async function jweEncrypt(plaintext, options) {
+    let bytes;
+    if (typeof plaintext === 'string') bytes = new TextEncoder().encode(plaintext);
+    else if (plaintext instanceof Uint8Array) bytes = plaintext;
+    else throw new TypeError('jweEncrypt: plaintext must be a Uint8Array or a string');
+    const o = options || {};
+    if (typeof o.alg !== 'string' || typeof o.enc !== 'string') {
+      throw new TypeError('jweEncrypt: options.alg and options.enc must be strings');
+    }
+    if (o.jwk === null || typeof o.jwk !== 'object') throw new TypeError('jweEncrypt: options.jwk must be a JWK object');
+    const args = { alg: o.alg, enc: o.enc, jwk: o.jwk, plaintext: bytesToBase64(bytes),
+      random: randomBase64(CIPHER_RANDOM_BYTES) };
+    if (o.header !== undefined) args.header = o.header;
+    return (await cipherOp('jweEncrypt', 'JWE encryption', args)).token;
+  }
+
   /**
    * Create an eddsa-rdfc-2022 Data Integrity proofValue over an
    * already-canonicalized document + proof config (entry_jsoo.ml's
@@ -2163,11 +2489,14 @@ function buildApi(driver) {
       // ops it actually has.
       shacl: has('shaclValidate'),
       shex: has('shexValidate'),
+      sparqlRl: has('datasetSparqlRlInfer'),
       owlClosure: has('owlClosure'),
       explain: has('explainGraph'),
       stages: has('stageList'),
       pipelineCheck: has('pipelineCheck'),
       pipelineCheckNodes: has('pipelineCheckNodes'),
+      graphCheck: has('graphCheckNodes'),
+      datasetMerge: has('datasetMerge'),
       entailment: has('queryRaw'),
       tableau: has('tableauMaterialise') && has('tableauDlInconsistent'),
       rml: has('rmlMap'),
@@ -2198,15 +2527,117 @@ function buildApi(driver) {
       turtlePrefixes: has('serializeTurtleWith'),
       store: has('storeOpen') && has('storeHandleQuery'),
       deltaLog: has('deltaLogEncode') && has('deltaLogDecode') && has('deltaLogMerge'),
+      literalValues: has('literalValue') && has('literalFromValue'),
+      cid: has('cidValidate') && has('cidRetrieve'),
     };
   }
 
+  // ---------------------------------------------------------------
+  // Literal values (https://github.com/danbri/factoidal/issues/1051 items 1-3).
+  // The ops literalValue and literalFromValue (formal/lean4/Wasm/Ops/
+  // LiteralValue.lean, over L4Factoidal.RDF.LiteralValue) make every
+  // decision: the XSD lexical-to-value mapping, validity, the canonical form,
+  // the datatype of a JavaScript value. These functions are SYNCHRONOUS, so a
+  // library-style API can call them in a getter; the engine must be loaded
+  // first (await ready(), or any other call).
+  // ---------------------------------------------------------------
+  function loadedEntry(who) {
+    if (!ctxCache) {
+      throw new FactoidalError(
+        `${who}: the engine is not loaded yet. Await any @factoidal/core call ` +
+        'first (for example `await ready()`); after that this function is synchronous.',
+        { code: 'op.unknown' });
+    }
+    return ctxCache.e;
+  }
+
+  function literalAnswer(term, who) {
+    if (!term || typeof term !== 'object' || term.termType !== 'Literal') {
+      throw new TypeError(`${who}: expected an RDF/JS Literal term`);
+    }
+    const e = loadedEntry(who);
+    requireEntryFn(e, 'literalValue', who);
+    return entryResult(e.literalValue(JSON.stringify(termToJson(term))), who);
+  }
+
+  // NaN and the infinities have no JSON number; the engine names them in
+  // `special`, and this copies the matching JavaScript number in.
+  const SPECIAL_NUMBERS = { NaN: NaN, INF: Infinity, '-INF': -Infinity };
+  function valueOut(v) {
+    if (v && typeof v.special === 'string' && v.special in SPECIAL_NUMBERS) {
+      return { ...v, number: SPECIAL_NUMBERS[v.special] };
+    }
+    // A JSON text -0 may reach this layer as 0; negativeZero is the engine's
+    // statement of the sign.
+    if (v && v.negativeZero === true) return { ...v, number: -0 };
+    return v;
+  }
+
+  /**
+   * The value of a literal: {datatype, recognized, valid, value?, canonical?}.
+   * `recognized` false: the engine has no lexical space for the datatype, and
+   * `valid` is null. `value` and `canonical` are present for a valid literal
+   * of a datatype with a value model (the shapes are in API.md).
+   */
+  function literalValue(term) {
+    const r = literalAnswer(term, 'literalValue');
+    const out = { datatype: r.datatype, recognized: r.recognized,
+      valid: r.recognized ? r.valid : null };
+    if (r.value !== undefined) out.value = valueOut(r.value);
+    if (r.canonical !== undefined) out.canonical = r.canonical;
+    return out;
+  }
+
+  /** true or false: the lexical form is in the datatype's lexical space;
+   * null: the engine has no lexical space for the datatype. */
+  function isValidLiteral(term) {
+    const r = literalAnswer(term, 'isValidLiteral');
+    return r.recognized ? r.valid : null;
+  }
+
+  /** The literal with the canonical lexical form of its value (XSD 1.1 Part 2
+   * section 2.3.1), the same datatype and language; null when the literal is
+   * not valid or the engine has no canonical mapping for its datatype. */
+  function canonicalLiteral(term) {
+    const r = literalAnswer(term, 'canonicalLiteral');
+    if (r.canonical === undefined) return null;
+    if (term.language) return dataFactory.literal(r.canonical, term.direction
+      ? { language: term.language, direction: term.direction } : term.language);
+    return dataFactory.literal(r.canonical, dataFactory.namedNode(r.datatype));
+  }
+
+  /**
+   * The literal of a JavaScript value. The engine chooses the datatype (table
+   * in API.md) unless `options.datatype` names one (an IRI, a NamedNode, or
+   * an XSD built-in local name such as 'int'); the value must then be in that
+   * datatype's value space, else a FactoidalError with code literal.value.
+   */
+  function literalFromValue(value, options) {
+    const who = 'literalFromValue';
+    const tagged = encodeJsValue(value);
+    if (!tagged) {
+      throw new TypeError(`${who}: expected a boolean, number, bigint, string or Date`);
+    }
+    const dt = options && options.datatype;
+    const hint = dt === undefined || dt === null ? ''
+      : (typeof dt === 'string' ? dt : (dt && typeof dt.value === 'string' ? dt.value : null));
+    if (hint === null) throw new TypeError(`${who}: options.datatype must be a string or a NamedNode`);
+    const e = loadedEntry(who);
+    requireEntryFn(e, 'literalFromValue', who);
+    const r = entryResult(e.literalFromValue(JSON.stringify(tagged), hint), who);
+    return dataFactory.literal(r.value, dataFactory.namedNode(r.datatype));
+  }
+
   // The node-composition API (lib/nodes.mjs, issue 1002 step 2).
   const nodeApi = buildNodes({
     entry, entryResult, requireEntryFn, Dataset,
-    parse, closure, shaclValidate, query, serialize, canonicalize, explain, csvwToRdf,
+    parse, closure, shaclValidate, query, serialize, canonicalize, canonicalHash, explain, csvwToRdf,
+    datasetMerge,
   });
 
+  // Controlled Identifiers v1.0 (lib/cid.mjs, issue 1100 items 7 and 9).
+  const cid = cidFunctions({ entry, entryResult, requireEntryFn, host: driver.cidHost });
+
   return {
     parse,
     query,
@@ -2224,8 +2655,10 @@ function buildApi(driver) {
     canonicalize,
     graphs,
     canonicalHash,
+    asDefaultGraph,
     shaclValidate,
     shexValidate,
+    sparqlRlInfer,
     owlClosure,
     coreRdfsClosure,
     coreRdfsCheck,
@@ -2233,6 +2666,7 @@ function buildApi(driver) {
     stages: nodeApi.stages,
     node: nodeApi.node,
     pipe: nodeApi.pipe,
+    graph: nodeApi.graph,
     run: nodeApi.run,
     rdfsPlusClosure,
     rhoDfClosure,
@@ -2267,12 +2701,18 @@ function buildApi(driver) {
     vcEd25519SecretToPublic,
     vcEd25519Sign,
     vcEd25519Verify,
+    xmlDecrypt,
+    xmlEncrypt,
+    jweDecrypt,
+    jweEncrypt,
     vcEddsaCreateFromCanonical,
     vcEddsaVerifyFromCanonical,
     vcCheckCredential,
     vcCheckCredentialSubject,
     vcCheckNoDataLoss,
     vcCheckRelatedResourceDigests,
+    cidValidate: cid.cidValidate,
+    cidRetrieveVerificationMethod: cid.cidRetrieveVerificationMethod,
     capabilities,
     openStore,
     queryStore,
@@ -2286,9 +2726,21 @@ function buildApi(driver) {
     _deltaLogCorruptLastForTest,
     queryRaw,
     isomorphic,
+    datasetMerge,
     fromQuads,
+    literalValue,
+    isValidLiteral,
+    canonicalLiteral,
+    literalFromValue,
     ready,
     engineTables,
+    sameValue,
+    syntaxFor,
+    splitIri,
+    isNCName,
+    vocabularies,
+    memberIri,
+    memberOrdinal,
     Dataset,
     Store,
     FactoidalError,