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

package/dist/store/memory.js

@@ -1,813 +1,396 @@
-/**
- * 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 { Graph, rawOf } from '@astrale-os/kernel-core';
-import { edgeKey } from '../graph/index.js';
-import { mintedId, PatchBuilderImpl } from '../graph/mutate/index.js';
-import { HAS_PARENT_CLASS } from '../graph/query/edges.js';
-import { shapeInputToAST, shapeKey, stripCursors } from './canonicalize.js';
-import { EntityStore } from './entities.js';
-import { affectedShapes } from './invalidate.js';
-import { normalizePatch, Overlay } from './overlay.js';
-import { TaskQueue } from './schedule.js';
-import { integrateShape, materialize, ShapeStore, shapeViewOf } from './shapes.js';
-/** Bind the memory onto a `GraphApi`. */
-export function createMemory(api, opts) {
-    return new Memory(api, opts).facade(opts?.scope ?? 'default');
-}
-class Memory {
-    defaultApi;
-    scopes = new Map();
-    apis = new Map();
-    now;
-    ttlMs;
-    tombstoneTtlMs;
-    onError;
-    dev;
-    sweepEvery;
-    scheduler;
-    clock = 0;
-    mutationSeq = 0;
-    opCount = 0;
-    constructor(defaultApi, opts) {
-        this.defaultApi = defaultApi;
-        this.now = opts?.now ?? Date.now;
-        this.ttlMs = opts?.ttlMs ?? 30_000;
-        this.tombstoneTtlMs = opts?.tombstoneTtlMs ?? 300_000;
-        this.onError = opts?.onError;
-        this.dev = opts?.dev ?? false;
-        this.sweepEvery = opts?.sweepEvery ?? 128;
-        this.scheduler = new TaskQueue(opts?.concurrency ?? 4);
-    }
-    facade(scope) {
-        return {
-            scope,
-            api: this.apiFor(scope),
-            query: (shape, o) => this.query(scope, shape, o),
-            peek: (shape, o) => this.peek(scope, shape, o),
-            preload: (shape, o) => this.preload(scope, shape, o),
-            subscribe: (shape, cb, o) => this.subscribe(scope, shape, cb, o),
-            getSnapshot: (shape, o) => this.getSnapshot(scope, shape, o),
-            promise: (shape, o) => this.promise(scope, shape, o),
-            watch: (shape, cb, o) => this.watchShape(scope, shape, cb, o),
-            mutate: (arg, o) => this.mutate(scope, arg, o),
-            reconcile: (input) => this.runReconcile(scope, input),
-            update: (node, props, o) => this.update(scope, node, props, o),
-            create: (cls, at, props, o) => this.create(scope, cls, at, props, o),
-            remove: (node, o) => this.remove(scope, node, o),
-            link: (edge, o) => this.link(scope, edge, o),
-            unlink: (edge, o) => this.unlink(scope, edge, o),
-            overlay: (build, o) => this.openOverlay(o?.scope ?? scope, build),
-            forScope: (s, a) => {
-                if (a !== undefined)
-                    this.apis.set(s, a);
-                return this.facade(s);
-            },
-            sweep: () => this.sweep(),
-        };
-    }
-    // ── Scope + key plumbing ────────────────────────────────────────────────────
-    apiFor(scope) {
-        return this.apis.get(scope) ?? this.defaultApi;
-    }
-    /**
-     * The isolation key partitions the store by `(principal, with-lens)` (§5.7):
-     * two lenses over the same principal never share entities, shapes, or overlay.
-     */
-    isoKey(principal, withPerm) {
-        return withPerm === undefined ? principal : `${principal}::with=${withPerm}`;
-    }
-    state(principal, withPerm) {
-        const key = this.isoKey(principal, withPerm);
-        let s = this.scopes.get(key);
-        if (s === undefined) {
-            s = {
-                principal,
-                isoKey: key,
-                entities: new EntityStore(),
-                shapes: new ShapeStore(),
-                overlay: new Overlay(),
-                epoch: 0,
-            };
-            this.scopes.set(key, s);
+import { encodeEdgeKey } from '@astrale-os/kernel-core/graph/edge';
+import { ClientError } from '../errors/index.js';
+import { edgeIdentity, EntityIndex } from './entity-index.js';
+import { OptimisticOverlay } from './optimistic.js';
+import { COLD_SNAPSHOT, QueryShape } from './shape.js';
+export class GraphMemory {
+    options;
+    entities = new EntityIndex();
+    overlay = new OptimisticOverlay();
+    shapes = new Map();
+    pending = [];
+    active = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    ensure(key, ast, page) {
+        const existing = this.shapes.get(key);
+        const now = this.options.now();
+        if (existing !== undefined) {
+            this.touch(existing, now);
+            return existing;
         }
-        return s;
-    }
-    /** Every lens partition of a principal — a write reconciles across all of them. */
-    partitionsOf(principal) {
-        return [...this.scopes.values()].filter((s) => s.principal === principal);
-    }
-    keyOf(state, scope, ast) {
-        return shapeKey(ast, scope, (raw) => state.entities.resolvePathToId(raw));
-    }
-    /** Normalize an input to its AST, folding a per-read `with` onto it so it keys the shape. */
-    astFor(input, opts) {
-        const ast = shapeInputToAST(input);
-        if (opts?.with !== undefined && ast.with !== opts.with)
-            return { ...ast, with: opts.with };
-        return ast;
-    }
-    /** Resolve (and create) the entry for a shape input. */
-    entryFor(state, scope, input, opts) {
-        const ast = this.astFor(input, opts);
-        const key = this.keyOf(state, scope, ast);
-        const created = state.shapes.get(key) === undefined;
-        const entry = state.shapes.ensure(key, scope, stripCursors(ast), ast.from.map(rawOf));
-        // window is per-shape and fixed at creation — a later caller's option can't
-        // retune a shape other observers already read under.
-        if (created && opts?.window !== undefined)
-            entry.window = opts.window;
-        if (entry.observers === 0 && entry.releasedAt === null)
-            entry.releasedAt = this.now();
-        return entry;
-    }
-    /** Look up an existing entry without creating one (peek / render-pure getSnapshot). */
-    lookup(state, scope, input, opts) {
-        return state.shapes.get(this.keyOf(state, scope, this.astFor(input, opts)));
-    }
-    /** Follow the provisional→resolved alias to a subscription's live entry (post-merge). */
-    live(state, entry) {
-        return state.shapes.get(entry.key) ?? entry;
-    }
-    // ── Reads ────────────────────────────────────────────────────────────────────
-    async query(scope, input, opts) {
-        const state = this.state(scope, opts?.with);
-        let entry = this.entryFor(state, scope, input, opts);
-        this.tick();
-        if (!entry.hasData || entry.stale) {
-            try {
-                await this.revalidate(state, entry, entry.hasData ? 'reconcile' : 'fresh');
-            }
-            catch (error) {
-                // Warm shape: keep last-good data + `error` (§5.5); only a cold read throws.
-                if (!this.live(state, entry).hasData)
-                    throw error;
-            }
-            entry = this.live(state, entry);
+        this.releaseExpired(now);
+        if (this.shapes.size >= this.options.maximumShapes)
+            this.evictLeastRecentlyUsed();
+        if (this.shapes.size >= this.options.maximumShapes) {
+            throw new ClientError('GraphStore shape capacity is exhausted by observed or in-flight queries.');
         }
-        return this.snapshot(state, entry);
-    }
-    peek(scope, input, opts) {
-        const state = this.state(scope, opts?.with);
-        const entry = this.lookup(state, scope, input, opts);
-        if (entry === undefined || !entry.hasData)
-            return null;
-        return this.snapshot(state, entry);
-    }
-    async preload(scope, input, opts) {
-        const state = this.state(scope, opts?.with);
-        const entry = this.entryFor(state, scope, input, opts);
-        this.tick();
-        if (!entry.hasData)
-            await this.revalidate(state, entry, 'fresh').catch(() => { });
-    }
-    subscribe(scope, input, onStoreChange, opts) {
-        const state = this.state(scope, opts?.with);
-        const entry = this.entryFor(state, scope, input, opts);
-        entry.observers++;
-        entry.releasedAt = null;
-        entry.listeners.add(onStoreChange);
-        this.tick();
-        // Fetch when cold, and revalidate when known-stale (a prior write or a failed
-        // refresh left it stale) — §5.5. Reconcile preserves the accumulated window.
-        if ((!entry.hasData || entry.stale) && entry.inflight === null && opts?.live !== false) {
-            void this.revalidate(state, entry, entry.hasData ? 'reconcile' : 'fresh').catch(() => { });
-        }
-        return () => {
-            // A merge (rehome) may have moved this subscription onto the surviving
-            // entry — re-resolve so the count/listener land on the live one.
-            const e = this.live(state, entry);
-            e.listeners.delete(onStoreChange);
-            e.observers = Math.max(0, e.observers - 1);
-            if (e.observers === 0)
-                e.releasedAt = this.now();
-        };
-    }
-    /**
-     * Render-pure (§5.7): reads an EXISTING entry, never creates one (entry
-     * creation is a subscribe/query concern — creating here double-mints entries
-     * under StrictMode's double render). A cold shape returns a shared, stable
-     * placeholder so useSyncExternalStore sees a referentially constant snapshot.
-     */
-    getSnapshot(scope, input, opts) {
-        const state = this.state(scope, opts?.with);
-        const entry = this.lookup(state, scope, input, opts);
-        if (entry === undefined)
-            return COLD;
-        return this.snapshot(state, entry);
-    }
-    promise(scope, input, opts) {
-        const state = this.state(scope, opts?.with);
-        const entry = this.entryFor(state, scope, input, opts);
-        if (entry.hasData)
-            return Promise.resolve(this.snapshot(state, entry));
-        return this.revalidate(state, entry, 'fresh').then(() => this.snapshot(state, this.live(state, entry)));
-    }
-    watchShape(scope, input, cb, opts) {
-        const state = this.state(scope, opts?.with);
-        const entry = this.entryFor(state, scope, input, opts);
-        const unsub = this.subscribe(scope, input, () => cb(this.snapshot(state, this.live(state, entry))), opts);
-        cb(this.snapshot(state, this.live(state, entry)));
-        return unsub;
-    }
-    // ── Fetch / integrate ─────────────────────────────────────────────────────────
-    /** The AST + membership mode a revalidation intent requests (§5.7 window-preserving). */
-    fetchPlan(entry, intent) {
-        if (intent === 'more') {
-            return {
-                ast: entry.contAst ?? entry.baseAst,
-                mode: entry.window === 'paged' ? 'replace' : 'append',
-            };
+        const shape = new QueryShape(key, ast, page, now);
+        shape.releasedAt = now;
+        this.shapes.set(key, shape);
+        return shape;
+    }
+    get(key) {
+        const shape = this.shapes.get(key);
+        if (shape !== undefined)
+            this.touch(shape, this.options.now());
+        return shape;
+    }
+    async read(shape, options) {
+        this.options.requireOpen();
+        requireReadLive(options.signal, this.options.lifecycle);
+        const reusable = shape.response !== undefined &&
+            shape.state === 'ready' &&
+            shape.refreshedAt !== undefined &&
+            this.options.now() - shape.refreshedAt < this.options.ttlMs;
+        if (options.freshness !== 'refresh' && reusable)
+            return shape.response;
+        if (shape.inflight !== undefined) {
+            return observeRead(shape.inflight, options, this.options.lifecycle);
         }
-        // A reconcile re-requests the whole accumulated window so an 'append' window
-        // never collapses to page 1 on a write; a fresh eval resets to page 1.
-        if (intent === 'reconcile')
-            return { ast: windowAst(entry.baseAst, entry.windowPages), mode: 'replace' };
-        return { ast: entry.baseAst, mode: 'replace' };
-    }
-    /**
-     * Fetch a page and fold it in. Deduped on `entry.inflight` (two identical
-     * in-flight shapes share ONE api call). The merge clock is stamped at response
-     * ARRIVAL, and a response older than a committed mutation (dispatch-epoch <
-     * current epoch) is integrated-then-restaled to close the straddle window.
-     */
-    revalidate(state, entry, intent) {
-        if (entry.inflight !== null)
-            return entry.inflight;
-        const { ast, mode } = this.fetchPlan(entry, intent);
-        const dispatchEpoch = state.epoch;
-        const p = this.apiFor(entry.scope)
-            .query(ast)
-            .then((result) => {
-            const wire = result.wire;
-            const seq = ++this.clock; // ARRIVAL order (§5.7), not dispatch order
-            state.entities.integrate(wire, seq);
-            const resolvedKey = this.keyOf(state, entry.scope, entry.baseAst);
-            const live = state.shapes.rehome(entry, resolvedKey);
-            live.inflight = null;
-            if (intent === 'more' && mode === 'append')
-                live.windowPages++;
-            else if (intent === 'fresh')
-                live.windowPages = 1;
-            integrateShape(live, wire, seq, mode);
-            if (dispatchEpoch < state.epoch) {
-                // Read straddled a commit: integrate (so a cold shape still gets data
-                // and continuous writes can't starve it) THEN restale (so it converges
-                // — at quiescence the last refetch's epoch matches). Chosen over
-                // discard for those two reasons.
-                live.stale = true;
-                void this.scheduleReconcile(state, live);
+        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));
+            this.options.requireOpen();
+            const integration = this.entities.integrate(result.result);
+            shape.references = integration.references;
+            shape.confirmed = result;
+            shape.response = this.materialize(result, integration.references);
+            shape.refreshedAt = this.options.now();
+            this.touch(shape, shape.refreshedAt);
+            this.publish(shape, this.overlay.hasAny() ? 'optimistic' : 'ready');
+            for (const other of this.shapes.values()) {
+                if (other === shape || other.response === undefined)
+                    continue;
+                if (other.referencesAny(integration.changedNodes, integration.changedEdges)) {
+                    other.response = this.materialize(other.confirmed, other.references);
+                    this.publish(other, other.state);
+                }
             }
-            this.notify(live);
-            this.audit(state);
-            return wire;
+            return shape.response;
         })
             .catch((error) => {
-            const live = state.shapes.get(entry.key) ?? entry;
-            live.inflight = null;
-            live.error = error;
-            live.stale = true;
-            live.dirty = true;
-            this.emit({ kind: 'refresh', shape: live.key, error });
-            this.notify(live);
+            if (prior === undefined)
+                this.publish(shape, 'failed', error);
+            else {
+                shape.response = prior;
+                this.publish(shape, this.overlay.hasAny() ? 'optimistic' : 'stale');
+            }
             throw error;
+        })
+            .finally(() => {
+            if (shape.inflight === inflight)
+                shape.inflight = undefined;
         });
-        entry.inflight = p;
-        entry.dirty = true;
-        this.notify(entry);
-        return p;
+        shape.inflight = inflight;
+        return observeRead(inflight, options, this.options.lifecycle);
     }
-    /** Coalesced, concurrency-capped reconcile refetch — resolves when it lands (§5.7). */
-    scheduleReconcile(state, entry) {
-        return this.scheduler.request(entry, () => this.revalidate(state, this.live(state, entry), 'reconcile').then(() => undefined, () => undefined));
+    snapshot(shape) {
+        return shape?.snapshot ?? COLD_SNAPSHOT;
     }
-    // ── Snapshot (referential stability) ──────────────────────────────────────────
-    /** The live result, rebuilt only when the shape is dirty (stable ref otherwise). */
-    snapshot(state, entry) {
-        if (!entry.dirty && entry.result !== null)
-            return entry.result;
-        const mat = materialize(entry, state.entities, state.overlay);
-        const result = {
-            graph: mat.graph,
-            roots: mat.roots,
-            nodes: mat.nodes,
-            first: mat.first,
-            node: mat.first,
-            children: mat.children,
-            gathered: (alias) => mat.gathered(alias),
-            pending: entry.inflight !== null,
-            stale: entry.stale,
-            error: entry.error,
-            live: entry.observers > 0,
-            seq: 0,
-            more: {
-                has: !entry.exhausted && entry.contAst !== null,
-                pending: entry.inflight !== null,
-                load: async () => {
-                    const e = this.live(state, entry);
-                    if (e.exhausted || e.contAst === null)
-                        return;
-                    await this.revalidate(state, e, 'more');
-                },
-            },
-            refetch: async () => {
-                const e = this.live(state, entry);
-                e.stale = true;
-                await this.revalidate(state, e, 'reconcile'); // window-preserving
-            },
+    subscribe(shape, listener) {
+        this.options.requireOpen();
+        shape.listeners.add(listener);
+        shape.accessedAt = this.options.now();
+        shape.releasedAt = undefined;
+        return () => {
+            shape.listeners.delete(listener);
+            if (!shape.observed)
+                shape.releasedAt = this.options.now();
         };
-        entry.result = result;
-        entry.dirty = false;
-        return result;
     }
-    notify(entry) {
-        entry.dirty = true;
-        for (const listener of entry.listeners)
-            listener();
-    }
-    // ── Writes (dispatch → reconcile; display-only overlay) ─────────────────────────
-    async mutate(scope, arg, opts) {
-        if (typeof arg === 'function') {
-            const builder = new PatchBuilderImpl();
-            await arg(builder);
-            const patch = builder.build();
-            const result = await this.applyWrite(scope, patch, opts);
-            builder.resolve(result.createdNodes);
-            return result;
-        }
-        return this.applyWrite(scope, arg, opts);
-    }
-    async runReconcile(scope, input) {
-        const result = await this.apiFor(scope).reconcile(input);
-        if (!result.applied)
-            return result;
-        const dispatched = normalizePatch(result.patch);
-        if (!patchHasOperations(dispatched))
-            return result;
-        for (const part of this.partitionsOf(scope)) {
-            part.epoch++;
-            for (const p of this.markStaleByPatch(part, dispatched))
-                void p;
+    invalidate(shape) {
+        this.options.requireOpen();
+        for (const candidate of shape === undefined ? this.shapes.values() : [shape]) {
+            if (candidate.response === undefined)
+                continue;
+            this.publish(candidate, this.overlay.hasAny() ? 'optimistic' : 'stale');
+            if (candidate.observed && candidate.inflight === undefined) {
+                void this.read(candidate, { page: candidate.page }).catch((error) => this.report(error));
+            }
         }
-        return result;
-    }
-    async update(scope, node, props, opts) {
-        const state = this.state(scope);
-        const patch = {
-            nodes: { update: [{ class: this.classOf(state, node), path: refPathRaw(node), props }] },
-        };
-        await this.applyWrite(scope, patch, opts);
     }
-    async create(scope, cls, at, props, opts) {
-        const atRaw = rawOf(at);
-        const patch = {
-            nodes: { create: [{ class: rawOf(cls), at: atRaw, props: props ?? {} }] },
-        };
-        const result = await this.applyWrite(scope, patch, opts);
-        return mintedId(result.createdNodes, atRaw, 'node');
-    }
-    async remove(scope, node, opts) {
-        const state = this.state(scope);
-        const patch = {
-            nodes: { delete: [{ class: this.classOf(state, node), path: refPathRaw(node) }] },
-        };
-        await this.applyWrite(scope, patch, opts);
-    }
-    async link(scope, edge, opts) {
-        const { props, ...identity } = edge;
-        const patch = {
-            edges: { create: [{ ...rawIdentity(identity), props: props ?? {} }] },
-        };
-        const result = await this.applyWrite(scope, patch, opts);
-        return mintedId(result.createdEdges, edgeKey(identity), 'edge');
-    }
-    async unlink(scope, edge, opts) {
-        const patch = { edges: { delete: [rawIdentity(edge)] } };
-        await this.applyWrite(scope, patch, opts);
-    }
-    /**
-     * SAFE MODE write (§5.7): dispatch, then reconcile the touched shapes by
-     * refetch. `optimistic` selects the DISPLAY overlay (never folded): `'auto'`
-     * (default) overlays the display-safe arms of the authored patch (prop updates
-     * on cached nodes + deletes); a function overlays a manually-built patch's
-     * display-safe arms; `false` skips the overlay. Creates/links/unlinks are
-     * always reconcile-only — no structural membership is ever predicted.
-     */
-    async applyWrite(scope, patch, opts) {
-        const home = this.state(scope);
-        const mode = opts?.optimistic ?? 'auto';
-        const dispatched = normalizePatch(patch);
-        const display = mode === false
-            ? null
-            : this.displayArms(home, mode === 'auto' ? dispatched : normalizePatch(this.buildPatch(mode)));
-        const txn = display !== null && display.has ? this.beginOverlay(home, display.patch) : null;
-        this.tick();
-        try {
-            const result = await this.apiFor(scope).mutate(patch);
-            // Commit acked (§5.7 ordering): bump every lens partition's epoch so any
-            // read now in flight (dispatched pre-commit) is caught as a straddle.
-            for (const part of this.partitionsOf(scope))
-                part.epoch++;
-            this.reconcile(scope, dispatched, home, txn);
-            opts?.onCommit?.(result);
-            return result;
-        }
-        catch (error) {
-            if (txn !== null && opts?.rollback !== false)
-                this.rollbackOverlay(home, txn);
-            opts?.onError?.(error);
-            this.emit({ kind: 'mutation', mutationId: txn?.mutationId ?? '(none)', error });
-            throw error;
+    optimistic() {
+        for (const shape of this.shapes.values()) {
+            if (shape.response === undefined)
+                continue;
+            shape.response = this.materialize(shape.confirmed, shape.references);
+            this.publish(shape, 'optimistic');
         }
     }
-    /**
-     * The display-safe subset of a patch: prop updates on ALREADY-CACHED nodes
-     * whose every key is unambiguously qualifiable, plus deletes. Creates, edges,
-     * uncached/ambiguous updates are dropped (reconcile-only) — a create/link
-     * misprediction would be a phantom (forbidden); a delete misprediction is
-     * merely loud (§5.7).
-     */
-    displayArms(state, dispatched) {
-        const update = [];
-        for (const u of dispatched.nodes.update) {
-            const id = state.entities.resolvePathToId(u.path);
-            if (id === undefined)
-                continue; // not cached → reconcile-only (can't predict blind)
-            const ref = state.entities.node(id)?.wire.props;
-            const q = qualifyKeys(u.props, ref);
-            if (q.unresolved)
-                continue; // ambiguous/unqualifiable key → reconcile-only
-            update.push({ ...u, props: q.props });
+    settleOptimistic() {
+        for (const shape of this.shapes.values()) {
+            if (shape.response === undefined)
+                continue;
+            shape.response = this.materialize(shape.confirmed, shape.references);
+            this.publish(shape, this.overlay.hasAny() ? 'optimistic' : 'stale');
         }
-        const del = dispatched.nodes.delete;
-        const patch = {
-            nodes: { create: [], update, delete: del },
-            edges: { create: [], update: [], delete: [] },
-        };
-        return { patch, has: update.length > 0 || del.length > 0 };
     }
-    /** Apply a display overlay unit (no membership mutation) and notify its shapes. */
-    beginOverlay(state, displayPatch) {
-        const mutationId = `m${++this.mutationSeq}`;
-        state.overlay.add({
-            mutationId,
-            patch: displayPatch,
-            provisionalNodes: new Map(),
-            provisionalEdges: new Map(),
-        });
-        const affected = this.affectedEntries(state, displayPatch);
-        for (const entry of affected)
-            this.notify(entry);
-        this.audit(state);
-        return { mutationId, patch: displayPatch, affected };
-    }
-    /** Drop a rolled-back display overlay (the dispatch failed). No membership to undo. */
-    rollbackOverlay(state, txn) {
-        state.overlay.drop(txn.mutationId);
-        for (const entry of txn.affected)
-            this.notify(entry);
-        this.audit(state);
+    sweep() {
+        this.options.requireOpen();
+        this.releaseExpired(this.options.now());
     }
-    /**
-     * After a commit ACK: mark every shape the write touched stale and revalidate
-     * the observed ones (across all lens partitions). Then HOLD the display overlay
-     * until those reconciling refetches land, and DROP it — server truth has
-     * replaced the prediction.
-     */
-    reconcile(scope, dispatched, home, txn) {
-        const promises = [];
-        for (const part of this.partitionsOf(scope)) {
-            for (const p of this.markStaleByPatch(part, dispatched))
-                promises.push(p);
+    releaseExpired(now) {
+        for (const [key, shape] of this.shapes) {
+            if (this.releasable(shape) && now - shape.releasedAt >= this.options.ttlMs) {
+                this.shapes.delete(key);
+            }
         }
-        if (txn === null)
-            return;
-        void Promise.allSettled(promises).then(() => this.dropOverlay(home, txn));
-    }
-    /**
-     * Drop a held overlay once its reconciling refetch has landed, emitting a
-     * DIVERGENCE event if what it displayed differs from the refetched truth
-     * (a delete whose node the server still returns; an update the server didn't
-     * apply). This is the Tier-0 tripwire that a prediction was wrong.
-     */
-    dropOverlay(state, txn) {
-        this.detectDivergence(state, txn);
-        state.overlay.drop(txn.mutationId);
-        for (const entry of txn.affected)
-            this.notify(entry);
-        this.audit(state);
+        this.sweepEntities();
     }
-    detectDivergence(state, txn) {
-        if (this.onError === undefined)
-            return;
-        const shape = firstKey(txn.affected);
-        const eff = state.overlay.effects(state.entities);
-        for (const u of txn.patch.nodes.update) {
-            const id = state.entities.resolvePathToId(u.path);
-            if (id === undefined)
+    evictLeastRecentlyUsed() {
+        let oldest;
+        for (const shape of this.shapes.values()) {
+            if (!this.releasable(shape))
                 continue;
-            const predicted = state.overlay.effectiveNode(id, state.entities, eff);
-            const confirmed = state.entities.node(id)?.wire ?? null;
-            for (const key of Object.keys(u.props)) {
-                if (!Object.is(predicted?.props[key], confirmed?.props[key])) {
-                    this.emit({ kind: 'divergence', shape, id: String(id), detail: `update:${key}` });
-                    break;
-                }
-            }
+            if (oldest === undefined || shape.accessedAt < oldest.accessedAt)
+                oldest = shape;
         }
-        for (const d of txn.patch.nodes.delete) {
-            const id = state.entities.resolvePathToId(d.path);
-            // The predicted absence diverges iff a reconciled shape still holds it.
-            if (id !== undefined && [...txn.affected].some((e) => e.memberSet.has(id))) {
-                this.emit({ kind: 'divergence', shape, id: String(id), detail: 'delete:still-present' });
-            }
+        if (oldest !== undefined) {
+            this.shapes.delete(oldest.key);
+            this.sweepEntities();
         }
     }
-    /** The set of shape entries a patch affects (§5.6 matcher over this partition). */
-    affectedEntries(state, patch) {
-        const ctx = {
-            hasParentClass: HAS_PARENT_CLASS,
-            resolve: (raw) => state.entities.resolvePathToId(raw),
-        };
-        const entries = [...state.shapes.all()];
-        const ids = affectedShapes(patch, entries.map((e) => shapeViewOf(e, state.entities)), ctx);
-        return new Set(entries.filter((e) => ids.has(e.key)));
+    releasable(shape) {
+        return !shape.observed && shape.inflight === undefined && shape.releasedAt !== undefined;
     }
-    /**
-     * Mark shapes a write affects stale and coalesce a reconcile refetch for the
-     * observed ones (§5.5) — server-computed effects and every reconcile-only op
-     * land here. Unobserved shapes revalidate lazily on their next subscribe/query.
-     * Returns the observed shapes' reconcile promises so a held overlay knows when
-     * to drop.
-     */
-    markStaleByPatch(state, patch) {
-        const promises = [];
-        for (const entry of this.affectedEntries(state, patch)) {
-            entry.stale = true;
-            this.notify(entry);
-            if (entry.observers > 0)
-                promises.push(this.scheduleReconcile(state, entry));
+    touch(shape, now) {
+        shape.accessedAt = now;
+        if (!shape.observed)
+            shape.releasedAt = now;
+    }
+    sweepEntities() {
+        const nodes = new Set();
+        const edges = new Set();
+        for (const shape of this.shapes.values()) {
+            shape.references?.nodes.forEach((id) => nodes.add(id));
+            shape.references?.edges.forEach((key) => edges.add(key));
         }
-        return promises;
+        this.entities.sweep(nodes, edges);
     }
-    /** Build a wire patch from a manual overlay builder callback. */
-    buildPatch(build) {
-        const b = new PatchBuilderImpl();
-        build(b);
-        return b.build();
+    close(error) {
+        for (const shape of this.shapes.values()) {
+            shape.listeners.clear();
+            shape.inflight?.catch(() => undefined);
+        }
+        this.shapes.clear();
+        this.entities.clear();
+        this.overlay.clear();
+        while (this.pending.length > 0)
+            this.pending.shift()?.reject(error);
+    }
+    materialize(template, references) {
+        return Object.freeze({
+            result: this.materializeResult(template.result, references),
+            page: template.page,
+        });
     }
-    /**
-     * Open a manual display overlay decoupled from any dispatch (§1.6). The caller
-     * dispatches its own call (e.g. a domain method) and then `commit`s (reconcile
-     * the touched shapes from the server, drop the display) or `rollback`s.
-     */
-    openOverlay(scope, build) {
-        const state = this.state(scope);
-        const display = this.displayArms(state, normalizePatch(this.buildPatch(build)));
-        const txn = display.has ? this.beginOverlay(state, display.patch) : null;
-        let settled = false;
-        return {
-            commit: (_result) => {
-                if (settled)
-                    return;
-                settled = true;
-                for (const part of this.partitionsOf(scope))
-                    part.epoch++;
-                if (txn === null)
-                    return;
-                const promises = [];
-                for (const entry of txn.affected) {
-                    entry.stale = true;
-                    this.notify(entry);
-                    if (entry.observers > 0)
-                        promises.push(this.scheduleReconcile(state, entry));
+    materializeResult(template, references) {
+        if (template.kind === 'nodes') {
+            const nodes = [];
+            for (const projection of template.nodes) {
+                if (projection.kind === 'reference') {
+                    nodes.push(projection);
+                    continue;
                 }
-                void Promise.allSettled(promises).then(() => this.dropOverlay(state, txn));
-            },
-            rollback: () => {
-                if (settled)
-                    return;
-                settled = true;
-                if (txn !== null)
-                    this.rollbackOverlay(state, txn);
-            },
-        };
-    }
-    classOf(state, node) {
-        if (isNodeValue(node))
-            return rawOf(node.class);
-        const id = state.entities.resolvePathToId(rawOf(node));
-        const cls = id !== undefined ? state.entities.node(id)?.wire.class : undefined;
-        if (cls === undefined) {
-            throw new Error(`memory: cannot resolve the class of "${rawOf(node)}" for a write — ` +
-                'pass the Node value (not a bare path) for a node not yet in the memory.');
+                const node = this.overlay.node(projection.value.id, this.entities);
+                if (node !== undefined)
+                    nodes.push(Object.freeze({ kind: 'value', value: node }));
+            }
+            return Object.freeze({
+                kind: 'nodes',
+                nodes: Object.freeze(nodes),
+            });
         }
-        return cls;
-    }
-    // ── GC / dev invariants ──────────────────────────────────────────────────────
-    /** Amortized housekeeping — sweep GC every `sweepEvery` ops (§5.7, no binding trust). */
-    tick() {
-        if (++this.opCount % this.sweepEvery === 0)
-            this.sweep();
-    }
-    sweep() {
-        const now = this.now();
-        for (const state of this.scopes.values()) {
-            const expired = [];
-            for (const entry of state.shapes.all()) {
-                if (entry.observers === 0 &&
-                    entry.releasedAt !== null &&
-                    now - entry.releasedAt > this.ttlMs) {
-                    expired.push(entry);
+        if (template.kind === 'edges') {
+            const edges = [];
+            for (const item of template.edges) {
+                const edge = item.edge.kind === 'reference'
+                    ? item.edge
+                    : (() => {
+                        const value = this.entities.edge(edgeIdentity(item.edge.value));
+                        return value === undefined
+                            ? undefined
+                            : Object.freeze({ kind: 'value', value });
+                    })();
+                const source = item.source.kind === 'reference'
+                    ? item.source
+                    : (() => {
+                        const value = this.overlay.node(item.source.value.id, this.entities);
+                        return value === undefined
+                            ? undefined
+                            : Object.freeze({ kind: 'value', value });
+                    })();
+                const target = item.target.kind === 'reference'
+                    ? item.target
+                    : (() => {
+                        const value = this.overlay.node(item.target.value.id, this.entities);
+                        return value === undefined
+                            ? undefined
+                            : Object.freeze({ kind: 'value', value });
+                    })();
+                if (edge !== undefined && source !== undefined && target !== undefined) {
+                    edges.push(Object.freeze({ edge, source, target }));
                 }
             }
-            for (const entry of expired)
-                state.shapes.delete(entry);
-            const reach = state.shapes.reachable();
-            state.entities.gc(reach.nodes, reach.edges, now, this.tombstoneTtlMs);
+            return Object.freeze({
+                kind: 'edges',
+                edges: Object.freeze(edges),
+            });
         }
-    }
-    /**
-     * Dev-mode invariants after a notify batch (§5.7 loudness): no optimistic id
-     * survives in SETTLED confirmed membership, every settled membership id
-     * resolves in the entity store, and listener count == observer count. Off by
-     * default; violations surface on the event channel as `{ kind: 'invariant' }`.
-     */
-    audit(state) {
-        if (!this.dev)
+        const nodes = references.nodes
+            .map((id) => this.overlay.node(id, this.entities))
+            .filter((node) => node !== undefined);
+        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));
+        const graph = Object.freeze({ nodes: Object.freeze(nodes), edges: Object.freeze(edges) });
+        const selection = materializeSelection(template.selection, visibleNodeIds, edges);
+        return selection.kind === 'node'
+            ? Object.freeze({ kind: 'graph', graph, selection })
+            : Object.freeze({ kind: 'graph', graph, selection });
+    }
+    publish(shape, state, error) {
+        const next = snapshotFor(state, shape.response, error);
+        if (sameSnapshot(shape.snapshot, next))
             return;
-        for (const entry of state.shapes.all()) {
-            if (entry.listeners.size !== entry.observers) {
-                this.emit({
-                    kind: 'invariant',
-                    shape: entry.key,
-                    detail: `listeners ${entry.listeners.size} != observers ${entry.observers}`,
-                });
-            }
-            if (entry.inflight !== null)
-                continue; // only settled shapes are checked
-            for (const id of entry.nodeMembers) {
-                if (String(id).startsWith('optimistic:')) {
-                    this.emit({
-                        kind: 'invariant',
-                        shape: entry.key,
-                        detail: `optimistic id ${id} in membership`,
-                    });
-                }
+        shape.state = state;
+        shape.snapshot = next;
+        for (const listener of Array.from(shape.listeners)) {
+            try {
+                listener();
             }
-            if (state.overlay.size === 0) {
-                for (const id of entry.nodeMembers) {
-                    if (state.entities.node(id) === undefined && !state.entities.isNodeTombstoned(id)) {
-                        this.emit({
-                            kind: 'invariant',
-                            shape: entry.key,
-                            detail: `dangling membership id ${id}`,
-                        });
-                    }
-                }
+            catch (error) {
+                this.report(error);
             }
         }
     }
-    emit(event) {
-        this.onError?.(event);
+    schedule(task) {
+        return new Promise((resolve, reject) => {
+            const run = () => {
+                this.active += 1;
+                void task()
+                    .then(resolve, reject)
+                    .finally(() => {
+                    this.active -= 1;
+                    this.drain();
+                });
+            };
+            this.pending.push({ run, reject });
+            this.drain();
+        });
+    }
+    drain() {
+        while (this.active < this.options.concurrency && this.pending.length > 0) {
+            this.pending.shift().run();
+        }
+    }
+    report(error) {
+        try {
+            this.options.onError?.(error);
+        }
+        catch {
+            // Error observers cannot replace the operation's public outcome.
+        }
     }
 }
-// ── COLD placeholder (render-pure getSnapshot) ─────────────────────────────────
-/**
- * The stable snapshot a cold shape returns from `getSnapshot` (§5.7). One frozen
- * value shared across all cold shapes so useSyncExternalStore never tears on a
- * fresh object; subscribe/query create the real entry, after which snapshots are
- * per-entry and memoized.
- */
-const COLD = Object.freeze({
-    graph: Graph.fromWire({ nodes: [], edges: [] }),
-    roots: [],
-    nodes: [],
-    first: null,
-    node: null,
-    children: [],
-    gathered: () => ({ nodes: [], first: null }),
-    pending: false,
-    stale: false,
-    error: undefined,
-    live: false,
-    seq: 0,
-    more: Object.freeze({ has: false, pending: false, load: async () => { } }),
-    refetch: async () => { },
-});
-// ── ref helpers ────────────────────────────────────────────────────────────────
-function firstKey(entries) {
-    for (const e of entries)
-        return e.key;
-    return '';
-}
-function isNodeValue(x) {
-    return typeof x === 'object' && x !== null && 'id' in x && 'class' in x && 'path' in x;
-}
-function refPathRaw(x) {
-    return isNodeValue(x) ? rawOf(x.path) : rawOf(x);
-}
-function rawIdentity(edge) {
-    return {
-        class: rawOf(edge.class),
-        source: rawOf(edge.source),
-        ...(edge.slug !== undefined ? { slug: edge.slug } : {}),
-        target: rawOf(edge.target),
-    };
+function materializeSelection(selection, visibleNodes, visibleEdges) {
+    if (selection.kind === 'node') {
+        return Object.freeze({
+            kind: selection.kind,
+            ids: Object.freeze(selection.ids.filter((id) => visibleNodes.has(id))),
+        });
+    }
+    const edges = new Set(visibleEdges.map(encodeEdgeKey));
+    return Object.freeze({
+        kind: selection.kind,
+        keys: Object.freeze(selection.keys.filter((key) => edges.has(encodeEdgeKey(key)))),
+    });
 }
-function patchHasOperations(patch) {
-    return (patch.nodes.create.length > 0 ||
-        patch.nodes.update.length > 0 ||
-        patch.nodes.delete.length > 0 ||
-        patch.edges.create.length > 0 ||
-        patch.edges.update.length > 0 ||
-        patch.edges.delete.length > 0);
+function queryOptions(page, lifecycle) {
+    return Object.freeze({
+        signal: lifecycle,
+        page,
+    });
 }
-/**
- * Fold the accumulated window into a reconcile AST (§5.7): each paged expand's
- * limit grows to `baseLimit × windowPages`, so a post-write refetch re-requests
- * everything the window had scrolled to instead of collapsing to page 1. An
- * unbounded (no-limit) expand already covers its whole selection — left as is.
- */
-function windowAst(base, pages) {
-    if (pages <= 1 || base.steps === undefined)
-        return base;
-    const steps = base.steps.map((step) => {
-        if (!('expand' in step))
-            return step;
-        const limit = step.expand.page?.limit;
-        if (limit === undefined)
-            return step;
-        return { expand: { ...step.expand, page: { ...step.expand.page, limit: limit * pages } } };
+function observeRead(pending, options, lifecycle) {
+    try {
+        requireReadLive(options.signal, lifecycle);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return new Promise((resolve, reject) => {
+        let timeout;
+        const callerCancelled = () => settleReject(cancellation(options.signal.reason));
+        const storeClosed = () => settleReject(cancellation(lifecycle.reason));
+        let settled = false;
+        const cleanup = () => {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            options.signal?.removeEventListener('abort', callerCancelled);
+            lifecycle.removeEventListener('abort', storeClosed);
+        };
+        const settleResolve = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(result);
+        };
+        function settleReject(error) {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        }
+        options.signal?.addEventListener('abort', callerCancelled, { once: true });
+        lifecycle.addEventListener('abort', storeClosed, { once: true });
+        if (options.timeoutMs !== undefined) {
+            timeout = setTimeout(() => settleReject(new ClientError('Store read timed out.')), options.timeoutMs);
+        }
+        void pending.then(settleResolve, settleReject);
     });
-    return { ...base, steps };
 }
-// ── prop-key canonicalization ────────────────────────────────────────────────
-/** A fully-qualified prop key carries both a domain origin (`:`) and `.property.`. */
-function isQualifiedKey(key) {
-    return key.includes(':') && key.includes('.property.');
+function requireReadLive(signal, lifecycle) {
+    if (lifecycle.aborted)
+        throw cancellation(lifecycle.reason);
+    if (signal?.aborted === true)
+        throw cancellation(signal.reason);
 }
-/** The prop leaf — the final dot-segment (`title` from `…​.property.title`, or a bare key). */
-function leafOf(key) {
-    return key.slice(key.lastIndexOf('.') + 1);
+function cancellation(reason) {
+    return reason instanceof Error
+        ? reason
+        : new ClientError('Store read was cancelled.', { cause: reason });
 }
-/**
- * Rewrite non-qualified write keys to the fully-qualified key the reference node
- * already carries with the same leaf. A key with NO match, or with MORE THAN ONE
- * match (two qualified keys sharing a leaf — ambiguous, never first-match-wins,
- * §5.7 7a), passes through and flags `unresolved` so the write is reconcile-only
- * rather than mispredicted.
- */
-function qualifyKeys(props, ref) {
-    let unresolved = false;
-    const out = {};
-    for (const [k, v] of Object.entries(props)) {
-        if (isQualifiedKey(k)) {
-            out[k] = v;
-            continue;
-        }
-        const leaf = leafOf(k);
-        const matches = ref !== undefined
-            ? Object.keys(ref).filter((rk) => isQualifiedKey(rk) && leafOf(rk) === leaf)
-            : [];
-        if (matches.length === 1)
-            out[matches[0]] = v;
-        else {
-            out[k] = v;
-            unresolved = true; // 0 matches OR >1 (ambiguous) → reconcile, don't guess
+function snapshotFor(state, response, error) {
+    switch (state) {
+        case 'cold':
+            return Object.freeze({ state });
+        case 'loading':
+            return Object.freeze({ state });
+        case 'failed':
+            return Object.freeze({ state, error, ...(response === undefined ? {} : { response }) });
+        case 'ready':
+        case 'stale':
+        case 'refreshing':
+        case 'optimistic':
+            if (response === undefined)
+                throw new TypeError(`Store ${state} snapshot requires a response.`);
+            return Object.freeze({ state, response });
+    }
+}
+function sameSnapshot(left, right) {
+    if (left.state !== right.state)
+        return false;
+    if ('response' in left || 'response' in right) {
+        if (!('response' in left) || !('response' in right) || left.response !== right.response) {
+            return false;
         }
     }
-    return { props: out, unresolved };
+    return left.state !== 'failed' || right.state !== 'failed' || left.error === right.error;
 }
-//# sourceMappingURL=memory.js.map