@factoidal/core 0.10.0 → 0.12.0

package/fn.js

@@ -27,7 +27,8 @@ const engineApi = require('./index.js');
 const {
   DatasetCore,
   dataFactory,
-  quadToNQuads,
+  quadKey,
+  termKey,
   quadsToNQuads,
 } = require('./rdfjs.js');
 
@@ -132,7 +133,7 @@ function makeFnDataset(quadsIterable) {
   const out = [];
   for (const q of quadsIterable) {
     const frozen = dataFactory.fromQuad(q); // normalizes + (re)freezes
-    const key = quadToNQuads(frozen);
+    const key = quadKey(frozen); // RDF/JS Term.equals identity, no syntax
     if (seen.has(key)) continue;
     seen.add(key);
     out.push(frozen);
@@ -210,7 +211,7 @@ async function engineOf(ds) {
   if (ds._backend.engine) return ds._backend.engine;
   let eds = ENGINE_CACHE.get(ds);
   if (!eds) {
-    eds = await engineApi.openDataset({ text: quadsToNQuads(ds.toArray()), format: 'nquads' });
+    eds = await engineApi.fromQuads(ds.toArray());
     ENGINE_CACHE.set(ds, eds);
   }
   return eds;
@@ -251,7 +252,7 @@ function builder() {
   let finished = false;
   return {
     addChunk(chunk) {
-      if (finished) throw new Error('builder: addChunk() called after finish()');
+      if (finished) throw new engineApi.FactoidalError('builder: addChunk() called after finish()', { code: 'op.failed' });
       if (chunk && typeof chunk.termType === 'string') {
         pending.push(chunk); // a single Quad
       } else {
@@ -259,7 +260,7 @@ function builder() {
       }
     },
     finish() {
-      if (finished) throw new Error('builder: finish() already called');
+      if (finished) throw new engineApi.FactoidalError('builder: finish() already called', { code: 'op.failed' });
       finished = true;
       const result = makeFnDataset(pending);
       pending = null; // release; no further mutation is possible anyway
@@ -297,8 +298,8 @@ function union(a, b) {
 /** Quads in a that are not in b. */
 function difference(a, b) {
   assertFnDataset(a, 'difference'); assertFnDataset(b, 'difference');
-  const bKeys = new Set(b.toArray().map(quadToNQuads));
-  return makeFnDataset(a.toArray().filter((q) => !bKeys.has(quadToNQuads(q))));
+  const bKeys = new Set(b.toArray().map(quadKey));
+  return makeFnDataset(a.toArray().filter((q) => !bKeys.has(quadKey(q))));
 }
 
 /** Keep quads matching quadPred(quad) => boolean. */
@@ -353,64 +354,22 @@ async function query(ds, sparql, options) {
  * per-graph closure semantics that the underlying query() does not
  * define today.
  */
-// Case-insensitive regime aliases ('rdfs', 'owl-rl', 'owlrl', 'owl_rl')
-// normalized to the engine's exact-case ENTAIL_VALUES spelling ('RDFS',
-// 'OWL-RL'); anything else (including already-correct casing, or a value
-// that names no regime) passes through unchanged, so engineApi.query's own
-// validation reports the error and this function does not guess what the
-// caller meant.
-const ENTAIL_REGIME_ALIASES = {
-  none: 'none', rdfs: 'RDFS', 'owl-rl': 'OWL-RL', owlrl: 'OWL-RL', owl_rl: 'OWL-RL',
-};
-
-function normalizeEntailRegime(regime) {
-  const key = String(regime == null ? 'none' : regime).toLowerCase();
-  return ENTAIL_REGIME_ALIASES[key] || regime;
-}
-
-// x-ikl-* is NOT IMPLEMENTED. It is not withheld by policy.
-//
-// CORRECTION 2026-08-26: an earlier version of this comment said the
-// family was withheld by owner decision, citing the direction-B ruling
-// of https://github.com/danbri/factoidal/issues/618. That ruling was
-// about the IKL-to-RDF projection, not about this regime family, and
-// attributing it here misstated a decision the owner did not make.
-//
-// The x-ikl-* family is the OWNER'S design
-// (https://github.com/danbri/factoidal/issues/581). Its Lean dispatch
-// was deleted on 2026-08-26 as collateral of the projection purge
-// (https://github.com/danbri/factoidal/issues/626), not as its target.
-// The SEMANTICS survived: Unified/ClBridge.lean's asserted_merge_sound
-// is this regime's soundness statement -- lifting asserted named-graph
-// content into the default graph -- and it carries no naming scheme.
-// Restoring the family is a dispatch branch plus flipping this guard.
-//
-// The owner's own statement of what IKL does not supply, 2026-08-26:
-// no profiles, no entailment procedures, no mapping from RDF datasets.
-// Checked the same day against the IKL GUIDE and Hayes 2009: correct.
-//
-// engineApi.query() (lib/api.js) already rejects this, but
-// normalizeEntailRegime() above passes any unrecognised string through
-// UNCHANGED before it gets there — check explicitly here too, so this
-// function's own contract states the rule rather than depending on a
-// downstream check someone could relax without noticing this call
-// site. Case-insensitive, any suffix; see test/select.test.js.
-function rejectIklRegime(regime, who) {
-  if (regime != null && /^x-ikl/i.test(String(regime))) {
-    throw new TypeError(
-      `${who}: entail '${regime}' is not implemented. The x-ikl-* ` +
-      'entailment regimes are the owner\'s design ' +
-      '(danbri/factoidal#581); the Lean engine\'s dispatch for them was ' +
-      'deleted on 2026-08-26 as collateral of the IKL-to-RDF projection ' +
-      'purge (danbri/factoidal#626). This is not a policy exclusion.');
-  }
+// The regime names and their case-insensitive aliases are the engine's tables
+// (op engineTables): no host copy
+// (https://github.com/danbri/factoidal/issues/894 item 5). A name with no
+// alias passes through unchanged and engineApi.query refuses it with the
+// engine's code (regime.refused for x-ikl-*, option.invalid-value otherwise).
+async function regimeOf(regime) {
+  const t = await engineApi.engineTables();
+  const r = regime == null ? 'none' : String(regime);
+  return t.entailAliases[r.toLowerCase()] || regime;
 }
 
 async function entail(ds, regime) {
   assertFnDataset(ds, 'entail');
-  rejectIklRegime(regime, 'entail');
+  const entailRegime = await regimeOf(regime);
   const rows = await engineApi.query((await engineOf(ds)), 'SELECT ?s ?p ?o WHERE { ?s ?p ?o }',
-    { entail: normalizeEntailRegime(regime) });
+    { entail: entailRegime });
   return makeFnDataset(
     rows.map((row) => dataFactory.quad(row.get('s'), row.get('p'), row.get('o'))));
 }
@@ -696,60 +655,34 @@ function peekHash(ds) {
   return typeof c === 'string' ? c : null;
 }
 
-function hasBlankNode(ds) {
-  for (const q of ds) {
-    if (q.subject.termType === 'BlankNode') return true;
-    if (q.object.termType === 'BlankNode') return true;
-    if (q.graph.termType === 'BlankNode') return true;
-  }
-  return false;
-}
-
 /**
- * Structural equality, cheapest-correct-path first (see the design
- * doc's cost model section for the full argument):
- *
- *  1. Different sizes -> not equal, O(1).
- *  2. Both sides already have a memoized hash -> compare those, O(1).
- *  3. Exact quad-set match (same terms, same labels) -> equal, O(n).
- *     This is sound regardless of blank nodes: identical tokens can
- *     never be a false positive.
- *  4. No blank nodes anywhere -> the step-3 negative is authoritative
- *     (ground quads have no relabeling to hide behind) -> not equal.
- *  5. Otherwise (blank nodes present, step 3 was inconclusive) ->
- *     the only sound test left is RDFC-1.0 canonical-hash equality,
- *     which is exactly the O(n log n) canonicalize() cost this module
- *     tries to avoid paying twice.
+ * Dataset isomorphism (RDF 1.1 Concepts 3.6 and 4, blank nodes inside RDF
+ * 1.2 triple terms included), decided by the engine
+ * (Dataset.isomorphicOutcome, op datasetIsomorphic). The same FnDataset is
+ * equal to itself without a call.
  */
 async function equals(a, b) {
   assertFnDataset(a, 'equals'); assertFnDataset(b, 'equals');
   if (a === b) return true;
-  if (a.size !== b.size) return false;
-  const ha = peekHash(a);
-  const hb = peekHash(b);
-  if (ha !== null && hb !== null) return ha === hb;
-  const aKeys = new Set(a.toArray().map(quadToNQuads));
-  const bTokens = b.toArray().map(quadToNQuads);
-  const exact = bTokens.length === aKeys.size &&
-    bTokens.every((t) => aKeys.has(t));
-  if (exact) return true;
-  if (!hasBlankNode(a) && !hasBlankNode(b)) return false;
-  const [h1, h2] = await Promise.all([hash(a), hash(b)]);
-  return h1 === h2;
+  return engineApi.isomorphic(await engineOf(a), await engineOf(b));
 }
 
 /**
- * Enumerate named graphs (default graph excluded), first-seen order.
- * Reuses index.js's graphs() enumeration; wraps each per-graph
- * Dataset back into an FnDataset.
+ * Enumerate named graphs (default graph excluded), first-seen order. An
+ * engine-backed dataset asks the engine (op datasetGraphNames); an array of
+ * JS quads groups by RDF/JS Term.equals identity, so an IRI and a blank node
+ * with the same string are two graphs.
  */
 function graphs(ds) {
   assertFnDataset(ds, 'graphs');
+  if (ds._backend.engine) {
+    return engineApi.graphs(ds._backend.engine).map(([name, g]) => [name, wrapEngine(g)]);
+  }
   const seen = new Map();
   for (const q of ds) {
-    if (q.graph.termType !== 'DefaultGraph' && !seen.has(q.graph.value)) seen.set(q.graph.value, q.graph);
+    if (q.graph.termType !== 'DefaultGraph' && !seen.has(termKey(q.graph))) seen.set(termKey(q.graph), q.graph);
   }
-  return [...seen].map(([iri, g]) => [iri, ds.match(null, null, null, g)]);
+  return [...seen.values()].map((g) => [g, ds.match(null, null, null, g)]);
 }
 
 // ---------------------------------------------------------------------

package/index.d.ts

@@ -84,27 +84,85 @@ export interface DataFactory {
 export const dataFactory: DataFactory;
 
 /**
- * A parse failure that carries a position (issue #344): `line`/
- * `column`/`offset` are set when the failing engine call reported one
- * (Turtle, TriG, N-Triples, N-Quads); `undefined` for an RDF/XML or
- * JSON-LD failure, or any non-parse engine error, which stay a plain
- * `Error`. `name` is `'ParseError'`.
+ * The stable error codes. The engine decides the code of every refusal
+ * (formal/lean4/Wasm/Ops/ErrorModel.lean); `engineTables().errorCodes` lists
+ * each with its specification section and summary, and the README table
+ * "Errors" is generated from that list. `host.io` is a failure of
+ * the host (file system, IndexedDB), not of the engine.
  */
-export class ParseError extends Error {
-  readonly name: 'ParseError';
-  /** 1-based line of the error. */
-  readonly line?: number;
-  /** 1-based column of the error, counted in Unicode scalar values. */
-  readonly column?: number;
+export type FactoidalErrorCode =
+  | 'parse.syntax'
+  | 'parse.rdf12-required'
+  | 'term.invalid-iri'
+  | 'term.invalid-langtag'
+  | 'term.invalid'
+  | 'query.syntax'
+  | 'query.failed'
+  | 'update.syntax'
+  | 'update.failed'
+  | 'format.unknown'
+  | 'serialize.unsupported-rdf12'
+  | 'serialize.failed'
+  | 'canon.unsupported-rdf12'
+  | 'canon.failed'
+  | 'owl.unsupported-rdf12'
+  | 'reason.failed'
+  | 'regime.refused'
+  | 'validate.failed'
+  | 'xml.failed'
+  | 'crypto.failed'
+  | 'store.failed'
+  | 'registry.failed'
+  | 'handle.unknown'
+  | 'handle.disposed'
+  | 'option.unknown'
+  | 'option.invalid-value'
+  | 'option.conflict'
+  | 'capacity.exceeded'
+  | 'call.arity'
+  | 'call.arguments'
+  | 'op.unknown'
+  | 'op.failed'
+  | 'host.io';
+
+/** Where in the input a FactoidalError happened. */
+export interface FactoidalErrorPosition {
+  /** 1-based line. */
+  line: number;
+  /** 1-based column, counted in Unicode scalar values. */
+  column: number;
   /**
-   * The position of the error as a UTF-16 code-unit index into the input
-   * JavaScript string: `text.slice(err.offset)` starts at the error. A
-   * character outside the Basic Multilingual Plane (U+10000 and above)
-   * counts 2, as in every JavaScript string index. (The engine reports a
-   * count of Unicode scalar values; the wrapper converts.)
+   * A UTF-16 code-unit index into the input JavaScript string:
+   * `text.slice(err.position.offset)` starts at the error.
    */
-  readonly offset?: number;
+  offset: number;
+  /** The same position as a count of UTF-8 bytes from the start of the input. */
+  byteOffset: number;
+}
+
+/**
+ * The one error class of the package. Every function rejects (or throws)
+ * with it; a `TypeError` is thrown only when an argument has the wrong
+ * JavaScript type. The engine decides `code`, `spec` and `position`.
+ */
+export class FactoidalError extends Error {
+  constructor(message: string, info?: {
+    code?: FactoidalErrorCode; position?: FactoidalErrorPosition | null;
+    spec?: string | null; cause?: unknown; format?: string; formatInferred?: boolean;
+  });
+  readonly name: 'FactoidalError';
+  /** The stable machine code. */
+  readonly code: FactoidalErrorCode;
+  /** Where the input defines a position (a parse, a query, an update), else null. */
+  readonly position: FactoidalErrorPosition | null;
+  /** The URL of the specification section that defines the condition, else null. */
+  readonly spec: string | null;
+  /** The underlying error, when there is one (host.io). */
+  readonly cause?: unknown;
+  /** For a parse failure of text: the syntax it was read as. */
   readonly format?: string;
+  /** For a parse failure of text: true when the syntax was inferred. */
+  readonly formatInferred?: boolean;
 }
 
 /** One recoverable-parse diagnostic from a `{lenient:true}` parse() call. */
@@ -112,7 +170,7 @@ export interface ParseDiagnostic {
   message: string;
   /**
    * The position of the error as a UTF-16 code-unit index into the input
-   * JavaScript string, as ParseError.offset: `text.slice(d.offset)` starts
+   * JavaScript string, as FactoidalError.position.offset: `text.slice(d.offset)` starts
    * at the error.
    */
   offset: number;
@@ -222,8 +280,6 @@ export class Dataset implements Iterable<Quad> {
   [Symbol.dispose](): void;
 }
 
-/** @deprecated The name of Dataset before 0.10.0; removed in 0.11.0. */
-export const DatasetHandle: typeof Dataset;
 
 export type ClosureRegime = 'rdfs' | 'owl-rl' | 'rho-df' | 'rdfs-plus';
 
@@ -302,7 +358,7 @@ export interface ParseOptions {
    * entry per skipped statement. RDF/XML and JSON-LD parse strictly. A
    * document with no error gives the strict result and no diagnostics.
    * Default: false (strict; a syntax error, an undeclared prefix, or an
-   * unresolvable relative IRI rejects the whole parse with a ParseError).
+   * unresolvable relative IRI rejects the whole parse with a FactoidalError).
    */
   lenient?: boolean;
   /**
@@ -323,7 +379,7 @@ export interface QueryOptions extends DatasetQueryOptions {
  * order is sorted (canonical N-Quads order), not document order;
  * anonymous blank-node labels (`_anonN`) DO reflect document order.
  * See README.md's "Blank nodes, labels and statement order". Strict
- * by default (issue #344): a syntax error rejects with a ParseError
+ * by default (issue #344): a syntax error rejects with a FactoidalError
  * (`line`/`column`/`offset` for Turtle/TriG/N-Triples/N-Quads; a
  * message only for RDF/XML and JSON-LD). `options.lenient` recovers
  * instead; see ParseOptions.
@@ -337,7 +393,7 @@ export function parse(text: string, options?: ParseOptions | DataFormat): Promis
  * Concise Bounded Description of each resource named). A `SERVICE <iri>`
  * whose IRI no registerServiceEndpoint() call named answers no
  * solutions even without SILENT
- * (https://github.com/danbri/factoidal/issues/717). `data` may be a DatasetHandle
+ * (https://github.com/danbri/factoidal/issues/717). `data` may be a Dataset
  * from openDataset(), in which case this routes to `data.query()` and
  * `options.entail` must be 'none' or omitted (a handle carries no
  * entailment-closure step).
@@ -447,7 +503,7 @@ export function serialize(
 /**
  * RDFC-1.0 dataset canonicalization: canonical blank-node labels plus
  * sorted canonical N-Quads. Two isomorphic inputs canonicalize to the
- * same string. `data` may be a DatasetHandle, in which case this
+ * same string. `data` may be a Dataset, in which case this
  * routes to `data.canonicalize()` (options are ignored for a handle).
  */
 export function canonicalize(
@@ -462,7 +518,7 @@ export function canonicalize(
  * `graph` is the same Dataset filtered to that one graph name (what
  * `dataset.match(null, null, null, graphTerm)` would return).
  */
-export function graphs(dataset: Dataset): Array<[iri: string, graph: Dataset]>;
+export function graphs(dataset: Dataset): Array<[name: NamedNode | BlankNode, graph: Dataset]>;
 
 /**
  * RDFC-1.0 canonical form of a single graph -- the graph-scoped
@@ -476,6 +532,23 @@ export function graphs(dataset: Dataset): Array<[iri: string, graph: Dataset]>;
  */
 export function canonicalHash(datasetOrGraph: Dataset): Promise<string>;
 
+/**
+ * Whether two datasets are isomorphic (RDF 1.1 Concepts 3.6 and 4; blank
+ * nodes inside RDF 1.2 triple terms included). The engine decides
+ * (op datasetIsomorphic); rejects when its blank-node search budget is
+ * exceeded.
+ */
+export function isomorphic(a: DataInput, b: DataInput, options?: { format?: string; baseIRI?: string }): Promise<boolean>;
+
+/** 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>;
+
+/** The engine's name tables: format names, entailment regimes, query outputs, pack syntaxes. */
+export function engineTables(): Promise<Record<string, unknown>>;
+
 /** A SHACL validation-report term (see shaclValidate). */
 export interface ShaclValidateResult {
   conforms: boolean;
@@ -1240,7 +1313,7 @@ export function capabilities(): Promise<{
   entailment: boolean;
   /** queryHdt() (op queryHdt) is served. */
   hdt: boolean;
-  /** query()'s `sparql12` and DatasetHandle.query's (queryDataset12, datasetQuery12). */
+  /** query()'s `sparql12` and Dataset.query's (queryDataset12, datasetQuery12). */
   sparql12: boolean;
   /** openStore() and the Store methods (storeOpen, storeHandleQuery). */
   store: boolean;
@@ -1250,7 +1323,7 @@ export function capabilities(): Promise<{
   profile: 'full' | string;
   /** The dispatch ABI version string of the loaded wasm module. */
   abiVersion: string;
-  /** openDataset()/DatasetHandle (datasetOpen/Query/Update/Serialize/Close) are present. */
+  /** openDataset()/Dataset (datasetOpen/Query/Update/Serialize/Close) are present. */
   datasetHandles: boolean;
   /** parse()'s `{lenient:true}` (parseDocument) is present. */
   parseDiagnostics: boolean;
@@ -1329,6 +1402,10 @@ declare const _default: {
   canonicalize: typeof canonicalize;
   graphs: typeof graphs;
   canonicalHash: typeof canonicalHash;
+  isomorphic: typeof isomorphic;
+  fromQuads: typeof fromQuads;
+  ready: typeof ready;
+  engineTables: typeof engineTables;
   shaclValidate: typeof shaclValidate;
   shexValidate: typeof shexValidate;
   owlClosure: typeof owlClosure;
@@ -1380,9 +1457,8 @@ declare const _default: {
   vcCheckRelatedResourceDigests: typeof vcCheckRelatedResourceDigests;
   capabilities: typeof capabilities;
   Dataset: typeof Dataset;
-  DatasetHandle: typeof DatasetHandle;
   Store: typeof Store;
-  ParseError: typeof ParseError;
+  FactoidalError: typeof FactoidalError;
   dataFactory: DataFactory;
   queryRaw: typeof queryRaw;
   version: string;

package/index.mjs

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

package/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 = "2347d124e551";
+const WASM_VERSION = "ec99e3524f1a";
 
 import createModule from './l4factoidal.mjs';