@astrale-os/kernel-client 0.5.1 → 0.6.0-beta.10

package/dist/session/views/catalog.js

@@ -0,0 +1,70 @@
+import { acceptViewResolution, } from '@astrale-os/kernel-core/schema/kernel/syscalls/view-resolution';
+import { Key as ViewKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { ClientError } from '../../errors/index.js';
+import { allowEndpoint } from '../context/index.js';
+export function rootViewCatalog(publication, artifact, policy) {
+    const views = publication.bindings.views
+        .map((binding) => {
+        allowEndpoint(binding.href, policy);
+        const declaration = artifact.root.views[viewName(binding.view)];
+        if (declaration === undefined) {
+            throw new ClientError('Published View has no verified root declaration.');
+        }
+        const { ref: _ref, ...viewDeclaration } = declaration;
+        return Object.freeze({
+            key: binding.view,
+            declaration: Object.freeze(viewDeclaration),
+            href: binding.href,
+            handshake: binding.handshake,
+            issuer: publication.identity.issuer,
+            etag: publication.etag,
+            revision: publication.schema.revision,
+        });
+    })
+        .sort((left, right) => compareKeys(left.key, right.key));
+    const catalogViews = Object.freeze(views);
+    const entrypointRef = publication.manifest?.entrypoint;
+    const entrypoint = entrypointRef === undefined
+        ? undefined
+        : catalogViews.find(({ key }) => key === ViewKey.of(entrypointRef));
+    if (entrypointRef !== undefined && entrypoint === undefined) {
+        throw new ClientError('Published View entrypoint has no verified Publication binding.');
+    }
+    return Object.freeze({
+        ...(entrypoint === undefined ? {} : { entrypoint }),
+        views: catalogViews,
+    });
+}
+export function catalogFromKeys(root, keys) {
+    const selected = new Set(keys);
+    const views = Object.freeze(root.views.filter(({ key }) => selected.has(key)));
+    return Object.freeze({
+        ...(root.entrypoint !== undefined && selected.has(root.entrypoint.key)
+            ? { entrypoint: root.entrypoint }
+            : {}),
+        views,
+    });
+}
+/** Re-admit one Runtime-resolved heterogeneous View catalog at the Client trust boundary. */
+export function targetViewCatalog(input, policy) {
+    let resolution;
+    try {
+        resolution = acceptViewResolution(input);
+    }
+    catch (cause) {
+        throw new ClientError('Resolved View catalog is invalid.', { cause });
+    }
+    for (const view of resolution.views)
+        allowEndpoint(view.href, policy);
+    return Object.freeze({ views: resolution.views });
+}
+function compareKeys(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function viewName(input) {
+    const coordinate = input.slice(input.indexOf(':') + 1);
+    const match = /^view\.([A-Za-z][A-Za-z0-9_]*)$/u.exec(coordinate);
+    if (match === null)
+        throw new ClientError('Published View key is invalid.');
+    return match[1];
+}

package/dist/session/views/index.d.ts

@@ -0,0 +1,2 @@
+export { catalogFromKeys, rootViewCatalog, targetViewCatalog, type ResolvedView, type ViewCatalog, } from './catalog.js';
+export { resolveViewsFor, type ViewCatalogAdmission, type ViewInvoker } from './resolve.js';

package/dist/session/views/index.js

@@ -0,0 +1,2 @@
+export { catalogFromKeys, rootViewCatalog, targetViewCatalog, } from './catalog.js';
+export { resolveViewsFor } from './resolve.js';

package/dist/session/views/resolve.d.ts

@@ -0,0 +1,11 @@
+import type { PathLike } from '@astrale-os/kernel-core/path';
+import type { Call, Input } from '../../client/index.js';
+import type { SessionOperation } from '../context/index.js';
+import type { ViewCatalog } from './catalog.js';
+export type ViewInvoker = (call: Call, operation: SessionOperation) => Promise<Input>;
+export type ViewCatalogAdmission = (input: unknown) => ViewCatalog;
+/**
+ * Invoke Runtime-owned target View resolution through the canonical source Kernel call, then admit
+ * its heterogeneous installed-Publication projection.
+ */
+export declare function resolveViewsFor(invoke: ViewInvoker, admitCatalog: ViewCatalogAdmission, target: PathLike, operation: SessionOperation): Promise<ViewCatalog>;

package/dist/session/views/resolve.js

@@ -0,0 +1,13 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { view } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { call } from '../../client/index.js';
+/**
+ * Invoke Runtime-owned target View resolution through the canonical source Kernel call, then admit
+ * its heterogeneous installed-Publication projection.
+ */
+export async function resolveViewsFor(invoke, admitCatalog, target, operation) {
+    const path = Path.from(target).raw;
+    const owner = Path.project(view.resolve.owner);
+    const targetView = Path.staticMethod(owner, view.resolve.name);
+    return admitCatalog(await invoke(call(targetView, { target: path }), operation));
+}

package/dist/store/entity-index.d.ts

@@ -0,0 +1,22 @@
+import type { Edge, EdgeKey } from '@astrale-os/kernel-core/graph/edge';
+import type { Node, NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { QueryResult } from '@astrale-os/kernel-core/graph/query';
+export interface FactReferences {
+    readonly nodes: readonly NodeId[];
+    readonly edges: readonly string[];
+}
+export interface Integration {
+    readonly references: FactReferences;
+    readonly changedNodes: ReadonlySet<NodeId>;
+    readonly changedEdges: ReadonlySet<string>;
+}
+export declare class EntityIndex {
+    private readonly nodes;
+    private readonly edges;
+    integrate(result: QueryResult): Integration;
+    node(id: NodeId): Node | undefined;
+    edge(key: string): Edge | undefined;
+    sweep(reachableNodes: ReadonlySet<NodeId>, reachableEdges: ReadonlySet<string>): void;
+    clear(): void;
+}
+export declare function edgeIdentity(key: EdgeKey): string;

package/dist/store/entity-index.js

@@ -0,0 +1,94 @@
+import { encodeEdgeKey } from '@astrale-os/kernel-core/graph/edge';
+export class EntityIndex {
+    nodes = new Map();
+    edges = new Map();
+    integrate(result) {
+        const changedNodes = new Set();
+        const changedEdges = new Set();
+        const nodeReferences = [];
+        const edgeReferences = [];
+        const integrateNode = (node) => {
+            nodeReferences.push(node.id);
+            const current = this.nodes.get(node.id);
+            if (current === undefined || signature(current) !== signature(node)) {
+                this.nodes.set(node.id, node);
+                changedNodes.add(node.id);
+            }
+        };
+        const referenceNode = (node) => {
+            nodeReferences.push(node.id);
+        };
+        const integrateEdge = (edge) => {
+            const key = encodeEdgeKey(edge);
+            edgeReferences.push(key);
+            const current = this.edges.get(key);
+            if (current === undefined || signature(current) !== signature(edge)) {
+                this.edges.set(key, edge);
+                changedEdges.add(key);
+            }
+        };
+        const referenceEdge = (edge) => {
+            edgeReferences.push(encodeEdgeKey(edge));
+        };
+        if (result.kind === 'graph') {
+            result.graph.nodes.forEach(integrateNode);
+            result.graph.edges.forEach(integrateEdge);
+        }
+        else if (result.kind === 'nodes') {
+            for (const projection of result.nodes) {
+                if (projection.kind === 'value')
+                    integrateNode(projection.value);
+                else
+                    referenceNode(projection.value);
+            }
+        }
+        else if (result.kind === 'edges') {
+            for (const item of result.edges) {
+                if (item.edge.kind === 'value')
+                    integrateEdge(item.edge.value);
+                else
+                    referenceEdge(item.edge.value);
+                if (item.source.kind === 'value')
+                    integrateNode(item.source.value);
+                else
+                    referenceNode(item.source.value);
+                if (item.target.kind === 'value')
+                    integrateNode(item.target.value);
+                else
+                    referenceNode(item.target.value);
+            }
+        }
+        return Object.freeze({
+            references: Object.freeze({
+                nodes: Object.freeze(nodeReferences),
+                edges: Object.freeze(edgeReferences),
+            }),
+            changedNodes,
+            changedEdges,
+        });
+    }
+    node(id) {
+        return this.nodes.get(id);
+    }
+    edge(key) {
+        return this.edges.get(key);
+    }
+    sweep(reachableNodes, reachableEdges) {
+        for (const id of this.nodes.keys())
+            if (!reachableNodes.has(id))
+                this.nodes.delete(id);
+        for (const key of this.edges.keys())
+            if (!reachableEdges.has(key))
+                this.edges.delete(key);
+    }
+    clear() {
+        this.nodes.clear();
+        this.edges.clear();
+    }
+}
+export function edgeIdentity(key) {
+    return encodeEdgeKey(key);
+}
+function signature(value) {
+    return JSON.stringify(value);
+}

package/dist/store/index.d.ts

@@ -1,26 +1 @@
-/**
- * The client-side graph memory (FRONTEND_GRAPH_DX_SPEC / SHELL_REACT_API).
- *
- * A partial, normalized client copy of the graph kept correct by shapes
- * (standing queries): entity store + shape store + optimistic overlay, over a
- * `GraphApi`. Framework-free — the React bindings layer over `createMemory`.
- * Tier 0 (client self-invalidation) — see `memory.ts` for the interim-ordering
- * caveats until the wire amendments (§6) land.
- *
- * Layout: `canonicalize` (shape keying), `entities`, `shapes`, `overlay`,
- * `invalidate` (§5.6 matching), `memory` (the facade).
- */
-export { createMemory } from './memory.js';
-export type { GraphMemory } from './memory.js';
-export { canonicalizeAST, shapeInputToAST, shapeKey, stableStringify, stripCursors, } from './canonicalize.js';
-export type { RootResolver, ShapeInput } from './canonicalize.js';
-export { EntityStore } from './entities.js';
-export type { EdgeRecord, NodeRecord, ResultLike } from './entities.js';
-export { ShapeStore } from './shapes.js';
-export type { ShapeEntry } from './shapes.js';
-export { Overlay, normalizePatch } from './overlay.js';
-export type { NormalPatch, OverlayEffects, OverlayUnit } from './overlay.js';
-export { affectedShapes, matchesEdge, matchesNodeStructural, subtreeDelta } from './invalidate.js';
-export type { GatherSpec, InvalidateCtx, ShapeView } from './invalidate.js';
-export type { GatherMeta, LiveResult, MaterializedShape, MutateOptions, ReadOptions, MemoryError, MemoryEvent, MemoryOptions, ShapeMeta, Windowed, } from './types.js';
-//# sourceMappingURL=index.d.ts.map
+export { GraphStore, type StoreMutationOptions, type StoreOptions, type StoreQuery, type StoreQueryResponse, type StoreReadOptions, type StoreSnapshot, } from './store.js';

package/dist/store/index.js

@@ -1,19 +1 @@
-/**
- * The client-side graph memory (FRONTEND_GRAPH_DX_SPEC / SHELL_REACT_API).
- *
- * A partial, normalized client copy of the graph kept correct by shapes
- * (standing queries): entity store + shape store + optimistic overlay, over a
- * `GraphApi`. Framework-free — the React bindings layer over `createMemory`.
- * Tier 0 (client self-invalidation) — see `memory.ts` for the interim-ordering
- * caveats until the wire amendments (§6) land.
- *
- * Layout: `canonicalize` (shape keying), `entities`, `shapes`, `overlay`,
- * `invalidate` (§5.6 matching), `memory` (the facade).
- */
-export { createMemory } from './memory.js';
-export { canonicalizeAST, shapeInputToAST, shapeKey, stableStringify, stripCursors, } from './canonicalize.js';
-export { EntityStore } from './entities.js';
-export { ShapeStore } from './shapes.js';
-export { Overlay, normalizePatch } from './overlay.js';
-export { affectedShapes, matchesEdge, matchesNodeStructural, subtreeDelta } from './invalidate.js';
-//# sourceMappingURL=index.js.map
+export { GraphStore, } from './store.js';

package/dist/store/memory.d.ts

@@ -1,99 +1,48 @@
-/**
- * createMemory (FRONTEND §4.5, SHELL_REACT §5) — the framework-free memory
- * facade over a `GraphApi`.
- *
- * One partial client copy of the graph per scope (= principal): entity store +
- * shape store + optimistic overlay. Reads are shape-keyed, deduped, and
- * stale-while-revalidate; a `subscribe`/`getSnapshot` pair gives
- * useSyncExternalStore semantics (tear-free, referentially stable when
- * unchanged) and `promise` a cold-shape handle for React suspense.
- *
- * SAFE MODE (§5.7 — ratified until the §6 wire amendments land). One rule:
- * **confirmed state comes only from server responses; client predictions live
- * only in a display layer guaranteed to be discarded and replaced by server
- * truth.** Concretely:
- *   - Confirmed state (EntityStore + shape membership) is written ONLY by read
- *     responses (`integrate` / `integrateShape`).
- *   - Every write DISPATCHES, then marks the shapes it touched stale and
- *     REVALIDATES them (refetch = reconcile). "Slow but never wrong."
- *   - The optimistic overlay is DISPLAY-ONLY. Prop updates on cached nodes and
- *     deletes get an overlay (no-flicker prediction); creates/links/unlinks are
- *     reconcile-only (a create/link misprediction is a phantom, forbidden; a
- *     delete misprediction is loud — a brief reappearance). The overlay is held
- *     from apply until the reconciling refetch lands, then dropped — never
- *     folded into confirmed state.
- *   - Ordering: the logical merge clock is stamped at response ARRIVAL, and a
- *     per-scope mutation EPOCH closes the read-straddles-commit window (a
- *     response older than a commit is integrated-then-restaled).
- *   - Isolation: the `with` lens partitions the ENTITY store, not just the
- *     shape key — lenses never share entities.
- *
- * The public surface (`GraphMemory`/`LiveResult`, `createMemory`) is stable:
- * when seq/rev/delta/watch (§6/§7) land, this becomes "fast and never wrong"
- * with no surface change (`commitOverlay` is already the server-delta seam).
- */
-import type { Node } from '@astrale-os/kernel-core';
-import type { EdgeIdentity, GraphApi, MutationResultWire, PatchBuilder, PatchInput, PathLike, Properties, ReconcileInput, ReconcileResult } from '../graph/index.js';
-import type { ShapeInput } from './canonicalize.js';
-import type { LiveResult, MutateOptions, ReadOptions, MemoryOptions } from './types.js';
-/** The framework-free memory surface (SHELL_REACT §5 + FRONTEND §4.5). */
-export interface GraphMemory {
-    /** The principal/isolation key this handle is bound to. */
-    readonly scope: string;
-    /** The raw floor, untouched. */
-    readonly api: GraphApi;
-    /** Read-through: resolve the shape, fetching if cold, then return the live result. */
-    query(shape: ShapeInput, opts?: ReadOptions): Promise<LiveResult>;
-    /** Memory-only, synchronous — no I/O. `null` when the shape is cold. */
-    peek(shape: ShapeInput, opts?: ReadOptions): LiveResult | null;
-    /** Warm the exact shape a later render reads. */
-    preload(shape: ShapeInput, opts?: ReadOptions): Promise<void>;
-    /** External-store subscription: `onStoreChange` fires when this shape changes. */
-    subscribe(shape: ShapeInput, onStoreChange: () => void, opts?: ReadOptions): () => void;
-    /** The current live result for a shape — stable ref when unchanged (getSnapshot). */
-    getSnapshot(shape: ShapeInput, opts?: ReadOptions): LiveResult;
-    /** A promise that resolves once the shape first has confirmed data (suspense). */
-    promise(shape: ShapeInput, opts?: ReadOptions): Promise<LiveResult>;
-    /** Convenience: subscribe + push the current (and each subsequent) snapshot to `cb`. */
-    watch(shape: ShapeInput, cb: (result: LiveResult) => void, opts?: ReadOptions): () => void;
-    /** Batch write — optimistic-auto (§4.4). Builder or pre-built patch. */
-    mutate(arg: ((m: PatchBuilder) => void | Promise<void>) | PatchInput, opts?: MutateOptions): Promise<MutationResultWire>;
-    /** Delegates to `GraphApi.reconcile`; the store only invalidates touched shapes. */
-    reconcile(input: ReconcileInput): Promise<ReconcileResult>;
-    update(node: Node | PathLike, props: Properties, opts?: MutateOptions): Promise<void>;
-    create(cls: PathLike, at: PathLike, props?: Properties, opts?: MutateOptions): Promise<string>;
-    remove(node: Node | PathLike, opts?: MutateOptions): Promise<void>;
-    link(edge: EdgeIdentity & {
-        props?: Properties;
-    }, opts?: MutateOptions): Promise<string>;
-    unlink(edge: EdgeIdentity, opts?: MutateOptions): Promise<void>;
-    /**
-     * Apply a MANUAL optimistic overlay decoupled from any dispatch (§1.6 — the
-     * method-dispatch seam a patch arm can't express, e.g. `user::switchSpace`).
-     * SAFE MODE: only the display-safe arms (prop updates on cached nodes,
-     * deletes) predict; the caller dispatches whatever it likes, then `commit()`s
-     * (reconcile the touched shapes from the server, drop the overlay) or
-     * `rollback()`s.
-     */
-    overlay(build: (m: PatchBuilder) => void, opts?: {
-        scope?: string;
-    }): OptimisticOverlay;
-    /** An isolated handle for another scope (principal). No store sharing (§5.4). */
-    forScope(scope: string, api?: GraphApi): GraphMemory;
-    /** Release unobserved shapes past their ttl and GC unreachable entities. */
-    sweep(): void;
+import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { QueryPageRequest } from '../graph/index.js';
+import type { GraphApi } from '../graph/index.js';
+import type { StoreQueryResponse, StoreReadOptions, StoreSnapshot } from './store.js';
+import { ClientError } from '../errors/index.js';
+import { EntityIndex } from './entity-index.js';
+import { OptimisticOverlay } from './optimistic.js';
+import { QueryShape } from './shape.js';
+export interface GraphMemoryOptions {
+    readonly graph: GraphApi;
+    readonly ttlMs: number;
+    readonly concurrency: number;
+    readonly maximumShapes: number;
+    readonly now: () => number;
+    readonly onError?: (error: unknown) => void;
+    readonly lifecycle: AbortSignal;
+    readonly requireOpen: () => void;
 }
-/** A live manual-overlay handle (see {@link GraphMemory.overlay}). */
-export interface OptimisticOverlay {
-    /**
-     * Reconcile the shapes this overlay touched from the server and drop the
-     * display prediction. The `result` param is retained for the §6.3 server-delta
-     * path; on Tier-0 it is unused (reconciliation is by refetch).
-     */
-    commit(result?: MutationResultWire): void;
-    /** Drop the overlay — the dispatch failed. */
-    rollback(): void;
+export declare class GraphMemory {
+    private readonly options;
+    readonly entities: EntityIndex;
+    readonly overlay: OptimisticOverlay;
+    private readonly shapes;
+    private readonly pending;
+    private active;
+    constructor(options: GraphMemoryOptions);
+    ensure(key: string, ast: QueryAST, page: QueryPageRequest): QueryShape;
+    get(key: string): QueryShape | undefined;
+    read(shape: QueryShape, options: StoreReadOptions): Promise<StoreQueryResponse>;
+    snapshot(shape: QueryShape | undefined): StoreSnapshot;
+    subscribe(shape: QueryShape, listener: () => void): () => void;
+    invalidate(shape?: QueryShape): void;
+    optimistic(): void;
+    settleOptimistic(): void;
+    sweep(): void;
+    private releaseExpired;
+    private evictLeastRecentlyUsed;
+    private releasable;
+    private touch;
+    private sweepEntities;
+    close(error: ClientError): void;
+    private materialize;
+    private materializeResult;
+    private publish;
+    private schedule;
+    private drain;
+    private report;
 }
-/** Bind the memory onto a `GraphApi`. */
-export declare function createMemory(api: GraphApi, opts?: MemoryOptions): GraphMemory;
-//# sourceMappingURL=memory.d.ts.map