@astrale-os/kernel-client 0.6.0-beta.14 → 0.6.0-beta.16

package/dist/graph/provenance.d.ts

@@ -8,5 +8,7 @@ export interface QueryProvenance {
 }
 /** Retain authenticated query provenance without adding serialized response metadata. */
 export declare function retainQueryProvenance(response: QueryResponse, closure: readonly DomainDependency[]): QueryResponse;
+/** Reattach the exact authenticated closure when Store materialization replaces response objects. */
+export declare function retainDerivedQueryProvenance(source: QueryResponse, derived: QueryResponse): QueryResponse;
 export declare function provenanceOfGraphValue(value: Node | Edge): QueryProvenance | undefined;
 export declare function provenanceOfResponse(value: QueryResponse): QueryProvenance | undefined;

package/dist/graph/provenance.js

@@ -29,6 +29,11 @@ export function retainQueryProvenance(response, closure) {
     }
     return response;
 }
+/** Reattach the exact authenticated closure when Store materialization replaces response objects. */
+export function retainDerivedQueryProvenance(source, derived) {
+    const provenance = responses.get(source);
+    return provenance === undefined ? derived : retainQueryProvenance(derived, provenance.closure);
+}
 export function provenanceOfGraphValue(value) {
     return graphValues.get(value);
 }

package/dist/store/memory.d.ts

@@ -1,4 +1,5 @@
 import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 import type { GraphApi } from '../graph/index.js';
 import type { StoreQueryResponse, StoreReadOptions, StoreSnapshot } from './store.js';
