@astrale-os/kernel-client 0.2.3 → 0.3.0

package/dist/store/memory.js

@@ -0,0 +1,790 @@
+/**
+ * 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';
+import { mintedId, PatchBuilderImpl } from '../graph/mutate';
+import { HAS_PARENT_CLASS } from '../graph/query/edges';
+import { shapeInputToAST, shapeKey, stripCursors } from './canonicalize';
+import { EntityStore } from './entities';
+import { affectedShapes } from './invalidate';
+import { normalizePatch, Overlay } from './overlay';
+import { TaskQueue } from './schedule';
+import { integrateShape, materialize, ShapeStore, shapeViewOf } from './shapes';
+/** 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),
+            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);
+        }
+        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);
+        }
+        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',
+            };
+        }
+        // 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);
+            }
+            this.notify(live);
+            this.audit(state);
+            return wire;
+        })
+            .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);
+            throw error;
+        });
+        entry.inflight = p;
+        entry.dirty = true;
+        this.notify(entry);
+        return p;
+    }
+    /** 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 (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
+            },
+        };
+        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 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;
+        }
+    }
+    /**
+     * 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 });
+        }
+        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);
+    }
+    /**
+     * 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);
+        }
+        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);
+    }
+    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)
+                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;
+                }
+            }
+        }
+        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' });
+            }
+        }
+    }
+    /** 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)));
+    }
+    /**
+     * 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));
+        }
+        return promises;
+    }
+    /** Build a wire patch from a manual overlay builder callback. */
+    buildPatch(build) {
+        const b = new PatchBuilderImpl();
+        build(b);
+        return b.build();
+    }
+    /**
+     * 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));
+                }
+                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.');
+        }
+        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);
+                }
+            }
+            for (const entry of expired)
+                state.shapes.delete(entry);
+            const reach = state.shapes.reachable();
+            state.entities.gc(reach.nodes, reach.edges, now, this.tombstoneTtlMs);
+        }
+    }
+    /**
+     * 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)
+            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`,
+                    });
+                }
+            }
+            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}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    emit(event) {
+        this.onError?.(event);
+    }
+}
+// ── 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),
+    };
+}
+/**
+ * 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 } } };
+    });
+    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.');
+}
+/** The prop leaf — the final dot-segment (`title` from `…​.property.title`, or a bare key). */
+function leafOf(key) {
+    return key.slice(key.lastIndexOf('.') + 1);
+}
+/**
+ * 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
+        }
+    }
+    return { props: out, unresolved };
+}
+//# sourceMappingURL=memory.js.map