foottrace 0.0.0-stage → 1.0.0

package/dist/lib/memory/logModel.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * logModel.ts — the read model of ONE commit log: the writer rule and the value rule of `keyPaths.ts`,
+ * answered at a cost proportional to the answer, not to the log (F3, 9.33.0).
+ *
+ * WHY THIS FILE EXISTS. The rules are simple to state and expensive to apply naively: a key's writers
+ * include the commits AROUND it whose change reached it, and deciding that needs the value at the key
+ * before and after such a commit — a fold of its top-level key. Folding once per KEY made a causal walk
+ * over nested keys cubic in the log (every key re-scanned the log and re-folded its root). Here:
+ *
+ *   - the log is indexed ONCE (`keyPaths · buildWriterIndex`, a path trie): a key's candidates cost
+ *     O(depth + matches) — its node, its ancestors, its subtree — and the rows under a top-level key are
+ *     reached through the index, never a scan;
+ *   - each top-level key is folded ONCE (`verbs · foldKey`, copy-on-write), keeping its value before and
+ *     after every commit a verdict can ask about: a commit with a row on a path that has written paths
+ *     below it (it can be AROUND a written key), and a commit that writes THROUGH a string-valued
+ *     container (`nativeSet` replaces the string, and the characters a key read from it vanish — the one
+ *     way a row BESIDE a key moves it). A key's verdict is then two `nativeGet`s and a `deepEqual`;
+ *   - the last writer before a point is found LAZILY: the last write on or inside the key, then only the
+ *     around-candidates after it — most questions need no verdict at all.
+ *
+ * One shape keeps a per-key fold (memoised per key): a key that was never written, under a container that
+ * was only ever written WHOLE (its node has no written children, so no generation is kept there).
+ *
+ * A model of a FROZEN log (every engine log since F3: `EventLog · record` freezes each bundle and
+ * `getSnapshot` freezes the array) is memoised on the log — the record cannot change under it. A log that
+ * is not frozen (hand-built, parsed from JSON) gets a fresh model per question.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogModel = exports.leavesStringAbove = exports.writesAtOrInside = exports.memoisedModel = exports.logModel = void 0;
+const equality_js_1 = require("./equality.js");
+const keyPaths_js_1 = require("./keyPaths.js");
+const pathOps_js_1 = require("./pathOps.js");
+const paths_js_1 = require("./paths.js");
+const verbs_js_1 = require("./verbs.js");
+const MODELS = new WeakMap();
+/** Is the log immutable — the array and every bundle and trace frozen (an engine snapshot's log)? */
+function isFrozenLog(log) {
+    if (!Object.isFrozen(log))
+        return false;
+    // The shape `EventLog · record` leaves: the bundle, its payloads and its rows. A hand-built log
+    // frozen less deeply than that could change after a query, so it is never memoised.
+    for (const bundle of log) {
+        if (!Object.isFrozen(bundle) || !Object.isFrozen(bundle.trace))
+            return false;
+        if (!Object.isFrozen(bundle.overwrite) || !Object.isFrozen(bundle.updates))
+            return false;
+        if (!bundle.trace.every((row) => Object.isFrozen(row)))
+            return false;
+    }
+    return true;
+}
+/** The read model of `log` — memoised when the log is frozen, fresh otherwise. */
+function logModel(log) {
+    const memo = MODELS.get(log);
+    if (memo !== undefined)
+        return memo;
+    const model = new LogModel(log);
+    if (isFrozenLog(log))
+        MODELS.set(log, model);
+    return model;
+}
+exports.logModel = logModel;
+/** The memoised model of a frozen log (built on first ask), or undefined for a log that is not frozen. */
+function memoisedModel(log) {
+    return MODELS.get(log) ?? (isFrozenLog(log) ? logModel(log) : undefined);
+}
+exports.memoisedModel = memoisedModel;
+/** Does the commit hold a non-`delete` row on `key` or inside it? (A `delete` cannot replace a string container.) */
+function writesAtOrInside(bundle, key) {
+    for (const t of bundle.trace) {
+        if (t.verb === 'delete')
+            continue;
+        const r = (0, keyPaths_js_1.relation)(t.path, key);
+        if (r === 'exact' || r === 'inside')
+            return true;
+    }
+    return false;
+}
+exports.writesAtOrInside = writesAtOrInside;
+/**
+ * Can this commit leave a STRING-valued container above `key` — a row around the key whose recorded value
+ * holds a string at the row's path or anywhere between it and the key? Only then can a later write beside the
+ * key move it (`nativeSet` replaces the string). A conservative, payload-only check: no fold.
+ */
+function leavesStringAbove(bundle, key) {
+    const keySegs = key.split(paths_js_1.DELIM);
+    for (const t of bundle.trace) {
+        if (t.verb === 'delete' || (0, keyPaths_js_1.relation)(t.path, key) !== 'around')
+            continue;
+        const segs = t.path.split(paths_js_1.DELIM);
+        let value = (0, pathOps_js_1.nativeGet)(t.verb === 'merge' ? bundle.updates : bundle.overwrite, segs);
+        for (let depth = segs.length; depth < keySegs.length; depth++) {
+            if (typeof value === 'string')
+                return true;
+            if (value === null || typeof value !== 'object')
+                break;
+            value = (0, pathOps_js_1.nativeGet)(value, [keySegs[depth]]);
+        }
+    }
+    return false;
+}
+exports.leavesStringAbove = leavesStringAbove;
+class LogModel {
+    log;
+    index;
+    roots = new Map();
+    histories = new Map();
+    changesByKey = new Map();
+    writersByKey = new Map();
+    constructor(log) {
+        this.log = log;
+        this.index = (0, keyPaths_js_1.buildWriterIndex)(log);
+        for (const bundle of log)
+            keyPaths_js_1.queryWork.units += bundle.trace.length;
+    }
+    // ── rows ─────────────────────────────────────────────────────────────────
+    rootRows(root) {
+        let entry = this.roots.get(root);
+        if (entry !== undefined)
+            return entry;
+        const node = this.index.roots.get(root);
+        const rows = [];
+        let refused;
+        let refusedAt = Number.POSITIVE_INFINITY;
+        if (node !== undefined) {
+            for (const c of (0, keyPaths_js_1.subtreePositions)(node)) {
+                const trace = this.log[c].trace;
+                keyPaths_js_1.queryWork.units += trace.length;
+                for (let row = 0; row < trace.length && refused === undefined; row++) {
+                    const { path, verb } = trace[row];
+                    if (path !== root && (0, keyPaths_js_1.relation)(path, root) !== 'inside')
+                        continue;
+                    if (!(0, verbs_js_1.isVerb)(verb)) {
+                        refused = new verbs_js_1.UnknownVerbError(verb, { path, row, commit: c });
+                        refusedAt = c;
+                        // the refused commit and everything after it are left out: an answer that reaches them is refused
+                        while (rows.length > 0 && rows[rows.length - 1].commitIdx === c)
+                            rows.pop();
+                    }
+                    else
+                        rows.push({ verb, bundle: this.log[c], commitIdx: c, path });
+                }
+                if (refused !== undefined)
+                    break;
+            }
+        }
+        entry = { rows, ...(refused !== undefined && { refused }), refusedAt };
+        this.roots.set(root, entry);
+        return entry;
+    }
+    /** Refuse an answer that reaches a row whose verb the law does not know (one in commits `after` < c ≤ `end`). */
+    refuseThrough(root, end, after = -1) {
+        const rr = this.rootRows(root);
+        if (rr.refused !== undefined && rr.refusedAt <= end && rr.refusedAt > after)
+            throw rr.refused;
+        return rr;
+    }
+    /** Every row under `key`'s top-level key up to `end`, with its relation to `key` — through the index. */
+    rowsUnderRoot(key, end) {
+        const rr = this.refuseThrough((0, keyPaths_js_1.rootOf)(key), end);
+        const out = [];
+        for (const t of rr.rows) {
+            if (t.commitIdx > end)
+                break;
+            const r = (0, keyPaths_js_1.relation)(t.path, key);
+            out.push(r === undefined ? t : { ...t, relation: r });
+        }
+        return out;
+    }
+    // ── the root fold, once per top-level key ───────────────────────────────
+    history(root) {
+        let h = this.histories.get(root);
+        if (h !== undefined)
+            return h;
+        const kept = new Map();
+        const replaced = new Map();
+        const rr = this.rootRows(root);
+        keyPaths_js_1.queryWork.units += rr.rows.length;
+        (0, verbs_js_1.foldKey)(rr.rows, [root], {
+            generations: {
+                at: (c, state) => {
+                    let keep = false;
+                    keyPaths_js_1.queryWork.units += this.log[c].trace.length;
+                    for (const t of this.log[c].trace) {
+                        if (t.path !== root && (0, keyPaths_js_1.relation)(t.path, root) !== 'inside')
+                            continue;
+                        if (((0, keyPaths_js_1.nodeAt)(this.index, t.path)?.children.size ?? 0) > 0)
+                            keep = true;
+                        const segs = t.path.split(paths_js_1.DELIM);
+                        for (let j = 1; j < segs.length; j++) {
+                            if (typeof (0, pathOps_js_1.nativeGet)(state, segs.slice(0, j)) !== 'string')
+                                continue;
+                            const container = (0, keyPaths_js_1.nodeAt)(this.index, segs.slice(0, j).join(paths_js_1.DELIM));
+                            if (container !== undefined) {
+                                const list = replaced.get(container) ?? [];
+                                if (list[list.length - 1] !== c)
+                                    list.push(c);
+                                replaced.set(container, list);
+                            }
+                            keep = true;
+                        }
+                    }
+                    return keep;
+                },
+                keep: (c, before, after) => {
+                    kept.set(c, { before, after });
+                },
+            },
+        });
+        h = { kept, keptAt: [...kept.keys()].sort((a, b) => a - b), replaced };
+        this.histories.set(root, h);
+        return h;
+    }
+    /** A key never written, under a container only ever written whole: no generation is kept for it. */
+    needsOwnFold(key, ancestors) {
+        return (0, keyPaths_js_1.nodeAt)(this.index, key) === undefined && ancestors[ancestors.length - 1].children.size === 0;
+    }
+    /** Every commit across which the value at `key` changed — one fold for this key (the fallback shape). */
+    ownChanges(key) {
+        let changes = this.changesByKey.get(key);
+        if (changes !== undefined)
+            return changes;
+        const segs = key.split(paths_js_1.DELIM);
+        const verdict = new Map();
+        let commit = -1;
+        let start;
+        keyPaths_js_1.queryWork.units += this.rootRows(segs[0]).rows.length;
+        (0, verbs_js_1.foldKey)(this.rootRows(segs[0]).rows, segs, {
+            everyRow: true,
+            observe: (touch, before, after) => {
+                if (touch.commitIdx !== commit) {
+                    commit = touch.commitIdx;
+                    start = before;
+                }
+                verdict.set(commit, !(0, equality_js_1.deepEqual)(start, after, 'copies'));
+            },
+        });
+        changes = [...verdict].filter(([, changed]) => changed).map(([c]) => c);
+        this.changesByKey.set(key, changes);
+        return changes;
+    }
+    /**
+     * The commits in the OPEN range (`after`, `before`) with no row on or inside `key` across which the value
+     * at `key` changed — the AROUND half of the writer rule (and the string-container case beside it).
+     */
+    changedAround(key, after, before) {
+        const ancestors = (0, keyPaths_js_1.ancestorNodes)(this.index, key);
+        if (ancestors.length === 0 || ancestors.every((a) => a.positions.length === 0))
+            return [];
+        const root = ancestors[0].path;
+        // The answer reads the rows of the window: refuse it when one of them is a verb the law does not know.
+        this.refuseThrough(root, before - 1, after);
+        if (this.needsOwnFold(key, ancestors))
+            return (0, keyPaths_js_1.between)(this.ownChanges(key), after, before);
+        const h = this.history(root);
+        const candidates = (0, keyPaths_js_1.ascendingUnion)([
+            ...ancestors.map((a) => (0, keyPaths_js_1.between)(a.positions, after, before)),
+            ...ancestors.map((a) => (0, keyPaths_js_1.between)(h.replaced.get(a) ?? [], after, before)),
+        ]);
+        const rest = key.split(paths_js_1.DELIM).slice(1);
+        keyPaths_js_1.queryWork.units += candidates.length;
+        return candidates.filter((c) => {
+            const g = h.kept.get(c);
+            return g !== undefined && !(0, equality_js_1.deepEqual)((0, pathOps_js_1.nativeGet)(g.before, rest), (0, pathOps_js_1.nativeGet)(g.after, rest), 'copies');
+        });
+    }
+    // ── the writer rule ──────────────────────────────────────────────────────
+    /** Every commit that WROTE `key`, ascending (memoised per key). */
+    writersOf(key) {
+        let writers = this.writersByKey.get(key);
+        if (writers !== undefined)
+            return writers;
+        const node = (0, keyPaths_js_1.nodeAt)(this.index, key);
+        const atOrInside = node === undefined ? [] : (0, keyPaths_js_1.subtreePositions)(node);
+        const around = this.changedAround(key, -1, Number.POSITIVE_INFINITY);
+        writers = around.length === 0 ? atOrInside.slice() : (0, keyPaths_js_1.ascendingUnion)([atOrInside, around]);
+        this.writersByKey.set(key, writers);
+        return writers;
+    }
+    /** The ARRAY position of the last commit before `before` that wrote `key`, or -1. */
+    lastWriterBefore(key, before) {
+        keyPaths_js_1.queryWork.units += 1;
+        const node = (0, keyPaths_js_1.nodeAt)(this.index, key);
+        const lastAI = node === undefined ? -1 : (0, keyPaths_js_1.lastBefore)((0, keyPaths_js_1.subtreePositions)(node), before);
+        const ancestors = (0, keyPaths_js_1.ancestorNodes)(this.index, key);
+        keyPaths_js_1.queryWork.units += ancestors.length; // the scans over them below
+        if (ancestors.length === 0)
+            return lastAI;
+        // A row around the key in the last write's OWN commit counts when it can leave a string container above
+        // the key (a later write beside the key then replaces it).
+        const aroundInWindow = ancestors.some((a) => (0, keyPaths_js_1.between)(a.positions, lastAI, before).length > 0) ||
+            (lastAI !== -1 && leavesStringAbove(this.log[lastAI], key));
+        // A `delete` cannot replace a string container, so a character read through one can still move after it.
+        const deleteOnly = lastAI !== -1 && !writesAtOrInside(this.log[lastAI], key);
+        if (!aroundInWindow && !(deleteOnly && ancestors.some((a) => a.positions.length > 0)))
+            return lastAI;
+        const changed = this.changedAround(key, lastAI, before);
+        return changed.length > 0 ? changed[changed.length - 1] : lastAI;
+    }
+    // ── the value rule ───────────────────────────────────────────────────────
+    /**
+     * The value of `key` after commit `idx` (inclusive). The fold of the rows under its top-level key — but
+     * when its last total row up to `idx` is a `set` ON the key and nothing around it was written since, only
+     * the rows on and inside the key from that `set` on can move it, and only they are folded.
+     */
+    valueAt(key, idx) {
+        const segs = key.split(paths_js_1.DELIM);
+        this.refuseThrough(segs[0], idx);
+        const node = (0, keyPaths_js_1.nodeAt)(this.index, key);
+        const ancestors = (0, keyPaths_js_1.ancestorNodes)(this.index, key);
+        if (node === undefined && ancestors.length === 0)
+            return undefined;
+        if (node !== undefined) {
+            const anchor = (0, keyPaths_js_1.lastBefore)(node.totals, idx + 1);
+            if (anchor !== -1 &&
+                lastTotalIsSet(this.log[anchor], key) &&
+                ancestors.every((a) => (0, keyPaths_js_1.between)(a.positions, anchor - 1, idx + 1).length === 0)) {
+                const rows = [];
+                for (const c of (0, keyPaths_js_1.between)((0, keyPaths_js_1.subtreePositions)(node), anchor - 1, idx + 1)) {
+                    const trace = this.log[c].trace;
+                    for (let row = 0; row < trace.length; row++) {
+                        const r = (0, keyPaths_js_1.relation)(trace[row].path, key);
+                        if (r === 'exact' || r === 'inside') {
+                            rows.push({
+                                verb: trace[row].verb,
+                                bundle: this.log[c],
+                                commitIdx: c,
+                                path: trace[row].path,
+                                relation: r,
+                            });
+                        }
+                    }
+                }
+                keyPaths_js_1.queryWork.units += rows.length;
+                return (0, verbs_js_1.foldKey)(rows, segs);
+            }
+        }
+        const rows = this.rowsUnderRoot(key, idx);
+        keyPaths_js_1.queryWork.units += rows.length;
+        if (!rows.some((row) => row.relation !== undefined))
+            return undefined;
+        // A memoised model folds from the last generation it keeps at or before `idx` — the rows after it only.
+        if (MODELS.get(this.log) === this) {
+            const h = this.history(segs[0]);
+            const kept = (0, keyPaths_js_1.lastBefore)(h.keptAt, idx + 1);
+            if (kept !== -1) {
+                const after = rows.filter((row) => row.commitIdx > kept);
+                // Folded FROM the kept generation, the answer can BE it (no row after it) or share its parts, and
+                // the memo answers every later question: detach it, as the value rule promises (until 9.44.2 an
+                // edit of one answer changed the next).
+                return detached((0, verbs_js_1.foldKey)(after, segs, { anchored: true, start: h.kept.get(kept)?.after }));
+            }
+        }
+        return (0, verbs_js_1.foldKey)(rows, segs, { anchored: true });
+    }
+}
+exports.LogModel = LogModel;
+/** A value the caller owns: a container is cloned, a primitive is itself. */
+function detached(value) {
+    return value !== null && typeof value === 'object' ? structuredClone(value) : value;
+}
+/** Is the last `set` / `delete` row ON `key` in this commit a `set`? */
+function lastTotalIsSet(bundle, key) {
+    for (let i = bundle.trace.length - 1; i >= 0; i--) {
+        const t = bundle.trace[i];
+        if (t.path === key && (t.verb === 'set' || t.verb === 'delete'))
+            return t.verb === 'set';
+    }
+    return false;
+}

