@factoidal/core 0.19.0 → 0.21.0

package/index.d.ts

@@ -99,6 +99,7 @@ export type FactoidalErrorCode =
   | 'term.invalid-iri'
   | 'term.invalid-langtag'
   | 'term.invalid'
+  | 'literal.value'
   | 'query.syntax'
   | 'query.failed'
   | 'update.syntax'
@@ -236,6 +237,10 @@ export interface FormatCapability {
   write12: boolean;
   /** 'core' when both engines serve it; 'full' when only the full engine does. */
   engine: 'core' | 'full';
+  /** The registered media types (W3C registration; empty for a row with none). syntaxFor() reads the same table. */
+  mediaTypes: string[];
+  /** The registered file extensions, with the leading dot ('.ttl'). */
+  extensions: string[];
 }
 
 /**
@@ -283,11 +288,31 @@ export class Dataset implements Iterable<Quad> {
   toString(formatOrOptions?: WriteFormat | WriteOptions): string;
   toNQuads(): string;
   clone(): Dataset;
-  /** RDF/JS DatasetCore (https://rdf.js.org/dataset-spec/); match and has use the engine indexes. */
-  has(quad: Quad): boolean;
+  /**
+   * RDF/JS DatasetCore (https://rdf.js.org/dataset-spec/); match and has use
+   * the engine indexes. `{match: 'value'}`: a literal object matches every
+   * object literal that is the same term or has the same value (sameValue());
+   * the other positions match by term.
+   */
+  has(quad: Quad, options?: MatchOptions): boolean;
   add(quad: Quad): this;
-  delete(quad: Quad): this;
-  match(subject?: Term | null, predicate?: Term | null, object?: Term | null, graph?: Term | null): Dataset;
+  /** With `{match: 'value'}`: remove every quad of the same subject, predicate
+   *  and graph whose object has the same value as the quad's literal object. */
+  delete(quad: Quad, options?: MatchOptions): this;
+  match(subject?: Term | null, predicate?: Term | null, object?: Term | null, graph?: Term | null,
+    options?: MatchOptions): Dataset;
+  /**
+   * The items of the RDF list (rdf:first/rdf:rest) at `head`, in order
+   * (https://github.com/danbri/factoidal/issues/1051 item 6). `rdf:nil` is
+   * the empty list. A list that is not well formed (a node with no or with two
+   * rdf:first or rdf:rest, or a cycle) is a FactoidalError, code `op.failed`.
+   * `graph`: omitted, null or the DefaultGraph for the default graph.
+   */
+  listItems(head: Term, graph?: Term | null): Term[];
+  /** The members rdf:_1, rdf:_2, ... of `node`, sorted by n, and its kind (rdf:Bag, rdf:Seq, rdf:Alt) from its rdf:type. */
+  containerItems(node: Term, graph?: Term | null): { kind: NamedNode | null; items: Array<{ ordinal: number; term: Term }> };
+  /** Add a new RDF list of `items` on fresh blank nodes; answers its head (rdf:nil for no items). */
+  addList(items: Iterable<Term>, graph?: Term | null): Term;
   toArray(): Quad[];
   [Symbol.iterator](): Iterator<Quad>;
   dispose(): void;
