@oml/owl 0.19.3 → 0.20.0

package/src/owl/owl-sparql-oxigraph.ts

@@ -0,0 +1,527 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+// Experimental Oxigraph-backed SPARQL engine, gated behind OML_SPARQL_ENGINE=oxigraph.
+// Rationale (benchmarked 2026-06): Comunica's per-pattern actor mediation collapses on
+// cross-graph queries (`GRAPH ?g` over a large import closure) — 565s vs ~20ms on Oxigraph.
+// We keep N3 as the reasoning store (native chainers; Oxigraph match()/add() are far slower
+// per-quad across the WASM boundary) and MIRROR reasoned quads into a single global Oxigraph
+// store for querying. The mirror syncs per dirty model via fast bulk N-Triples load(); query
+// scoping to the import closure uses Oxigraph's default_graph / named_graphs options.
+//
+// Node-only: oxigraph is dynamically imported so the browser/worker bundle (which never sets
+// the flag) does not pull in the WASM module. Comunica remains the default everywhere.
+
+import type * as RDF from '@rdfjs/types';
+import type { NamedNode, Quad, Store } from 'n3';
+import type {
+    OwlABoxEntailmentState,
+    OwlAskResult,
+    OwlConstructResult,
+    OwlImportGraph,
+    OwlInferenceRunner,
+    OwlQueryResult,
+    OwlQueryRow,
+    OwlQueryTerm,
+    OwlSparqlEngine,
+    OwlStore,
+} from './owl-interfaces.js';
+
+// Minimal structural typing over the `oxigraph` module surface we use, so this file
+// type-checks without a hard static import of the WASM package.
+type OxTerm = { termType: string; value: string; datatype?: { value: string }; language?: string };
+type OxQuad = unknown;
+type OxStore = {
+    load(data: string, options: { format: string; to_graph_name?: unknown; base_iri?: string }): void;
+    query(query: string, options?: Record<string, unknown>): unknown;
+    update(update: string): void;
+    add(quad: OxQuad): void;
+    delete(quad: OxQuad): void;
+};
+type OxModule = {
+    Store: new () => OxStore;
+    namedNode(value: string): unknown;
+    quad(subject: unknown, predicate: unknown, object: unknown, graph?: unknown): OxQuad;
+    fromTerm(term: RDF.Term): unknown;
+};
+
+const XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
+const RDF_LANG_STRING = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#langString';
+
+interface ClosureContext {
+    store: OxStore;
+    missingModels: string[];
+    /** Base IRI for the query, so relative IRIs (e.g. IRI("/edge/..") in diagram CONSTRUCTs) resolve. */
+    baseIri?: string;
+}
+
+export class OxigraphSparqlService implements OwlSparqlEngine {
+    private oxModule?: OxModule;
+    private oxInit?: Promise<void>;
+
+    // Per-query-context Oxigraph store, keyed by the queried model URI. Each store holds only
+    // that model's import closure under ontology-IRI graph names, so queries can use
+    // use_default_graph_as_union (fast) instead of a huge explicit graph list (which Oxigraph
+    // evaluates ~200x slower: 24ms vs 5s for this workspace's closure).
+    //
+    // `mirrored` records, per closure model, the generation of its data currently in the store and
+    // the ontology IRI its graphs live under. On the next query the store is re-synced against the
+    // global `modelGen`: only models whose generation advanced (edited/re-chained) are re-loaded,
+    // and models that left the closure are cleared — so an edit patches a few graphs instead of
+    // rebuilding the whole mirror.
+    private readonly contextStores = new Map<string, { store: OxStore; mirrored: Map<string, { gen: number; ontologyIri: string }> }>();
+
+    private ontologyIriResolver: (modelUri: string) => string;
+
+    constructor(
+        private readonly reasoningStore: OwlStore,
+        private readonly importGraph: OwlImportGraph,
+        private readonly aboxEntailmentCache: OwlABoxEntailmentState,
+        private readonly reasoningService: OwlInferenceRunner,
+        resolveOntologyIriForModelUri?: (modelUri: string) => string,
+    ) {
+        this.ontologyIriResolver = resolveOntologyIriForModelUri ?? ((modelUri) => modelUri);
+    }
+
+    setOntologyIriResolver(resolver: (modelUri: string) => string): void {
+        this.ontologyIriResolver = resolver;
+    }
+
+    invalidateFilteredStore(_modelUri: string): void {
+        // No-op: the mirror re-syncs against the reasoning store's per-model data generation on
+        // every query (see syncStore), so a cached store never needs to be dropped or explicitly
+        // flagged when a closure member changes — only the models whose data actually changed are
+        // re-loaded. (Kept on the interface for the Comunica engine, which caches differently.)
+    }
+
+    removeFilteredStore(modelUri: string): void {
+        // A query context that no longer exists — drop its cached store.
+        this.contextStores.delete(modelUri);
+    }
+
+    private targetGraphIris(ontologyIri: string): string[] {
+        return [ontologyIri, `${ontologyIri}__entailments`, `${ontologyIri}__shacl_rules`];
+    }
+
+    async query(modelUri: string, sparql: string): Promise<OwlQueryResult> {
+        try {
+            const { context, warnings } = await this.prepare(modelUri);
+            const result = this.execute(sparql, context);
+            const rows: OwlQueryRow[] = [];
+            for (const binding of result as Iterable<Map<string, OxTerm>>) {
+                const row: OwlQueryRow = new Map();
+                for (const [variable, term] of binding) {
+                    if (!isQueryValueTerm(term)) {
+                        continue;
+                    }
+                    row.set(variable, toQueryTerm(term));
+                }
+                rows.push(row);
+            }
+            return { success: true, rows, warnings };
+        } catch (error) {
+            return { success: false, rows: [], warnings: this.safeMissingWarnings(modelUri), error: messageOf(error) };
+        }
+    }
+
+    async construct(modelUri: string, sparql: string): Promise<OwlConstructResult> {
+        try {
+            const { context, warnings } = await this.prepare(modelUri);
+            const result = this.execute(sparql, context) as Iterable<RDF.Quad>;
+            const seen = new Set<string>();
+            const quads: RDF.Quad[] = [];
+            for (const quad of result) {
+                const key = `${quad.subject.value}\x00${quad.predicate.value}\x00${quad.object.value}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    quads.push(quad);
+                }
+            }
+            return { success: true, quads, warnings };
+        } catch (error) {
+            return { success: false, quads: [], warnings: [], error: messageOf(error) };
+        }
+    }
+
+    async ask(modelUri: string, sparql: string): Promise<OwlAskResult> {
+        try {
+            const { context, warnings } = await this.prepare(modelUri);
+            const result = this.execute(sparql, context) as boolean;
+            return { success: true, result: Boolean(result), warnings };
+        } catch (error) {
+            return { success: false, result: false, warnings: [], error: messageOf(error) };
+        }
+    }
+
+    async withMaterializedQuads<T>(modelUri: string, quads: RDF.Quad[], action: () => Promise<T>): Promise<T> {
+        // Oxigraph queries read the cached mirror, not the live N3 store, so attaching the quads to
+        // the N3 store (as Comunica does) would be invisible here. Instead apply them as a delta
+        // directly to the cached context store's shaclRules graph, then remove them afterwards —
+        // far cheaper than invalidating and rebuilding the whole closure mirror per SHACL rule.
+        if (quads.length === 0) {
+            return action();
+        }
+        await this.ensureModule();
+        // Build/refresh the context first so the delta lands on the store the query will read,
+        // and so prepare() inside `action` is a cache hit that does not rebuild it without the delta.
+        this.ensureFreshEntailments(modelUri);
+        const mod = this.oxModule!;
+        let targetGraph: unknown;
+        let store: OxStore;
+        try {
+            store = this.getOrBuildContext(modelUri).store;
+            targetGraph = mod.namedNode(`${this.toOntologyGraphIri(this.resolveOntologyIri(modelUri))}__shacl_rules`);
+        } catch {
+            return action();
+        }
+        const oxQuads = quads.map((q) => mod.quad(mod.fromTerm(q.subject), mod.fromTerm(q.predicate), mod.fromTerm(q.object), targetGraph));
+        for (const q of oxQuads) {
+            store.add(q);
+        }
+        try {
+            return await action();
+        } finally {
+            for (const q of oxQuads) {
+                store.delete(q);
+            }
+        }
+    }
+
+    // --- internals -------------------------------------------------------------
+
+    private async ensureModule(): Promise<OxModule> {
+        if (this.oxModule) {
+            return this.oxModule;
+        }
+        if (!this.oxInit) {
+            this.oxInit = (async () => {
+                const mod = (await import('oxigraph')) as unknown as OxModule;
+                // In the browser worker the web build must be wasm-initialized before use; the worker
+                // entry kicks that off and exposes the promise. Await it here (first query). In Node
+                // the build auto-inits and no promise is present.
+                const ready = (globalThis as { __omlOxigraphInit?: Promise<unknown> }).__omlOxigraphInit;
+                if (ready) {
+                    await ready;
+                }
+                this.oxModule = mod;
+            })();
+        }
+        await this.oxInit;
+        return this.oxModule!;
+    }
+
+    private async prepare(modelUri: string): Promise<{ context: ClosureContext; warnings: string[] }> {
+        this.ensureFreshEntailments(modelUri);
+        await this.ensureModule();
+        const context = this.getOrBuildContext(modelUri);
+        const warnings = this.composeWarnings(modelUri, context.missingModels);
+        return { context, warnings };
+    }
+
+    private execute(sparql: string, context: ClosureContext): unknown {
+        // The context store holds only the closure, so unioning all its graphs reproduces the
+        // unionDefaultGraph semantics while keeping GRAPH ?g scoped to the closure.
+        const options: Record<string, unknown> = { use_default_graph_as_union: true };
+        if (context.baseIri) {
+            options.base_iri = context.baseIri;
+        }
+        return context.store.query(sparql, options);
+    }
+
+    // Build (or reuse a cached) Oxigraph store containing the queried model's full import
+    // closure, with each model's reasoned graphs remapped to ontology-IRI graph names.
+    private getOrBuildContext(modelUri: string): ClosureContext {
+        const cached = this.contextStores.get(modelUri);
+        if (cached) {
+            const missingModels = this.syncStore(modelUri, cached);
+            return { store: cached.store, missingModels, baseIri: this.resolveBaseIri(modelUri) };
+        }
+        const mod = this.oxModule!;
+        const store = new mod.Store();
+        const n3store: Store = this.reasoningStore.getStore();
+        const allUris = [modelUri, ...this.importGraph.dependenciesOf(modelUri)];
+        const seen = new Set<string>();
+        const missingModels: string[] = [];
+        const mirrored = new Map<string, { gen: number; ontologyIri: string }>();
+        // Serialize the closure as N-Quads (graph as the 4th term) and bulk-load in batches.
+        // Per-graph load() calls cross the WASM boundary thousands of times for a large closure;
+        // batching collapses that to a handful of parse passes while keeping the in-flight buffer
+        // bounded (a single all-at-once buffer OOMs the Node heap on large workspaces).
+        const CHUNK_LINES = 100_000;
+        let buffer: string[] = [];
+        const flush = (): void => {
+            if (buffer.length === 0) {
+                return;
+            }
+            store.load(buffer.join('\n'), { format: 'application/n-quads' });
+            buffer = [];
+        };
+        for (const uri of allUris) {
+            if (seen.has(uri)) {
+                continue;
+            }
+            seen.add(uri);
+            let sourceGraphs: { own: NamedNode; entailments: NamedNode; shaclRules: NamedNode };
+            try {
+                sourceGraphs = this.reasoningStore.graphs(uri);
+            } catch {
+                missingModels.push(uri);
+                continue;
+            }
+            const ontologyIri = this.toOntologyGraphIri(this.resolveOntologyIri(uri));
+            mirrored.set(uri, { gen: this.reasoningStore.getModelDataGen(uri), ontologyIri });
+            const targets: Array<[NamedNode, string]> = [
+                [sourceGraphs.own, ontologyIri],
+                [sourceGraphs.entailments, `${ontologyIri}__entailments`],
+                [sourceGraphs.shaclRules, `${ontologyIri}__shacl_rules`],
+            ];
+            for (const [sourceGraph, targetIri] of targets) {
+                const quads = n3store.getQuads(null, null, null, sourceGraph);
+                if (quads.length === 0) {
+                    continue;
+                }
+                const graphNT = `<${escapeIri(targetIri)}>`;
+                for (const quad of quads) {
+                    buffer.push(quadToNQuad(quad, graphNT));
+                }
+                if (buffer.length >= CHUNK_LINES) {
+                    flush();
+                }
+            }
+        }
+        flush();
+        this.contextStores.set(modelUri, { store, mirrored });
+        return { store, missingModels, baseIri: this.resolveBaseIri(modelUri) };
+    }
+
+    // Re-sync a cached store against the current closure + per-model generations: re-load models
+    // whose data advanced, clear models that left the closure, leave everything else untouched.
+    private syncStore(
+        modelUri: string,
+        entry: { store: OxStore; mirrored: Map<string, { gen: number; ontologyIri: string }> },
+    ): string[] {
+        const closure = new Set([modelUri, ...this.importGraph.dependenciesOf(modelUri)]);
+        const toCheck = new Set<string>([...closure, ...entry.mirrored.keys()]);
+        const missingModels: string[] = [];
+        for (const uri of toCheck) {
+            const have = entry.mirrored.get(uri);
+            if (!closure.has(uri)) {
+                if (have) {
+                    this.clearModelInStore(entry, uri);
+                }
+                continue;
+            }
+            const curGen = this.reasoningStore.getModelDataGen(uri);
+            if (!have || have.gen !== curGen) {
+                if (!this.patchModelInStore(entry, uri)) {
+                    missingModels.push(uri);
+                }
+            }
+        }
+        return missingModels;
+    }
+
+    // Replace one model's graphs in a cached store with its current reasoned quads. Returns false
+    // if the model is no longer loaded/resolvable (its graphs are then cleared).
+    private patchModelInStore(
+        entry: { store: OxStore; mirrored: Map<string, { gen: number; ontologyIri: string }> },
+        uri: string,
+    ): boolean {
+        const curGen = this.reasoningStore.getModelDataGen(uri);
+        const prev = entry.mirrored.get(uri);
+        const graphsToClear = new Set<string>(prev ? this.targetGraphIris(prev.ontologyIri) : []);
+        let sourceGraphs: { own: NamedNode; entailments: NamedNode; shaclRules: NamedNode };
+        let ontologyIri: string;
+        try {
+            sourceGraphs = this.reasoningStore.graphs(uri);
+            ontologyIri = this.toOntologyGraphIri(this.resolveOntologyIri(uri));
+        } catch {
+            // Model no longer loaded/resolvable — clear whatever was mirrored and forget it.
+            for (const graph of graphsToClear) {
+                entry.store.update(`CLEAR SILENT GRAPH <${escapeIri(graph)}>`);
+            }
+            entry.mirrored.delete(uri);
+            return false;
+        }
+        for (const graph of this.targetGraphIris(ontologyIri)) {
+            graphsToClear.add(graph);
+        }
+        for (const graph of graphsToClear) {
+            entry.store.update(`CLEAR SILENT GRAPH <${escapeIri(graph)}>`);
+        }
+        const n3store: Store = this.reasoningStore.getStore();
+        const targets: Array<[NamedNode, string]> = [
+            [sourceGraphs.own, ontologyIri],
+            [sourceGraphs.entailments, `${ontologyIri}__entailments`],
+            [sourceGraphs.shaclRules, `${ontologyIri}__shacl_rules`],
+        ];
+        const buffer: string[] = [];
+        for (const [sourceGraph, targetIri] of targets) {
+            const quads = n3store.getQuads(null, null, null, sourceGraph);
+            const graphNT = `<${escapeIri(targetIri)}>`;
+            for (const quad of quads) {
+                buffer.push(quadToNQuad(quad, graphNT));
+            }
+        }
+        if (buffer.length > 0) {
+            entry.store.load(buffer.join('\n'), { format: 'application/n-quads' });
+        }
+        entry.mirrored.set(uri, { gen: curGen, ontologyIri });
+        return true;
+    }
+
+    private clearModelInStore(
+        entry: { store: OxStore; mirrored: Map<string, { gen: number; ontologyIri: string }> },
+        uri: string,
+    ): void {
+        const have = entry.mirrored.get(uri);
+        if (have) {
+            for (const graph of this.targetGraphIris(have.ontologyIri)) {
+                entry.store.update(`CLEAR SILENT GRAPH <${escapeIri(graph)}>`);
+            }
+        }
+        entry.mirrored.delete(uri);
+    }
+
+    private resolveBaseIri(modelUri: string): string | undefined {
+        // Mirror the Comunica path: relative IRIs in queries resolve against the model's own graph IRI.
+        try {
+            return this.reasoningStore.graphs(modelUri).own.value;
+        } catch {
+            return modelUri;
+        }
+    }
+
+    private resolveOntologyIri(modelUri: string): string {
+        const resolved = this.ontologyIriResolver(modelUri);
+        if (!resolved || resolved === modelUri) {
+            throw new Error(`Missing ontology IRI mapping for model '${modelUri}'.`);
+        }
+        return resolved;
+    }
+
+    private toOntologyGraphIri(iri: string): string {
+        return iri.endsWith('#') ? iri.slice(0, -1) : iri;
+    }
+
+    private ensureFreshEntailments(modelUri: string): void {
+        const closure = [modelUri, ...this.importGraph.dependenciesOf(modelUri)];
+        // Mirror runInference's own chaining condition: it only (re)chains a model that is dirty,
+        // or the query root when its entailments are absent. A non-root dependency that stays
+        // 'absent' (runInference never chains it, so its entailment graph is genuinely empty) must
+        // NOT be treated as stale here — otherwise every query re-runs inference and invalidates
+        // the whole mirror, even though nothing changed.
+        const stale = closure.filter((uri) =>
+            this.aboxEntailmentCache.isDirty(uri)
+            || (uri === modelUri && this.aboxEntailmentCache.isAbsent(uri)));
+        if (stale.length === 0) {
+            return;
+        }
+        // runInference re-chains the stale models, mutating their entailment graphs in the reasoning
+        // store — which bumps those models' data generations. getOrBuildContext's syncStore then
+        // re-loads exactly those models into cached mirrors; no explicit invalidation needed here.
+        this.reasoningService.runInference(modelUri);
+    }
+
+    private composeWarnings(modelUri: string, missingModels: string[]): string[] {
+        const closureWarnings = [modelUri, ...this.importGraph.dependenciesOf(modelUri)]
+            .flatMap((uri) => this.aboxEntailmentCache.getValidationWarnings(uri));
+        return [...new Set([...missingModels.map((uri) => `Model not loaded: ${uri}`), ...closureWarnings])];
+    }
+
+    private safeMissingWarnings(modelUri: string): string[] {
+        try {
+            return this.composeWarnings(modelUri, []);
+        } catch {
+            return [];
+        }
+    }
+}
+
+function isQueryValueTerm(term: OxTerm): boolean {
+    return term.termType === 'NamedNode' || term.termType === 'BlankNode' || term.termType === 'Literal';
+}
+
+function toQueryTerm(term: OxTerm): OwlQueryTerm {
+    if (term.termType === 'NamedNode') {
+        return { termType: 'NamedNode', value: term.value };
+    }
+    if (term.termType === 'BlankNode') {
+        return { termType: 'BlankNode', value: term.value };
+    }
+    return {
+        termType: 'Literal',
+        value: term.value,
+        datatype: term.datatype?.value,
+        language: term.language,
+    };
+}
+
+function messageOf(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+// --- N-Triples serialization (fast bulk-load path into Oxigraph) -----------------
+// NOTE: blank nodes are serialized per-graph; a blank node shared across a model's own
+// and entailment graphs would split into distinct nodes on reload. OML reasoning rarely
+// shares blank nodes across these graphs, and the experimental flag documents this limit.
+
+// N-Quads line: subject predicate object graph . — graphNT is the pre-serialized graph IRI.
+function quadToNQuad(quad: Quad, graphNT: string): string {
+    return `${termToNT(quad.subject)} ${termToNT(quad.predicate)} ${termToNT(quad.object)} ${graphNT} .`;
+}
+
+function termToNT(term: RDF.Term): string {
+    switch (term.termType) {
+        case 'NamedNode':
+            return `<${escapeIri(term.value)}>`;
+        case 'BlankNode':
+            return `_:${term.value}`;
+        case 'Literal': {
+            const literal = term as RDF.Literal;
+            const lex = `"${escapeLiteral(literal.value)}"`;
+            if (literal.language) {
+                return `${lex}@${literal.language}`;
+            }
+            const dt = literal.datatype?.value;
+            if (dt && dt !== XSD_STRING && dt !== RDF_LANG_STRING) {
+                return `${lex}^^<${escapeIri(dt)}>`;
+            }
+            return lex;
+        }
+        default:
+            throw new Error(`Unsupported term type for N-Triples serialization: ${term.termType}`);
+    }
+}
+
+const IRI_DELIMITERS = new Set(['<', '>', '"', '{', '}', '|', '^', '`', '\\']);
+// Control chars (<= 0x20) or the IRIREF delimiters that are illegal unescaped.
+const IRI_NEEDS_ESCAPE = /[\u0000-\u0020<>"{}|^\u0060\\]/;
+
+function escapeIri(value: string): string {
+    // Fast path: the overwhelming majority of OML IRIs contain no character needing escaping.
+    // Serializing the full closure runs this millions of times, so skip the char loop when clean.
+    if (!IRI_NEEDS_ESCAPE.test(value)) {
+        return value;
+    }
+    // N-Triples IRIREF: \uXXXX-escape control chars, space, and the delimiters illegal
+    // unescaped. \u escapes round-trip to the same code point, preserving the IRI value.
+    let out = '';
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code <= 0x20 || IRI_DELIMITERS.has(ch)) {
+            out += `\\u${code.toString(16).toUpperCase().padStart(4, '0')}`;
+        } else {
+            out += ch;
+        }
+    }
+    return out;
+}
+
+function escapeLiteral(value: string): string {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}