@@ -24,7 +25,7 @@ export declare class GraphMemory {
     private readonly pending;
     private active;
     constructor(options: GraphMemoryOptions);
-    ensure(key: string, ast: QueryAST, page: QueryPageRequest): QueryShape;
+    ensure(key: string, ast: QueryAST, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined): QueryShape;
     get(key: string): QueryShape | undefined;
     read(shape: QueryShape, options: StoreReadOptions): Promise<StoreQueryResponse>;
     snapshot(shape: QueryShape | undefined): StoreSnapshot;

package/dist/store/memory.js

@@ -1,5 +1,6 @@
 import { encodeEdgeKey } from '@astrale-os/kernel-core/graph/edge';
 import { ClientError } from '../errors/index.js';
+import { retainDerivedQueryProvenance } from '../graph/provenance.js';
 import { edgeIdentity, EntityIndex } from './entity-index.js';
 import { OptimisticOverlay } from './optimistic.js';
 import { COLD_SNAPSHOT, QueryShape } from './shape.js';
@@ -13,7 +14,7 @@ export class GraphMemory {
     constructor(options) {
         this.options = options;
     }
-    ensure(key, ast, page) {
+    ensure(key, ast, page, expected) {
         const existing = this.shapes.get(key);
         const now = this.options.now();
         if (existing !== undefined) {
@@ -26,7 +27,7 @@ export class GraphMemory {
         if (this.shapes.size >= this.options.maximumShapes) {
             throw new ClientError('GraphStore shape capacity is exhausted by observed or in-flight queries.');
         }
-        const shape = new QueryShape(key, ast, page, now);
+        const shape = new QueryShape(key, ast, page, expected, now);
         shape.releasedAt = now;
         this.shapes.set(key, shape);
         return shape;
@@ -52,7 +53,7 @@ export class GraphMemory {
         const prior = shape.response;
         this.publish(shape, prior === undefined ? 'loading' : this.overlay.hasAny() ? 'optimistic' : 'refreshing');
         const inflight = this.schedule(async () => {
-            const result = await this.options.graph.query(shape.ast, queryOptions(shape.page, this.options.lifecycle));
+            const result = await this.options.graph.query(shape.ast, queryOptions(shape.page, this.options.lifecycle, shape.expected));
             this.options.requireOpen();
             const integration = this.entities.integrate(result.result);
             shape.references = integration.references;
@@ -182,10 +183,11 @@ export class GraphMemory {
             this.pending.shift()?.reject(error);
     }
     materialize(template, references) {
-        return Object.freeze({
+        const response = Object.freeze({
             result: this.materializeResult(template.result, references),
             page: template.page,
         });
+        return retainDerivedQueryProvenance(template, response);
     }
     materializeResult(template, references) {
         if (template.kind === 'nodes') {
@@ -196,8 +198,9 @@ export class GraphMemory {
                     continue;
                 }
                 const node = this.overlay.node(projection.value.id, this.entities);
-                if (node !== undefined)
-                    nodes.push(Object.freeze({ kind: 'value', value: node }));
+                if (node !== undefined) {
+                    nodes.push(Object.freeze({ kind: 'value', value: materializeNode(node) }));
+                }
             }
             return Object.freeze({
                 kind: 'nodes',
@@ -213,7 +216,7 @@ export class GraphMemory {
                         const value = this.entities.edge(edgeIdentity(item.edge.value));
                         return value === undefined
                             ? undefined
-                            : Object.freeze({ kind: 'value', value });
+                            : Object.freeze({ kind: 'value', value: materializeEdge(value) });
                     })();
                 const source = item.source.kind === 'reference'
                     ? item.source
@@ -221,7 +224,7 @@ export class GraphMemory {
                         const value = this.overlay.node(item.source.value.id, this.entities);
                         return value === undefined
                             ? undefined
-                            : Object.freeze({ kind: 'value', value });
+                            : Object.freeze({ kind: 'value', value: materializeNode(value) });
                     })();
                 const target = item.target.kind === 'reference'
                     ? item.target
@@ -229,7 +232,7 @@ export class GraphMemory {
                         const value = this.overlay.node(item.target.value.id, this.entities);
                         return value === undefined
                             ? undefined
-                            : Object.freeze({ kind: 'value', value });
+                            : Object.freeze({ kind: 'value', value: materializeNode(value) });
                     })();
                 if (edge !== undefined && source !== undefined && target !== undefined) {
                     edges.push(Object.freeze({ edge, source, target }));
@@ -242,11 +245,13 @@ export class GraphMemory {
         }
         const nodes = references.nodes
             .map((id) => this.overlay.node(id, this.entities))
-            .filter((node) => node !== undefined);
+            .filter((node) => node !== undefined)
+            .map(materializeNode);
         const visibleNodeIds = new Set(nodes.map(({ id }) => id));
         const edges = references.edges
             .map((key) => this.entities.edge(key))
-            .filter((edge) => edge !== undefined && visibleNodeIds.has(edge.source) && visibleNodeIds.has(edge.target));
+            .filter((edge) => edge !== undefined && visibleNodeIds.has(edge.source) && visibleNodeIds.has(edge.target))
+            .map(materializeEdge);
         const graph = Object.freeze({ nodes: Object.freeze(nodes), edges: Object.freeze(edges) });
         const selection = materializeSelection(template.selection, visibleNodeIds, edges);
         return selection.kind === 'node'
@@ -297,6 +302,12 @@ export class GraphMemory {
         }
     }
 }
+function materializeNode(value) {
+    return Object.freeze({ ...value });
+}
+function materializeEdge(value) {
+    return Object.freeze({ ...value });
+}
 function materializeSelection(selection, visibleNodes, visibleEdges) {
     if (selection.kind === 'node') {
         return Object.freeze({
@@ -310,10 +321,11 @@ function materializeSelection(selection, visibleNodes, visibleEdges) {
         keys: Object.freeze(selection.keys.filter((key) => edges.has(encodeEdgeKey(key)))),
     });
 }
-function queryOptions(page, lifecycle) {
+function queryOptions(page, lifecycle, expected) {
     return Object.freeze({
         signal: lifecycle,
         page,
+        ...(expected === undefined ? {} : { expected }),
     });
 }
 function observeRead(pending, options, lifecycle) {

package/dist/store/query-key.d.ts

@@ -1,5 +1,6 @@
 import type { QueryAST as QueryASTValue } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 export declare function admitQuery(input: QueryASTValue): QueryASTValue;
 export declare function admitPage(input: QueryPageRequest): QueryPageRequest;
-export declare function queryKey(ast: QueryASTValue, page: QueryPageRequest): string;
+export declare function queryKey(ast: QueryASTValue, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined): string;

package/dist/store/query-key.js

@@ -17,6 +17,11 @@ export function admitPage(input) {
         ...(input.after === undefined ? {} : { after: input.after }),
     });
 }
-export function queryKey(ast, page) {
-    return JSON.stringify([QueryAST.fingerprint(ast), page.size, page.after ?? null]);
+export function queryKey(ast, page, expected) {
+    return JSON.stringify([
+        QueryAST.fingerprint(ast),
+        page.size,
+        page.after ?? null,
+        expected ?? null,
+    ]);
 }

package/dist/store/shape.d.ts

@@ -1,5 +1,6 @@
 import type { NodeId } from '@astrale-os/kernel-core/graph/node';
 import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 import type { FactReferences } from './entity-index.js';
 import type { StoreQueryResponse, StoreSnapshot } from './store.js';
@@ -8,6 +9,7 @@ export declare class QueryShape {
     readonly key: string;
     readonly ast: QueryAST;
     readonly page: QueryPageRequest;
+    readonly expected: readonly DomainDependency[] | undefined;
     readonly listeners: Set<() => void>;
     state: ShapeState;
     confirmed?: StoreQueryResponse;
@@ -18,7 +20,7 @@ export declare class QueryShape {
     accessedAt: number;
     refreshedAt?: number;
     snapshot: StoreSnapshot;
-    constructor(key: string, ast: QueryAST, page: QueryPageRequest, now: number);
+    constructor(key: string, ast: QueryAST, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined, now: number);
     get observed(): boolean;
     referencesAny(nodes: ReadonlySet<NodeId>, edges: ReadonlySet<string>): boolean;
 }

package/dist/store/shape.js

@@ -2,6 +2,7 @@ export class QueryShape {
     key;
     ast;
     page;
+    expected;
     listeners = new Set();
     state = 'cold';
     confirmed;
@@ -12,10 +13,11 @@ export class QueryShape {
     accessedAt;
     refreshedAt;
     snapshot = COLD_SNAPSHOT;
-    constructor(key, ast, page, now) {
+    constructor(key, ast, page, expected, now) {
         this.key = key;
         this.ast = ast;
         this.page = page;
+        this.expected = expected;
         this.accessedAt = now;
     }
     get observed() {

package/dist/store/store.js

@@ -1,4 +1,5 @@
 import { ClientError } from '../errors/index.js';
+import { captureExpected } from '../graph/expectation.js';
 import { GraphMemory } from './memory.js';
 import { mutateStore } from './mutation.js';
 import { observeStore } from './observe.js';
@@ -105,7 +106,7 @@ export class GraphStore {
         const identity = this.identity(query, options);
         return {
             ...identity,
-            shape: this.memory.ensure(identity.key, identity.ast, identity.page),
+            shape: this.memory.ensure(identity.key, identity.ast, identity.page, identity.expected),
             options: options,
         };
     }
@@ -121,6 +122,7 @@ export class GraphStore {
             throw new TypeError('Store freshness option is invalid.');
         }
         const page = admitPage(options.page);
+        const expected = captureExpected(options.expected);
         if (options.timeoutMs !== undefined &&
             (!Number.isSafeInteger(options.timeoutMs) ||
                 options.timeoutMs < 1 ||
@@ -128,8 +130,8 @@ export class GraphStore {
             throw new TypeError('Store read timeoutMs must be a positive platform integer.');
         }
         const ast = admitQuery(query);
-        const key = queryKey(ast, page);
-        return { key, ast, page };
+        const key = queryKey(ast, page, expected);
+        return { key, ast, page, expected };
     }
     requireOpen() {
         if (this.closed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.14",
+  "version": "0.6.0-beta.16",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",