rdf-reasoner-konclude 0.1.0

package/LICENSE

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/NOTICE

@@ -0,0 +1,44 @@
+rdf-reasoner-konclude
+=====================
+
+TypeScript wrapper and build scripts: GNU Lesser General Public License v3.
+Copyright (c) 2026 Thomas Hanke. See LICENSE.
+
+-------------------------------------------------------------------------------
+Third-party component: Konclude OWL-DL Reasoning Kernel
+-------------------------------------------------------------------------------
+
+The file dist/konclude.wasm is compiled from the Konclude reasoning kernel,
+which is copyright (c) University of Ulm and released under the GNU Lesser
+General Public License v3.0 (LGPLv3).
+
+  Liebig, T., Jaeger, M., Möller, R., & Möller, B. (2014).
+  Konclude: System Description.
+  Web Semantics, 27–28, 78–85. doi:10.1016/j.websem.2014.06.003
+
+As required by LGPLv3 §4, the complete Konclude source with all applied
+modifications is available at:
+
+  https://github.com/ThHanke/rdf-reasoner-konclude
+
+Clone with --recurse-submodules to obtain vendor/konclude/ (the Konclude source)
+and patches/ (every modification applied to it). To recompile the WASM binary:
+
+  git clone --recurse-submodules https://github.com/ThHanke/rdf-reasoner-konclude
+  docker compose run --rm build
+
+The full text of the LGPLv3 is available at:
+  https://www.gnu.org/licenses/lgpl-3.0.txt
+
+-------------------------------------------------------------------------------
+Development acknowledgement: Claude (Anthropic)
+-------------------------------------------------------------------------------
+
+This WebAssembly port — including the Qt-elimination shim layer, Emscripten
+build pipeline, threading architecture, TypeScript API, and test suite — was
+developed with substantial AI assistance from Claude, an AI assistant made by
+Anthropic (https://www.anthropic.com).
+
+The reasoning algorithm, correctness, and all intellectual property of the
+Konclude OWL-DL reasoner belong entirely to its original authors at the
+University of Ulm.

package/README.md

@@ -0,0 +1,253 @@
+# rdf-reasoner-konclude
+
+[![npm version](https://img.shields.io/npm/v/rdf-reasoner-konclude)](https://www.npmjs.com/package/rdf-reasoner-konclude)
+[![license](https://img.shields.io/badge/license-LGPL--3.0--or--later-blue)](LICENSE)
+
+OWL-DL tableau reasoning via [Konclude](https://github.com/konclude/Konclude) compiled to WebAssembly, with an async TypeScript API using RDF.js Quad types.
+
+## Installation
+
+```bash
+npm install rdf-reasoner-konclude n3
+```
+
+`n3` is a required peer dependency (used for NTriples serialization/deserialization).
+
+## Node.js quick-start
+
+```typescript
+import { RdfReasoner, INFERRED_GRAPH_IRI } from 'rdf-reasoner-konclude';
+import { Store, Parser } from 'n3';
+
+// Load your ontology into an N3 Store
+const store = new Store();
+const parser = new Parser({ format: 'Turtle' });
+parser.parse(`
+  @prefix owl: <http://www.w3.org/2002/07/owl#> .
+  @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+  :A rdfs:subClassOf :B .
+  :B rdfs:subClassOf :C .
+`, (err, quad) => { if (quad) store.addQuad(quad); });
+
+const reasoner = new RdfReasoner();
+await reasoner.ready;
+
+await reasoner.reason(store);
+
+// Inferred triples are written into the INFERRED_GRAPH_IRI named graph
+const inferred = store.getQuads(null, null, null, INFERRED_GRAPH_IRI);
+console.log(inferred.map(q => `${q.subject.value} → ${q.object.value}`));
+// e.g. [ ':A → :C' ]  (transitive subClassOf)
+
+reasoner.terminate();
+```
+
+No Worker setup needed — Node.js 18+ picks up the `"node"` export condition which installs a `worker_threads` shim automatically.
+
+## Browser / Vite quick-start
+
+```typescript
+import { RdfReasoner, INFERRED_GRAPH_IRI } from 'rdf-reasoner-konclude';
+import { Store } from 'n3';
+
+const store = new Store(/* ... your quads ... */);
+const reasoner = new RdfReasoner();
+await reasoner.ready;
+
+await reasoner.reason(store);
+
+const inferred = store.getQuads(null, null, null, INFERRED_GRAPH_IRI);
+```
+
+The browser build requires COOP/COEP HTTP headers for `SharedArrayBuffer` (used by pthreads). See [Browser Deployment](#browser-deployment) for server configuration.
+
+## API reference
+
+### `RdfReasoner`
+
+```typescript
+const reasoner = new RdfReasoner();
+await reasoner.ready;              // resolves when WASM module is loaded
+
+await reasoner.reason(store);      // classify + write inferred triples into store
+await reasoner.classify(store);    // alias for reason(store)
+const ok = await reasoner.checkConsistency(store); // returns boolean
+
+reasoner.terminate();              // shut down the Worker
+```
+
+`reason(store)` and `classify(store)` write inferred triples into the
+`INFERRED_GRAPH_IRI` named graph inside the store. The graph is cleared before
+each call — do not store ontology triples there.
+
+Named graphs in the input are dropped at the WASM boundary (NTriples wire
+format is triple-only). Reasoning runs over the union of all graphs.
+
+Options for `reason(store, opts)` and `classify(store, opts)`:
+
+```typescript
+interface StoreReasoningOptions {
+  inferredGraph?: string; // IRI of the named graph for inferred triples
+                          // default: INFERRED_GRAPH_IRI
+}
+```
+
+### `INFERRED_GRAPH_IRI`
+
+```typescript
+import { INFERRED_GRAPH_IRI } from 'rdf-reasoner-konclude';
+// "urn:konclude:inferred"
+```
+
+The default named graph where inferred triples are written by `reason(store)`.
+
+### Deprecated overloads
+
+`reason(quads: Iterable<Quad>)` and `classify(quads)` / `checkConsistency(quads)` accept a raw `Iterable<Quad>` and return `Promise<Quad[]>` / `Promise<boolean>`. These overloads are deprecated — use the `Store`-based API instead.
+
+## Browser deployment
+
+The WASM binary uses pthreads, which requires `SharedArrayBuffer`. Browsers
+block `SharedArrayBuffer` unless the page is cross-origin isolated:
+
+```http
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+### Vite dev server
+
+```js
+// vite.config.js
+export default {
+  server: {
+    headers: {
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    },
+  },
+}
+```
+
+### nginx (production)
+
+```nginx
+add_header Cross-Origin-Opener-Policy same-origin;
+add_header Cross-Origin-Embedder-Policy require-corp;
+```
+
+### Caddy (production)
+
+```caddyfile
+header {
+    Cross-Origin-Opener-Policy same-origin
+    Cross-Origin-Embedder-Policy require-corp
+}
+```
+
+### webpack 5
+
+```js
+// webpack.config.js
+module.exports = { experiments: { asyncWebAssembly: true } }
+```
+
+## Performance
+
+Benchmarked on an 8-core Linux host. Native = Konclude v0.7.0 binary; TS = Node.js 20 via this package. Threads: 8 (both native and WASM pthreads).
+
+| Ontology | Expressivity | NTriples | Native classify | TS total | Ratio |
+| --- | --- | --- | --- | --- | --- |
+| LUBM schema | SHI | 307 | 35 ms | 266 ms | ~7.3× |
+| GALEN | SHIF | 30 817 | 225 ms | 941 ms | ~4.2× |
+| Roberts family | SROIQ | 3 866 | 1 801 ms | 2 603 ms | ~1.4× |
+| LUBM schema + data | SHI | 100 850 | 160 ms | 2 104 ms | ~13× |
+
+TS total includes NTriples serialization/deserialization (the main JS overhead).
+The WASM classify step alone is within 1.4×–7.3× of native. Run `npm run bench`
+to reproduce (requires a built WASM binary — see [Build from source](#build-from-source)).
+
+## How it works
+
+```text
+main thread
+  RdfReasoner.reason(store)
+    → serialize Store quads to NTriples (n3.js Writer)
+    → postMessage to Worker
+
+Worker (pthreads WASM)
+  → KoncludeReasoner::loadNTriples()     // NTriples → librdf model (Raptor2)
+  → mapTriples()                         // librdf → OWL expression model
+  → KoncludeReasoner::classify()         // OWL-DL tableau (KPSet, parallel)
+  → KoncludeReasoner::getInferredNTriples()
+    → postMessage result back
+
+main thread
+  → parse NTriples → Quad[] (n3.js Parser)
+  → write into store[INFERRED_GRAPH_IRI]
+```
+
+The WASM binary is compiled from Konclude's C++ tableau engine with Qt removed
+(replaced by `std::` shims) and pthreads enabled. The KPSet classifier requires
+real threads — cooperative dispatch deadlocks.
+
+## Build from source
+
+Requires Docker. First build (Raptor2 + librdf cross-compile + kernel) takes
+roughly 20–30 minutes. Subsequent runs use ccache and skip already-built libs.
+
+```bash
+# 1. Populate submodule and pre-apply Qt-removal patches
+git submodule update --init
+bash scripts/apply-patches.sh
+
+# 2. Cross-compile Raptor2/librdf for WASM and build the kernel
+docker compose run --rm build
+
+# 3. Verify
+docker compose run --rm smoke-test
+
+# 4. Compile TypeScript
+npm run build
+```
+
+Incremental rebuild (Raptor/librdf already built):
+
+```bash
+docker compose run --rm build
+```
+
+Interactive shell:
+
+```bash
+docker compose run --rm shell
+```
+
+## Licence
+
+The TypeScript wrapper and build scripts in this repository are licensed under
+**LGPL-3.0-or-later**. See [LICENSE](LICENSE).
+
+The WASM binary (`dist/konclude.wasm`) contains the Konclude reasoning kernel,
+which is © University of Ulm and also released under **LGPLv3**.
+
+As required by LGPLv3 §4, complete Konclude source with all applied
+modifications is available at:
+
+<https://github.com/ThHanke/rdf-reasoner-konclude>
+
+Clone with `--recurse-submodules` to obtain `vendor/konclude/` (Konclude source)
+and `patches/` (every modification). To recompile: `docker compose run --rm build`.
+
+See [NOTICE](NOTICE) for full third-party notices.
+
+> Liebig, T., Jaeger, M., Möller, R., & Möller, B. (2014). *Konclude: System Description.*
+> Web Semantics, 27–28, 78–85. doi:10.1016/j.websem.2014.06.003
+
+## Acknowledgements
+
+Konclude was developed at the Institute of Artificial Intelligence, University
+of Ulm, by Thorsten Liebig, Murat Özcep, Stefan Wandelt, and others. All
+credit for the reasoning algorithm belongs to the Konclude authors. This
+package is an independent WebAssembly port developed with AI assistance from
+[Claude](https://anthropic.com) (Anthropic).

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Main thread TypeScript wrapper for the Konclude OWL-DL reasoner.
+ *
+ * `RdfReasoner` is the public API. It spawns a Web Worker running the WASM
+ * reasoning kernel and exposes:
+ *   - `ready` — resolves when the Worker has finished loading the WASM module
+ *   - `reason(quads, opts?)` — runs OWL-DL inference over the input quads
+ *   - `classify(quads)` — alias for reason(quads, {mode:'classify'})
+ *   - `checkConsistency(quads)` — checks whether the ontology is consistent
+ *   - `terminate()` — terminates the underlying Worker
+ *
+ * Named graphs in the input quads are silently dropped (NTriples is
+ * triple-only). All returned quads are placed in the DefaultGraph.
+ */
+import type { Quad } from "@rdfjs/types";
+import { Store } from "n3";
+export type { ReasoningOptions, ReasoningResult, StoreReasoningOptions } from "./types.js";
+export { INFERRED_GRAPH_IRI } from "./types.js";
+import type { ReasoningOptions, StoreReasoningOptions } from "./types.js";
+export declare class RdfReasoner {
+    /** Resolves when the Worker WASM module is ready; rejects on init failure. */
+    readonly ready: Promise<void>;
+    private readonly worker;
+    private nextId;
+    private readonly pending;
+    /**
+     * Serialization queue: each reason() / checkConsistency() call chains onto
+     * this promise so that concurrent calls never interleave their
+     * loadNTriples → classify → getInferredNTriples sequences.
+     */
+    private _queue;
+    constructor();
+    /**
+     * Send a method call to the Worker and return a Promise for the result.
+     */
+    private _call;
+    /** Run OWL-DL reasoning over a Store. Inferred triples are written into
+     *  `opts.inferredGraph` (default `INFERRED_GRAPH_IRI`). The graph is cleared
+     *  before each call. Concurrent calls are serialized. */
+    reason(store: Store, opts?: StoreReasoningOptions): Promise<void>;
+    /**
+     * @deprecated Use `reason(store)` instead.
+     *
+     * Run OWL-DL reasoning over the provided quads.
+     *
+     * Named graphs in the input are dropped (NTriples wire format is
+     * triple-only). All returned quads are in the DefaultGraph.
+     *
+     * Concurrent calls are serialized: each call waits for the previous one to
+     * complete before sending its first Worker message.
+     */
+    reason(quads: Iterable<Quad>, opts?: ReasoningOptions): Promise<Quad[]>;
+    private _reasonOnStore;
+    private _reasonOnQuads;
+    /** Classify a Store (alias for `reason(store)`). */
+    classify(store: Store, opts?: StoreReasoningOptions): Promise<void>;
+    /**
+     * @deprecated Use `classify(store)` instead.
+     *
+     * Classify the given quads (alias for `reason(quads, { mode: 'classify' })`).
+     *
+     * Returns the inferred rdfs:subClassOf quads in the default graph.
+     */
+    classify(quads: Iterable<Quad>): Promise<Quad[]>;
+    /** Check consistency of a Store. Does not write inferred triples. */
+    checkConsistency(store: Store): Promise<boolean>;
+    /**
+     * @deprecated Use `checkConsistency(store)` instead.
+     *
+     * Check whether the given quads form a consistent ontology.
+     *
+     * Internally: loadNTriples → classify → isConsistent.
+     *
+     * Concurrent calls are serialized: each call waits for the previous one to
+     * complete before sending its first Worker message.
+     */
+    checkConsistency(quads: Iterable<Quad>): Promise<boolean>;
+    /** Terminate the underlying Worker and reject all pending calls. */
+    terminate(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAkB,KAAK,EAAe,MAAM,IAAI,CAAC;AAExD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAmE1E,qBAAa,WAAW;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IAEJ;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAoC;;IAoElD;;OAEG;IACH,OAAO,CAAC,KAAK;IAab;;6DAEyD;IACzD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IACjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAWvE,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,cAAc;IAgCtB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IACnE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAehD,qEAAqE;IACrE,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IAChD;;;;;;;;;OASG;IACH,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBzD,oEAAoE;IACpE,SAAS,IAAI,IAAI;CAQlB"}