@undefineds.co/xpod 0.3.75 → 0.4.0-rc.140

package/dist/storage/rdf/PostgresRdfVectorIndex.js

@@ -5,7 +5,21 @@ const pglite_1 = require("@electric-sql/pglite");
 const PostgresPoolManager_1 = require("../database/PostgresPoolManager");
 const RdfSearchSourceFilter_1 = require("./RdfSearchSourceFilter");
 const PostgresRdfSqlExecutor_1 = require("./PostgresRdfSqlExecutor");
+const PostgresRdfSchemaValidation_1 = require("./PostgresRdfSchemaValidation");
 const RdfVectorIndex_1 = require("./RdfVectorIndex");
+const PG_RDF_VECTOR_SCHEMA_LOCK_KEY = 2026072902;
+const PG_RDF_VECTOR_DOMAIN_TABLES = [
+    'rdf_vector_metadata',
+    'rdf_vector_sources',
+    'rdf_vector_chunks',
+    'rdf_vector_components',
+];
+const PG_RDF_VECTOR_REQUIRED_COLUMNS = {
+    rdf_vector_metadata: ['key', 'value'],
+    rdf_vector_sources: ['id', 'source_key', 'source', 'workspace', 'local_path', 'content_type', 'source_version', 'source_hash', 'updated_at'],
+    rdf_vector_chunks: ['id', 'source_id', 'chunk_key', 'ordinal', 'level', 'heading', 'path', 'content', 'start_offset', 'end_offset', 'embedding_json', 'summary_metadata', 'dimensions', 'magnitude', 'provider', 'model', 'model_version', 'input_kind', 'input_hash', 'projection_policy_version', 'updated_at'],
+    rdf_vector_components: ['chunk_id', 'dimension', 'value', 'updated_at'],
+};
 class PostgresRdfVectorIndex {
     constructor(options = {}) {
         this.executor = null;
@@ -48,6 +62,14 @@ class PostgresRdfVectorIndex {
     async clear() {
         await this.requireExecutor().exec('DELETE FROM rdf_vector_components; DELETE FROM rdf_vector_chunks; DELETE FROM rdf_vector_sources;');
     }
+    async schemaVersion() {
+        return await this.readSchemaVersion(this.requireExecutor());
+    }
+    async readSchemaVersion(executor) {
+        const row = await executor
+            .query("SELECT value FROM rdf_vector_metadata WHERE key = 'schema_version'");
+        return Number(row[0]?.value ?? 0) || 0;
+    }
     async indexVector(source, chunks) {
         const executor = this.requireExecutor();
         await executor.transaction(async (tx) => {
@@ -190,6 +212,58 @@ class PostgresRdfVectorIndex {
             return Number(deletedRows[0]?.count ?? 0);
         });
     }
+    async moveSource(oldSource, next) {
+        const executor = this.requireExecutor();
+        return await executor.transaction(async (tx) => {
+            const oldRows = await tx.query('SELECT * FROM rdf_vector_sources WHERE source = $1', [oldSource]);
+            const oldRow = oldRows[0];
+            if (!oldRow) {
+                return 0;
+            }
+            const oldId = Number(oldRow.id);
+            const sourceKey = oldRow.source_key;
+            if (next.sourceKey && next.sourceKey !== sourceKey) {
+                throw new Error(`RDF vector source key mismatch for source ${oldSource}: expected ${sourceKey}, got ${next.sourceKey}`);
+            }
+            const countRows = await tx.query('SELECT COUNT(*) AS count FROM rdf_vector_chunks WHERE source_id = $1', [oldId]);
+            const targetRows = await tx.query('SELECT * FROM rdf_vector_sources WHERE source = $1', [next.source]);
+            const targetRow = targetRows[0];
+            if (targetRow && Number(targetRow.id) !== oldId) {
+                const targetId = Number(targetRow.id);
+                await tx.exec(`
+          DELETE FROM rdf_vector_components
+          WHERE chunk_id IN (
+            SELECT id FROM rdf_vector_chunks WHERE source_id = $1
+          )
+        `, [targetId]);
+                await tx.exec('DELETE FROM rdf_vector_chunks WHERE source_id = $1', [targetId]);
+                await tx.exec('DELETE FROM rdf_vector_sources WHERE id = $1', [targetId]);
+            }
+            await tx.exec(`
+        UPDATE rdf_vector_sources
+        SET
+          source_key = $1,
+          source = $2,
+          workspace = $3,
+          local_path = $4,
+          content_type = $5,
+          source_version = $6,
+          source_hash = $7,
+          updated_at = now()
+        WHERE id = $8
+      `, [
+                sourceKey,
+                next.source,
+                next.workspace,
+                next.localPath ?? null,
+                next.contentType ?? null,
+                next.sourceVersion ?? null,
+                next.sourceHash ?? oldRow.source_hash ?? null,
+                oldId,
+            ]);
+            return Math.max(Number(countRows[0]?.count ?? 0), 1);
+        });
+    }
     async search(options) {
         const embedding = (0, RdfVectorIndex_1.normalizeEmbedding)(options.embedding);
         if (embedding.length === 0) {
@@ -380,13 +454,25 @@ class PostgresRdfVectorIndex {
         await this.initializeSchema();
     }
     async initializeSchema() {
-        if (this.usesPgVectorBackend()) {
-            await this.requireExecutor().exec('CREATE EXTENSION IF NOT EXISTS vector');
-        }
-        await this.requireExecutor().exec(`
-      CREATE TABLE IF NOT EXISTS rdf_vector_sources (
+        await this.requireExecutor().transaction(async (executor) => {
+            await executor.exec('SELECT pg_advisory_xact_lock($1)', [PG_RDF_VECTOR_SCHEMA_LOCK_KEY]);
+            if (await (0, PostgresRdfSchemaValidation_1.pgHasAnyDomainTable)(executor, PG_RDF_VECTOR_DOMAIN_TABLES)) {
+                await this.validateSchema(executor);
+                return;
+            }
+            const embeddingVectorColumnSql = this.usesPgVectorBackend() ? 'embedding_vector vector,' : '';
+            if (this.usesPgVectorBackend()) {
+                await executor.exec('CREATE EXTENSION IF NOT EXISTS vector');
+            }
+            await executor.exec(`
+      CREATE TABLE rdf_vector_metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+
+      CREATE TABLE rdf_vector_sources (
         id BIGSERIAL PRIMARY KEY,
-        source_key TEXT,
+        source_key TEXT NOT NULL UNIQUE,
         source TEXT NOT NULL UNIQUE,
         workspace TEXT NOT NULL,
         local_path TEXT,
@@ -396,7 +482,7 @@ class PostgresRdfVectorIndex {
         updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
       );
 
-      CREATE TABLE IF NOT EXISTS rdf_vector_chunks (
+      CREATE TABLE rdf_vector_chunks (
         id BIGSERIAL PRIMARY KEY,
         source_id BIGINT NOT NULL REFERENCES rdf_vector_sources(id) ON DELETE CASCADE,
         chunk_key TEXT NOT NULL,
@@ -417,6 +503,7 @@ class PostgresRdfVectorIndex {
         input_kind TEXT NOT NULL DEFAULT '',
         input_hash TEXT NOT NULL DEFAULT '',
         projection_policy_version TEXT NOT NULL DEFAULT '',
+        ${embeddingVectorColumnSql}
         updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
         UNIQUE (
           source_id,
@@ -430,7 +517,7 @@ class PostgresRdfVectorIndex {
         )
       );
 
-      CREATE TABLE IF NOT EXISTS rdf_vector_components (
+      CREATE TABLE rdf_vector_components (
         chunk_id BIGINT NOT NULL REFERENCES rdf_vector_chunks(id) ON DELETE CASCADE,
         dimension INTEGER NOT NULL,
         value DOUBLE PRECISION NOT NULL,
@@ -438,28 +525,31 @@ class PostgresRdfVectorIndex {
         PRIMARY KEY (chunk_id, dimension)
       );
 
-      CREATE INDEX IF NOT EXISTS rdf_vector_sources_workspace ON rdf_vector_sources(workspace);
-      CREATE INDEX IF NOT EXISTS rdf_vector_sources_source ON rdf_vector_sources(source);
-      CREATE INDEX IF NOT EXISTS rdf_vector_chunks_source ON rdf_vector_chunks(source_id, ordinal);
-      CREATE INDEX IF NOT EXISTS rdf_vector_components_dimension ON rdf_vector_components(dimension, chunk_id);
-    `);
-        await this.ensureSourceKeyColumn();
-        await this.ensureVectorIdentityColumns();
-        if (this.usesPgVectorBackend()) {
-            await this.ensurePgVectorColumn();
+      CREATE INDEX rdf_vector_sources_workspace ON rdf_vector_sources(workspace);
+      CREATE INDEX rdf_vector_sources_source ON rdf_vector_sources(source);
+      CREATE INDEX rdf_vector_chunks_source ON rdf_vector_chunks(source_id, ordinal);
+      CREATE INDEX rdf_vector_components_dimension ON rdf_vector_components(dimension, chunk_id);
+      CREATE INDEX rdf_vector_chunks_model_dimensions
+      ON rdf_vector_chunks(provider, model, model_version, input_kind, projection_policy_version, dimensions);
+
+      INSERT INTO rdf_vector_metadata (key, value)
+      VALUES ('schema_version', '${RdfVectorIndex_1.RDF_VECTOR_SCHEMA_VERSION}');
+      `);
+        });
+    }
+    async validateSchema(executor = this.requireExecutor()) {
+        for (const table of PG_RDF_VECTOR_DOMAIN_TABLES) {
+            await (0, PostgresRdfSchemaValidation_1.assertPgRequiredColumns)(executor, table, PG_RDF_VECTOR_REQUIRED_COLUMNS[table], 'vector');
         }
-        else {
-            await this.backfillVectorComponents();
+        const version = await this.readSchemaVersion(executor);
+        if (version !== RdfVectorIndex_1.RDF_VECTOR_SCHEMA_VERSION) {
+            throw new Error(`Unsupported PostgreSQL RDF vector index schema version: expected ${RdfVectorIndex_1.RDF_VECTOR_SCHEMA_VERSION}, got ${version}`);
+        }
+        await (0, PostgresRdfSchemaValidation_1.assertPgNotNullColumn)(executor, 'rdf_vector_sources', 'source_key', 'vector');
+        await (0, PostgresRdfSchemaValidation_1.assertPgUniqueColumn)(executor, 'rdf_vector_sources', 'source_key', 'vector');
+        if (this.usesPgVectorBackend()) {
+            await (0, PostgresRdfSchemaValidation_1.assertPgColumnType)(executor, 'rdf_vector_chunks', 'embedding_vector', 'vector', 'vector');
         }
-    }
-    async ensurePgVectorColumn() {
-        await this.requireExecutor().exec('ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS embedding_vector vector');
-        await this.requireExecutor().exec(`
-      UPDATE rdf_vector_chunks
-      SET embedding_vector = embedding_json::vector
-      WHERE embedding_vector IS NULL
-        AND embedding_json IS NOT NULL
-    `);
     }
     async ensurePgVectorSearchIndex(dimensions, metric) {
         if (!this.usesPgVectorBackend()) {
@@ -480,97 +570,12 @@ class PostgresRdfVectorIndex {
     `);
         this.ensuredPgVectorIndexes.add(key);
     }
-    async ensureSourceKeyColumn() {
-        await this.requireExecutor().exec('ALTER TABLE rdf_vector_sources ADD COLUMN IF NOT EXISTS source_key TEXT');
-        await this.requireExecutor().exec('UPDATE rdf_vector_sources SET source_key = source WHERE source_key IS NULL OR source_key = \'\'');
-    }
-    async ensureVectorIdentityColumns() {
-        await this.requireExecutor().exec(`
-      ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS provider TEXT NOT NULL DEFAULT '';
-      ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS model_version TEXT NOT NULL DEFAULT '';
-      ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS input_kind TEXT NOT NULL DEFAULT '';
-      ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS input_hash TEXT NOT NULL DEFAULT '';
-      ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS projection_policy_version TEXT NOT NULL DEFAULT '';
-      ALTER TABLE rdf_vector_chunks ADD COLUMN IF NOT EXISTS summary_metadata TEXT;
-      UPDATE rdf_vector_chunks
-      SET
-        provider = COALESCE(provider, ''),
-        model_version = COALESCE(model_version, ''),
-        input_kind = COALESCE(input_kind, ''),
-        input_hash = COALESCE(input_hash, ''),
-        projection_policy_version = COALESCE(projection_policy_version, '');
-    `);
-        await this.ensureVectorChunkIdentityUniqueConstraint();
-        await this.requireExecutor().exec(`
-      CREATE INDEX IF NOT EXISTS rdf_vector_chunks_model_dimensions
-      ON rdf_vector_chunks(provider, model, model_version, input_kind, projection_policy_version, dimensions);
-    `);
-    }
-    async ensureVectorChunkIdentityUniqueConstraint() {
-        const rows = await this.requireExecutor().query(`
-      SELECT
-        constraint_info.conname,
-        string_agg(attribute.attname, ',' ORDER BY constraint_key.ordinality) AS columns
-      FROM pg_constraint constraint_info
-      JOIN unnest(constraint_info.conkey) WITH ORDINALITY AS constraint_key(attnum, ordinality) ON TRUE
-      JOIN pg_attribute attribute
-        ON attribute.attrelid = constraint_info.conrelid
-       AND attribute.attnum = constraint_key.attnum
-      WHERE constraint_info.conrelid = 'rdf_vector_chunks'::regclass
-        AND constraint_info.contype = 'u'
-      GROUP BY constraint_info.conname
-    `);
-        let hasIdentityUnique = false;
-        for (const row of rows) {
-            if (row.columns === 'source_id,chunk_key') {
-                await this.requireExecutor().exec(`ALTER TABLE rdf_vector_chunks DROP CONSTRAINT ${quotePgIdentifier(row.conname)}`);
-            }
-            else if (row.columns === 'source_id,chunk_key,provider,model,model_version,input_kind,projection_policy_version,input_hash') {
-                hasIdentityUnique = true;
-            }
-        }
-        if (hasIdentityUnique) {
-            return;
-        }
-        await this.requireExecutor().exec(`
-      CREATE UNIQUE INDEX IF NOT EXISTS rdf_vector_chunks_identity_unique
-      ON rdf_vector_chunks (
-        source_id,
-        chunk_key,
-        provider,
-        model,
-        model_version,
-        input_kind,
-        projection_policy_version,
-        input_hash
-      )
-    `);
-    }
-    async backfillVectorComponents() {
-        const rows = await this.requireExecutor().query(`
-      SELECT
-        chunk.id,
-        chunk.dimensions,
-        chunk.embedding_json,
-        COUNT(component.dimension) AS component_count
-      FROM rdf_vector_chunks chunk
-      LEFT JOIN rdf_vector_components component ON component.chunk_id = chunk.id
-      WHERE chunk.dimensions > 0
-      GROUP BY chunk.id
-      HAVING COUNT(component.dimension) <> chunk.dimensions
-    `);
-        if (rows.length === 0) {
-            return;
-        }
-        await this.requireExecutor().transaction(async (tx) => {
-            for (const row of rows) {
-                const chunkId = Number(row.id);
-                await tx.exec('DELETE FROM rdf_vector_components WHERE chunk_id = $1', [chunkId]);
-                await insertVectorComponents(tx, chunkId, (0, RdfVectorIndex_1.parseEmbedding)(row.embedding_json));
-            }
-        });
-    }
     async upsertSource(tx, source) {
+        const existing = await tx.query('SELECT * FROM rdf_vector_sources WHERE source = $1', [source.source]);
+        if (existing[0] && source.sourceKey && existing[0].source_key !== source.sourceKey) {
+            throw new Error(`RDF vector source key mismatch for source ${source.source}: expected ${existing[0].source_key}, got ${source.sourceKey}`);
+        }
+        const sourceKey = existing[0]?.source_key ?? source.sourceKey ?? source.source;
         const rows = await tx.query(`
       INSERT INTO rdf_vector_sources (
         source_key,
@@ -585,7 +590,6 @@ class PostgresRdfVectorIndex {
       VALUES ($1, $2, $3, $4, $5, $6, $7, now())
       ON CONFLICT (source)
       DO UPDATE SET
-        source_key = COALESCE(EXCLUDED.source_key, rdf_vector_sources.source_key, EXCLUDED.source),
         workspace = EXCLUDED.workspace,
         local_path = EXCLUDED.local_path,
         content_type = EXCLUDED.content_type,
@@ -594,7 +598,7 @@ class PostgresRdfVectorIndex {
         updated_at = EXCLUDED.updated_at
       RETURNING id
     `, [
-            source.sourceKey ?? source.source,
+            sourceKey,
             source.source,
             source.workspace,
             source.localPath ?? null,

package/dist/storage/rdf/PostgresRdfVectorIndex.jsonld

@@ -291,6 +291,14 @@
           "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_clear",
           "memberFieldName": "clear"
         },
+        {
+          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_schemaVersion",
+          "memberFieldName": "schemaVersion"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_readSchemaVersion",
+          "memberFieldName": "readSchemaVersion"
+        },
         {
           "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_indexVector",
           "memberFieldName": "indexVector"
@@ -299,6 +307,10 @@
           "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_deleteSource",
           "memberFieldName": "deleteSource"
         },
+        {
+          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_moveSource",
+          "memberFieldName": "moveSource"
+        },
         {
           "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_search",
           "memberFieldName": "search"
@@ -328,29 +340,13 @@
           "memberFieldName": "initializeSchema"
         },
         {
-          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_ensurePgVectorColumn",
-          "memberFieldName": "ensurePgVectorColumn"
+          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_validateSchema",
+          "memberFieldName": "validateSchema"
         },
         {
           "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_ensurePgVectorSearchIndex",
           "memberFieldName": "ensurePgVectorSearchIndex"
         },
-        {
-          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_ensureSourceKeyColumn",
-          "memberFieldName": "ensureSourceKeyColumn"
-        },
-        {
-          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_ensureVectorIdentityColumns",
-          "memberFieldName": "ensureVectorIdentityColumns"
-        },
-        {
-          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_ensureVectorChunkIdentityUniqueConstraint",
-          "memberFieldName": "ensureVectorChunkIdentityUniqueConstraint"
-        },
-        {
-          "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_backfillVectorComponents",
-          "memberFieldName": "backfillVectorComponents"
-        },
         {
           "@id": "undefineds:dist/storage/rdf/PostgresRdfVectorIndex.jsonld#PostgresRdfVectorIndex__member_upsertSource",
           "memberFieldName": "upsertSource"

package/dist/storage/rdf/QleverSparqlEngine.d.ts

@@ -0,0 +1,35 @@
+import type { AsyncIterator } from 'asynciterator';
+import type { Quad, Term, Variable } from '@rdfjs/types';
+import type { SparqlEngine, SparqlQueryOptions, SparqlVoidOptions } from '../sparql/SubgraphQueryEngine';
+import type { RdfAccessScope } from './RdfAccessScope';
+import type { RdfEngineLike } from './types';
+type QleverBindingsStream = AsyncIterator<QleverBindings> & {
+    metadata(): Promise<{
+        variables: Variable[];
+    }>;
+};
+/**
+ * Thin CSS SparqlEngine adapter over the shared native QLever envelope.
+ *
+ * It performs product-boundary validation and result decoding only. It has no
+ * alternate evaluator, planner, update compiler, or secondary execution path.
+ */
+export declare class QleverSparqlEngine implements SparqlEngine {
+    private readonly rdfEngine;
+    constructor(rdfEngine: RdfEngineLike);
+    queryBindings(query: string, basePath: string, accessScope?: RdfAccessScope, options?: SparqlQueryOptions): Promise<QleverBindingsStream>;
+    queryBoolean(query: string, basePath: string, accessScope?: RdfAccessScope, options?: SparqlQueryOptions): Promise<boolean>;
+    queryQuads(query: string, basePath: string, accessScope?: RdfAccessScope, options?: SparqlQueryOptions): Promise<AsyncIterator<Quad>>;
+    queryVoid(_query: string, _basePath: string, _accessScope?: RdfAccessScope, _options?: SparqlVoidOptions): Promise<void>;
+    constructGraph(graph: string, basePath: string, accessScope?: RdfAccessScope): Promise<AsyncIterator<Quad>>;
+    listGraphs(basePath: string, accessScope?: RdfAccessScope): Promise<Set<string>>;
+    close(): Promise<void>;
+    private execute;
+}
+declare class QleverBindings extends Map<Variable, Term> {
+    private readonly byName;
+    constructor(entries: [Variable, Term][]);
+    get(key: string | Variable): Term | undefined;
+    has(key: string | Variable): boolean;
+}
+export {};

package/dist/storage/rdf/QleverSparqlEngine.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QleverSparqlEngine = void 0;
+const asynciterator_1 = require("asynciterator");
+const n3_1 = require("n3");
+const rdf_data_factory_1 = require("rdf-data-factory");
+const RdfSparqlBoundary_1 = require("./RdfSparqlBoundary");
+const RdfSparqlSerialization_1 = require("./RdfSparqlSerialization");
+const rdfDataFactory = new rdf_data_factory_1.DataFactory();
+const XPOD_RDF_STATUS_CANCELLED = 3;
+/**
+ * Thin CSS SparqlEngine adapter over the shared native QLever envelope.
+ *
+ * It performs product-boundary validation and result decoding only. It has no
+ * alternate evaluator, planner, update compiler, or secondary execution path.
+ */
+class QleverSparqlEngine {
+    constructor(rdfEngine) {
+        this.rdfEngine = rdfEngine;
+        if (typeof rdfEngine.sparqlQuery !== 'function') {
+            throw new Error('QleverSparqlEngine requires an RdfEngine with native SPARQL support');
+        }
+    }
+    async queryBindings(query, basePath, accessScope, options) {
+        const result = await this.execute(query, basePath, 'queryBindings', 'application/sparql-results+json', accessScope, options);
+        const payload = parseSparqlJson(result);
+        if (!payload.results) {
+            throw new RdfSparqlBoundary_1.NativeSparqlExecutionError('QLever SELECT result does not contain bindings');
+        }
+        const variables = payload.head?.vars ?? inferVariableNames(payload.results.bindings ?? []);
+        const rows = (payload.results.bindings ?? []).map((row) => toBindings(row, variables));
+        const iterator = new asynciterator_1.ArrayIterator(rows);
+        iterator.metadata = async () => ({
+            variables: variables.map((name) => rdfDataFactory.variable(name)),
+        });
+        return iterator;
+    }
+    async queryBoolean(query, basePath, accessScope, options) {
+        const result = await this.execute(query, basePath, 'queryBoolean', 'application/sparql-results+json', accessScope, options);
+        const payload = parseSparqlJson(result);
+        if (typeof payload.boolean !== 'boolean') {
+            throw new RdfSparqlBoundary_1.NativeSparqlExecutionError('QLever ASK result does not contain a boolean');
+        }
+        return payload.boolean;
+    }
+    async queryQuads(query, basePath, accessScope, options) {
+        const result = await this.execute(query, basePath, 'queryQuads', 'application/n-quads', accessScope, options);
+        return new asynciterator_1.ArrayIterator(parseGraph(result));
+    }
+    async queryVoid(_query, _basePath, _accessScope, _options) {
+        throw new RdfSparqlBoundary_1.UnsupportedSparqlQueryError('Direct SPARQL UPDATE execution is disabled; use the Pod update authority prepared-delta path', {
+            code: 'rdf.sparql.update_authority_required',
+            capability: 'sparql.update.authority',
+            hint: 'Send the update through the Pod SPARQL HTTP endpoint so the authority can prepare and atomically commit source-file changes.',
+        });
+    }
+    async constructGraph(graph, basePath, accessScope) {
+        return this.queryQuads(`CONSTRUCT { ?s ?p ?o } WHERE { GRAPH ${(0, RdfSparqlSerialization_1.serializeSparqlIri)(graph)} { ?s ?p ?o } }`, basePath, accessScope);
+    }
+    async listGraphs(basePath, accessScope) {
+        const stream = await this.queryBindings('SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } }', basePath, accessScope);
+        const graphs = new Set();
+        for await (const binding of stream) {
+            const graph = binding.get('g');
+            if (graph?.termType === 'NamedNode') {
+                graphs.add(graph.value);
+            }
+        }
+        return graphs;
+    }
+    async close() {
+        await this.rdfEngine.close();
+    }
+    async execute(query, basePath, operation, acceptMediaType, accessScope, options) {
+        (0, RdfSparqlBoundary_1.assertServerOwnedNativeSparqlQuery)(query, basePath);
+        const result = await this.rdfEngine.sparqlQuery(query, {
+            basePath,
+            operation,
+            acceptMediaType,
+            ...(accessScope ? { accessScope } : {}),
+            ...(options?.sourceUri === undefined ? {} : { sourceUri: options.sourceUri }),
+            ...(options?.defaultDataset === undefined ? {} : { defaultDataset: options.defaultDataset }),
+            ...(options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        if (result.status === 'ok') {
+            return result;
+        }
+        if (result.status === 'unsupported') {
+            throw new RdfSparqlBoundary_1.UnsupportedSparqlQueryError(result.error || 'QLever reported the SPARQL query as unsupported', { capability: 'sparql.qlever' });
+        }
+        if (options?.timeoutMs !== undefined && result.queryStatus === XPOD_RDF_STATUS_CANCELLED) {
+            throw new RdfSparqlBoundary_1.NativeSparqlTimeoutError(options.timeoutMs, result.error);
+        }
+        throw new RdfSparqlBoundary_1.NativeSparqlExecutionError(result.error || 'QLever returned an error result');
+    }
+}
+exports.QleverSparqlEngine = QleverSparqlEngine;
+function parseSparqlJson(result) {
+    try {
+        return JSON.parse(result.body);
+    }
+    catch (error) {
+        throw new RdfSparqlBoundary_1.NativeSparqlExecutionError(`QLever returned invalid SPARQL JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function parseGraph(result) {
+    const mediaType = result.mediaType.toLowerCase();
+    try {
+        return new n3_1.Parser({
+            format: mediaType.includes('n-quads')
+                ? 'N-Quads'
+                : mediaType.includes('turtle')
+                    ? 'Turtle'
+                    : 'N-Triples',
+        }).parse(result.body);
+    }
+    catch (error) {
+        throw new RdfSparqlBoundary_1.NativeSparqlExecutionError(`QLever returned an invalid graph result: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function toBindings(row, variables) {
+    const entries = [];
+    for (const variable of variables) {
+        const term = sparqlJsonTerm(row[variable]);
+        if (term) {
+            entries.push([rdfDataFactory.variable(variable), term]);
+        }
+    }
+    return new QleverBindings(entries);
+}
+function inferVariableNames(rows) {
+    const names = new Set();
+    for (const row of rows) {
+        for (const name of Object.keys(row)) {
+            names.add(name);
+        }
+    }
+    return [...names];
+}
+function sparqlJsonTerm(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const term = value;
+    if (typeof term.value !== 'string') {
+        return undefined;
+    }
+    if (term.type === 'uri') {
+        return rdfDataFactory.namedNode(term.value);
+    }
+    if (term.type === 'bnode') {
+        return rdfDataFactory.blankNode(term.value);
+    }
+    if (term.type === 'literal' || term.type === 'typed-literal') {
+        if (term['xml:lang']) {
+            return rdfDataFactory.literal(term.value, term['xml:lang']);
+        }
+        if (term.datatype) {
+            return rdfDataFactory.literal(term.value, rdfDataFactory.namedNode(term.datatype));
+        }
+        return rdfDataFactory.literal(term.value);
+    }
+    return undefined;
+}
+class QleverBindings extends Map {
+    constructor(entries) {
+        super(entries);
+        this.byName = new Map();
+        for (const [variable, term] of entries) {
+            this.byName.set(variable.value, term);
+        }
+    }
+    get(key) {
+        return typeof key === 'string'
+            ? this.byName.get(key)
+            : this.byName.get(key.value) ?? super.get(key);
+    }
+    has(key) {
+        return typeof key === 'string'
+            ? this.byName.has(key)
+            : this.byName.has(key.value) || super.has(key);
+    }
+}
+//# sourceMappingURL=QleverSparqlEngine.js.map

package/dist/storage/rdf/QleverSparqlEngine.jsonld

@@ -0,0 +1,70 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine",
+      "@type": "Class",
+      "requireElement": "QleverSparqlEngine",
+      "extends": [
+        "undefineds:dist/storage/sparql/SubgraphQueryEngine.jsonld#SparqlEngine"
+      ],
+      "comment": "Thin CSS SparqlEngine adapter over the shared native QLever envelope.  It performs product-boundary validation and result decoding only. It has no alternate evaluator, planner, update compiler, or secondary execution path.",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine_rdfEngine",
+          "range": "undefineds:dist/storage/rdf/types.jsonld#RdfEngineLike"
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_rdfEngine",
+          "memberFieldName": "rdfEngine"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_queryBindings",
+          "memberFieldName": "queryBindings"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_queryBoolean",
+          "memberFieldName": "queryBoolean"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_queryQuads",
+          "memberFieldName": "queryQuads"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_queryVoid",
+          "memberFieldName": "queryVoid"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_constructGraph",
+          "memberFieldName": "constructGraph"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_listGraphs",
+          "memberFieldName": "listGraphs"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_close",
+          "memberFieldName": "close"
+        },
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine__member_execute",
+          "memberFieldName": "execute"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/storage/rdf/QleverSparqlEngine.jsonld#QleverSparqlEngine_rdfEngine"
+        }
+      ]
+    }
+  ]
+}