@undefineds.co/xpod 0.3.58 → 0.3.62

package/dist/storage/rdf/SolidRdfSparqlEngine.js

@@ -2,12 +2,89 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SolidRdfSparqlEngine = void 0;
 const asynciterator_1 = require("asynciterator");
+const node_crypto_1 = require("node:crypto");
 const rdf_data_factory_1 = require("rdf-data-factory");
 const n3_1 = require("n3");
 const RdfSparqlAdapter_1 = require("./RdfSparqlAdapter");
+const RdfAccessScope_1 = require("./RdfAccessScope");
 const rdfDataFactory = new rdf_data_factory_1.DataFactory();
+const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+const DCT_CREATED = 'http://purl.org/dc/terms/created';
+const DCT_TITLE = 'http://purl.org/dc/terms/title';
+const SIOC_HAS_CONTAINER = 'http://rdfs.org/sioc/ns#has_container';
+const SIOC_HAS_MEMBER = 'http://rdfs.org/sioc/ns#has_member';
+const SIOC_HAS_PARENT = 'http://rdfs.org/sioc/ns#has_parent';
+const SIOC_THREAD = 'http://rdfs.org/sioc/ns#Thread';
+const MEETING_MESSAGE = 'http://www.w3.org/ns/pim/meeting#Message';
+const MEETING_LONG_CHAT = 'http://www.w3.org/ns/pim/meeting#LongChat';
+const FOAF_AGENT = 'http://xmlns.com/foaf/0.1/Agent';
+const VCARD_INDIVIDUAL = 'http://www.w3.org/2006/vcard/ns#Individual';
+const SCHEMA_CREATIVE_WORK = 'http://schema.org/CreativeWork';
+const SCHEMA_PROPERTY_VALUE = 'http://schema.org/PropertyValue';
+const UDFS_TASK = 'https://undefineds.co/ns#Task';
+const UDFS_RUN = 'https://undefineds.co/ns#Run';
+const UDFS_RUN_STEP = 'https://undefineds.co/ns#RunStep';
+const UDFS_SCHEDULE = 'https://undefineds.co/ns#Schedule';
+const UDFS_SESSION = 'https://undefineds.co/ns#Session';
+const UDFS_ISSUE = 'https://undefineds.co/ns#Issue';
+const UDFS_LAST_MESSAGE = 'https://undefineds.co/ns#lastMessage';
+const UDFS_STATUS = 'https://undefineds.co/ns#status';
+const UDFS_MESSAGE_STATUS = 'https://undefineds.co/ns#messageStatus';
+const UDFS_WORKSPACE = 'https://undefineds.co/ns#workspace';
+const UDFS_RUN_RELATION = 'https://undefineds.co/ns#run';
+const UDFS_TASK_RELATION = 'https://undefineds.co/ns#task';
+const UDFS_IN_THREAD = 'https://undefineds.co/ns#inThread';
+const UDFS_NEXT_RUN_AT = 'https://undefineds.co/ns#nextRunAt';
+const UDFS_LEASE_OWNER = 'https://undefineds.co/ns#leaseOwner';
+const UDFS_SESSION_STATUS = 'https://undefineds.co/ns#sessionStatus';
+const UDFS_CONVERSATION = 'https://undefineds.co/ns#conversation';
+const UDFS_TOKEN_USAGE = 'https://undefineds.co/ns#tokenUsage';
+const UDFS_PRIORITY = 'https://undefineds.co/ns#priority';
+const UDFS_SCORE = 'https://undefineds.co/ns#score';
+const XPOD_AI_PROVIDER = 'https://vocab.xpod.dev/ai#Provider';
+const XPOD_AI_MODEL = 'https://vocab.xpod.dev/ai#Model';
+const XPOD_AI_IS_PROVIDED_BY = 'https://vocab.xpod.dev/ai#isProvidedBy';
+const XPOD_CREDENTIAL = 'https://vocab.xpod.dev/credential#Credential';
+const XPOD_CREDENTIAL_PROVIDER = 'https://vocab.xpod.dev/credential#provider';
+const XPOD_CREDENTIAL_FAIL_COUNT = 'https://vocab.xpod.dev/credential#failCount';
+const PRODUCT_VIEW_MATERIALIZED_VERSION = 'v1';
+const SETTINGS_RESOURCE_TYPE_VIEWS = new Map([
+    [XPOD_AI_PROVIDER, 'ai-providers'],
+    [XPOD_AI_MODEL, 'ai-models'],
+    [XPOD_CREDENTIAL, 'credentials'],
+]);
+const PRODUCT_RESOURCE_TYPE_VIEWS = new Map([
+    [MEETING_LONG_CHAT, 'chats'],
+    [MEETING_MESSAGE, 'messages'],
+    [SIOC_THREAD, 'threads'],
+    [UDFS_TASK, 'tasks'],
+    [UDFS_RUN, 'runs'],
+    [UDFS_RUN_STEP, 'run-steps'],
+    [UDFS_SCHEDULE, 'schedules'],
+    [UDFS_SESSION, 'sessions'],
+    [UDFS_ISSUE, 'issues'],
+    [FOAF_AGENT, 'agents'],
+    [VCARD_INDIVIDUAL, 'contacts'],
+    [SCHEMA_CREATIVE_WORK, 'favorites'],
+    [SCHEMA_PROPERTY_VALUE, 'settings'],
+]);
+const PRODUCT_RELATION_PREDICATE_VIEWS = new Map([
+    [DCT_CREATED, 'created-timeline'],
+    [DCT_TITLE, 'title-hydration'],
+    [SIOC_HAS_PARENT, 'threads-by-chat'],
+    [UDFS_LAST_MESSAGE, 'chat-latest-message'],
+    [UDFS_STATUS, 'status-index'],
+    [UDFS_MESSAGE_STATUS, 'message-status-index'],
+    [UDFS_WORKSPACE, 'runs-by-workspace'],
+    [UDFS_RUN_RELATION, 'steps-by-run'],
+    [UDFS_TASK_RELATION, 'runs-by-task'],
+    [UDFS_IN_THREAD, 'runs-by-thread'],
+    [UDFS_NEXT_RUN_AT, 'schedules-by-due-time'],
+    [UDFS_LEASE_OWNER, 'runs-by-lease-owner'],
+    [UDFS_SESSION_STATUS, 'sessions-by-status'],
+]);
 class SolidRdfSparqlEngine {
-    constructor(rdfEngine, fallback, shadowStore, enablePrimary = true, onFallback) {
+    constructor(rdfEngine, fallback, shadowStore, enablePrimary = true, onFallback, autoMaterializeProductViews = true) {
         this.adapter = new RdfSparqlAdapter_1.RdfSparqlAdapter();
         this.operationCounts = new Map();
         this.rdfEngine = rdfEngine;
@@ -15,19 +92,25 @@ class SolidRdfSparqlEngine {
         this.shadowStore = shadowStore;
         this.enablePrimary = enablePrimary;
         this.onFallback = onFallback;
+        this.autoMaterializeProductViews = autoMaterializeProductViews;
     }
-    async queryBindings(query, basePath) {
+    async queryBindings(query, basePath, accessScope) {
         await this.ensureReady();
         if (!this.enablePrimary) {
-            return this.fallbackWith('queryBindings', 'primary disabled', (fallback) => fallback.queryBindings(query, basePath));
+            return this.fallbackWith('queryBindings', 'primary disabled', (fallback) => fallback.queryBindings(query, basePath, accessScope), accessScope);
         }
         const start = Date.now();
         try {
+            const native = await this.executeNativeSelectPrimary(query, basePath, 'queryBindings', start, accessScope);
+            if (native) {
+                return this.bindingsStream(native.result, native.variables);
+            }
             const compiled = this.adapter.compile(query, basePath);
             if (compiled.queryType !== 'SELECT') {
-                return this.fallbackWith('queryBindings', `compiled ${compiled.queryType} cannot produce bindings`, (fallback) => fallback.queryBindings(query, basePath));
+                return this.fallbackWith('queryBindings', `compiled ${compiled.queryType} cannot produce bindings`, (fallback) => fallback.queryBindings(query, basePath, accessScope), accessScope);
             }
-            const result = await this.rdfEngine.query(compiled.query);
+            const selectedQuery = this.applyMaterializedQuerySelector('queryBindings', compiled.query);
+            const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(selectedQuery, accessScope));
             this.recordPrimary('queryBindings', start, result);
             return this.bindingsStream(result, compiled.variables);
         }
@@ -35,21 +118,26 @@ class SolidRdfSparqlEngine {
             if (error instanceof RdfSparqlAdapter_1.DisabledSparqlFeatureError) {
                 throw error;
             }
-            return this.fallbackWith('queryBindings', fallbackReason(error), (fallback) => fallback.queryBindings(query, basePath));
+            return this.fallbackWith('queryBindings', fallbackReason(error), (fallback) => fallback.queryBindings(query, basePath, accessScope), accessScope, error);
         }
     }
-    async queryBoolean(query, basePath) {
+    async queryBoolean(query, basePath, accessScope) {
         await this.ensureReady();
         if (!this.enablePrimary) {
-            return this.fallbackWith('queryBoolean', 'primary disabled', (fallback) => fallback.queryBoolean(query, basePath));
+            return this.fallbackWith('queryBoolean', 'primary disabled', (fallback) => fallback.queryBoolean(query, basePath, accessScope), accessScope);
         }
         const start = Date.now();
         try {
+            const native = await this.executeNativeBooleanPrimary(query, basePath, 'queryBoolean', start, accessScope);
+            if (native !== undefined) {
+                return native;
+            }
             const compiled = this.adapter.compile(query, basePath);
             if (compiled.queryType !== 'ASK') {
-                return this.fallbackWith('queryBoolean', `compiled ${compiled.queryType} cannot produce boolean`, (fallback) => fallback.queryBoolean(query, basePath));
+                return this.fallbackWith('queryBoolean', `compiled ${compiled.queryType} cannot produce boolean`, (fallback) => fallback.queryBoolean(query, basePath, accessScope), accessScope);
             }
-            const result = await this.rdfEngine.query(compiled.query);
+            const selectedQuery = this.applyMaterializedQuerySelector('queryBoolean', compiled.query);
+            const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(selectedQuery, accessScope));
             this.recordPrimary('queryBoolean', start, result);
             return result.bindings.length > 0;
         }
@@ -57,33 +145,37 @@ class SolidRdfSparqlEngine {
             if (error instanceof RdfSparqlAdapter_1.DisabledSparqlFeatureError) {
                 throw error;
             }
-            return this.fallbackWith('queryBoolean', fallbackReason(error), (fallback) => fallback.queryBoolean(query, basePath));
+            return this.fallbackWith('queryBoolean', fallbackReason(error), (fallback) => fallback.queryBoolean(query, basePath, accessScope), accessScope, error);
         }
     }
-    async queryQuads(query, basePath) {
+    async queryQuads(query, basePath, accessScope) {
         await this.ensureReady();
         if (!this.enablePrimary) {
-            return this.fallbackWith('queryQuads', 'primary disabled', (fallback) => fallback.queryQuads(query, basePath));
+            return this.fallbackWith('queryQuads', 'primary disabled', (fallback) => fallback.queryQuads(query, basePath, accessScope), accessScope);
         }
         const start = Date.now();
         try {
-            const quads = await this.executeQuadsPrimary(query, basePath, 'queryQuads', start);
+            const quads = await this.executeQuadsPrimary(query, basePath, 'queryQuads', start, accessScope);
             return new asynciterator_1.ArrayIterator(quads);
         }
         catch (error) {
             if (error instanceof RdfSparqlAdapter_1.DisabledSparqlFeatureError) {
                 throw error;
             }
-            return this.fallbackWith('queryQuads', fallbackReason(error), (fallback) => fallback.queryQuads(query, basePath));
+            return this.fallbackWith('queryQuads', fallbackReason(error), (fallback) => fallback.queryQuads(query, basePath, accessScope), accessScope, error);
         }
     }
-    async queryVoid(query, basePath) {
+    async queryVoid(query, basePath, accessScope, options) {
         await this.ensureReady();
         if (!this.enablePrimary) {
-            return this.fallbackWith('queryVoid', 'primary disabled', (fallback) => fallback.queryVoid(query, basePath));
+            return this.fallbackWith('queryVoid', 'primary disabled', (fallback) => fallback.queryVoid(query, basePath, accessScope, options), accessScope);
         }
         const start = Date.now();
         try {
+            const native = await this.executeNativeVoidPrimary(query, basePath, 'queryVoid', start, accessScope, options);
+            if (native) {
+                return undefined;
+            }
             const delta = this.adapter.compileUpdateDelta(query, basePath, {
                 defaultGraph: implicitUpdateDefaultGraph(basePath),
             });
@@ -92,28 +184,33 @@ class SolidRdfSparqlEngine {
             let computedInserts = 0;
             for (const operation of delta.operations) {
                 if (operation.type === 'delete') {
+                    this.assertUpdateQuadsAllowedByAccessScope(operation.quads, basePath, accessScope);
                     deletedRows += (await this.rdfEngine.applyDelta(operation.quads.map(quadToPattern), [])).deletedRows;
                 }
                 else if (operation.type === 'insert') {
+                    this.assertUpdateQuadsAllowedByAccessScope(operation.quads, basePath, accessScope);
                     await this.rdfEngine.applyDelta([], operation.quads);
                 }
                 else if (operation.type === 'insertDeleteWhere') {
-                    const result = await this.rdfEngine.query(operation.query);
+                    const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(operation.query, accessScope));
                     const deletes = this.adapter.materializeDeleteWhere(operation.deletes, result.bindings);
                     const inserts = this.adapter.materializeDeleteWhere(operation.inserts, result.bindings);
+                    this.assertUpdateQuadsAllowedByAccessScope([...deletes, ...inserts], basePath, accessScope);
                     computedDeletes += deletes.length;
                     computedInserts += inserts.length;
                     deletedRows += (await this.rdfEngine.applyDelta(deletes.map(quadToPattern), inserts)).deletedRows;
                 }
                 else if (operation.type === 'insertWhere') {
-                    const result = await this.rdfEngine.query(operation.query);
+                    const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(operation.query, accessScope));
                     const inserts = this.adapter.materializeDeleteWhere(operation.inserts, result.bindings);
+                    this.assertUpdateQuadsAllowedByAccessScope(inserts, basePath, accessScope);
                     computedInserts += inserts.length;
                     await this.rdfEngine.applyDelta([], inserts);
                 }
                 else {
-                    const result = await this.rdfEngine.query(operation.query);
+                    const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(operation.query, accessScope));
                     const quads = this.adapter.materializeDeleteWhere(operation.template, result.bindings);
+                    this.assertUpdateQuadsAllowedByAccessScope(quads, basePath, accessScope);
                     computedDeletes += quads.length;
                     deletedRows += (await this.rdfEngine.applyDelta(quads.map(quadToPattern), [])).deletedRows;
                 }
@@ -138,15 +235,15 @@ class SolidRdfSparqlEngine {
             if (error instanceof RdfSparqlAdapter_1.DisabledSparqlFeatureError) {
                 throw error;
             }
-            return this.fallbackWith('queryVoid', fallbackReason(error), (fallback) => fallback.queryVoid(query, basePath));
+            return this.fallbackWith('queryVoid', fallbackReason(error), (fallback) => fallback.queryVoid(query, basePath, accessScope, options), accessScope, error);
         }
     }
-    async constructGraph(graph, basePath) {
+    async constructGraph(graph, basePath, accessScope) {
         await this.ensureReady();
         if (!this.enablePrimary) {
-            return this.fallbackWith('constructGraph', 'primary disabled', (fallback) => fallback.constructGraph(graph, basePath));
+            return this.fallbackWith('constructGraph', 'primary disabled', (fallback) => fallback.constructGraph(graph, basePath, accessScope), accessScope);
         }
-        if (!graph.startsWith(basePath)) {
+        if (!graph.startsWith(basePath) || (accessScope && !(0, RdfAccessScope_1.rdfAccessGraphAllowed)(graph, accessScope))) {
             return new asynciterator_1.ArrayIterator([]);
         }
         const start = Date.now();
@@ -154,26 +251,26 @@ class SolidRdfSparqlEngine {
             const quads = await this.executeConstructPrimary(`
         CONSTRUCT { ?s ?p ?o }
         WHERE { GRAPH <${escapeIri(graph)}> { ?s ?p ?o } }
-      `, basePath, 'constructGraph', start);
+      `, basePath, 'constructGraph', start, accessScope);
             return new asynciterator_1.ArrayIterator(quads);
         }
         catch (error) {
             if (error instanceof RdfSparqlAdapter_1.DisabledSparqlFeatureError) {
                 throw error;
             }
-            return this.fallbackWith('constructGraph', fallbackReason(error), (fallback) => fallback.constructGraph(graph, basePath));
+            return this.fallbackWith('constructGraph', fallbackReason(error), (fallback) => fallback.constructGraph(graph, basePath, accessScope), accessScope, error);
         }
     }
-    async listGraphs(basePath) {
+    async listGraphs(basePath, accessScope) {
         await this.ensureReady();
         if (!this.enablePrimary) {
-            return this.fallbackWith('listGraphs', 'primary disabled', (fallback) => fallback.listGraphs(basePath));
+            return this.fallbackWith('listGraphs', 'primary disabled', (fallback) => fallback.listGraphs(basePath, accessScope), accessScope);
         }
         const start = Date.now();
         try {
             const result = await this.executeSelectPrimary(`
         SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } }
-      `, basePath, 'listGraphs', start);
+      `, basePath, 'listGraphs', start, accessScope);
             const graphs = new Set();
             for (const binding of result.bindings) {
                 const graph = binding.g;
@@ -181,13 +278,13 @@ class SolidRdfSparqlEngine {
                     graphs.add(graph.value);
                 }
             }
-            return graphs;
+            return (0, RdfAccessScope_1.filterRdfAccessGraphs)(graphs, accessScope);
         }
         catch (error) {
             if (error instanceof RdfSparqlAdapter_1.DisabledSparqlFeatureError) {
                 throw error;
             }
-            return this.fallbackWith('listGraphs', fallbackReason(error), (fallback) => fallback.listGraphs(basePath));
+            return this.fallbackWith('listGraphs', fallbackReason(error), (fallback) => fallback.listGraphs(basePath, accessScope), accessScope, error);
         }
     }
     async close() {
@@ -246,6 +343,22 @@ class SolidRdfSparqlEngine {
         });
         return iterator;
     }
+    applyMaterializedQuerySelector(operation, query) {
+        if (query.cache?.materialized || !this.autoMaterializeProductViews) {
+            return query;
+        }
+        const materialized = defaultMaterializedQuerySelector(operation, query);
+        if (!materialized) {
+            return query;
+        }
+        return {
+            ...query,
+            cache: {
+                ...query.cache,
+                materialized,
+            },
+        };
+    }
     bindings(binding, variables) {
         const entries = variables
             .map((variableName) => {
@@ -255,9 +368,24 @@ class SolidRdfSparqlEngine {
             .filter((entry) => entry !== null);
         return new RdfBindings(entries);
     }
-    async fallbackWith(operation, reason, run) {
+    async fallbackWith(operation, reason, run, accessScope, cause) {
+        const embeddedReason = embeddedUnsupportedReason(reason);
+        if (cause instanceof RdfSparqlAdapter_1.NativeSparqlExecutionError) {
+            throw cause;
+        }
+        const inherited = cause instanceof RdfSparqlAdapter_1.UnsupportedSparqlQueryError
+            ? {
+                code: cause.code,
+                capability: cause.capability,
+                hint: cause.hint,
+                correction: cause.correction,
+            }
+            : undefined;
+        if ((0, RdfAccessScope_1.isRestrictiveRdfAccessScope)(accessScope)) {
+            throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`Embedded SPARQL engine cannot execute ${operation} inside ACL/ACR-restricted scope: ${embeddedReason}`, inherited);
+        }
         if (!this.fallback) {
-            throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`No compatibility SPARQL fallback configured for ${operation}: ${reason}`);
+            throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`Embedded SPARQL engine cannot execute ${operation}: ${embeddedReason}`, inherited);
         }
         this.onFallback?.({ operation, reason });
         const start = Date.now();
@@ -273,21 +401,43 @@ class SolidRdfSparqlEngine {
             await this.shadowStore.open();
         }
     }
-    async executeSelectPrimary(query, basePath, operation, start) {
+    async executeSelectPrimary(query, basePath, operation, start, accessScope) {
+        const native = await this.executeNativeSelectPrimary(query, basePath, operation, start, accessScope);
+        if (native) {
+            return native.result;
+        }
         const compiled = this.adapter.compile(query, basePath);
         if (compiled.queryType !== 'SELECT') {
             throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`compiled ${compiled.queryType} cannot produce bindings`);
         }
-        const result = await this.rdfEngine.query(compiled.query);
+        const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(compiled.query, accessScope));
         this.recordPrimary(operation, start, result);
         return result;
     }
-    async executeConstructPrimary(query, basePath, operation, start) {
+    assertUpdateQuadsAllowedByAccessScope(quads, basePath, accessScope) {
+        if (!isWriteAccessScope(accessScope) || !(0, RdfAccessScope_1.isRestrictiveRdfAccessScope)(accessScope)) {
+            return;
+        }
+        for (const quad of quads) {
+            const graph = quad.graph.termType === 'DefaultGraph' ? basePath : quad.graph.value;
+            if (!(0, RdfAccessScope_1.rdfAccessGraphAllowed)(graph, accessScope)) {
+                throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`Embedded SPARQL engine cannot execute queryVoid: update target graph is outside the authorized RDF access scope: ${graph}`, {
+                    capability: 'sparql.update.access_scope',
+                    hint: 'Authorize the target graph for this write, or split the update so each write target is inside the granted graph scope.',
+                });
+            }
+        }
+    }
+    async executeConstructPrimary(query, basePath, operation, start, accessScope) {
+        const native = await this.executeNativeGraphPrimary(query, basePath, operation, start, accessScope);
+        if (native) {
+            return native;
+        }
         const compiled = this.adapter.compile(query, basePath);
         if (compiled.queryType !== 'CONSTRUCT' || !compiled.constructTemplate) {
             throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`compiled ${compiled.queryType} cannot produce quads`);
         }
-        const result = await this.rdfEngine.query(compiled.query);
+        const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(compiled.query, accessScope));
         const quads = this.adapter.materializeConstruct(compiled.constructTemplate, result.bindings, rdfDataFactory.defaultGraph());
         this.recordPrimary(operation, start, {
             ...result,
@@ -300,10 +450,14 @@ class SolidRdfSparqlEngine {
         });
         return quads;
     }
-    async executeQuadsPrimary(query, basePath, operation, start) {
+    async executeQuadsPrimary(query, basePath, operation, start, accessScope) {
+        const native = await this.executeNativeGraphPrimary(query, basePath, operation, start, accessScope);
+        if (native) {
+            return native;
+        }
         const compiled = this.adapter.compile(query, basePath);
         if (compiled.queryType === 'CONSTRUCT' && compiled.constructTemplate) {
-            const result = await this.rdfEngine.query(compiled.query);
+            const result = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(compiled.query, accessScope));
             const quads = this.adapter.materializeConstruct(compiled.constructTemplate, result.bindings, rdfDataFactory.defaultGraph());
             this.recordPrimary(operation, start, {
                 ...result,
@@ -317,12 +471,12 @@ class SolidRdfSparqlEngine {
             return quads;
         }
         if (compiled.queryType === 'DESCRIBE' && compiled.describeTargets) {
-            return this.executeDescribePrimary(compiled.query, compiled.describeTargets, basePath, operation, start);
+            return this.executeDescribePrimary(compiled.query, compiled.describeTargets, basePath, operation, start, accessScope);
         }
         throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`compiled ${compiled.queryType} cannot produce quads`);
     }
-    async executeDescribePrimary(query, targets, basePath, operation, start) {
-        const seed = await this.rdfEngine.query(query);
+    async executeDescribePrimary(query, targets, basePath, operation, start, accessScope) {
+        const seed = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)(query, accessScope));
         const quads = [];
         const seen = new Set();
         for (const target of targets) {
@@ -331,7 +485,7 @@ class SolidRdfSparqlEngine {
                 if (!subject || subject.termType !== 'NamedNode') {
                     continue;
                 }
-                const describe = await this.rdfEngine.query({
+                const describe = await this.rdfEngine.query((0, RdfAccessScope_1.applyRdfAccessScope)({
                     patterns: [
                         {
                             subject,
@@ -341,7 +495,7 @@ class SolidRdfSparqlEngine {
                         },
                     ],
                     select: ['p', 'o'],
-                });
+                }, accessScope));
                 for (const row of describe.bindings) {
                     const predicate = row.p;
                     const object = row.o;
@@ -367,6 +521,83 @@ class SolidRdfSparqlEngine {
         });
         return quads;
     }
+    async executeNativeVoidPrimary(query, basePath, operation, start, accessScope, options) {
+        const envelope = await this.runNativeSparql(query, basePath, operation, 'application/sparql-results+json', accessScope, options);
+        if (!envelope) {
+            return false;
+        }
+        this.recordPrimary(operation, start, {
+            bindings: [],
+            metrics: nativeSparqlMetrics(envelope, 0, Date.now() - start),
+        });
+        return true;
+    }
+    async executeNativeSelectPrimary(query, basePath, operation, start, accessScope) {
+        const envelope = await this.runNativeSparql(query, basePath, operation, 'application/sparql-results+json', accessScope);
+        if (!envelope) {
+            return undefined;
+        }
+        const parsed = parseNativeSparqlJsonResult(envelope, Date.now() - start);
+        if (!parsed.result) {
+            throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError('native SPARQL result did not contain SELECT bindings');
+        }
+        this.recordPrimary(operation, start, parsed.result);
+        return {
+            result: parsed.result,
+            variables: parsed.variables,
+        };
+    }
+    async executeNativeBooleanPrimary(query, basePath, operation, start, accessScope) {
+        const envelope = await this.runNativeSparql(query, basePath, operation, 'application/sparql-results+json', accessScope);
+        if (!envelope) {
+            return undefined;
+        }
+        const parsed = parseNativeSparqlJsonResult(envelope, Date.now() - start);
+        if (parsed.boolean === undefined) {
+            throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError('native SPARQL result did not contain ASK boolean');
+        }
+        const result = {
+            bindings: parsed.boolean ? [{}] : [],
+            metrics: nativeSparqlMetrics(envelope, parsed.boolean ? 1 : 0, Date.now() - start),
+        };
+        this.recordPrimary(operation, start, result);
+        return parsed.boolean;
+    }
+    async executeNativeGraphPrimary(query, basePath, operation, start, accessScope) {
+        const envelope = await this.runNativeSparql(query, basePath, operation, 'application/n-triples', accessScope);
+        if (!envelope) {
+            return undefined;
+        }
+        const quads = parseNativeGraphResult(envelope);
+        this.recordPrimary(operation, start, {
+            bindings: [],
+            metrics: nativeSparqlMetrics(envelope, quads.length, Date.now() - start),
+        });
+        return quads;
+    }
+    async runNativeSparql(query, basePath, operation, acceptMediaType, accessScope, options) {
+        if (typeof this.rdfEngine.sparqlQuery !== 'function') {
+            return undefined;
+        }
+        this.adapter.assertServerOwnedNativeQuery(query, basePath);
+        const result = await this.rdfEngine.sparqlQuery(query, {
+            basePath,
+            operation,
+            acceptMediaType,
+            accessScope,
+            ...(options?.loadDocument ? { loadDocument: options.loadDocument } : {}),
+        });
+        if (result.status === 'ok') {
+            return result;
+        }
+        if (result.status === 'error') {
+            throw new RdfSparqlAdapter_1.NativeSparqlExecutionError(result.error || 'native SPARQL engine returned error status');
+        }
+        throw new RdfSparqlAdapter_1.UnsupportedSparqlQueryError(`native SPARQL engine returned ${result.status}${result.error ? `: ${result.error}` : ''}`, {
+            capability: 'sparql.native',
+            hint: 'Run the query through a native SPARQL engine that can access the current Pod scope, or disable the native SPARQL path for this engine.',
+        });
+    }
     recordPrimary(operation, start, result) {
         const durationMs = Date.now() - start;
         const counts = this.countsFor(operation);
@@ -379,6 +610,7 @@ class SolidRdfSparqlEngine {
             returnedRows: result.metrics.returnedRows,
             plan: result.metrics.plan,
             indexChoices: result.metrics.indexChoices,
+            nativeProfile: result.metrics.nativeProfile,
         };
     }
     recordFallback(operation, reason, durationMs) {
@@ -407,6 +639,92 @@ class SolidRdfSparqlEngine {
     }
 }
 exports.SolidRdfSparqlEngine = SolidRdfSparqlEngine;
+function parseNativeSparqlJsonResult(envelope, durationMs) {
+    const payload = JSON.parse(envelope.body);
+    const variables = payload.head?.vars ?? [];
+    if (typeof payload.boolean === 'boolean') {
+        return { variables, boolean: payload.boolean };
+    }
+    const bindings = (payload.results?.bindings ?? []).map((row) => nativeSparqlBindingRow(row));
+    return {
+        variables,
+        result: {
+            bindings,
+            metrics: nativeSparqlMetrics(envelope, bindings.length, durationMs),
+        },
+    };
+}
+function nativeSparqlBindingRow(row) {
+    const binding = {};
+    for (const [variable, value] of Object.entries(row)) {
+        const term = nativeSparqlJsonTerm(value);
+        if (term) {
+            binding[variable] = term;
+        }
+    }
+    return binding;
+}
+function nativeSparqlJsonTerm(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;
+}
+function parseNativeGraphResult(envelope) {
+    const mediaType = envelope.mediaType.toLowerCase();
+    const parser = new n3_1.Parser({
+        format: mediaType.includes('n-quads')
+            ? 'N-Quads'
+            : mediaType.includes('turtle')
+                ? 'Turtle'
+                : 'N-Triples',
+    });
+    return parser.parse(envelope.body);
+}
+function nativeSparqlMetrics(envelope, returnedRows, durationMs) {
+    const profile = envelope.profile && typeof envelope.profile === 'object'
+        ? envelope.profile
+        : undefined;
+    const root = profile?.root && typeof profile.root === 'object'
+        ? profile.root
+        : undefined;
+    const rootKind = typeof root?.kind === 'string' ? root.kind : undefined;
+    const descriptor = typeof root?.descriptor === 'string' ? root.descriptor : undefined;
+    const profiledRows = typeof root?.outputRows === 'number' && Number.isFinite(root.outputRows)
+        ? root.outputRows
+        : returnedRows;
+    return {
+        engine: 'solid-rdf',
+        plan: ['NativeSparql', envelope.mediaType, ...(rootKind ? [`Native:${rootKind}`] : [])],
+        nativeProfile: envelope.profile,
+        scannedRows: profiledRows,
+        joinedRows: returnedRows,
+        returnedRows,
+        durationMs,
+        indexChoices: ['native-sparql', ...(descriptor ? [descriptor] : [])],
+        filtersApplied: 0,
+        filtersPushedDown: 0,
+    };
+}
 class RdfBindings extends Map {
     constructor(entries) {
         super(entries);
@@ -449,6 +767,12 @@ function isQuadObjectTerm(term) {
         && term.termType !== 'DefaultGraph'
         && term.termType !== 'Quad');
 }
+function isWriteAccessScope(scope) {
+    return Boolean(scope
+        && (scope.mode === RdfAccessScope_1.RdfAccessMode.APPEND
+            || scope.mode === RdfAccessScope_1.RdfAccessMode.DELETE
+            || scope.mode === RdfAccessScope_1.RdfAccessMode.WRITE));
+}
 function fallbackReason(error) {
     if (error instanceof RdfSparqlAdapter_1.UnsupportedSparqlQueryError) {
         return error.message;
@@ -458,6 +782,11 @@ function fallbackReason(error) {
     }
     return String(error);
 }
+function embeddedUnsupportedReason(reason) {
+    return reason
+        .replace(/\s+fallback to compatibility engine\b/gi, ' is not supported by the embedded RDF engine')
+        .replace(/\bis handled by the compatibility engine\b/gi, 'is not supported by the embedded RDF engine');
+}
 function operationCountSnapshot(operation, counts) {
     const totalCount = counts.primaryCount + counts.fallbackCount;
     return {
@@ -473,6 +802,307 @@ function operationCountSnapshot(operation, counts) {
 function ratio(numerator, denominator) {
     return denominator === 0 ? 0 : numerator / denominator;
 }
+function defaultMaterializedQuerySelector(operation, query) {
+    if (operation !== 'queryBindings') {
+        return undefined;
+    }
+    if (hasSearchSources(query)) {
+        return undefined;
+    }
+    return statsProductViewMaterializedResult(query)
+        ?? threadHistoryMaterializedResult(query)
+        ?? settingsProductViewMaterializedResult(query)
+        ?? agentContextMaterializedResult(query)
+        ?? stableProductViewMaterializedResult(query);
+}
+function statsProductViewMaterializedResult(query) {
+    const view = statsProductView(query);
+    if (!view) {
+        return undefined;
+    }
+    return {
+        key: `models/stats/${view}/${shortHash(stableQueryFingerprint(query))}`,
+        version: PRODUCT_VIEW_MATERIALIZED_VERSION,
+    };
+}
+function statsProductView(query) {
+    if (!hasStatsShape(query) || !hasProductGraphScope(query)) {
+        return undefined;
+    }
+    const predicates = new Set();
+    const hasType = new Set();
+    for (const pattern of query.patterns) {
+        const predicate = namedNodeValue(pattern.predicate);
+        if (!predicate) {
+            continue;
+        }
+        predicates.add(predicate);
+        if (predicate === RDF_TYPE) {
+            const type = namedNodeValue(pattern.object);
+            if (type) {
+                hasType.add(type);
+            }
+        }
+    }
+    if (predicates.has(XPOD_AI_IS_PROVIDED_BY) && predicates.has(XPOD_CREDENTIAL_PROVIDER)) {
+        return predicates.has(XPOD_CREDENTIAL_FAIL_COUNT)
+            ? 'provider-credential-failures'
+            : 'provider-credential-counts';
+    }
+    if (predicates.has(SIOC_HAS_CONTAINER) || predicates.has(SIOC_HAS_MEMBER)) {
+        return predicates.has(UDFS_SCORE)
+            ? 'message-score-by-thread'
+            : 'message-count-by-thread';
+    }
+    if (predicates.has(UDFS_STATUS) && predicates.has(UDFS_PRIORITY)) {
+        return 'run-priority-summary';
+    }
+    const views = new Set();
+    for (const type of hasType) {
+        const view = SETTINGS_RESOURCE_TYPE_VIEWS.get(type) ?? PRODUCT_RESOURCE_TYPE_VIEWS.get(type);
+        if (view) {
+            views.add(view);
+        }
+    }
+    for (const predicate of predicates) {
+        const view = PRODUCT_RELATION_PREDICATE_VIEWS.get(predicate);
+        if (view) {
+            views.add(view);
+        }
+    }
+    if (views.size === 0) {
+        return undefined;
+    }
+    return `${[...views].sort().join('+')}-${statsAggregateKind(query)}`;
+}
+function hasStatsShape(query) {
+    return queryAggregates(query).length > 0
+        || (query.groupBy?.length ?? 0) > 0
+        || (query.having?.length ?? 0) > 0;
+}
+function statsAggregateKind(query) {
+    const aggregates = queryAggregates(query);
+    const aggregateKind = aggregates.every((aggregate) => aggregate.type === 'count')
+        ? 'counts'
+        : 'numeric-summary';
+    return (query.groupBy?.length ?? 0) > 0 ? `grouped-${aggregateKind}` : aggregateKind;
+}
+function queryAggregates(query) {
+    return query.aggregates && query.aggregates.length > 0
+        ? query.aggregates
+        : query.aggregate
+            ? [query.aggregate]
+            : [];
+}
+function threadHistoryMaterializedResult(query) {
+    const threadIri = threadHistoryQueryThreadIri(query);
+    if (!threadIri) {
+        return undefined;
+    }
+    return {
+        key: `chatkit/thread-history/${shortHash(threadIri)}/${shortHash(stableQueryFingerprint(query))}`,
+        version: PRODUCT_VIEW_MATERIALIZED_VERSION,
+    };
+}
+function threadHistoryQueryThreadIri(query) {
+    for (const pattern of query.patterns) {
+        const predicate = namedNodeValue(pattern.predicate);
+        if (predicate !== SIOC_HAS_CONTAINER && predicate !== SIOC_HAS_MEMBER) {
+            continue;
+        }
+        const object = namedNodeValue(pattern.object);
+        if (object) {
+            return object;
+        }
+    }
+    return undefined;
+}
+function settingsProductViewMaterializedResult(query) {
+    const view = settingsProductView(query);
+    if (!view) {
+        return undefined;
+    }
+    return {
+        key: `models/settings/${view}/${shortHash(stableQueryFingerprint(query))}`,
+        version: PRODUCT_VIEW_MATERIALIZED_VERSION,
+    };
+}
+function settingsProductView(query) {
+    const typeViews = new Set();
+    let hasModelProviderLink = false;
+    let hasCredentialProviderLink = false;
+    for (const pattern of query.patterns) {
+        const predicate = namedNodeValue(pattern.predicate);
+        if (predicate === RDF_TYPE) {
+            const typeView = SETTINGS_RESOURCE_TYPE_VIEWS.get(namedNodeValue(pattern.object) ?? '');
+            if (typeView) {
+                typeViews.add(typeView);
+            }
+            continue;
+        }
+        if (predicate === XPOD_AI_IS_PROVIDED_BY) {
+            hasModelProviderLink = true;
+            continue;
+        }
+        if (predicate === XPOD_CREDENTIAL_PROVIDER) {
+            hasCredentialProviderLink = true;
+        }
+    }
+    if (hasModelProviderLink && hasCredentialProviderLink) {
+        return 'provider-model-credentials';
+    }
+    if (typeViews.size === 0) {
+        return undefined;
+    }
+    return [...typeViews].sort().join('+');
+}
+function agentContextMaterializedResult(query) {
+    const view = agentContextProductView(query);
+    if (!view) {
+        return undefined;
+    }
+    return {
+        key: `models/agent-context/${view}/${shortHash(stableQueryFingerprint(query))}`,
+        version: PRODUCT_VIEW_MATERIALIZED_VERSION,
+    };
+}
+function agentContextProductView(query) {
+    if (!query.patterns.some(isProductGraphScoped)) {
+        return undefined;
+    }
+    const types = new Set();
+    const predicates = new Set();
+    for (const pattern of query.patterns) {
+        const predicate = namedNodeValue(pattern.predicate);
+        if (!predicate) {
+            continue;
+        }
+        predicates.add(predicate);
+        if (predicate === RDF_TYPE) {
+            const type = namedNodeValue(pattern.object);
+            if (type) {
+                types.add(type);
+            }
+        }
+    }
+    if (types.has(UDFS_SESSION)
+        && types.has(MEETING_LONG_CHAT)
+        && types.has(SIOC_THREAD)
+        && predicates.has(UDFS_SESSION_STATUS)
+        && predicates.has(UDFS_CONVERSATION)
+        && predicates.has(UDFS_IN_THREAD)) {
+        return predicates.has(UDFS_TOKEN_USAGE)
+            ? 'active-session-thread-usage'
+            : 'active-session-thread-hydration';
+    }
+    return undefined;
+}
+function stableProductViewMaterializedResult(query) {
+    const view = stableProductView(query);
+    if (!view) {
+        return undefined;
+    }
+    return {
+        key: `models/product-views/${view}/${shortHash(stableQueryFingerprint(query))}`,
+        version: PRODUCT_VIEW_MATERIALIZED_VERSION,
+    };
+}
+function stableProductView(query) {
+    const views = new Set();
+    for (const pattern of query.patterns) {
+        const predicate = namedNodeValue(pattern.predicate);
+        if (predicate === RDF_TYPE) {
+            const typeView = PRODUCT_RESOURCE_TYPE_VIEWS.get(namedNodeValue(pattern.object) ?? '');
+            if (typeView) {
+                views.add(typeView);
+            }
+            continue;
+        }
+        const predicateView = isProductGraphScoped(pattern)
+            ? PRODUCT_RELATION_PREDICATE_VIEWS.get(predicate ?? '')
+            : undefined;
+        if (predicateView) {
+            views.add(predicateView);
+        }
+    }
+    if (views.size === 0) {
+        return undefined;
+    }
+    return [...views].sort().join('+');
+}
+function hasSearchSources(query) {
+    return (query.textSearch?.length ?? 0) > 0
+        || (query.vectorSearch?.length ?? 0) > 0;
+}
+function isProductGraphScoped(pattern) {
+    const graph = namedNodeValue(pattern.graph) ?? graphPrefixValue(pattern.graph);
+    return Boolean(graph && isProductGraphPath(graph));
+}
+function hasProductGraphScope(query) {
+    if (query.patterns.some(isProductGraphScoped)) {
+        return true;
+    }
+    const graphVariables = new Set(query.patterns
+        .map((pattern) => variableValue(pattern.graph))
+        .filter((variable) => Boolean(variable)));
+    if (graphVariables.size === 0) {
+        return false;
+    }
+    return (query.filters ?? []).some((filter) => (graphVariables.has(filter.variable)
+        && filter.operator === '$startsWith'
+        && filter.operand === 'stringValue'
+        && typeof filter.value === 'string'
+        && isProductGraphPath(filter.value)));
+}
+function isProductGraphPath(graph) {
+    return graph.includes('/.data/chat/')
+        || graph.includes('/.data/task/')
+        || graph.includes('/.data/sessions/')
+        || graph.includes('/.data/agents/')
+        || graph.includes('/.data/approvals/')
+        || graph.includes('/.data/audits/')
+        || graph.includes('/.data/issues/')
+        || graph.includes('/settings/');
+}
+function graphPrefixValue(term) {
+    if (!term || typeof term !== 'object' || 'variable' in term || 'termType' in term) {
+        return undefined;
+    }
+    return '$startsWith' in term && typeof term.$startsWith === 'string'
+        ? term.$startsWith
+        : undefined;
+}
+function namedNodeValue(term) {
+    if (!term || typeof term !== 'object' || 'variable' in term || !('termType' in term)) {
+        return undefined;
+    }
+    return term.termType === 'NamedNode' ? term.value : undefined;
+}
+function variableValue(term) {
+    if (!term || typeof term !== 'object' || !('variable' in term)) {
+        return undefined;
+    }
+    return term.variable;
+}
+function stableQueryFingerprint(query) {
+    const { cache: _cache, ...rest } = query;
+    return stableStringify(rest);
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entry]) => typeof entry !== 'function' && entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+}
+function shortHash(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, 16);
+}
 function implicitUpdateDefaultGraph(basePath) {
     return basePath.endsWith('/') ? undefined : basePath;
 }