@origintrail-official/dkg-query 10.0.5 → 10.0.7

package/dist/dkg-query-engine.d.ts

@@ -1,5 +1,5 @@
-import type { TripleStore, Quad } from '@origintrail-official/dkg-storage';
-import type { QueryResult, QueryOptions, QueryEngine } from './query-engine.js';
+import type { TripleStore } from '@origintrail-official/dkg-storage';
+import type { QueryResult, QueryOptions, GraphAwareQueryEngine, ResolvedKnowledgeAsset, ResolvedLegacyKnowledgeAsset } from './query-engine.js';
 import { type GetView, TrustLevel } from '@origintrail-official/dkg-core';
 /**
  * Result of resolving a V10 GET view to concrete graph targets.
@@ -50,7 +50,7 @@ export declare function resolveViewGraphs(view: GetView, contextGraphId: string,
  * Isolation). All data must arrive via protocol messages (publish, access,
  * sync) before it can be queried here.
  */
-export declare class DKGQueryEngine implements QueryEngine {
+export declare class DKGQueryEngine implements GraphAwareQueryEngine {
     private readonly store;
     private readonly graphManager;
     private readonly scopedContentGraphAllowListInFlight;
@@ -65,6 +65,8 @@ export declare class DKGQueryEngine implements QueryEngine {
      * Execute a SPARQL query scoped to a declared V10 state view.
      */
     private queryWithView;
+    /** Canonical graph rewrite for root + per-KA/per-cgId verifiable-memory reads. */
+    private wrapVerifiableMemoryGraphSet;
     private queryMultipleGraphs;
     private discoverGraphsByPrefix;
     /**
@@ -78,6 +80,15 @@ export declare class DKGQueryEngine implements QueryEngine {
      * private/SWM rows.
      */
     private discoverContextGraphPerCgIdDataGraphs;
+    /**
+     * Resolve only the immutable private graphs referenced by valid current V2
+     * metadata in this exact context graph. The broad `/_private/` prefix also
+     * contains mutable WM drafts, so prefix-enumerating it would let an
+     * `includePrivate` query cross the draft/finalized boundary. Deriving each
+     * graph from the canonical UAL + assertion version keeps the allow-list
+     * fail-closed and makes GRAPH-variable discovery work for rootless KAs.
+     */
+    private discoverGraphScopedPrivateGraphs;
     /**
      * Resolve a WM assertion's allocated KA number (`dkg:kaId`) off its lifecycle URN
      * in `_meta`, for single-graph by-name reads under the uniform layout. Returns
@@ -92,12 +103,10 @@ export declare class DKGQueryEngine implements QueryEngine {
     private discoverRegisteredAssertionGraphs;
     private discoverKnownChildContextGraphUris;
     private execAndNormalize;
-    resolveKA(ual: string): Promise<{
-        rootEntity: string;
-        rootEntities: string[];
-        contextGraphId: string;
-        quads: Quad[];
-    }>;
+    resolveKA(ual: string): Promise<ResolvedLegacyKnowledgeAsset>;
+    resolveKnowledgeAsset(ual: string): Promise<ResolvedKnowledgeAsset>;
+    private resolveGraphScopedKA;
+    private resolveLegacyRootScopedKA;
     /**
      * Execute a query across all locally-stored context graphs.
      */

package/dist/dkg-query-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dkg-query-engine.d.ts","sourceRoot":"","sources":["../src/dkg-query-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAmC,MAAM,mCAAmC,CAAC;AAE5G,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAOL,KAAK,OAAO,EAEZ,UAAU,EAEX,MAAM,gCAAgC,CAAC;AAQxC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE;IACL,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,cAAc,CA0IhB;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAG5C,OAAO,CAAC,QAAQ,CAAC,mCAAmC,CAAwC;gBAEhF,KAAK,EAAE,WAAW;IAKxB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAyLzE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;YACW,aAAa;YA0Jb,mBAAmB;YAuEnB,sBAAsB;IAOpC;;;;;;;;;OASG;YACW,qCAAqC;IASnD;;;;;OAKG;YACW,4BAA4B;YAsB5B,mCAAmC;YAqBnC,kCAAkC;YAsBlC,mCAAmC;YA8BnC,+BAA+B;YAsB/B,iCAAiC;YAqBjC,kCAAkC;YA2BlC,gBAAgB;IAmBxB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QACpC,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,IAAI,EAAE,CAAC;KACf,CAAC;IAgFF;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAYlE;AA05BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoCtE"}
+{"version":3,"file":"dkg-query-engine.d.ts","sourceRoot":"","sources":["../src/dkg-query-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAyC,MAAM,mCAAmC,CAAC;AAO5G,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,EAErB,sBAAsB,EACtB,4BAA4B,EAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAQL,KAAK,OAAO,EAEZ,UAAU,EAOX,MAAM,gCAAgC,CAAC;AAQxC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE;IACL,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,cAAc,CAgKhB;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,qBAAqB;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAG5C,OAAO,CAAC,QAAQ,CAAC,mCAAmC,CAAwC;gBAEhF,KAAK,EAAE,WAAW;IAKxB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA+LzE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;YACW,aAAa;IA+J3B,kFAAkF;IAClF,OAAO,CAAC,4BAA4B;YAQtB,mBAAmB;YAsFnB,sBAAsB;IAOpC;;;;;;;;;OASG;YACW,qCAAqC;IASnD;;;;;;;OAOG;YACW,gCAAgC;IAkE9C;;;;;OAKG;YACW,4BAA4B;YAsB5B,mCAAmC;YAqBnC,kCAAkC;YAsBlC,mCAAmC;YA8BnC,+BAA+B;YAsB/B,iCAAiC;YAqBjC,kCAAkC;YA2BlC,gBAAgB;IAmBxB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC;IAU7D,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;YAe3D,oBAAoB;YAsCpB,yBAAyB;IAkFvC;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAYlE;AAo6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoCtE"}

package/dist/dkg-query-engine.js

@@ -1,5 +1,5 @@
-import { GraphManager } from '@origintrail-official/dkg-storage';
-import { contextGraphDataUri, contextGraphSharedMemoryUri, contextGraphVerifiableMemoryUri, contextGraphAssertionUri, contextGraphLayerUri, MemoryLayer, contextGraphSubGraphUri, contextGraphMetaUri, contextGraphSharedMemoryMetaUri, assertionLifecycleUri, contextGraphSubGraphMetaUri, contextGraphPrivateUri, contextGraphSubGraphPrivateUri, assertSafeIri, escapeSparqlLiteral, validateSubGraphName, ASSERTION_NAMED_GRAPH_PREFIX, isAssertionScopedChildGraph, REMOVED_VIEWS, TrustLevel, TRUST_LEVEL_PREDICATE, } from '@origintrail-official/dkg-core';
+import { ExactGraphReadError, GraphManager, readExactGraphPaged, resolveGraphScopedOrLegacyMetadata, } from '@origintrail-official/dkg-storage';
+import { contextGraphDataUri, contextGraphSharedMemoryUri, contextGraphVerifiableMemoryUri, contextGraphAssertionUri, MemoryLayer, contextGraphLayerUriCandidates, contextGraphLayerPrefixCandidates, contextGraphSubGraphUri, contextGraphMetaUri, contextGraphSharedMemoryMetaUri, assertionLifecycleUri, contextGraphSubGraphMetaUri, contextGraphPrivateUri, contextGraphSubGraphPrivateUri, assertSafeIri, escapeSparqlLiteral, validateSubGraphName, ASSERTION_NAMED_GRAPH_PREFIX, isAssertionScopedChildGraph, REMOVED_VIEWS, TrustLevel, TRUST_LEVEL_PREDICATE, GRAPH_KA_CONTENT_SCOPE_VERSION, createGraphKnowledgeAssetScope, knowledgeAssetLayerGraphUri, buildLegacyKnowledgeAssetMetadataQuery, } from '@origintrail-official/dkg-core';
 import { validateReadOnlySparql, emptyResultForSparql, detectSparqlQueryForm, } from './sparql-guard.js';
 import { stripLiteralsAndComments } from './sparql-utils.js';
 export class ScopedQueryViolationError extends Error {
@@ -38,32 +38,41 @@ export function resolveViewGraphs(view, contextGraphId, opts) {
             // `subGraphName` + `assertionName` read targets the ROOT assertion graph and
             // misses sub-graph assertions (Codex review on PR #1132).
             if (opts.assertionName) {
+                if (opts.kaNumber !== undefined) {
+                    return {
+                        graphs: contextGraphLayerUriCandidates(contextGraphId, MemoryLayer.WorkingMemory, opts.agentAddress, opts.kaNumber, opts.subGraphName),
+                        graphPrefixes: [],
+                    };
+                }
                 return {
-                    graphs: [opts.kaNumber !== undefined
-                            ? contextGraphLayerUri(contextGraphId, MemoryLayer.WorkingMemory, opts.agentAddress, opts.kaNumber, opts.subGraphName)
-                            : contextGraphAssertionUri(contextGraphId, opts.agentAddress, opts.assertionName, opts.subGraphName)],
+                    graphs: [contextGraphAssertionUri(contextGraphId, opts.agentAddress, opts.assertionName, opts.subGraphName)],
                     graphPrefixes: [],
                 };
             }
             // PR #1107 review (🟡): span the primary address AND every
             // same-identity alias so a node default agent's legacy peerId-keyed
             // drafts and rc.17+ wallet-keyed drafts are both visible from one
-            // unscoped WM read. Dedupe case-insensitively — graph URIs embed the
-            // address verbatim, so the prefix must use the caller's original form.
-            const seen = new Set([opts.agentAddress.toLowerCase()]);
-            const addresses = [opts.agentAddress];
-            for (const alias of opts.agentAddressAliases ?? []) {
-                if (!alias || seen.has(alias.toLowerCase()))
+            // unscoped WM read. New full EVM-address writes use the lowercase core
+            // identity, while the caller's original casing is retained as a legacy
+            // read prefix for graphs written before canonicalization.
+            const graphPrefixes = [];
+            const seen = new Set();
+            for (const address of [opts.agentAddress, ...(opts.agentAddressAliases ?? [])]) {
+                if (!address)
                     continue;
-                seen.add(alias.toLowerCase());
-                addresses.push(alias);
+                for (const candidate of contextGraphLayerPrefixCandidates(contextGraphId, MemoryLayer.WorkingMemory, address, opts.subGraphName)) {
+                    if (seen.has(candidate))
+                        continue;
+                    seen.add(candidate);
+                    graphPrefixes.push(candidate);
+                }
             }
             return {
                 graphs: [],
                 // Combine main's same-identity alias span (#1107 review 🟡) with
                 // #1132's sub-graph scoping (#184/#675): one prefix per alias address,
                 // each carrying the optional sub-graph suffix.
-                graphPrefixes: addresses.map((addr) => `did:dkg:context-graph:${contextGraphId}${sg}/_working_memory/${addr}/`),
+                graphPrefixes,
             };
         }
         case 'shared-working-memory':
@@ -265,6 +274,7 @@ export class DKGQueryEngine {
                     subGraphName
                         ? contextGraphSubGraphPrivateUri(effectiveContextGraphId, subGraphName)
                         : contextGraphPrivateUri(effectiveContextGraphId),
+                    ...(await this.discoverGraphScopedPrivateGraphs(effectiveContextGraphId, subGraphName)),
                 ]
                 : [];
             const explicitAllowedGraphs = [...allowedGraphs, ...metaAllowList, ...privateAllowList];
@@ -304,7 +314,8 @@ export class DKGQueryEngine {
                 // Per-KA VM: read-both the published per-KA …/_verifiable_memory/{addr}/{number} + root.
                 const vmGraphsInc = await this.discoverGraphsByPrefix(`${dataGraph}/_verifiable_memory/`);
                 const dataSparql = vmGraphsInc.length > 0
-                    ? (wrapWithGraphUnion(sparql, [dataGraph, ...vmGraphsInc]) ?? wrapWithGraph(sparql, dataGraph))
+                    ? (this.wrapVerifiableMemoryGraphSet(sparql, [dataGraph, ...vmGraphsInc])
+                        ?? wrapWithGraph(sparql, dataGraph))
                     : wrapWithGraph(sparql, dataGraph);
                 // Per-KA SWM: union the discovered …/_shared_memory/{addr}/{number} graphs.
                 const swmGraphs = await this.discoverGraphsByPrefix(`${sharedMemoryGraph}/`);
@@ -327,7 +338,8 @@ export class DKGQueryEngine {
                 // Per-KA VM: read-both the published per-KA …/_verifiable_memory/{addr}/{number} + root.
                 const vmGraphs = await this.discoverGraphsByPrefix(`${dataGraph}/_verifiable_memory/`);
                 effectiveSparql = vmGraphs.length > 0
-                    ? (wrapWithGraphUnion(sparql, [dataGraph, ...vmGraphs]) ?? wrapWithGraph(sparql, dataGraph))
+                    ? (this.wrapVerifiableMemoryGraphSet(sparql, [dataGraph, ...vmGraphs])
+                        ?? wrapWithGraph(sparql, dataGraph))
                     : wrapWithGraph(sparql, dataGraph);
             }
         }
@@ -486,16 +498,46 @@ export class DKGQueryEngine {
         if (allGraphs.length === 1) {
             return this.execAndNormalize(wrapWithGraph(effectiveSparql, allGraphs[0]));
         }
+        if (view === 'verifiable-memory') {
+            const rewritten = this.wrapVerifiableMemoryGraphSet(effectiveSparql, allGraphs);
+            if (rewritten !== null)
+                return this.execAndNormalize(rewritten);
+        }
         return this.queryMultipleGraphs(effectiveSparql, allGraphs);
     }
+    /** Canonical graph rewrite for root + per-KA/per-cgId verifiable-memory reads. */
+    wrapVerifiableMemoryGraphSet(sparql, graphs) {
+        if (graphs.length === 0)
+            return sparql;
+        if (graphs.length === 1)
+            return wrapWithGraph(sparql, graphs[0]);
+        return wrapWithDeduplicatedGraphValues(sparql, graphs)
+            ?? wrapWithGraphValues(sparql, graphs)
+            ?? wrapWithGraphUnion(sparql, graphs);
+    }
     async queryMultipleGraphs(sparql, graphs) {
         if (graphs.length === 0)
             return { bindings: [] };
         if (graphs.length === 1) {
             return this.execAndNormalize(wrapWithGraph(sparql, graphs[0]));
         }
-        // Build a single union query so LIMIT/ORDER BY/DISTINCT/aggregates
-        // apply over the full dataset rather than per-graph.
+        // Prefer a single `VALUES ?g { … } GRAPH ?g { … }` query: it scopes the
+        // read to the named-graph set as ONE basic graph pattern iterated over a
+        // table, instead of one `{ GRAPH <g> { … } }` UNION branch per graph. A
+        // per-graph UNION over the ~1.4k SWM graphs of a large public context
+        // graph builds a ~1.4k-branch UnionNode that makes the oxigraph-server
+        // planner blow up and drop the socket ("fetch failed", issue #1596); the
+        // VALUES form plans in constant depth. LIMIT/ORDER BY/DISTINCT/aggregate
+        // semantics are preserved because those modifiers stay in the outer query
+        // around the injected block.
+        const valuesSparql = wrapWithGraphValues(sparql, graphs);
+        if (valuesSparql !== null) {
+            return this.execAndNormalize(valuesSparql);
+        }
+        // Residual shapes `wrapWithGraphValues` declines (an inner top-level
+        // UNION, no locatable WHERE block, or a sentinel-variable collision) keep
+        // the original union / per-graph fallback so the #789 form-aware
+        // cross-graph merge below is preserved unchanged.
         const unionSparql = wrapWithGraphUnion(sparql, graphs);
         if (unionSparql !== null) {
             return this.execAndNormalize(unionSparql);
@@ -577,6 +619,67 @@ export class DKGQueryEngine {
             return rest.length > 0 && !rest.includes('/');
         });
     }
+    /**
+     * Resolve only the immutable private graphs referenced by valid current V2
+     * metadata in this exact context graph. The broad `/_private/` prefix also
+     * contains mutable WM drafts, so prefix-enumerating it would let an
+     * `includePrivate` query cross the draft/finalized boundary. Deriving each
+     * graph from the canonical UAL + assertion version keeps the allow-list
+     * fail-closed and makes GRAPH-variable discovery work for rootless KAs.
+     */
+    async discoverGraphScopedPrivateGraphs(contextGraphId, subGraphName) {
+        const metaGraph = contextGraphMetaUri(contextGraphId);
+        const subGraphClause = subGraphName
+            ? `?ual <http://dkg.io/ontology/subGraphName> "${escapeSparqlLiteral(subGraphName)}" .`
+            : `FILTER NOT EXISTS { ?ual <http://dkg.io/ontology/subGraphName> ?_subGraphName . }`;
+        const result = await this.store.query(`SELECT DISTINCT ?ual ?scopeVersion ?kaUal ?assertionVersion ?assertionGraph ?privateCount WHERE {
+        GRAPH <${assertSafeIri(metaGraph)}> {
+          ?ual <http://dkg.io/ontology/contentScopeVersion> ?scopeVersion ;
+               <http://dkg.io/ontology/kaUal> ?kaUal ;
+               <http://dkg.io/ontology/assertionVersion> ?assertionVersion ;
+               <http://dkg.io/ontology/assertionGraph> ?assertionGraph ;
+               <http://dkg.io/ontology/privateTripleCount> ?privateCount ;
+               <http://dkg.io/ontology/status> ?status .
+          FILTER(?status IN ("confirmed", "tentative"))
+          ${subGraphClause}
+        }
+      }`);
+        if (result.type !== 'bindings')
+            return [];
+        const privateRoot = subGraphName
+            ? contextGraphSubGraphPrivateUri(contextGraphId, subGraphName)
+            : contextGraphPrivateUri(contextGraphId);
+        const graphs = new Set();
+        for (const row of result.bindings) {
+            const ual = row['ual'];
+            const metadataUal = row['kaUal'];
+            const assertionGraph = row['assertionGraph'];
+            const scopeVersion = parseCanonicalIntegerBinding(row['scopeVersion']);
+            const assertionVersion = parseCanonicalIntegerBinding(row['assertionVersion']);
+            const privateCount = parseCanonicalIntegerBinding(row['privateCount']);
+            if (!ual
+                || metadataUal !== ual
+                || !assertionGraph
+                || scopeVersion !== BigInt(GRAPH_KA_CONTENT_SCOPE_VERSION)
+                || assertionVersion === undefined
+                || assertionVersion < 1n
+                || privateCount === undefined
+                || privateCount < 1n) {
+                continue;
+            }
+            try {
+                const scope = createGraphKnowledgeAssetScope(ual, assertionVersion);
+                const expectedPublicGraph = knowledgeAssetLayerGraphUri(contextGraphId, MemoryLayer.VerifiableMemory, scope, subGraphName);
+                if (assertionGraph !== expectedPublicGraph)
+                    continue;
+                graphs.add(assertSafeIri(`${privateRoot}/${scope.agentAddress}/${scope.kaNumber}/assertions/${scope.assertionVersion}`));
+            }
+            catch {
+                // Invalid or non-canonical metadata never widens the private allow-list.
+            }
+        }
+        return [...graphs];
+    }
     /**
      * Resolve a WM assertion's allocated KA number (`dkg:kaId`) off its lifecycle URN
      * in `_meta`, for single-graph by-name reads under the uniform layout. Returns
@@ -721,28 +824,55 @@ export class DKGQueryEngine {
         return { bindings: [] };
     }
     async resolveKA(ual) {
-        // Look up KA metadata across all meta graphs, including subGraphName if recorded.
-        // Design B (OT-RFC-44): one KA can hold MULTIPLE rootEntities, so collect
-        // every `?ka <rootEntity>` binding (not just bindings[0]) — PR #968 salvage.
-        // Read-both (RFC ka-metadata-trim P3.1): the collapsed shape carries
-        // `dkg:rootEntity` directly on the UAL subject (no `<ual>/<n>` token rows,
-        // no `dkg:partOf`); legacy-shape rows synced from older nodes still use
-        // the token-row + partOf form, so both branches are queried.
-        const metaResult = await this.store.query(`SELECT ?ka ?rootEntity ?ctxGraph ?sgName WHERE {
-        GRAPH ?g {
-          {
-            ?ka <http://dkg.io/ontology/rootEntity> ?rootEntity .
-            ?ka <http://dkg.io/ontology/partOf> <${assertSafeIri(ual)}> .
-          }
-          UNION
-          {
-            <${assertSafeIri(ual)}> <http://dkg.io/ontology/rootEntity> ?rootEntity .
-            BIND(<${assertSafeIri(ual)}> AS ?ka)
-          }
-          <${assertSafeIri(ual)}> <http://dkg.io/ontology/contextGraph> ?ctxGraph .
-          OPTIONAL { <${assertSafeIri(ual)}> <http://dkg.io/ontology/subGraphName> ?sgName }
+        const resolved = await this.resolveKnowledgeAsset(ual);
+        if (resolved.contentScopeVersion === GRAPH_KA_CONTENT_SCOPE_VERSION) {
+            throw new Error('Graph-scoped Knowledge Assets do not have root entities; use resolveKnowledgeAsset()');
+        }
+        return resolved;
+    }
+    async resolveKnowledgeAsset(ual) {
+        const safeUal = assertSafeIri(ual);
+        const resolved = await resolveGraphScopedOrLegacyMetadata(this.store, safeUal, () => this.resolveLegacyRootScopedKA(safeUal), { source: 'query.resolveKnowledgeAsset.metadata' });
+        if (resolved.kind === 'graph') {
+            return this.resolveGraphScopedKA(safeUal, resolved.metadata);
+        }
+        if (resolved.kind === 'legacy')
+            return resolved.metadata;
+        throw new Error(`KA not found for UAL: ${safeUal}`);
+    }
+    async resolveGraphScopedKA(ual, metadata) {
+        const expectedGraph = metadata.assertionGraph;
+        let quads;
+        try {
+            quads = await readExactGraphPaged(this.store, expectedGraph, {
+                expectedQuadCount: metadata.publicTripleCount,
+                queryOptions: { source: 'query.resolveKnowledgeAsset' },
+            });
+        }
+        catch (error) {
+            if (error instanceof ExactGraphReadError && error.code === 'QUAD_COUNT_MISMATCH') {
+                throw new Error(`Graph-scoped KA ${ual} graph integrity mismatch: metadata declares ` +
+                    `${metadata.publicTripleCount} public triples, found ${error.actual ?? 'an unknown count'}`);
+            }
+            throw error;
+        }
+        if (quads.length !== metadata.publicTripleCount) {
+            throw new Error(`Graph-scoped KA ${ual} graph integrity mismatch: metadata declares ${metadata.publicTripleCount} public triples, found ${quads.length}`);
         }
-      } ORDER BY ?ka`);
+        return {
+            ual: metadata.scope.ual,
+            contentScopeVersion: GRAPH_KA_CONTENT_SCOPE_VERSION,
+            assertionVersion: metadata.scope.assertionVersion,
+            assertionGraph: expectedGraph,
+            rootEntities: [],
+            contextGraphId: metadata.contextGraphId,
+            quads,
+        };
+    }
+    async resolveLegacyRootScopedKA(ual) {
+        // Existing V10 metadata can use either token-row + partOf membership or
+        // the collapsed UAL-subject rootEntity form. This path is read-only.
+        const metaResult = await this.store.query(buildLegacyKnowledgeAssetMetadataQuery(ual));
         if (metaResult.type !== 'bindings' || metaResult.bindings.length === 0) {
             throw new Error(`KA not found for UAL: ${ual}`);
         }
@@ -755,9 +885,21 @@ export class DKGQueryEngine {
             throw new Error(`KA not found for UAL: ${ual}`);
         }
         const rootEntity = rootEntities[0];
-        const contextGraphUri = metaResult.bindings[0]['ctxGraph'];
-        const contextGraphId = contextGraphUri.replace('did:dkg:context-graph:', '');
-        const sgNameRaw = metaResult.bindings[0]['sgName'];
+        const contextGraphUris = [
+            ...new Set(metaResult.bindings
+                .map((row) => row['ctxGraph'])
+                .filter((value) => typeof value === 'string' && value.length > 0)),
+        ];
+        if (contextGraphUris.length !== 1) {
+            throw new Error(`Legacy KA ${ual} has ambiguous contextGraph metadata`);
+        }
+        const contextGraphPrefix = 'did:dkg:context-graph:';
+        const contextGraphUri = contextGraphUris[0];
+        if (!contextGraphUri.startsWith(contextGraphPrefix)) {
+            throw new Error(`Legacy KA ${ual} has invalid contextGraph metadata`);
+        }
+        const contextGraphId = contextGraphUri.slice(contextGraphPrefix.length);
+        const sgNameRaw = metaResult.bindings[0]?.['sgName'];
         const subGraphName = sgNameRaw ? sgNameRaw.replace(/^"(.*)".*$/, '$1') : undefined;
         const dataGraph = subGraphName
             ? contextGraphSubGraphUri(contextGraphId, subGraphName)
@@ -765,7 +907,6 @@ export class DKGQueryEngine {
         const rootFilter = rootEntities
             .map((root) => `(?s = <${assertSafeIri(root)}> || STRSTARTS(STR(?s), "${escapeSparqlLiteral(root)}/.well-known/genid/"))`)
             .join(' || ');
-        // Fetch all triples for every KA member root from the correct data graph.
         const dataResult = await this.store.query(`SELECT ?s ?p ?o WHERE {
         GRAPH <${assertSafeIri(dataGraph)}> {
           ?s ?p ?o .
@@ -780,7 +921,14 @@ export class DKGQueryEngine {
                 graph: dataGraph,
             }))
             : [];
-        return { rootEntity, rootEntities, contextGraphId, quads };
+        return {
+            ual,
+            contentScopeVersion: 1,
+            rootEntity,
+            rootEntities,
+            contextGraphId,
+            quads,
+        };
     }
     /**
      * Execute a query across all locally-stored context graphs.
@@ -877,6 +1025,17 @@ function stripSparqlLiteralValue(value) {
         return '';
     return value.replace(/^"/, '').replace(/"(?:\^\^<[^>]+>|@[a-zA-Z-]+)?$/, '');
 }
+function parseCanonicalIntegerBinding(value) {
+    const lexical = stripSparqlLiteralValue(value);
+    if (!/^(?:0|[1-9][0-9]*)$/.test(lexical))
+        return undefined;
+    try {
+        return BigInt(lexical);
+    }
+    catch {
+        return undefined;
+    }
+}
 function assertNoCallerDatasetClauses(sparql) {
     if (hasCallerDatasetClause(sparql)) {
         throw new ScopedQueryViolationError('FROM clauses are not allowed on scoped local queries');
@@ -2172,6 +2331,193 @@ function wrapWithGraphUnion(sparql, graphUris) {
         .join(' UNION ');
     return `${before} ${unionBranches} ${after}`;
 }
+/** The graph variable `wrapWithGraphValues` injects. Double-underscore + a
+ *  view-specific name so a user query is astronomically unlikely to bind it;
+ *  a collision is nonetheless detected and declined (never silently clamped). */
+const VIEW_GRAPH_SENTINEL = '?__dkgViewGraph';
+const DEDUP_GRAPH_SENTINEL = '?__dkgDedupGraph';
+const DEDUP_RANK_SENTINEL = '?__dkgDedupRank';
+const DEDUP_PRIOR_GRAPH_SENTINEL = '?__dkgDedupPriorGraph';
+const DEDUP_PRIOR_RANK_SENTINEL = '?__dkgDedupPriorRank';
+function wrapWithProjectedGraphSubselect(sparql, graphUris, helperVariables, buildGraphPattern, acceptsInner = () => true) {
+    if (hasGraphClause(sparql))
+        return sparql;
+    if (graphUris.length === 0)
+        return sparql;
+    const braceStart = findWhereBraceStart(sparql);
+    if (braceStart === -1)
+        return null;
+    const braceEnd = findMatchingCloseBrace(sparql, braceStart);
+    if (braceEnd === -1)
+        return null;
+    const before = sparql.slice(0, braceStart + 1);
+    const inner = sparql.slice(braceStart + 1, braceEnd);
+    const after = sparql.slice(braceEnd);
+    const graphs = [...new Set(graphUris)];
+    if (graphs.length === 1) {
+        return `${before} GRAPH <${assertSafeIri(graphs[0])}> { ${inner} } ${after}`;
+    }
+    if (/\bUNION\b/i.test(inner) || !acceptsInner(inner))
+        return null;
+    const helperNames = new Set(helperVariables.map((variable) => variable.slice(1)));
+    if (collectQueryVariables(sparql).some((variable) => helperNames.has(variable.slice(1)))) {
+        return null;
+    }
+    const innerVars = collectQueryVariables(inner);
+    if (innerVars.length === 0)
+        return null;
+    const graphPattern = buildGraphPattern(inner, graphs);
+    return `${before} { SELECT ${innerVars.join(' ')} WHERE { ${graphPattern} } } ${after}`;
+}
+/**
+ * Run one graph pattern across an ordered graph set while suppressing only a
+ * solution mapping already produced by an earlier graph. The comparison uses
+ * every variable bound by the caller's inner pattern, before the caller's
+ * projection runs. Thus an identical mirrored triple is emitted once, while
+ * distinct triples that both project to the same `?s` still produce two rows.
+ *
+ * Helper graph/rank variables are hidden inside a sub-SELECT, preserving
+ * `SELECT *` and caller DISTINCT semantics. Unsupported/colliding query shapes
+ * return null so the existing generic multi-graph fallback remains available.
+ */
+function wrapWithDeduplicatedGraphValues(sparql, graphUris) {
+    return wrapWithProjectedGraphSubselect(sparql, graphUris, [
+        DEDUP_GRAPH_SENTINEL,
+        DEDUP_RANK_SENTINEL,
+        DEDUP_PRIOR_GRAPH_SENTINEL,
+        DEDUP_PRIOR_RANK_SENTINEL,
+    ], (inner, graphs) => {
+        const rows = graphs
+            .map((graph, rank) => `(<${assertSafeIri(graph)}> ${rank})`)
+            .join(' ');
+        return [
+            `VALUES (${DEDUP_GRAPH_SENTINEL} ${DEDUP_RANK_SENTINEL}) { ${rows} }`,
+            `GRAPH ${DEDUP_GRAPH_SENTINEL} { ${inner} }`,
+            'FILTER NOT EXISTS {',
+            `  VALUES (${DEDUP_PRIOR_GRAPH_SENTINEL} ${DEDUP_PRIOR_RANK_SENTINEL}) { ${rows} }`,
+            `  FILTER (${DEDUP_PRIOR_RANK_SENTINEL} < ${DEDUP_RANK_SENTINEL})`,
+            `  GRAPH ${DEDUP_PRIOR_GRAPH_SENTINEL} { ${inner} }`,
+            '}',
+        ].join(' ');
+    }, isDedupSafeBasicGraphPattern);
+}
+/**
+ * Wrap a query so it runs over a set of named graphs in ONE execution using a
+ * single `VALUES ?g { <g1> … } GRAPH ?g { inner }` block, instead of one
+ * `{ GRAPH <g> { inner } } UNION …` branch per graph.
+ *
+ * Why this exists (issue #1596): the per-graph UNION form (`wrapWithGraphUnion`)
+ * emits an N-branch UnionNode. At the ~1,424 SWM graphs of a large public
+ * context graph that is a ~257 KB query whose union tree makes the
+ * oxigraph-server query planner blow up and reset the connection ("fetch
+ * failed"). A single VALUES table is one basic graph pattern iterated over the
+ * graph list — constant plan depth — so it scales.
+ *
+ * Semantics are preserved. LIMIT/ORDER BY/DISTINCT/GROUP BY/aggregate all live
+ * in the outer query (the `before`/`after` slices) and reduce over the merged
+ * solution set exactly as the UNION form did. The one hazard is the injected
+ * graph variable leaking into the caller's projection: a bare `SELECT *` would
+ * expose `?__dkgViewGraph` as a mystery column, and cross-graph DISTINCT of an
+ * identical triple would split on the graph. Both are neutralised by scoping
+ * the VALUES+GRAPH block inside a sub-SELECT that projects ONLY the user's own
+ * variables (collected from `inner`), so the sentinel never escapes.
+ *
+ * Returns `null` (caller falls back to `wrapWithGraphUnion` / per-graph
+ * execution) when the WHERE block cannot be located, when `inner` carries a
+ * top-level UNION (kept on the #789 form-aware fallback so its behaviour and
+ * tests are untouched), when the user query already binds the sentinel, or
+ * when the WHERE body binds no user variable at all (a var-less body offers
+ * nowhere to hide the sentinel from a `SELECT *` projection).
+ */
+function wrapWithGraphValues(sparql, graphUris) {
+    return wrapWithProjectedGraphSubselect(sparql, graphUris, [VIEW_GRAPH_SENTINEL], (inner, graphs) => {
+        const values = graphs.map((graph) => `<${assertSafeIri(graph)}>`).join(' ');
+        return `VALUES ${VIEW_GRAPH_SENTINEL} { ${values} } GRAPH ${VIEW_GRAPH_SENTINEL} { ${inner} }`;
+    });
+}
+/**
+ * The mirror anti-join is valid only for a flat basic graph pattern (plus
+ * FILTER expressions). Nested graph patterns can differ by boundness, where a
+ * correlated NOT EXISTS compatibility check is not exact mapping equality.
+ */
+function isDedupSafeBasicGraphPattern(inner) {
+    const forbidden = ['OPTIONAL', 'MINUS', 'SERVICE', 'VALUES', 'BIND', 'SELECT', 'GRAPH', 'EXISTS'];
+    let i = 0;
+    while (i < inner.length) {
+        const ch = inner[i];
+        if (ch === '#') {
+            while (i < inner.length && inner[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            i = skipSparqlStringLiteral(inner, i);
+            continue;
+        }
+        if (ch === '<') {
+            const end = skipSparqlIriRef(inner, i);
+            i = end ?? i + 1;
+            continue;
+        }
+        if (ch === '{' || ch === '}')
+            return false;
+        if (isKeywordStart(inner, i)) {
+            let end = i + 1;
+            while (end < inner.length && isWordContinuation(inner[end]))
+                end++;
+            if (forbidden.some((keyword) => isSparqlKeyword(inner, i, end, keyword))) {
+                return false;
+            }
+            i = end;
+            continue;
+        }
+        i++;
+    }
+    return true;
+}
+/**
+ * Collect every distinct SPARQL variable (`?x` / `$x`, in first-seen order,
+ * sigil included) in a query fragment, skipping tokens inside line comments,
+ * string literals, and IRI refs. Reuses the same literal/comment/IRI-aware
+ * primitives as `collectGraphVariables` so a `?`/`$` inside a literal or IRI is
+ * never mistaken for a variable.
+ */
+function collectQueryVariables(sparql) {
+    const variables = [];
+    const seen = new Set();
+    const n = sparql.length;
+    let i = 0;
+    while (i < n) {
+        const ch = sparql[i];
+        if (ch === '#') {
+            while (i < n && sparql[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            i = skipSparqlStringLiteral(sparql, i);
+            continue;
+        }
+        if (ch === '<') {
+            const end = skipSparqlIriRef(sparql, i);
+            i = end ?? i + 1;
+            continue;
+        }
+        if (ch === '?' || ch === '$') {
+            const variable = readSparqlVariable(sparql, i);
+            if (variable) {
+                if (!seen.has(variable)) {
+                    seen.add(variable);
+                    variables.push(variable);
+                }
+                i += variable.length;
+                continue;
+            }
+        }
+        i++;
+    }
+    return variables;
+}
 /**
  * Rewrites a SPARQL query so EVERY subject variable used in its WHERE
  * block also matches `<http://dkg.io/ontology/trustLevel> ?__trustN`