@@ -380,6 +405,12 @@ export interface ParseOptions {
    * with one diagnostic of class 'too-many-errors'. Default: no limit.
    */
   maxErrors?: number;
+  /**
+   * Read JSON-LD as JSON-LD-star (`@triple`, `@reifies`, `@annotation` as
+   * RDF 1.2 triple terms and reifiers), as `jsonldToRdf` does. Format
+   * 'jsonld' only (given or inferred); not with `lenient`. Default: false.
+   */
+  rdfstar?: boolean;
 }
 
 export interface QueryOptions extends DatasetQueryOptions {
@@ -499,6 +530,18 @@ export function closure(
   options?: { format?: DataFormat; baseIRI?: string }
 ): Promise<Dataset>;
 
+/**
+ * SPARQL 1.2 RL infer (https://w3c.github.io/data-shapes/sparql12-rl/): the
+ * inference graph of the rule set `rules` (SPARQL-RL text) over the default
+ * graph of `data`, as a new Dataset. Rejects when the rule set has a syntax
+ * error, is not well-formed or not stratifiable, or has IMPORTS.
+ */
+export function sparqlRlInfer(
+  data: DataInput,
+  rules: string,
+  options?: { format?: DataFormat; baseIRI?: string }
+): Promise<Dataset>;
+
 /** The syntaxes the engine reads and writes, from the engine (op datasetFormats). */
 export function formats(): Promise<FormatCapability[]>;
 
@@ -535,17 +578,31 @@ export function canonicalize(
 export function graphs(dataset: Dataset): Array<[name: NamedNode | BlankNode, graph: Dataset]>;
 
 /**
- * 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.
+ * 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. The engine computes the canonical form and the digest. 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 (for example one entry of graphs()), use
+ * canonicalHash(asDefaultGraph(g)). Rejects when the input holds an RDF 1.2
+ * triple term or the section 4.4 call budget is exceeded. The input is what
+ * canonicalize() takes: a Dataset, or text with `format` and `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.
  */
-export function canonicalHash(datasetOrGraph: Dataset): Promise<string>;
+export function canonicalHash(
+  data: Dataset | string | { text: string; format?: DataFormat; baseIRI?: string },
+  options?: { format?: DataFormat; baseIRI?: string },
+): Promise<string>;
+
+/**
+ * A new Dataset with the triples of every graph of `dataset`, all in the
+ * default graph (the engine's union of the graphs). With one entry of
+ * graphs(), it is that graph without its name. Dispose of it when done.
+ */
+export function asDefaultGraph(dataset: Dataset): Dataset;
 
 /**
  * Whether two datasets are isomorphic (RDF 1.1 Concepts 3.6 and 4; blank
@@ -555,15 +612,152 @@ export function canonicalHash(datasetOrGraph: Dataset): Promise<string>;
  */
 export function isomorphic(a: DataInput, b: DataInput, options?: { format?: string; baseIRI?: string }): Promise<boolean>;
 
+/**
+ * The RDF merge of two datasets (RDF 1.1 Semantics 5.2): the quads of both,
+ * with the blank nodes of each input kept apart (`_:b` in `a` and `_:b` in
+ * `b` are two blank nodes). The engine computes it (op datasetMerge, Lean
+ * theorem mergeDatasets_isMerge). Prefixes: those of `a`, then those of `b`
+ * whose label `a` does not declare. Since 0.21.0.
+ */
+export function datasetMerge(a: DataInput, b: DataInput, options?: { format?: string; baseIRI?: string }): Promise<Dataset>;
+
 /** A Dataset holding RDF/JS quads; each term is sent to the engine as its components. */
 export function fromQuads(quads: Iterable<Quad>): Promise<Dataset>;
 
 /** Load the engine. Afterwards the N-Quads text functions of `@factoidal/core/rdfjs` work. */
 export function ready(): Promise<void>;
 
+// ---------------------------------------------------------------------
+// Literal values (https://github.com/danbri/factoidal/issues/1051 items 1-3).
+// Synchronous after the engine is loaded (`await ready()` or any other call);
+// before that they throw a FactoidalError. The engine decides everything
+// (formal/lean4/L4Factoidal/RDF/LiteralValue.lean). API.md "Literal values".
+// ---------------------------------------------------------------------
+
+/**
+ * The value of a literal, as JSON-safe data. A number that a JavaScript
+ * number may not hold exactly is a decimal string; `number` is present only
+ * when the value is exactly a binary64 value. Integer components are numbers
+ * when |n| <= 2^53 - 1, else decimal strings.
+ */
+export type LiteralValueData =
+  | { kind: 'string' | 'anyURI'; string: string }
+  | { kind: 'boolean'; boolean: boolean }
+  | { kind: 'decimal'; decimal: string; integer: boolean; number?: number }
+  | { kind: 'float' | 'double'; decimal?: string; number: number;
+      negativeZero?: true; special?: 'NaN' | 'INF' | '-INF' }
+  | { kind: 'duration'; months: number | string; seconds: string }
+  | { kind: 'dateTime' | 'time' | 'date' | 'gYearMonth' | 'gYear' | 'gMonthDay' | 'gDay' | 'gMonth';
+      year?: number | string; month?: number; day?: number; hour?: number;
+      minute?: number; second?: string; timezoneOffset?: number }
+  | { kind: 'hexBinary' | 'base64Binary'; hex: string }
+  | { kind: 'QName' | 'NOTATION'; prefix: string; localName: string }
+  | { kind: 'list'; items: LiteralValueData[] }
+  | { kind: 'langString'; string: string; language: string; direction?: 'ltr' | 'rtl' };
+
+export interface LiteralValueResult {
+  /** The datatype IRI. */
+  datatype: string;
+  /** false: the engine has no lexical space for this datatype. */
+  recognized: boolean;
+  /** The lexical form is in the lexical space (null when not recognized). */
+  valid: boolean | null;
+  /** Present for a valid literal of a datatype with a value model. */
+  value?: LiteralValueData;
+  /** The canonical lexical form (XSD 1.1 Part 2 section 2.3.1), when known. */
+  canonical?: string;
+}
+
+/** The XSD lexical-to-value mapping of a literal (RDF 1.1 Semantics section 7: no whiteSpace processing). */
+export function literalValue(term: Literal): LiteralValueResult;
+
+/** Whether the lexical form is in the datatype's lexical space; null when the engine has no lexical space for the datatype. */
+export function isValidLiteral(term: Literal): boolean | null;
+
+/** The literal with the canonical form of its value; null when it is not valid or has no canonical mapping. */
+export function canonicalLiteral(term: Literal): Literal | null;
+
+/**
+ * The literal of a JavaScript value. With no datatype the engine's table
+ * chooses: boolean xsd:boolean, string xsd:string, bigint xsd:integer, a safe
+ * integer Number xsd:integer, any other Number xsd:double, Date xsd:dateTime
+ * (UTC). `datatype` (an IRI, a NamedNode, or an XSD local name such as 'int')
+ * names the datatype; the value must be in its value space, else a
+ * FactoidalError with code 'literal.value'.
+ */
+export function literalFromValue(
+  value: boolean | number | bigint | string | Date,
+  options?: { datatype?: string | NamedNode }
+): Literal;
+
 /** The engine's name tables: format names, entailment regimes, query outputs, pack syntaxes. */
 export function engineTables(): Promise<Record<string, unknown>>;
 
+/**
+ * How Dataset.has, match and delete compare the object position
+ * (https://github.com/danbri/factoidal/issues/1052). 'term' (the default):
+ * RDF term equality. 'value': a literal object matches by value (sameValue()).
+ */
+export interface MatchOptions {
+  match?: 'term' | 'value';
+}
+
+/**
+ * SPARQL 1.1 `=` on two RDF terms (sections 17.3 and 17.4.1.7), decided by the
+ * engine: `true` the same value (`"01"^^xsd:integer` and `"1.0"^^xsd:decimal`),
+ * `false` different values, `null` incomparable (the operator's type error:
+ * two different literals of an unknown datatype, an ill-typed literal and
+ * another literal, `xsd:integer` and `xsd:boolean`). `"NaN"^^xsd:double` is
+ * not the same value as itself. A term is an RDF/JS term or an N-Triples term
+ * string. Synchronous: the engine must be loaded (`await ready()`).
+ */
+export function sameValue(a: Term | string, b: Term | string): boolean | null;
+
+/**
+ * The syntax of a document by its file name (or IRI path; the query and the
+ * fragment are ignored) and its media type, from the engine's table of the
+ * W3C registrations (https://github.com/danbri/factoidal/issues/1053): Turtle
+ * `text/turtle` `.ttl`, N-Triples `application/n-triples` `.nt`, N-Quads
+ * `application/n-quads` `.nq`, TriG `application/trig` `.trig`, RDF/XML
+ * `application/rdf+xml` `.rdf`, JSON-LD `application/ld+json` `.jsonld`. The
+ * media type wins when it is given (its parameters are ignored); an unknown
+ * media type does not fall back to the name. Answers a `name` of formats(),
+ * or `null`. Synchronous: the engine must be loaded (`await ready()`).
+ */
+export function syntaxFor(what: string | { fileName?: string; mediaType?: string }): string | null;
+
+/**
+ * An IRI as a namespace and a local name: the local name is the longest
+ * suffix that is an XML NCName (what an RDF/XML QName can carry), `''` when
+ * there is none; `namespace + localName` is the IRI
+ * (https://github.com/danbri/factoidal/issues/1051 item 4). Synchronous.
+ */
+export function splitIri(iri: string | NamedNode): { namespace: string; localName: string };
+
+/** Is the text an XML NCName (Namespaces in XML 1.0, production [4])? A prefix label check. Synchronous. */
+export function isNCName(text: string): boolean;
+
+/** One row of the engine's vocabulary table. A term IRI is `namespace + term`. */
+export interface VocabularyRow {
+  prefix: string;
+  namespace: string;
+  /** Local names; empty for a namespace whose vocabulary is not in the engine table. */
+  terms: string[];
+}
+
+/**
+ * The engine's vocabulary table (https://github.com/danbri/factoidal/issues/1051
+ * item 5): rdf, rdfs, xsd and owl with their terms; foaf, dcterms, dc and
+ * schema as namespaces only. The prefixes are those of the Turtle writer. Synchronous.
+ */
+export function vocabularies(): VocabularyRow[];
+
+/** The container membership property `rdf:_n` (n >= 1). Synchronous. */
+export function memberIri(n: number): NamedNode;
+
+/** The `n` of `rdf:_n` (no leading zero, n >= 1), or `null` for any other IRI. Synchronous. */
+export function memberOrdinal(iri: string | NamedNode): number | null;
+
 /** A SHACL validation-report term (see shaclValidate). */
 export interface ShaclValidateResult {
   conforms: boolean;
@@ -758,23 +952,43 @@ export interface EvidenceRecord {
   outside?: OutsideSetting[];
 }
 
-/** The value on a wire. */
+/**
+ * The value on a wire. After a node, `graph` is a value of the node's
+ * `wireOut`: a Dataset for the graph wires, text for String (a writer), the
+ * rows for Table (SELECT), a boolean for Answer (ASK), `[canonical, sha256]`
+ * for String × String (rdfcStage), the report object for ValidationReport,
+ * the explain result for ExplainGraphResult. Since 0.20.0; before, a node
+ * whose output was not a Dataset left its input on the wire.
+ */
 export interface Wire<G = unknown> {
   graph: G;
   evidence: EvidenceRecord[];
 }
 
+/** An input port of a node: its name and its wire. */
+export interface NodePort {
+  readonly name: string;
+  readonly wire: string;
+}
+
 /** A node: a registered stage with its parameters. */
 export interface FactoidalNode {
   readonly stage: string;
   readonly kind: string | null;
   /** The engine's status of this node with its settings (see NodeStatus). */
   readonly status: NodeStatus;
-  /** The registry status of the stage. */
-  readonly registryStatus: StageInfo['status'];
+  /** The registry status of the stage; null for a stage with more than one port (not a registry entry). */
+  readonly registryStatus: StageInfo['status'] | null;
   readonly contract: string | null;
   readonly assumptions: readonly string[];
-  readonly wireIn: string;
+  /**
+   * The input ports: one port 'in' for a registry stage; for a stage with
+   * more than one port (datasetMerge: 'left', 'right'), the engine's list
+   * (op graphCheckNodes). Such a node runs only in graph().
+   */
+  readonly ports: readonly NodePort[];
+  /** The input wire of a one-port stage; null for a stage with more than one port. */
+  readonly wireIn: string | null;
   /**
    * The output wire with these settings: for shippedEvaluator, 'Table' for
    * SELECT, 'Answer' for ASK, 'Dataset' for CONSTRUCT and DESCRIBE (Lean
@@ -783,7 +997,12 @@ export interface FactoidalNode {
   readonly wireOut: string;
   readonly runnable: boolean;
   readonly bound: boolean;
-  /** The settings as given (passed to the package function that runs the stage). */
+  /**
+   * The node's own copy of the settings as given (passed to the package
+   * function that runs the stage): frozen at every depth, a Dataset cloned,
+   * taken when node() checked them. A later change to the caller's objects
+   * does not reach the node; a change to a Dataset here makes run() refuse.
+   */
   readonly params: Readonly<Record<string, unknown>>;
   /** The settings as sent to the engine: JSON values, a Dataset as {$nquads}. */
   readonly settingsWire: Readonly<Record<string, unknown>>;
@@ -869,17 +1088,91 @@ export function stages(): Promise<StageInfo[]>;
  */
 export function node(name: string, params?: Record<string, unknown>): Promise<FactoidalNode>;
 
-/** Compose nodes and pipelines left to right. */
+/** Compose nodes and pipelines left to right. A node with more than one input port throws a TypeError (use graph()). */
 export function pipe(...nodes: Array<FactoidalNode | Pipeline>): Pipeline;
 
+/** Where a port's value comes from: graph input `input`, or the output of node `node` (an earlier node). */
+export type GraphSource = { readonly input: number } | { readonly node: number };
+
+/** The request of graph(). */
+export interface GraphSpec {
+  /** The wire of each graph input: a wire label of stages() (e.g. 'String', 'Dataset'). */
+  inputs?: string[];
+  /** The nodes in order; `from` has one source per input port of the node. */
+  nodes: Array<{ node: FactoidalNode; from: GraphSource[] }>;
+}
+
+/** An issue of the engine's static check of a graph (op graphCheckNodes, Lean graphIssues). */
+export type GraphIssue =
+  | { readonly kind: 'unknownInput'; readonly node: number; readonly port: number; readonly portName: string; readonly input: number }
+  | { readonly kind: 'forwardRef'; readonly node: number; readonly port: number; readonly portName: string; readonly ref: number }
+  | { readonly kind: 'portCount'; readonly node: number; readonly ports: number; readonly sources: number }
+  | { readonly kind: 'wireMismatch'; readonly node: number; readonly port: number; readonly portName: string; readonly source: string; readonly portWire: string };
+
+/** The engine's check of a graph with no issue (op graphCheckNodes). */
+export interface GraphCheck {
+  readonly issues: readonly GraphIssue[];
+  /** The output wire of the last node. */
+  readonly wireOut: string | null;
+  /** The union of the nodes' named assumptions: the premises of Graph.guarantee_sound. */
+  readonly assumptions: readonly string[];
+  readonly contract: { readonly theorem: string; readonly staticCheck: string };
+  readonly nodes: readonly {
+    readonly name: string; readonly kind: string | null; readonly status: NodeStatus;
+    /** null for a stage with more than one port (not a registry entry). */
+    readonly registryStatus: StageInfo['status'] | null;
+    readonly checked: boolean; readonly contract: string | null;
+    readonly theorems: readonly string[]; readonly assumptions: readonly string[];
+    readonly ports: readonly NodePort[]; readonly wireOut: string;
+    readonly settings: Record<string, unknown>; readonly settingsDigest: string;
+    readonly roles: Readonly<Record<string, string>>;
+    readonly outside: readonly OutsideSetting[];
+    readonly derived: Readonly<Record<string, string>>;
+  }[];
+}
+
+/** A graph from graph(): checked by the engine, with no issue. */
+export interface FactoidalGraph {
+  readonly inputs: readonly string[];
+  readonly nodes: readonly { readonly node: FactoidalNode; readonly from: readonly GraphSource[] }[];
+  readonly wireOut: string | null;
+  readonly assumptions: readonly string[];
+  readonly check: GraphCheck;
+}
+
+/** The result of run() on a graph. */
+export interface GraphRunResult<G = unknown> extends RunResult<G> {
+  /** The output of each node, in order; `graph` is the last one. */
+  values: unknown[];
+  issues: GraphIssue[];
+}
+
+/**
+ * A pipeline that is an acyclic graph of nodes with named input ports
+ * (https://github.com/danbri/factoidal/issues/1130). The engine's op
+ * graphCheckNodes checks it: a graph with an issue throws a FactoidalError
+ * (code 'op.failed') whose `issues` is the engine's list; an engine without
+ * the op throws code 'op.unknown'. Since 0.21.0.
+ */
+export function graph(spec: GraphSpec): FactoidalGraph;
+
 /**
  * Run a node or pipeline on `input` (a Wire, or the graph: text for a
  * reader, else a Dataset or data input). Rejects before any node runs when
  * a node's stage has status 'missing' (unless `options.unchecked`) or has
- * no package function, or when the engine's check finds the pipeline not
- * well typed (unless `options.unchecked`; then `proved` is false).
+ * no package function, when the engine's check finds the pipeline not
+ * well typed (unless `options.unchecked`; then `proved` is false), or when a
+ * node's settings changed after node() checked them. Rejects with code
+ * 'op.failed' when a node's runner gives a value that is not of the node's
+ * `wireOut` (see Wire).
  */
 export function run(pipeline: FactoidalNode | Pipeline, input: unknown, options?: RunOptions): Promise<RunResult>;
+/**
+ * Run a graph on `inputs`, one value per graph input. Each node runs on the
+ * values of its sources (a node with more than one port gets them in port
+ * order); one evidence record per node, with `node` (its index) and `from`.
+ */
+export function run(graph: FactoidalGraph, inputs: unknown[], options?: RunOptions): Promise<GraphRunResult>;
 
 /** Literature-name alias for coreRdfsClosure (ρdf). */
 export function rhoDfClosure(
@@ -1191,6 +1484,12 @@ export interface Sbm11Store {
   /** the generation CURRENT names, or "" when the source is a generation */
   generation: string;
   terms: number;
+  /** how the engine checks reads; undefined from a wasm module built before the Merkle check */
+  verify: 'merkle' | 'none' | undefined;
+  /** the SHA-256 of the bytes of manifest.sbm11, 64 lowercase hex digits, as
+   * the engine computed it at open (pin it, then give it as
+   * `manifestSha256`); undefined from a wasm module built before issue 1105 */
+  manifestSha256: string | undefined;
   query(sparql: string, options?: { base?: string; sparql12?: boolean; reference?: boolean }): Sbm11Answer;
   /** the resources the reader read, when its reader records them (lwsSbm11Reader) */
   readonly evidence: Sbm11ReadEvidence[] | undefined;
@@ -1198,8 +1497,16 @@ export interface Sbm11Store {
 }
 
 /** Open an SBM11 generation (https://github.com/danbri/factoidal/issues/1009).
- * Node: `source` is a directory unless a reader is given or registered. */
-export function openSbm11(source: string, options?: { reader?: Sbm11Reader }): Promise<Sbm11Store>;
+ * Node: `source` is a directory unless a reader is given or registered.
+ * `verify` (default 'merkle'): the engine checks every byte it decodes against
+ * the manifest's Merkle roots and refuses a changed file with its name;
+ * 'none' checks lengths only.
+ * `manifestSha256`: the trust anchor, the SHA-256 of the bytes of
+ * manifest.sbm11 as 64 hex digits (https://github.com/danbri/factoidal/issues/1105);
+ * the engine refuses the open when the manifest has another digest. */
+export function openSbm11(source: string, options?: {
+  reader?: Sbm11Reader; verify?: 'merkle' | 'none'; manifestSha256?: string
+}): Promise<Sbm11Store>;
 
 /** Serve `source` with `reader`; `null` removes it. */
 export function registerSbm11Source(source: string, reader: Sbm11Reader | null): void;
@@ -1563,6 +1870,45 @@ export function vcEd25519Verify(
   signatureHex: string
 ): Promise<boolean>;
 
+/**
+ * Decrypt every xenc:EncryptedData of an XML document (XML Encryption 1.1).
+ * RSA-OAEP, ECDH-ES and X25519 run in the wasm (HACL*); AES runs in the
+ * host's WebCrypto. Every failure after the structure check is the one
+ * error "XML decryption failed".
+ */
+export function xmlDecrypt(
+  document: string,
+  options: { keys: object[]; allowCbc?: boolean }
+): Promise<{ document: string; canonical: string }>;
+
+/** Encrypt an XML document element, or its content, for one recipient. */
+export function xmlEncrypt(
+  document: string,
+  options: {
+    recipient: object;
+    algorithm?: 'aes128-gcm' | 'aes256-gcm';
+    keyTransport?: 'rsa-oaep-mgf1p' | 'rsa-oaep-sha256';
+    keyWrap?: 'kw-aes128' | 'kw-aes256';
+    content?: boolean;
+    saml?: boolean;
+  }
+): Promise<{ document: string; canonical: string }>;
+
+/**
+ * Decrypt a compact JWE (RFC 7516). Every failure after the allowlist is
+ * the one error "decryption failed".
+ */
+export function jweDecrypt(
+  token: string,
+  options: { jwk: object }
+): Promise<{ header: Record<string, unknown>; plaintext: Uint8Array }>;
+
+/** Encrypt to a compact JWE (RFC 7516). */
+export function jweEncrypt(
+  plaintext: Uint8Array | string,
+  options: { alg: string; enc: string; jwk: object; header?: Record<string, unknown> }
+): Promise<string>;
+
 /**
  * Create an eddsa-rdfc-2022 Data Integrity proofValue (multibase-z,
  * base58btc) over already-canonicalized inputs — RDFC-1.0 canonical
@@ -1631,6 +1977,70 @@ export function vcCheckRelatedResourceDigests(
   credentialJson: string
 ): Promise<{ valid: boolean; reason?: string }>;
 
+/** One failed MUST of CID 1.0 §2 (cidValidate). */
+export interface CidValidationError {
+  /** The engine's name of the failed MUST, e.g. 'idNotUrl', 'jwkPrivateMember'. */
+  code: string;
+  message: string;
+  /** RFC 6901 JSON Pointer to the member, e.g. '/verificationMethod/1/publicKeyJwk/d'; '' is the whole document. */
+  path: string;
+}
+
+/**
+ * Controlled Identifiers v1.0 §2 (https://www.w3.org/TR/cid-1.0/): check a
+ * controlled identifier document. `valid` is the engine's answer
+ * (L4Factoidal.CID.parseDocument); `errors` lists every failed MUST it found,
+ * empty when valid. Issue 1100 item 9.
+ */
+export function cidValidate(doc: string | object): Promise<{ valid: boolean; errors: CidValidationError[] }>;
+
+/** An RFC 9457 problem details object. */
+export interface CidProblem {
+  /** https://w3id.org/security#<NAME> for a §3.5 error; a tag: URI for the others. */
+  type: string;
+  title: string;
+  detail: string;
+}
+
+export interface CidRetrieveOptions {
+  /**
+   * GET the URL the engine names. Called as fetch(url, init) with
+   * init.headers.accept, init.redirect 'manual' and, when the engine chose
+   * one, init.address (the address to connect to). Answers a Response, or
+   * { status, headers: { get(name) }, text() }. Default: Node and Deno
+   * connect to init.address; a browser uses the page's fetch.
+   */
+  fetch?: (url: string, init: { method: 'GET'; headers: { accept: string }; redirect: 'manual'; address?: string }) =>
+    Promise<{ status: number; headers: { get(name: string): string | null }; text(): Promise<string> }>;
+  /** Every address of a host name. Default: the system resolver (Node, Deno); none in a browser. null: none. */
+  resolve?: ((host: string) => Promise<string[]>) | null;
+  /** Refuse a method that has expired or been revoked at this time (a Date, or seconds since the epoch). */
+  now?: Date | number;
+  /** Allow an http document URL (default: https only). */
+  allowHttp?: boolean;
+  /** Allow loopback, link-local, private and localhost addresses (default: refused). */
+  allowPrivateFetch?: boolean;
+}
+
+/**
+ * Controlled Identifiers v1.0 §3.3 Retrieve Verification Method. The engine
+ * names each fetch and decides each answer (the private-address guard of the
+ * authorization server, the status, the Content-Type: application/cid,
+ * application/cid+json, application/ld+json or application/json, then §3.3);
+ * this function does the fetch. Never rejects for a failed retrieval: it
+ * answers `ok: false` with the §3.5 name (or FETCH_REFUSED, FETCH_FAILED,
+ * UNSUPPORTED_MEDIA_TYPE, VERIFICATION_METHOD_NOT_IN_FORCE) and an RFC 9457
+ * object. Issue 1100 items 7 and 9.
+ */
+export function cidRetrieveVerificationMethod(
+  url: string,
+  relationship: 'authentication' | 'assertionMethod' | 'keyAgreement' | 'capabilityInvocation' | 'capabilityDelegation',
+  options?: CidRetrieveOptions
+): Promise<
+  | { ok: true; verificationMethod: Record<string, unknown>; controllerDocument: string }
+  | { ok: false; code: string; problem: CidProblem }
+>;
+
 /**
  * Feature probe: which ops the loaded wasm module serves. A module older
  * than this package can lack some; an operation whose op is missing
@@ -1645,6 +2055,8 @@ export function capabilities(): Promise<{
   canonicalHash: boolean;
   shacl: boolean;
   shex: boolean;
+  /** the engine has the SPARQL 1.2 RL op (datasetSparqlRlInfer) */
+  sparqlRl: boolean;
   owlClosure: boolean;
   explain: boolean;
   stages: boolean;
@@ -1652,6 +2064,10 @@ export function capabilities(): Promise<{
   pipelineCheck: boolean;
   /** The op pipelineCheckNodes: node settings in evidence, and the evaluator's output wire from the query form. */
   pipelineCheckNodes: boolean;
+  /** The op graphCheckNodes: graph() and run() of a graph, and node('datasetMerge'). */
+  graphCheck: boolean;
+  /** The op datasetMerge: datasetMerge(). */
+  datasetMerge: boolean;
   tableau: boolean;
   rml: boolean;
   csvw: boolean;
@@ -1679,6 +2095,10 @@ export function capabilities(): Promise<{
   store: boolean;
   /** The deltaLog* functions (deltaLogEncode, deltaLogDecode, deltaLogMerge). */
   deltaLog: boolean;
+  /** ops literalValue and literalFromValue (issue 1051). */
+  literalValues: boolean;
+  /** ops cidValidate and cidRetrieve (issue 1100). */
+  cid: boolean;
   /** 'full': the whole library is in the wasm module. */
   profile: 'full' | string;
   /** The dispatch ABI version string of the loaded wasm module. */
@@ -1757,15 +2177,24 @@ declare const _default: {
   update: typeof update;
   openDataset: typeof openDataset;
   closure: typeof closure;
+  sparqlRlInfer: typeof sparqlRlInfer;
   formats: typeof formats;
   serialize: typeof serialize;
   canonicalize: typeof canonicalize;
   graphs: typeof graphs;
   canonicalHash: typeof canonicalHash;
+  asDefaultGraph: typeof asDefaultGraph;
   isomorphic: typeof isomorphic;
   fromQuads: typeof fromQuads;
   ready: typeof ready;
   engineTables: typeof engineTables;
+  sameValue: typeof sameValue;
+  syntaxFor: typeof syntaxFor;
+  splitIri: typeof splitIri;
+  isNCName: typeof isNCName;
+  vocabularies: typeof vocabularies;
+  memberIri: typeof memberIri;
+  memberOrdinal: typeof memberOrdinal;
   shaclValidate: typeof shaclValidate;
   shexValidate: typeof shexValidate;
   owlClosure: typeof owlClosure;
@@ -1809,18 +2238,28 @@ declare const _default: {
   vcEd25519SecretToPublic: typeof vcEd25519SecretToPublic;
   vcEd25519Sign: typeof vcEd25519Sign;
   vcEd25519Verify: typeof vcEd25519Verify;
+  xmlDecrypt: typeof xmlDecrypt;
+  xmlEncrypt: typeof xmlEncrypt;
+  jweDecrypt: typeof jweDecrypt;
+  jweEncrypt: typeof jweEncrypt;
   vcEddsaCreateFromCanonical: typeof vcEddsaCreateFromCanonical;
   vcEddsaVerifyFromCanonical: typeof vcEddsaVerifyFromCanonical;
   vcCheckCredential: typeof vcCheckCredential;
   vcCheckCredentialSubject: typeof vcCheckCredentialSubject;
   vcCheckNoDataLoss: typeof vcCheckNoDataLoss;
   vcCheckRelatedResourceDigests: typeof vcCheckRelatedResourceDigests;
+  cidValidate: typeof cidValidate;
+  cidRetrieveVerificationMethod: typeof cidRetrieveVerificationMethod;
   capabilities: typeof capabilities;
   Dataset: typeof Dataset;
   Store: typeof Store;
   FactoidalError: typeof FactoidalError;
   dataFactory: DataFactory;
   queryRaw: typeof queryRaw;
+  literalValue: typeof literalValue;
+  isValidLiteral: typeof isValidLiteral;
+  canonicalLiteral: typeof canonicalLiteral;
+  literalFromValue: typeof literalFromValue;
   version: string;
   engine: string;
 };