@factoidal/core 0.11.0 → 0.13.0

package/browser.d.ts

@@ -5,6 +5,8 @@
 // system, so a path string rejects.
 
 export type {
+  FactoidalErrorCode,
+  FactoidalErrorPosition,
   NamedNode, BlankNode, Literal, Variable, DefaultGraph, Quad, Term, DataFactory,
   DataFormat, EntailRegime, Bindings, DataInput, QueryInput, ParseOptions,
   QueryOptions, SerializeOptions, StoreReader, OpenStoreOptions,
@@ -89,9 +91,8 @@ export {
   didKeyResolve,
   capabilities,
   Dataset,
-  DatasetHandle,
   Store,
-  ParseError,
+  FactoidalError,
   dataFactory,
   version,
   engine,

package/browser.js

@@ -153,9 +153,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/fn.js

@@ -252,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 {
@@ -260,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
@@ -354,24 +354,20 @@ async function query(ds, sparql, options) {
  * per-graph closure semantics that the underlying query() does not
  * define today.
  */
-// The regime names, their case-insensitive aliases and the x-ikl-* refusal
-// are the engine's tables (op engineTables): no host copy
+// 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 reports it.
-async function regimeOf(regime, who) {
+// 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);
-  for (const [prefix, message] of Object.entries(t.refusedRegimePrefixes)) {
-    if (r.toLowerCase().startsWith(prefix)) {
-      throw new TypeError(message.replace('WHO', who).replace('REGIME', r));
-    }
-  }
   return t.entailAliases[r.toLowerCase()] || regime;
 }
 
 async function entail(ds, regime) {
   assertFnDataset(ds, 'entail');
-  const entailRegime = await regimeOf(regime, 'entail');
+  const entailRegime = await regimeOf(regime);
   const rows = await engineApi.query((await engineOf(ds)), 'SELECT ?s ?p ?o WHERE { ?s ?p ?o }',
     { entail: entailRegime });
   return makeFnDataset(

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(
@@ -624,11 +680,16 @@ export function tableauDlInconsistent(
 ): Promise<{ inconsistent: boolean; rlAlone: boolean }>;
 
 /**
- * OWL DL consistency verdict via the clash-detecting tableau
- * (L4Factoidal/OWL/Refute.lean) over the OWL RL closure.
- * Default graph only. `consistent` is three-valued: `false` (a clash on
- * every branch), `true` (a model built), or `null` -- a budget-out, with
- * `reason` naming the fuel cap (never a silent false).
+ * Checked consistency for the original default graph in a restricted
+ * atomic OWL fragment (named subclass/class assertions, Thing/Nothing,
+ * sameAs/differentFrom and limited declarations/annotations).
+ * false requires an accepted certificate; null means unsupported-syntax
+ * or incomplete-search. No model producer exists, so true is not returned.
+ * Named graphs do not contribute axioms. RDF 1.2 terms are refused.
+ * This narrows earlier unchecked coverage: restrictions, object/data
+ * property axioms, imports and equivalentClass are unsupported.
+ * fuel is retained for compatibility but does not change this fixed
+ * 64-round certificate check. This is not complete OWL DL support.
  */
 export function owlIsConsistent(
   data: DataInput,
@@ -638,8 +699,13 @@ export function owlIsConsistent(
 /**
  * OWL entailment check: does `premise` entail `conclusion`? Two paths: `via: "closure"` (the conclusion is in the OWL-RL
  * closure of the premise) or `via: "refutation"` (the negated
- * conclusion is refuted on every goal). Default graph only. `entailed` is `true`, `false`, or `null`
- * (a refutation budget-out, with `reason` naming the cap).
+ * conclusion is refuted on every goal). Default graph only. The current
+ * implementation returns `true` for those positive results and `null`
+ * when it cannot establish entailment. `reason` distinguishes budget-out,
+ * incomplete-search, unsupported-conclusion and unsupported-punning.
+ * No checked countermodel constructor exists, so it never returns `false`.
+ * The punning refusal is limited; full OWL DL recognition and universal
+ * Direct Semantics soundness are not established by this API.
  */
 export function owlEntails(
   premise: DataInput,
@@ -1257,7 +1323,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;
@@ -1267,7 +1333,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;
@@ -1401,9 +1467,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

@@ -137,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 = "15eb8d770829";
+const WASM_VERSION = "1b55f66d8e19";
 
 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-d83100e6ec03-web",
-  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/39574221615",
-  "gitSha": "d83100e6ec038328a71a245e9fd10fbd768a38a5",
-  "builtAt": "2026-10-21T09:44:37Z",
+  "release": "danbri/factoidal-builds build-6f5b96407a4c-web",
+  "releaseRun": "https://github.com/danbri/factoidal-builds/actions/runs/40076270080",
+  "gitSha": "6f5b96407a4cd95ac7452256ed2d4b9c938a7c49",
+  "builtAt": "2026-10-24T08:40:08Z",
   "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": "15eb8d770829f3f07dad4f8eabbbaf4503f55104a1803cb87209d05d093dc642",
-  "wasmBytes": 12362890,
+  "wasmSha256": "1b55f66d8e193c6a3d168838bd77e8a5b1accb94e0a7c84209b63429f4989396",
+  "wasmBytes": 14483288,
   "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"