package/dist/lib/memory/merge.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * merge.ts — the union merge the `merge` verb applies. A leaf (L0, imports
+ * only the own-slot writer): `deepSmartMerge`, the law every replay, fold and reader
+ * of a recorded `merge` row runs. Re-exported from `utils.ts`, so no importer
+ * moved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepSmartMerge = void 0;
+const ownData_js_1 = require("../capture/ownData.js");
+/**
+ * Deep union merge helper.
+ * - Arrays (non-empty): union without duplicates (encounter order preserved)
+ * - Arrays (empty):     replace — src `[]` clears the destination array.
+ *   Rationale: writing `scope.tags = []` means "clear tags", not "append nothing".
+ *   Without this rule, an empty-array write silently becomes a no-op which is
+ *   impossible to distinguish from a bug.
+ * - Objects: recursive merge of own enumerable string keys, including special keys;
+ *   inherited destination values and setters never participate.
+ * - Primitives: source wins
+ *
+ * Terminates on a CYCLIC `src` (9.18.1, same law as {@link deepEqual}: a
+ * state value survives `structuredClone`, which preserves cycles). A `src`
+ * object re-entered while it is still being merged higher up the stack hands
+ * back the output being built for it, so the merged value mirrors the cycle
+ * instead of unrolling it forever. Only the ancestors on the stack are
+ * guarded — a shared (acyclic) `src` reference met again at a different
+ * `dst` merges against THAT `dst`, exactly as before.
+ */
+function deepSmartMerge(dst, src) {
+    return mergeGuarded(dst, src, undefined);
+}
+exports.deepSmartMerge = deepSmartMerge;
+function mergeGuarded(dst, src, inFlight) {
+    if (src === null || typeof src !== 'object')
+        return src;
+    if (Array.isArray(src)) {
+        if (src.length === 0)
+            return []; // empty src = clear, not no-op
+        if (Array.isArray(dst))
+            return [...new Set([...dst, ...src])];
+        return [...src];
+    }
+    if (inFlight?.has(src))
+        return inFlight.get(src); // cycle — re-enter the value being built
+    const out = { ...(dst && typeof dst === 'object' ? dst : {}) };
+    (inFlight ??= new WeakMap()).set(src, out);
+    for (const k of Object.keys(src)) {
+        const owns = Object.prototype.hasOwnProperty.call(out, k);
+        const value = mergeGuarded(owns ? out[k] : undefined, src[k], inFlight);
+        (0, ownData_js_1.putOwn)(out, k, value);
+    }
+    inFlight.delete(src);
+    return out;
+}