@origintrail-official/dkg-query 10.0.0-rc.8 → 10.0.0

package/README.md

@@ -19,16 +19,27 @@ const engine = new DKGQueryEngine(store);
 
 const results = await engine.query(
   'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10',
-  { contextGraphId: 'urn:contextGraph:example' },
+  { contextGraphId: 'example', view: 'verifiable-memory' },
 );
 
-// Query with workspace data included
-const wsResults = await engine.query(
-  'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10',
-  { contextGraphId: 'urn:contextGraph:example', includeWorkspace: true },
+// Inspect allowed named graphs without expanding the selected scope.
+const graphResults = await engine.query(
+  'SELECT ?g ?s ?p ?o WHERE { GRAPH ?g { ?s ?p ?o } } LIMIT 10',
+  { contextGraphId: 'example', view: 'shared-working-memory' },
 );
 ```
 
+contextGraphId and view are authoritative for local queries. A local
+`GRAPH ?g` pattern is constrained locally to the graph set resolved from those
+fields; it cannot range over another context graph or memory view. Local scoped
+queries reject explicit out-of-scope `GRAPH <iri>` targets and `FROM` /
+`FROM NAMED` clauses because those would let caller SPARQL redefine the dataset.
+
+Remote raw SPARQL handled by `QueryHandler` remains stricter: `GRAPH`, `FROM`,
+and `FROM NAMED` clauses are rejected before execution. Structured remote
+lookups such as `ENTITIES_BY_TYPE` and `ENTITY_TRIPLES` continue to build their
+own internal graph patterns.
+
 ## Internal Dependencies
 
 - `@origintrail-official/dkg-core` — configuration, logging, protocol streams

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

@@ -10,26 +10,39 @@ export interface ViewResolution {
     /**
      * Graph URI prefixes — the engine discovers all named graphs matching
      * each prefix and unions the results. Used for working-memory (multiple
-     * assertions) and verified-memory (multiple quorum graphs).
+     * assertions) and verifiable-memory (multiple quorum graphs).
      */
     graphPrefixes: string[];
 }
+export declare class ScopedQueryViolationError extends Error {
+    constructor(message: string);
+}
 /**
  * Resolves a V10 GetView + context graph ID to the named-graph URIs (or
  * prefixes) that the query engine should target.
  *
  * Spec reference: §12 GET — Declared State Views.
  *
- * Trust-level semantics for `verified-memory`: graph scope is not a trust
- * signal. The root graph and `/_verified_memory/*` graphs are candidates;
+ * Trust-level semantics for `verifiable-memory`: graph scope is not a trust
+ * signal. The root graph and `/_verifiable_memory/*` graphs are candidates;
  * `minTrust` is enforced by explicit writer-side `dkg:trustLevel` metadata.
  */
 export declare function resolveViewGraphs(view: GetView, contextGraphId: string, opts?: {
     agentAddress?: string;
+    /** Same-identity WM namespace aliases — see QueryOptions.agentAddressAliases. */
+    agentAddressAliases?: string[];
     verifiedGraph?: string;
     assertionName?: string;
+    /** Resolved KA number for single-graph by-name reads under the uniform layout. */
+    kaNumber?: bigint;
     /** Spec §12/§14 trust-gradient filter. Enforced after graph resolution. */
     minTrust?: TrustLevel;
+    /**
+     * GH #184 — when set, the view is scoped to this registered sub-graph: the
+     * uniform layout stores sub-graph layer data at `…/{sub}/{slug}/…`, so the
+     * per-layer prefixes below gain the `/{sub}` segment.
+     */
+    subGraphName?: string;
 }): ViewResolution;
 /**
  * Local-only query engine that executes SPARQL against this node's own
@@ -40,6 +53,7 @@ export declare function resolveViewGraphs(view: GetView, contextGraphId: string,
 export declare class DKGQueryEngine implements QueryEngine {
     private readonly store;
     private readonly graphManager;
+    private readonly scopedContentGraphAllowListInFlight;
     constructor(store: TripleStore);
     query(sparql: string, options?: QueryOptions): Promise<QueryResult>;
     /**
@@ -53,9 +67,34 @@ export declare class DKGQueryEngine implements QueryEngine {
     private queryWithView;
     private queryMultipleGraphs;
     private discoverGraphsByPrefix;
+    /**
+     * GH #1098 — discover the per-cgId VM DATA graphs `<cg>/context/<onChainId>`
+     * for a context graph. Chain-reconciled / per-cgId-only publishes materialise
+     * confirmed VM content here rather than in the root content graph. We keep
+     * ONLY the bare `<cg>/context/<id>` data graphs: `discoverGraphsByPrefix`
+     * already drops `/_meta` + `/staging/`, and the extra `!rest.includes('/')`
+     * guard excludes any nested per-cgId sub-partition (`…/context/<id>/_private`,
+     * `…/context/<id>/_shared_memory`, …) so a VM content read never pulls
+     * private/SWM rows.
+     */
+    private discoverContextGraphPerCgIdDataGraphs;
+    /**
+     * 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
+     * `undefined` for an unallocated draft (legacy name-keyed graph fallback). Mirrors
+     * the publisher's `resolveKaNumber`.
+     */
+    private resolveWorkingMemoryKaNumber;
+    private resolveScopedGraphVariableAllowList;
+    private resolveScopedContentGraphAllowList;
+    private discoverScopedContentGraphAllowList;
+    private discoverRegisteredSubGraphNames;
+    private discoverRegisteredAssertionGraphs;
+    private discoverKnownChildContextGraphUris;
     private execAndNormalize;
     resolveKA(ual: string): Promise<{
         rootEntity: string;
+        rootEntities: string[];
         contextGraphId: string;
         quads: Quad[];
     }>;

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,EAIL,KAAK,OAAO,EAEZ,UAAU,EAEX,MAAM,gCAAgC,CAAC;AAMxC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;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,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB,GACA,cAAc,CA2EhB;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,KAAK,EAAE,WAAW;IAKxB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA6DzE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;YACW,aAAa;YA+Eb,mBAAmB;YAWnB,sBAAsB;YAOtB,gBAAgB;IAmBxB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QACpC,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,IAAI,EAAE,CAAC;KACf,CAAC;IAqDF;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAYlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,EAAE,IAAI,EAAmC,MAAM,mCAAmC,CAAC;AAE5G,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAKL,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;YAiJb,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;AA64BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoCtE"}