@astrale-os/kernel-client 0.5.0 → 0.6.0-beta.1

package/dist/store/memory.d.ts

@@ -1,99 +1,49 @@
-/**
- * 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 '@astrale-os/kernel-ports/query';
+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

package/dist/store/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/store/memory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../store/memory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,QAAQ,EAMT,MAAM,qCAAqC,CAAA;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAA;AAItE,OAAO,KAAK,EAAE,QAAQ,EAAqB,MAAM,mBAAmB,CAAA;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAErF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAgB,WAAW,EAAuB,MAAM,mBAAmB,CAAA;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAAiB,UAAU,EAAE,MAAM,YAAY,CAAA;AAItD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC3C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAA;CACjC;AAOD,qBAAa,WAAW;IAOV,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,QAAQ,CAAC,QAAQ,cAAoB;IACrC,QAAQ,CAAC,OAAO,oBAA0B;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,MAAM,CAAI;IAElB,YAA6B,OAAO,EAAE,kBAAkB,EAAI;IAE5D,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,GAAG,UAAU,CAkBrE;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAIvC;IAEK,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoDpF;IAED,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,aAAa,CAErD;IAED,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAS7D;IAED,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CASnC;IAED,UAAU,IAAI,IAAI,CAMjB;IAED,gBAAgB,IAAI,IAAI,CAMvB;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,aAAa;IAUrB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAS9B;IAED,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,iBAAiB;IAwEzB,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,MAAM;CAOf"}