@oml/owl 0.7.0

package/src/owl/owl-sparql.ts

@@ -0,0 +1,317 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+// NOTE: Comunica's QueryEngine attempts to spawn workers during construction.
+// This works in Node.js and browser main thread. For browser Web Worker contexts (language server),
+// the Worker constructor is mocked in browser-server.ts to prevent nested worker spawning while
+// allowing Comunica to initialize and execute queries successfully (without parallel execution).
+import { QueryEngine } from '@comunica/query-sparql';
+import type { Bindings } from '@comunica/types';
+import { Store } from 'n3';
+import type * as RDF from '@rdfjs/types';
+import type { NamedNode } from 'n3';
+import type { OwlABoxEntailmentState, OwlImportGraph, OwlInferenceRunner, OwlStore } from './owl-interfaces.js';
+import { deriveSelectQueryFromShacl, type DerivedShaclSelectQuery } from './owl-shacl.js';
+
+export interface RDFTerm {
+    termType: 'NamedNode' | 'Literal' | 'BlankNode';
+    value: string;
+    datatype?: string;
+    language?: string;
+}
+
+export type QueryRow = Map<string, RDFTerm>;
+
+export interface QueryResult {
+    success: boolean;
+    rows: QueryRow[];
+    warnings: string[];
+    error?: string;
+}
+
+export interface ConstructResult {
+    success: boolean;
+    quads: RDF.Quad[];
+    warnings: string[];
+    error?: string;
+}
+
+export interface AskResult {
+    success: boolean;
+    result: boolean;
+    warnings: string[];
+    error?: string;
+}
+
+interface QueryContext {
+    graphs: NamedNode[];
+    missingModels: string[];
+}
+
+export type DerivedShapeSelectQuery = DerivedShaclSelectQuery;
+export const deriveSelectQueryFromShape = deriveSelectQueryFromShacl;
+
+export class SparqlService {
+    private readonly engine = new QueryEngine();
+    private readonly filteredStoreCache = new Map<string, Store>();
+    private readonly dirtyFilteredStores = new Set<string>();
+
+    constructor(
+        private readonly reasoningStore: OwlStore,
+        private readonly importGraph: OwlImportGraph,
+        private readonly aboxEntailmentCache: OwlABoxEntailmentState,
+        private readonly reasoningService: OwlInferenceRunner,
+    ) {}
+
+    /**
+     * Executes a SPARQL query over the model's reasoned context.
+     * Queries must use explicit GRAPH patterns to access data.
+     * Available named graphs for a model context are:
+     *   <modelNamespace>               - asserted quads
+     *   <modelNamespace__entailments>  - inferred quads
+     * The same pattern applies to all models in the import closure.
+     */
+    async query(modelUri: string, sparql: string): Promise<QueryResult> {
+        try {
+            this.ensureFreshEntailments(modelUri);
+            return await this.querySelect(modelUri, sparql);
+        } catch (error) {
+            let warnings: string[] = [];
+            try {
+                warnings = this.toMissingModelsWarnings(this.getQueryContext(modelUri).missingModels);
+            } catch {
+                warnings = [];
+            }
+            return {
+                success: false,
+                rows: [],
+                warnings,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    /**
+     * Executes a SPARQL SELECT query over currently available store state.
+     * This method does not trigger inference refresh.
+     * The same named-graph contract applies as query(): explicit GRAPH patterns are required.
+     */
+    async queryRaw(modelUri: string, sparql: string): Promise<QueryResult> {
+        return this.querySelect(modelUri, sparql);
+    }
+
+    async construct(modelUri: string, sparql: string): Promise<ConstructResult> {
+        try {
+            this.ensureFreshEntailments(modelUri);
+            const queryContext = this.getQueryContext(modelUri);
+            const warnings = this.composeWarnings(modelUri, queryContext.missingModels);
+            const filteredStore = this.getOrCreateFilteredStore(modelUri, queryContext);
+            const baseIRI = this.resolveBaseIri(modelUri);
+            const quadsStream = await this.engine.queryQuads(sparql, {
+                sources: [filteredStore],
+                unionDefaultGraph: true,
+                baseIRI,
+            });
+
+            const quads: RDF.Quad[] = [];
+            for await (const inferred of quadsStream) {
+                quads.push(inferred);
+            }
+
+            return {
+                success: true,
+                quads,
+                warnings,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                quads: [],
+                warnings: [],
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    async ask(modelUri: string, sparql: string): Promise<AskResult> {
+        try {
+            this.ensureFreshEntailments(modelUri);
+            const queryContext = this.getQueryContext(modelUri);
+            const warnings = this.composeWarnings(modelUri, queryContext.missingModels);
+            const filteredStore = this.getOrCreateFilteredStore(modelUri, queryContext);
+            const baseIRI = this.resolveBaseIri(modelUri);
+            const result = await this.engine.queryBoolean(sparql, {
+                sources: [filteredStore],
+                unionDefaultGraph: true,
+                baseIRI,
+            });
+            return {
+                success: true,
+                result,
+                warnings,
+            };
+        } catch (error) {
+            return {
+                success: false,
+                result: false,
+                warnings: [],
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    getAvailableGraphs(modelUri: string): NamedNode[] {
+        return this.getQueryContext(modelUri).graphs;
+    }
+
+    invalidateFilteredStore(modelUri: string): void {
+        this.filteredStoreCache.delete(modelUri);
+        this.dirtyFilteredStores.add(modelUri);
+    }
+
+    removeFilteredStore(modelUri: string): void {
+        this.filteredStoreCache.delete(modelUri);
+        this.dirtyFilteredStores.delete(modelUri);
+    }
+
+    private async querySelect(modelUri: string, sparql: string): Promise<QueryResult> {
+        try {
+            const queryContext = this.getQueryContext(modelUri);
+            const warnings = this.composeWarnings(modelUri, queryContext.missingModels);
+            const filteredStore = this.getOrCreateFilteredStore(modelUri, queryContext);
+            const baseIRI = this.resolveBaseIri(modelUri);
+            const bindingsStream = await this.engine.queryBindings(sparql, {
+                sources: [filteredStore],
+                unionDefaultGraph: true,
+                baseIRI,
+            });
+
+            const rows: QueryRow[] = [];
+            for await (const binding of bindingsStream) {
+                const row = new Map<string, RDFTerm>();
+                (binding as Bindings).forEach((value, variable) => {
+                    if (!this.isQueryValueTerm(value)) {
+                        return;
+                    }
+                    const variableName = variable.value;
+                    row.set(variableName, this.toRdfTerm(value));
+                });
+                rows.push(row);
+            }
+
+            return {
+                success: true,
+                rows,
+                warnings,
+            };
+        } catch (error) {
+            const queryContext = this.getQueryContext(modelUri);
+            const warnings = this.composeWarnings(modelUri, queryContext.missingModels);
+            return {
+                success: false,
+                rows: [],
+                warnings,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    private ensureFreshEntailments(modelUri: string): void {
+        const closure = [modelUri, ...this.importGraph.dependenciesOf(modelUri)];
+        const requiresRefresh = closure.some((uri) => this.aboxEntailmentCache.isDirty(uri) || this.aboxEntailmentCache.isAbsent(uri));
+        if (requiresRefresh) {
+            this.reasoningService.runInference(modelUri);
+        }
+    }
+
+    private resolveBaseIri(modelUri: string): string {
+        try {
+            return this.reasoningStore.graphs(modelUri).own.value;
+        } catch {
+            return modelUri;
+        }
+    }
+
+    private getQueryContext(modelUri: string): QueryContext {
+        const allUris = [modelUri, ...this.importGraph.dependenciesOf(modelUri)];
+        const seen = new Set<string>();
+        const graphs: NamedNode[] = [];
+        const missingModels: string[] = [];
+        for (const uri of allUris) {
+            let own: NamedNode;
+            let entailments: NamedNode;
+            try {
+                ({ own, entailments } = this.reasoningStore.graphs(uri));
+            } catch {
+                missingModels.push(uri);
+                continue;
+            }
+            for (const graph of [own, entailments]) {
+                if (seen.has(graph.value)) {
+                    continue;
+                }
+                seen.add(graph.value);
+                graphs.push(graph);
+            }
+        }
+        return { graphs, missingModels };
+    }
+
+    private toRdfTerm(term: RDF.Term): RDFTerm {
+        if (term.termType === 'NamedNode') {
+            return { termType: 'NamedNode', value: term.value };
+        }
+        if (term.termType === 'BlankNode') {
+            return { termType: 'BlankNode', value: term.value };
+        }
+        const literal = term as RDF.Literal;
+        return {
+            termType: 'Literal',
+            value: term.value,
+            datatype: literal.datatype.value,
+            language: literal.language,
+        };
+    }
+
+    private isQueryValueTerm(term: RDF.Term): term is RDF.NamedNode | RDF.BlankNode | RDF.Literal {
+        return term.termType === 'NamedNode' || term.termType === 'BlankNode' || term.termType === 'Literal';
+    }
+
+    private toMissingModelsWarnings(missingModels: string[]): string[] {
+        return missingModels.map((modelUri) => `Model not loaded: ${modelUri}`);
+    }
+
+    private composeWarnings(modelUri: string, missingModels: string[]): string[] {
+        const closureWarnings = [modelUri, ...this.importGraph.dependenciesOf(modelUri)]
+            .flatMap((uri) => this.aboxEntailmentCache.getValidationWarnings(uri));
+        return [...new Set([...this.toMissingModelsWarnings(missingModels), ...closureWarnings])];
+    }
+
+    private createFilteredStore(graphs: NamedNode[]): Store {
+        const filteredStore = new Store();
+        const mainStore = this.reasoningStore.getStore();
+        const seenTriples = new Set<string>();
+        for (const graph of graphs) {
+            const uniqueQuads = mainStore.getQuads(null, null, null, graph).filter((quad) => {
+                const key = `${quad.subject.id}|${quad.predicate.id}|${quad.object.id}`;
+                if (seenTriples.has(key)) {
+                    return false;
+                }
+                seenTriples.add(key);
+                return true;
+            });
+            filteredStore.addQuads(uniqueQuads);
+        }
+        return filteredStore;
+    }
+
+    private getOrCreateFilteredStore(modelUri: string, queryContext: QueryContext): Store {
+        const cached = this.filteredStoreCache.get(modelUri);
+        if (cached && !this.dirtyFilteredStores.has(modelUri)) {
+            return cached;
+        }
+        const store = this.createFilteredStore(queryContext.graphs);
+        this.filteredStoreCache.set(modelUri, store);
+        this.dirtyFilteredStores.delete(modelUri);
+        return store;
+    }
+}

package/src/owl/owl-store.ts

@@ -0,0 +1,173 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import { DataFactory, Store } from 'n3';
+import type { NamedNode, Quad } from 'n3';
+
+const OML_NAMESPACE = 'http://opencaesar.io/oml#namespace';
+const { namedNode, quad } = DataFactory;
+
+export interface ModelDiff {
+    isEmpty: boolean;
+    retracted: Quad[];
+    asserted: Quad[];
+}
+
+export interface ModelGraphs {
+    own: NamedNode;
+    entailments: NamedNode;
+}
+
+export class ReasoningStore {
+    private readonly store = new Store();
+    private readonly modelGraphs = new Map<string, ModelGraphs>();
+
+    // Load a model's quads into its named graph.
+    // Retracts any existing quads for that model first.
+    // Graph IRI is derived from the ontology namespace embedded in the quads.
+    loadModel(modelUri: string, quads: Quad[]): void {
+        const graphs = this.resolveGraphs(modelUri, quads);
+        this.retractModel(modelUri);
+        this.modelGraphs.set(modelUri, graphs);
+        this.store.addQuads(quads.map((q) => this.withGraph(q, graphs.own)));
+    }
+
+    loadEntailments(modelUri: string, quads: Quad[]): void {
+        const graphs = this.requireGraphs(modelUri);
+        this.removeGraph(graphs.entailments);
+        if (quads.length === 0) {
+            return;
+        }
+        this.store.addQuads(quads.map((q) => this.withGraph(q, graphs.entailments)));
+    }
+
+    applyModelDelta(modelUri: string, quads: Quad[], retracted: Quad[], asserted: Quad[]): void {
+        const graphs = this.resolveGraphs(modelUri, quads, true);
+        this.modelGraphs.set(modelUri, graphs);
+        if (retracted.length > 0) {
+            this.store.removeQuads(retracted.map((q) => this.withGraph(q, graphs.own)));
+        }
+        if (asserted.length > 0) {
+            this.store.addQuads(asserted.map((q) => this.withGraph(q, graphs.own)));
+        }
+    }
+
+    // Retract all quads in all named graphs for a model
+    // (own quads + entailment quads)
+    retractModel(modelUri: string): void {
+        const graphs = this.modelGraphs.get(modelUri);
+        if (!graphs) return;
+        this.removeGraph(graphs.own);
+        this.removeGraph(graphs.entailments);
+        this.modelGraphs.delete(modelUri);
+    }
+
+    // Compare newly mapped quads against what is currently in the store.
+    // Returns the semantic difference — what was added and what was removed.
+    // If the diff is empty, nothing downstream needs to run.
+    diffModel(modelUri: string, newQuads: Quad[]): ModelDiff {
+        const graphs = this.resolveGraphs(modelUri, newQuads, true);
+        const existing = this.store.getQuads(null, null, null, graphs.own);
+        const next = newQuads.map((q) => this.withGraph(q, graphs.own));
+
+        const existingByKey = new Map(existing.map((q) => [this.quadKey(q), q]));
+        const nextByKey = new Map(next.map((q) => [this.quadKey(q), q]));
+
+        const retracted = [...existingByKey.entries()]
+            .filter(([key]) => !nextByKey.has(key))
+            .map(([, value]) => value)
+            .sort((a, b) => this.quadKey(a).localeCompare(this.quadKey(b)));
+
+        const asserted = [...nextByKey.entries()]
+            .filter(([key]) => !existingByKey.has(key))
+            .map(([, value]) => value)
+            .sort((a, b) => this.quadKey(a).localeCompare(this.quadKey(b)));
+
+        return {
+            isEmpty: retracted.length === 0 && asserted.length === 0,
+            retracted,
+            asserted,
+        };
+    }
+
+    // Clear only the entailment named graph for a model.
+    // Called before re-running TBox or ABox chaining.
+    clearEntailments(modelUri: string): void {
+        const graphs = this.requireGraphs(modelUri);
+        this.removeGraph(graphs.entailments);
+    }
+
+    // Returns the named graph IRIs for a model.
+    // Used by TBoxChainer, ABoxChainer, and SparqlService
+    // to know which graphs to read from and write to.
+    graphs(modelUri: string): ModelGraphs {
+        return this.requireGraphs(modelUri);
+    }
+
+    // Expose the underlying N3 Store for direct use by
+    // TBoxChainer, ABoxChainer, and Comunica.
+    getStore(): Store {
+        return this.store;
+    }
+
+    private resolveGraphs(modelUri: string, quads: Quad[], allowExisting = false): ModelGraphs {
+        const namespace = this.namespaceFromQuads(quads);
+        if (namespace) {
+            const graphs = this.graphsFromNamespace(namespace);
+            this.modelGraphs.set(modelUri, graphs);
+            return graphs;
+        }
+        if (allowExisting) {
+            const existing = this.modelGraphs.get(modelUri);
+            if (existing) return existing;
+        }
+        // Keep reasoning resilient during transient states (e.g. non-mappable documents):
+        // if namespace is missing, fall back to a stable graph derived from the model URI.
+        const fallback = this.graphsFromModelUri(modelUri);
+        this.modelGraphs.set(modelUri, fallback);
+        return fallback;
+    }
+
+    private graphsFromNamespace(namespace: string): ModelGraphs {
+        const ontologyIri = this.ontologyIriFromNamespace(namespace);
+        return {
+            own: namedNode(ontologyIri),
+            entailments: namedNode(`${ontologyIri}__entailments`),
+        };
+    }
+
+    private graphsFromModelUri(modelUri: string): ModelGraphs {
+        return {
+            own: namedNode(modelUri),
+            entailments: namedNode(`${modelUri}__entailments`)
+        };
+    }
+
+    private namespaceFromQuads(quads: Quad[]): string | undefined {
+        const namespaceQuad = quads.find((q) => q.predicate.value === OML_NAMESPACE && q.object.termType === 'NamedNode');
+        return namespaceQuad?.object.value;
+    }
+
+    private ontologyIriFromNamespace(namespace: string): string {
+        return namespace.replace(/[\/#]+$/, '');
+    }
+
+    private requireGraphs(modelUri: string): ModelGraphs {
+        const graphs = this.modelGraphs.get(modelUri);
+        if (!graphs) {
+            throw new Error(`Unknown model '${modelUri}'. Load the model first.`);
+        }
+        return graphs;
+    }
+
+    private withGraph(q: Quad, graph: NamedNode): Quad {
+        return quad(q.subject, q.predicate, q.object, graph);
+    }
+
+    private removeGraph(graph: NamedNode): void {
+        this.store.removeQuads(this.store.getQuads(null, null, null, graph));
+    }
+
+    private quadKey(q: Quad): string {
+        return `${q.subject.id}|${q.predicate.id}|${q.object.id}|${q.graph.id}`;
+    }
+}