@indigoai-us/hq-cloud 6.18.44-alpha.8 → 6.18.44

package/dist/sync/area-ledger.test.js

@@ -1,1401 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { spawn } from "node:child_process";
-import { once } from "node:events";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { MAX_PULLS_PER_COMPANY } from "../journal.js";
-import { AreaLedger, UNROUTED_AREA_ID, setAreaLedgerTestHooksForTest } from "./area-ledger.js";
-import { StateStore, setStateStoreWalRecordReadHookForTest } from "./state-store.js";
-import { JournalRowOverlay, JournalRowStore } from "../journal-row-store.js";
-import { forgetSharedAreaJournalRows } from "../journal-snapshot-rows.js";
-const roots = [];
-afterEach(() => {
-    setAreaLedgerTestHooksForTest(undefined);
-    setStateStoreWalRecordReadHookForTest(undefined);
-    // Vitest 4 returns an existing mock when a later case spies on the same
-    // method. Restore every case's prototype spies so their call history cannot
-    // cross the cache-performance assertions below.
-    vi.restoreAllMocks();
-    for (const root of roots.splice(0))
-        fs.rmSync(root, { recursive: true, force: true });
-});
-function entry(size) {
-    return {
-        hash: `${size}`.repeat(64),
-        size,
-        syncedAt: "2026-08-27T00:00:00.000Z",
-        direction: "up",
-    };
-}
-function pullRecord(index) {
-    const completedAt = new Date(Date.UTC(2026, 4, 20, 0, 0, 0, index)).toISOString();
-    return {
-        pullId: `pull-${String(index).padStart(3, "0")}`,
-        companyUid: "cmp_indigo",
-        startedAt: completedAt,
-        completedAt,
-        syncMode: "all",
-        prefixSet: [],
-        scopeChangeDetected: false,
-        orphansRemoved: 0,
-        orphansBlocked: 0,
-    };
-}
-function makeRoot() {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-area-ledger-test-"));
-    roots.push(root);
-    return root;
-}
-function open(root, initialJournal) {
-    return AreaLedger.open({
-        rootDir: root,
-        journalSlug: "personal-vault",
-        layoutEpoch: 1,
-        areaIds: ["root:alpha", "root:beta"],
-        resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : key.startsWith("beta/") ? "root:beta" : undefined,
-        initialJournal,
-        maxRecordsBeforeCompaction: 2,
-    });
-}
-function openMany(root, count) {
-    const areaIds = Array.from({ length: count }, (_, index) => `root:area-${index}`);
-    return AreaLedger.open({
-        rootDir: root,
-        journalSlug: "personal-vault",
-        layoutEpoch: 1,
-        areaIds,
-        resolveArea: (key) => {
-            const index = Number(/^area-(\d+)\//.exec(key)?.[1]);
-            return Number.isSafeInteger(index) && areaIds[index] !== undefined ? areaIds[index] : undefined;
-        },
-        maxRecordsBeforeCompaction: 8,
-    });
-}
-async function exitCode(child) {
-    const [code, signal] = await once(child, "exit");
-    if (code !== 0)
-        throw new Error(`area-ledger child failed with ${String(code)} / ${String(signal)}`);
-    return code;
-}
-if (process.env.AREA_LEDGER_CHILD_ROOT) {
-    describe("AreaLedger child append", () => {
-        it("appends its assigned independent area", () => {
-            const ledger = open(process.env.AREA_LEDGER_CHILD_ROOT);
-            ledger.append({ upserts: { "beta/from-child.md": entry(2) } });
-        });
-    });
-}
-else {
-    describe("AreaLedger — a key with no area must not wedge the whole vault", () => {
-        // THE PERMANENT-WEDGE BUG.
-        //
-        // The area layout is committed exactly once, at the legacy -> area
-        // cutover (`cutOver()` mints activeLayoutEpoch and nothing ever re-mints
-        // it). The resolver is then loaded from that frozen `area-resolver.json`
-        // — "an authority decision, not a hint" — so it knows only the top-level
-        // directories that existed on cutover day.
-        //
-        // Create ANY new top-level directory in the HQ root afterwards and every
-        // key beneath it resolves to nothing. `partition()` then throws out of
-        // `append()`, which aborts the ENTIRE personal-vault checkpoint — not just
-        // the unroutable key. Every unrelated change in the same transaction is
-        // lost with it, and because the layout is never rebuilt the next sync
-        // fails identically. On this fleet two machines stayed wedged for days;
-        // the only recovery was deleting the directory by hand.
-        //
-        // A new top-level directory is an ordinary thing for a user to make. It
-        // must never be able to stop their vault syncing.
-        function openWithUnroutable(root) {
-            return AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                // A layout frozen before `gamma/` existed.
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/")
-                    ? "root:alpha"
-                    : key.startsWith("beta/")
-                        ? "root:beta"
-                        : undefined,
-                maxRecordsBeforeCompaction: 2,
-            });
-        }
-        it("accepts an append containing a key the frozen layout cannot route", () => {
-            const root = makeRoot();
-            const ledger = openWithUnroutable(root);
-            expect(() => ledger.append({ upserts: { "gamma/new-top-level.md": entry(1) } })).not.toThrow();
-        });
-        it("does not discard the routable changes travelling with it", () => {
-            // The damage was never limited to the unroutable path: one unknown key
-            // took the whole transaction down with it.
-            const root = makeRoot();
-            const ledger = openWithUnroutable(root);
-            ledger.append({
-                upserts: {
-                    "alpha/keep-me.md": entry(1),
-                    "beta/keep-me-too.md": entry(2),
-                    "gamma/new-top-level.md": entry(3),
-                },
-            });
-            const files = openWithUnroutable(root).read().files;
-            expect(files["alpha/keep-me.md"]).toMatchObject({ size: 1 });
-            expect(files["beta/keep-me-too.md"]).toMatchObject({ size: 2 });
-        });
-        it("still journals the unroutable key so it is not silently forgotten", () => {
-            // Dropping the row would be its own bug: the file would then look
-            // untracked forever and never reconcile.
-            const root = makeRoot();
-            const ledger = openWithUnroutable(root);
-            ledger.append({ upserts: { "gamma/new-top-level.md": entry(7) } });
-            expect(openWithUnroutable(root).read().files["gamma/new-top-level.md"])
-                .toMatchObject({ size: 7 });
-        });
-        it("survives a second sync, the way the wedged machines never did", () => {
-            const root = makeRoot();
-            openWithUnroutable(root).append({
-                upserts: { "gamma/new-top-level.md": entry(1) },
-            });
-            expect(() => openWithUnroutable(root).append({
-                upserts: { "gamma/another.md": entry(2), "alpha/ok.md": entry(3) },
-            })).not.toThrow();
-            expect(openWithUnroutable(root).read().files["alpha/ok.md"])
-                .toMatchObject({ size: 3 });
-        });
-        it("routes a deletion of an unroutable key without throwing", () => {
-            const root = makeRoot();
-            const ledger = openWithUnroutable(root);
-            ledger.append({ upserts: { "gamma/gone.md": entry(1) } });
-            expect(() => openWithUnroutable(root).append({ deletes: ["gamma/gone.md"] })).not.toThrow();
-            expect(openWithUnroutable(root).read().files["gamma/gone.md"]).toBeUndefined();
-        });
-        /** Every byte an area holds on disk — the ground truth for placement. */
-        function storedText(dir) {
-            const walk = (at) => fs.readdirSync(at, { withFileTypes: true }).flatMap((item) => {
-                const full = path.join(at, item.name);
-                return item.isDirectory() ? walk(full) : [fs.readFileSync(full, "utf8")];
-            });
-            return fs.existsSync(dir) ? walk(dir).join("\n") : "";
-        }
-        it("keeps a routable key in ITS OWN area, not the overflow", () => {
-            // Negative control. A fix that simply swept every key into one overflow
-            // area would pass every test above while destroying the per-area
-            // partitioning the whole design exists for — and with it the per-area
-            // append locks two processes rely on. Placement is read off disk because
-            // an append opens every configured area whatever it writes, so the
-            // opened-area list cannot say where a row actually landed.
-            const root = makeRoot();
-            const ledger = openWithUnroutable(root);
-            ledger.append({
-                upserts: { "alpha/a.md": entry(1), "gamma/g.md": entry(2) },
-            });
-            const directories = ledger.stateDirectoriesForTest();
-            const alpha = storedText(directories.get("root:alpha"));
-            const overflow = storedText(directories.get(UNROUTED_AREA_ID));
-            expect(alpha).toContain("alpha/a.md");
-            expect(alpha).not.toContain("gamma/g.md");
-            expect(overflow).toContain("gamma/g.md");
-            expect(overflow).not.toContain("alpha/a.md");
-            // ...and the sibling area nobody wrote to holds neither of them.
-            expect(storedText(directories.get("root:beta"))).not.toContain("alpha/a.md");
-        });
-        it("routes every unroutable key to the SAME overflow area", () => {
-            // Otherwise a machine that grows many new top-level directories would
-            // grow an unbounded number of area state stores.
-            const root = makeRoot();
-            const ledger = openWithUnroutable(root);
-            ledger.append({
-                upserts: { "gamma/one.md": entry(1), "delta/two.md": entry(2) },
-            });
-            const directories = ledger.stateDirectoriesForTest();
-            expect([...directories.keys()].sort()).toEqual(["@meta", UNROUTED_AREA_ID, "root:alpha", "root:beta"].sort());
-            const overflow = storedText(directories.get(UNROUTED_AREA_ID));
-            expect(overflow).toContain("gamma/one.md");
-            expect(overflow).toContain("delta/two.md");
-        });
-    });
-    describe("AreaLedger — the overflow area must never collide with a real one", () => {
-        // The 2026-09-07 regression, reproduced end to end.
-        //
-        // hq-cloud 6.16.24 did two things in one release: it added the overflow
-        // area (so an unroutable key stops aborting the checkpoint) and it added
-        // the top-level lockfiles to the personal vault's exclusions. Together
-        // those turned a key that had a live entry in a REAL area into a key that
-        // no longer routes — so the next delta touching it took the overflow route
-        // and the SAME key was suddenly journaled in two areas at once.
-        //
-        // `combine` treated that as corruption and threw. It runs inside
-        // `primeAggregateCache`, which is on the JournalStore OPEN path, so it
-        // fired on every open: the watcher crash-looped, and unlike the
-        // append-time failure the overflow area was introduced to remove, there
-        // was nothing the user could do to recover. Both HQ outposts hit it within
-        // hours of upgrading — `pnpm-lock.yaml` on one, `package-lock.json` on the
-        // other.
-        //
-        // Two halves are tested here: the read path HEALS a ledger that already
-        // holds the duplicate, and the write path stops a new one being made.
-        /** A ledger whose layout knows `root:gamma`. */
-        function openWide(root) {
-            return AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:gamma"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : key.startsWith("gamma/") ? "root:gamma" : undefined,
-                maxRecordsBeforeCompaction: 2,
-            });
-        }
-        /**
-         * The same root seen by a build whose layout does NOT know `root:gamma` —
-         * which is how 6.16.24 behaved for a key it had just excluded. This is the
-         * writer that creates the duplicate, standing in for the released build
-         * that had no prevention in it.
-         */
-        function openNarrow(root) {
-            return AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha"],
-                resolveArea: (key) => (key.startsWith("alpha/") ? "root:alpha" : undefined),
-                maxRecordsBeforeCompaction: 2,
-            });
-        }
-        /**
-         * The production shape of the regression: the area list is frozen, so
-         * `root:gamma` is still configured, but the key no longer routes to it.
-         */
-        function openStranded(root) {
-            return AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:gamma"],
-                resolveArea: (key) => (key.startsWith("alpha/") ? "root:alpha" : undefined),
-                maxRecordsBeforeCompaction: 2,
-            });
-        }
-        /** Put `gamma/g.md` in BOTH `root:gamma` and the overflow area. */
-        function seedDuplicate(root) {
-            openWide(root).append({ upserts: { "gamma/g.md": entry(1) } });
-            openNarrow(root).append({ upserts: { "gamma/g.md": entry(2) } });
-        }
-        it("reproduces the duplicate: the same key lands in a real area AND the overflow", () => {
-            // Negative control for the two tests below. If this ever stops producing
-            // a duplicate, they would both pass without exercising anything.
-            const root = makeRoot();
-            seedDuplicate(root);
-            const directories = openWide(root).stateDirectoriesForTest();
-            const walk = (at) => fs.readdirSync(at, { withFileTypes: true }).flatMap((item) => {
-                const full = path.join(at, item.name);
-                return item.isDirectory() ? walk(full) : [fs.readFileSync(full, "utf8")];
-            });
-            const text = (dir) => (fs.existsSync(dir) ? walk(dir).join("\n") : "");
-            expect(text(directories.get("root:gamma"))).toContain("gamma/g.md");
-            expect(text(directories.get(UNROUTED_AREA_ID))).toContain("gamma/g.md");
-        });
-        it("reads a ledger that already holds the duplicate instead of throwing", () => {
-            const root = makeRoot();
-            seedDuplicate(root);
-            expect(() => openWide(root).read()).not.toThrow();
-        });
-        it("resolves the duplicate to the REAL area's entry, not the overflow copy", () => {
-            // Direction matters. The overflow area is the fallback for keys the
-            // layout cannot place, so a key it CAN place is governed by its placed
-            // entry; the overflow copy is stale by construction. Sizes 1 and 2 are
-            // what tell the two apart.
-            const root = makeRoot();
-            seedDuplicate(root);
-            expect(openWide(root).read().files["gamma/g.md"]?.size).toBe(1);
-        });
-        it("still throws when one key is present in two REAL areas", () => {
-            // The invariant this fix must NOT weaken. A routable key has exactly one
-            // home, so two real areas holding it means the on-disk state disagrees
-            // with itself, and silently picking a winner would hide that.
-            //
-            // Each writer below is given a layout containing only its OWN area, so
-            // neither can see — and therefore evict — the other's copy. That is what
-            // it now takes to build this state at all: through a layout that knows
-            // both areas, the eviction in `partition` converges it away instead (see
-            // the re-route test below).
-            const root = makeRoot();
-            const single = (areaId) => AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: [areaId],
-                resolveArea: () => areaId,
-                maxRecordsBeforeCompaction: 2,
-            });
-            single("root:alpha").append({ upserts: { "shared.md": entry(1) } });
-            single("root:beta").append({ upserts: { "shared.md": entry(2) } });
-            expect(() => AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: () => "root:alpha",
-                maxRecordsBeforeCompaction: 2,
-            }).read()).toThrow(/present in multiple areas/);
-        });
-        it("does not create a duplicate when a key stops routing but its area still holds it", () => {
-            // The prevention half. `root:gamma` is still a configured area holding
-            // the row; the key no longer resolves to it. The append must go to the
-            // area that already owns the row, NOT to the overflow.
-            const root = makeRoot();
-            openWide(root).append({ upserts: { "gamma/g.md": entry(1) } });
-            const stranded = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:gamma"],
-                // `gamma/` was excluded, so it routes nowhere now.
-                resolveArea: (key) => (key.startsWith("alpha/") ? "root:alpha" : undefined),
-                maxRecordsBeforeCompaction: 2,
-            });
-            stranded.append({ upserts: { "gamma/g.md": entry(3) } });
-            const directories = stranded.stateDirectoriesForTest();
-            const walk = (at) => fs.readdirSync(at, { withFileTypes: true }).flatMap((item) => {
-                const full = path.join(at, item.name);
-                return item.isDirectory() ? walk(full) : [fs.readFileSync(full, "utf8")];
-            });
-            const text = (dir) => (fs.existsSync(dir) ? walk(dir).join("\n") : "");
-            expect(text(UNROUTED_AREA_ID in Object.fromEntries(directories) ? directories.get(UNROUTED_AREA_ID) : "")).not.toContain("gamma/g.md");
-            expect(stranded.read().files["gamma/g.md"]?.size).toBe(3);
-        });
-        it("still routes a genuinely new unplaceable key to the overflow area", () => {
-            // The prevention must not swallow the case the overflow area exists for:
-            // a key no area has ever held still belongs in the overflow.
-            const root = makeRoot();
-            const ledger = openNarrow(root);
-            ledger.append({ upserts: { "delta/new.md": entry(1) } });
-            const directories = ledger.stateDirectoriesForTest();
-            const walk = (at) => fs.readdirSync(at, { withFileTypes: true }).flatMap((item) => {
-                const full = path.join(at, item.name);
-                return item.isDirectory() ? walk(full) : [fs.readFileSync(full, "utf8")];
-            });
-            expect(walk(directories.get(UNROUTED_AREA_ID)).join("\n")).toContain("delta/new.md");
-        });
-        it("reads a stranded row back through readRows right after an append", () => {
-            // Codex P1 on #502. `append()` clears the aggregate cache, and the
-            // area-authoritative migration path calls `verifyDeltaParity` -> `readRows`
-            // immediately afterwards. With a cold cache the row lookup used to have
-            // no opinion, so a key the layout can no longer route was read from the
-            // overflow area rather than from the real area the append had just
-            // written it to — returning undefined (or the stale overflow copy) and
-            // failing parity on every mutation of that key.
-            const root = makeRoot();
-            openWide(root).append({ upserts: { "gamma/g.md": entry(1) } });
-            const stranded = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:gamma"],
-                resolveArea: (key) => (key.startsWith("alpha/") ? "root:alpha" : undefined),
-                maxRecordsBeforeCompaction: 2,
-            });
-            stranded.append({ upserts: { "gamma/g.md": entry(7) } });
-            expect(stranded.readRows(["gamma/g.md"])["gamma/g.md"]).toMatchObject({ size: 7 });
-            expect(stranded.readScoped(["gamma/g.md"]).files["gamma/g.md"]).toMatchObject({ size: 7 });
-        });
-        it("keeps the real area's value when only the overflow area is refreshed", () => {
-            // Codex P1 on #502. The incremental refresh removes every key the
-            // refreshed area used to hold before reinstalling. For a duplicated key
-            // that removal also dropped the REAL area's winning value, so the
-            // collision guard never fired and the stale overflow entry was installed
-            // as the aggregate value — or the key vanished entirely when the overflow
-            // copy had been removed.
-            const root = makeRoot();
-            seedDuplicate(root);
-            const reader = openWide(root);
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(1);
-            // Another process changes ONLY the overflow area.
-            openNarrow(root).append({ upserts: { "delta/other.md": entry(9) } });
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(1);
-            // ...and again when the overflow copy is removed outright.
-            openNarrow(root).append({ deletes: ["gamma/g.md"] });
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(1);
-        });
-        it("lets a delete reach the row after the duplicate has been healed", () => {
-            // The user-visible symptom was that deletes never stuck. Healing the read
-            // is not enough on its own — the row must still be removable.
-            const root = makeRoot();
-            seedDuplicate(root);
-            const ledger = openWide(root);
-            // Read first, which is the order the sync runner uses: opening the
-            // journal store primes the aggregate cache before anything is written.
-            // That read is what notices the duplicate, and the append that follows
-            // is what drops the stale overflow copy.
-            ledger.read();
-            expect(() => ledger.append({ deletes: ["gamma/g.md"] })).not.toThrow();
-            expect(openWide(root).read().files["gamma/g.md"]).toBeUndefined();
-        });
-        it("lets a delete reach the row when nothing read the aggregate first", () => {
-            // Convergence must not be conditional on a prior aggregate read. An
-            // area-authoritative scoped pass never calls the aggregate path, so a
-            // ledger whose duplicate has never been observed still has to drop the
-            // overflow copy on the delete that removes the real one — otherwise the
-            // stale copy resurfaces and the row is undeletable, which is the
-            // production symptom this whole fix exists to remove.
-            const root = makeRoot();
-            seedDuplicate(root);
-            openWide(root).append({ deletes: ["gamma/g.md"] });
-            expect(openWide(root).read().files["gamma/g.md"]).toBeUndefined();
-        });
-        it("reads the live value after another process moves a stranded key to the overflow", () => {
-            // A warm cache records where a stranded key lived when it was primed.
-            // If another process then removes it from that real area and recreates
-            // it in the overflow, the cached owner is stale: refreshing only the now
-            // empty real area reports the key as missing even though its current
-            // value is on disk.
-            const root = makeRoot();
-            openWide(root).append({ upserts: { "gamma/g.md": entry(1) } });
-            const reader = openStranded(root);
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(1);
-            // Another process empties the real area, then writes the key afresh.
-            // With `root:gamma` no longer holding it, that write takes the overflow.
-            openWide(root).append({ deletes: ["gamma/g.md"] });
-            openStranded(root).append({ upserts: { "gamma/g.md": entry(2) } });
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(2);
-            expect(reader.readRows(["gamma/g.md"])["gamma/g.md"]?.size).toBe(2);
-            expect(reader.readScoped(["gamma/g.md"]).files["gamma/g.md"]?.size).toBe(2);
-        });
-        it("evicts an overflow copy that only became visible when its watermark landed", () => {
-            // The convergence probe memoizes what the overflow area holds, keyed on
-            // that area's on-disk generation. A row the overflow has PREPARED becomes
-            // visible when its watermark is published, and that write lands in meta —
-            // the overflow area's own generation never moves. A memo built in that
-            // window keeps answering "no row here", so the delete of the real copy
-            // skips the eviction and the row resurfaces.
-            //
-            // The window only exists INSIDE another writer's transaction, which is
-            // why this interleaves rather than crashing and recovering: a prepare
-            // abandoned before its watermark is discarded by recovery, never
-            // published, so it cannot produce this state.
-            const root = makeRoot();
-            openWide(root).append({ upserts: { "gamma/g.md": entry(1) } });
-            const ledger = openWide(root);
-            setAreaLedgerTestHooksForTest({
-                // Mid-transaction, after the overflow prepare is on disk and before its
-                // watermark: the long-lived instance builds its memo here, and sees no
-                // overflow row because the transaction is not yet visible.
-                afterDataBeforeWatermark: () => {
-                    ledger.append({ upserts: { "gamma/other.md": entry(3) } });
-                },
-                afterWatermarkBeforeFinalize: () => {
-                    throw new Error("simulated crash after watermark");
-                },
-            });
-            // A build that cannot see `root:gamma` writes the same key to the
-            // overflow, spanning the overflow and `root:alpha`.
-            expect(() => openNarrow(root).append({ upserts: { "gamma/g.md": entry(2), "alpha/a.md": entry(9) } })).toThrow("simulated crash after watermark");
-            setAreaLedgerTestHooksForTest(undefined);
-            ledger.append({ deletes: ["gamma/g.md"] });
-            expect(openWide(root).read().files["gamma/g.md"]).toBeUndefined();
-        });
-        it("sees a published cross-area row when probing for a stranded key's owner", () => {
-            // Visibility is per-area: whether a transaction counts as committed is
-            // computed from the areas that transaction NAMES. Probing candidate areas
-            // one at a time therefore has to recompute it per probe. Carrying the
-            // first candidate's answer forward hides a row that was published but not
-            // yet finalized, the probe reports the real owner as empty, and the key
-            // is treated as unplaceable — so its next delete or update goes to the
-            // overflow while the original row stays put.
-            const root = makeRoot();
-            const areaIds = ["root:alpha", "root:beta", "root:gamma"];
-            const writer = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds,
-                resolveArea: (key) => `root:${key.split("/")[0]}`,
-                maxRecordsBeforeCompaction: 2,
-            });
-            // Publish a transaction naming beta and gamma, then crash before it is
-            // finalized. `root:alpha` — the first candidate probed — does not name it.
-            setAreaLedgerTestHooksForTest({
-                afterWatermarkBeforeFinalize: () => {
-                    throw new Error("simulated crash after watermark");
-                },
-            });
-            expect(() => writer.append({ upserts: { "beta/b.md": entry(1), "gamma/g.md": entry(2) } })).toThrow("simulated crash after watermark");
-            setAreaLedgerTestHooksForTest(undefined);
-            const stranded = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds,
-                resolveArea: (key) => (key.startsWith("alpha/") ? "root:alpha" : undefined),
-                maxRecordsBeforeCompaction: 2,
-            });
-            expect(stranded.readRows(["gamma/g.md"])["gamma/g.md"]?.size).toBe(2);
-        });
-        it("reads the live value after another process moves a stranded key into a real area", () => {
-            // The mirror of the move-to-overflow case. A warm cache can record that
-            // NO real area holds a stranded key, so it resolves to the overflow; if
-            // another process — one whose layout still routes the key — then writes
-            // it into a real area, the cached answer sends the read to the overflow
-            // and returns the stale value or nothing at all.
-            const root = makeRoot();
-            openNarrow(root).append({ upserts: { "gamma/g.md": entry(2) } });
-            const reader = openStranded(root);
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(2);
-            // A build that CAN route the key writes it to `root:gamma`, and converges
-            // the overflow copy away in the same append.
-            openWide(root).append({ upserts: { "gamma/g.md": entry(1) } });
-            expect(reader.readRows(["gamma/g.md"])["gamma/g.md"]?.size).toBe(1);
-            expect(reader.readScoped(["gamma/g.md"]).files["gamma/g.md"]?.size).toBe(1);
-        });
-        it("still throws when an incremental refresh is what reveals two REAL areas", () => {
-            // The real-vs-real invariant has to hold on the incremental path too. A
-            // full rebuild rejects this state; an incremental refresh that only looks
-            // at the one changed area must not quietly install whichever copy was
-            // written last.
-            const root = makeRoot();
-            const reader = openWide(root);
-            reader.append({ upserts: { "gamma/g.md": entry(1) } });
-            expect(reader.read().files["gamma/g.md"]?.size).toBe(1);
-            // An external writer with a different layout puts the SAME key into
-            // `root:alpha`, which no overflow copy is involved in.
-            AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha"],
-                resolveArea: () => "root:alpha",
-                maxRecordsBeforeCompaction: 2,
-            }).append({ upserts: { "gamma/g.md": entry(2) } });
-            expect(() => reader.read()).toThrow(/present in multiple areas/);
-        });
-    });
-    describe("AreaLedger", () => {
-        const makeEventReplayFixture = () => {
-            const root = makeRoot();
-            const keys = Array.from({ length: 24 }, (_, index) => `alpha/random-${String(index).padStart(2, "0")}.md`);
-            const initialFiles = Object.fromEntries(keys.map((key, index) => [key, entry(index)]));
-            let routeKnown = true;
-            const ledger = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha"],
-                resolveArea: (key) => routeKnown && key.startsWith("alpha/") ? "root:alpha" : undefined,
-                initialJournal: { version: "2", lastSync: "", files: initialFiles, pulls: [] },
-                maxRecordsBeforeCompaction: 10_000,
-                maxWalBytesBeforeCompaction: 128 * 1024 * 1024,
-            });
-            const deltas = [];
-            const append = (delta) => {
-                deltas.push(delta);
-                ledger.append(delta);
-            };
-            const preparedDelta = { deletes: [keys[3]], upserts: { [keys[4]]: entry(1_004) } };
-            deltas.push(preparedDelta);
-            setAreaLedgerTestHooksForTest({
-                afterWatermarkBeforeFinalize: () => { throw new Error("leave committed prepare visible"); },
-            });
-            expect(() => ledger.append({
-                ...preparedDelta,
-                metadata: { lastSync: "prepared", pulls: [] },
-            })).toThrow("leave committed prepare visible");
-            setAreaLedgerTestHooksForTest(undefined);
-            append({ deletes: [keys[0]], upserts: {} });
-            append({ deletes: [], upserts: { [keys[0]]: entry(2_001) } });
-            append({ deletes: [], upserts: { [keys[1]]: entry(3_001) } });
-            append({ deletes: [keys[1]], upserts: {} });
-            append({ deletes: [keys[2]], upserts: { [keys[2]]: entry(5_001) } });
-            let randomState = 0x6d2b79f5;
-            const random = () => {
-                randomState = (Math.imul(randomState, 1_664_525) + 1_013_904_223) >>> 0;
-                return randomState / 0x1_0000_0000;
-            };
-            for (let eventIndex = 0; eventIndex < 32; eventIndex += 1) {
-                const deletes = new Set();
-                const upserts = {};
-                const deleteCount = 1 + Math.floor(random() * 4);
-                const upsertCount = 1 + Math.floor(random() * 4);
-                for (let index = 0; index < deleteCount; index += 1) {
-                    deletes.add(keys[Math.floor(random() * keys.length)]);
-                }
-                for (let index = 0; index < upsertCount; index += 1) {
-                    const key = keys[Math.floor(random() * keys.length)];
-                    upserts[key] = entry(10_000 + eventIndex * 10 + index);
-                }
-                append({ deletes: [...deletes], upserts });
-            }
-            const oldPerKeyMaterialization = (key) => {
-                let row = initialFiles[key];
-                for (const delta of deltas) {
-                    if (delta.deletes.includes(key))
-                        row = undefined;
-                    if (delta.upserts[key] !== undefined)
-                        row = delta.upserts[key];
-                }
-                return row;
-            };
-            return {
-                ledger,
-                keys,
-                oldPerKeyMaterialization,
-                eventCount: deltas.length,
-                setRouteKnown: (value) => { routeKnown = value; },
-            };
-        };
-        it("matches the old per-key fold while visiting direct events once in readRows", () => {
-            const { ledger, keys, oldPerKeyMaterialization, eventCount } = makeEventReplayFixture();
-            const expected = {};
-            for (const key of keys)
-                expected[key] = oldPerKeyMaterialization(key);
-            let eventVisits = 0;
-            setAreaLedgerTestHooksForTest({ onMaterializeEvent: () => { eventVisits += 1; } });
-            expect(ledger.readRows(keys)).toEqual(expected);
-            expect(eventVisits).toBe(eventCount);
-        });
-        it("folds a stranded-row probe tail once per area before reading requested rows", () => {
-            const { ledger, keys, oldPerKeyMaterialization, eventCount, setRouteKnown } = makeEventReplayFixture();
-            setRouteKnown(false);
-            const expected = {};
-            for (const key of keys)
-                expected[key] = oldPerKeyMaterialization(key);
-            let eventVisits = 0;
-            setAreaLedgerTestHooksForTest({ onMaterializeEvent: () => { eventVisits += 1; } });
-            expect(ledger.readRows(keys)).toEqual(expected);
-            // One event fold establishes presence for stranded-key placement; the
-            // second materializes the requested values. Work remains independent of
-            // the number of probes rather than replaying the tail per key.
-            expect(eventVisits).toBe(eventCount * 2);
-        });
-        it("folds readRowsUnder descendants in one pass over the direct events", () => {
-            const { ledger, keys, oldPerKeyMaterialization, eventCount } = makeEventReplayFixture();
-            const expected = {};
-            for (const key of keys) {
-                const row = oldPerKeyMaterialization(key);
-                if (row !== undefined)
-                    expected[key] = row;
-            }
-            let eventVisits = 0;
-            setAreaLedgerTestHooksForTest({ onMaterializeEvent: () => { eventVisits += 1; } });
-            expect(ledger.readRowsUnder(["alpha"], ["root:alpha"])).toEqual(expected);
-            expect(eventVisits).toBe(eventCount);
-        });
-        it("allows two processes to append independent areas through distinct append locks", async () => {
-            const root = makeRoot();
-            const child = spawn(process.execPath, [path.join(process.cwd(), "node_modules/vitest/vitest.mjs"), "run", "src/sync/area-ledger.test.ts", "--no-file-parallelism"], {
-                cwd: process.cwd(),
-                env: { ...process.env, AREA_LEDGER_CHILD_ROOT: root },
-                stdio: "pipe",
-            });
-            const parent = open(root);
-            parent.append({ upserts: { "alpha/from-parent.md": entry(1) } });
-            await exitCode(child);
-            const reopened = open(root);
-            expect(reopened.read().files).toMatchObject({
-                "alpha/from-parent.md": { size: 1 },
-                "beta/from-child.md": { size: 2 },
-            });
-            const directories = reopened.stateDirectoriesForTest();
-            const alphaLock = path.join(directories.get("root:alpha"), "append.lock");
-            const betaLock = path.join(directories.get("root:beta"), "append.lock");
-            expect(alphaLock).not.toBe(betaLock);
-            expect(fs.existsSync(alphaLock)).toBe(false);
-            expect(fs.existsSync(betaLock)).toBe(false);
-        }, 30_000);
-        it("preserves same-area append ordering and durability", () => {
-            const root = makeRoot();
-            const first = open(root);
-            const second = open(root);
-            first.append({ upserts: { "alpha/one.md": entry(1) } });
-            second.append({ upserts: { "alpha/two.md": entry(2) } });
-            expect(open(root).readScoped(["alpha/one.md", "alpha/two.md"]).files).toMatchObject({
-                "alpha/one.md": { size: 1 },
-                "alpha/two.md": { size: 2 },
-            });
-        });
-        it("opens only the routed data area for a scoped read", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            ledger.append({ upserts: { "alpha/one.md": entry(1) } });
-            ledger.append({ upserts: { "beta/two.md": entry(2) } });
-            const scoped = open(root);
-            expect(scoped.readScoped(["alpha/one.md"])).toMatchObject({ files: { "alpha/one.md": { size: 1 } } });
-            // Scoped reads refresh @meta so they can include a committed prepare.
-            // No unrelated beta data store is needed when no watermark names it.
-            expect(scoped.openedAreasForTest()).toEqual(["@meta", "root:alpha"]);
-        });
-        it("materializes scoped delete roots only by exact key or matching descendant", () => {
-            const root = makeRoot();
-            const files = Object.fromEntries(Array.from({ length: 1_000 }, (_, index) => [`alpha/unrelated/${index}.md`, entry(index)]));
-            Object.assign(files, {
-                "alpha/removed-dir/one.md": entry(1_001),
-                "alpha/removed-dir/two.md": entry(1_002),
-            });
-            const writer = open(root, { version: "2", lastSync: "", files, pulls: [] });
-            writer.append({
-                upserts: {
-                    "alpha/removed-file.md": entry(1_003),
-                    "alpha/removed-dir/from-visible-delta.md": entry(1_004),
-                },
-            });
-            const reader = open(root);
-            const materialized = [];
-            setAreaLedgerTestHooksForTest({ onMaterializeRow: (key) => materialized.push(key) });
-            expect(reader.readRowsUnder(["alpha/removed-file.md"], ["root:alpha"])).toMatchObject({
-                "alpha/removed-file.md": { size: 1_003 },
-            });
-            expect(materialized).toEqual(["alpha/removed-file.md"]);
-            materialized.length = 0;
-            const directoryRows = reader.readRowsUnder(["alpha/removed-dir"], ["root:alpha"]);
-            expect(directoryRows).toMatchObject({
-                "alpha/removed-dir/one.md": { size: 1_001 },
-                "alpha/removed-dir/two.md": { size: 1_002 },
-                "alpha/removed-dir/from-visible-delta.md": { size: 1_004 },
-            });
-            // The missing exact root is probed once; only matching descendants are
-            // materialized, never the thousand unrelated rows in this area.
-            expect(materialized).toHaveLength(Object.keys(directoryRows).length + 1);
-        });
-        it("keeps empty roots, exact rows, and path-segment matching equivalent", () => {
-            const root = makeRoot();
-            const writer = open(root, {
-                version: "2",
-                lastSync: "",
-                files: {
-                    "alpha/a/b/file.md": entry(1),
-                    "alpha/a/bc/file.md": entry(2),
-                    "alpha/exact.md": entry(3),
-                },
-                pulls: [],
-            });
-            const exact = writer.readRowsUnder(["alpha/exact.md"], ["root:alpha"]);
-            expect(Object.keys(exact)).toEqual(["alpha/exact.md"]);
-            const directory = writer.readRowsUnder(["alpha/a/b"], ["root:alpha"]);
-            expect(Object.keys(directory)).toEqual(["alpha/a/b/file.md"]);
-            const all = writer.readRowsUnder([""], ["root:alpha"]);
-            expect(Object.keys(all).sort()).toEqual([
-                "alpha/a/b/file.md",
-                "alpha/a/bc/file.md",
-                "alpha/exact.md",
-            ]);
-        });
-        it("orders a prepared update before later direct updates and deletes", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            ledger.append({ upserts: { "alpha/x.md": entry(1) }, metadata: { lastSync: "prepared", pulls: [] } });
-            ledger.append({ upserts: { "alpha/x.md": entry(2) } });
-            expect(ledger.read().files["alpha/x.md"]).toMatchObject({ size: 2 });
-            ledger.append({ upserts: { "alpha/x.md": entry(3) }, metadata: { lastSync: "prepared-again", pulls: [] } });
-            ledger.append({ deletes: ["alpha/x.md"] });
-            expect(ledger.read().files["alpha/x.md"]).toBeUndefined();
-        });
-        it("includes committed multi-area prepares in scoped reads and refreshes cached stores", () => {
-            const root = makeRoot();
-            const reader = open(root);
-            expect(reader.readScoped(["alpha/one.md"]).files).toEqual({});
-            const writer = open(root);
-            writer.append({
-                upserts: { "alpha/one.md": entry(1), "beta/two.md": entry(2) },
-                metadata: { lastSync: "visible", pulls: [] },
-            });
-            expect(reader.readScoped(["alpha/one.md"])).toMatchObject({
-                lastSync: "visible",
-                files: { "alpha/one.md": { size: 1 } },
-            });
-        });
-        it("keeps a warm aggregate connected after a scoped read", () => {
-            const root = makeRoot();
-            const writer = open(root);
-            writer.append({ upserts: { "alpha/one.md": entry(1) } });
-            const reader = open(root);
-            expect(reader.read().files["alpha/one.md"]?.size).toBe(1);
-            expect(reader.readScoped(["alpha/one.md"]).files["alpha/one.md"]?.size).toBe(1);
-            writer.append({ upserts: { "alpha/one.md": entry(2) } });
-            expect(reader.read().files["alpha/one.md"]?.size).toBe(2);
-        });
-        it("applies committed WAL records to a warm aggregate without replaying its growing tail", () => {
-            // The area writer now defers a snapshot until a bounded WAL threshold.
-            // A warm aggregate must apply each known durable delta directly: replaying
-            // all prior commits into an overlay after every append turns N small
-            // commits into O(N²) overlay work (and into a full-area CPU stall at
-            // production scale).
-            const root = makeRoot();
-            const ledger = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : "root:beta",
-                maxRecordsBeforeCompaction: 128,
-            });
-            ledger.readCached();
-            const replay = vi.spyOn(JournalRowOverlay.prototype, "dirtyLogSnapshot");
-            for (let index = 0; index < 32; index += 1) {
-                ledger.append({
-                    upserts: { [`alpha/watch/${index}.md`]: entry(index) },
-                    metadata: { lastSync: `tail-${index}`, pulls: [] },
-                });
-            }
-            const aggregate = ledger.readCached().journal;
-            expect(aggregate.files["alpha/watch/31.md"]?.size).toBe(31);
-            expect(aggregate.lastSync).toBe("tail-31");
-            expect(replay).not.toHaveBeenCalled();
-        });
-        it("bounds a fresh area-ledger open to one committed WAL tail per changed store", () => {
-            // A cache miss may replay a WAL, but it must replay one bounded tail,
-            // not re-open/replay it for every scoped call. Thirty-two published
-            // alpha transactions leave 32 alpha records and 32 @meta records; beta
-            // and overflow have only headers. The opener therefore has exactly 64
-            // durable records to apply.
-            const root = makeRoot();
-            const writer = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : "root:beta",
-                maxRecordsBeforeCompaction: 128,
-            });
-            for (let index = 0; index < 32; index += 1) {
-                writer.append({
-                    upserts: { [`alpha/cold/${index}.md`]: entry(index) },
-                    metadata: { lastSync: `cold-${index}`, pulls: [] },
-                });
-            }
-            let replayedRecords = 0;
-            setStateStoreWalRecordReadHookForTest(() => { replayedRecords += 1; });
-            const reader = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : "root:beta",
-                maxRecordsBeforeCompaction: 128,
-            });
-            expect(reader.readCached().journal.files["alpha/cold/31.md"]?.size).toBe(31);
-            expect(replayedRecords).toBe(64);
-            expect(replayedRecords).toBeLessThan(128);
-        });
-        it("reconciles an unrelated area refreshed during a metadata publish", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            // Prime the long-lived packed aggregate before a separate writer begins
-            // a metadata-bearing transaction.
-            expect(ledger.read().files).toEqual({});
-            setAreaLedgerTestHooksForTest({
-                // The watermark is durable but the writer has not finalized its own
-                // area yet. A peer advances beta in this exact window, so the writer's
-                // all-area refresh must reconcile beta before it records new cache
-                // identities or the warm aggregate will stay stale forever.
-                afterWatermarkBeforeFinalize: () => {
-                    const peer = open(root);
-                    peer.append({ upserts: { "beta/concurrent.md": entry(2) } });
-                    // A second append forces the tiny test store through its generation
-                    // replacement path rather than exercising only a WAL tail.
-                    peer.append({ upserts: { "beta/concurrent.md": entry(3) } });
-                },
-            });
-            ledger.append({
-                upserts: { "alpha/published.md": entry(1) },
-                metadata: { lastSync: "published", pulls: [] },
-            });
-            expect(ledger.read().files["alpha/published.md"]?.size).toBe(1);
-            expect(ledger.read().files["beta/concurrent.md"]?.size).toBe(3);
-        });
-        it("hides a watermark when independent recovery lost one named area prepare", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            setAreaLedgerTestHooksForTest({
-                afterWatermarkBeforeFinalize: () => { throw new Error("simulated crash after watermark"); },
-            });
-            expect(() => ledger.append({
-                upserts: { "alpha/one.md": entry(1), "beta/two.md": entry(2) },
-                metadata: { lastSync: "must-be-atomic", pulls: [] },
-            })).toThrow("simulated crash after watermark");
-            setAreaLedgerTestHooksForTest(undefined);
-            const betaDir = ledger.stateDirectoriesForTest().get("root:beta");
-            fs.rmSync(betaDir, { recursive: true, force: true });
-            expect(open(root).read().files).toEqual({});
-        });
-        it("retires published prepares and watermarks at the area WAL fold threshold", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            ledger.append({
-                upserts: { "alpha/one.md": entry(1), "beta/two.md": entry(2) },
-                metadata: { lastSync: "fold", pulls: [] },
-            });
-            // The first published transaction remains replayable in the WAL. This
-            // is the no-full-snapshot-per-scoped-commit contract; it is still fully
-            // visible to readers before a later bounded fold retires it.
-            expect(ledger.transactionCountsForTest()).toEqual({ prepared: 2, watermarks: 1, finalized: 0 });
-            expect(ledger.read().files).toMatchObject({ "alpha/one.md": { size: 1 }, "beta/two.md": { size: 2 } });
-            // `open()` sets a two-record test threshold. The second transaction
-            // reaches it and must fold both committed transactions atomically.
-            ledger.append({
-                upserts: { "alpha/three.md": entry(3), "beta/four.md": entry(4) },
-                metadata: { lastSync: "folded", pulls: [] },
-            });
-            expect(ledger.transactionCountsForTest()).toEqual({ prepared: 0, watermarks: 0, finalized: 0 });
-            expect(ledger.read().files).toMatchObject({
-                "alpha/one.md": { size: 1 },
-                "beta/two.md": { size: 2 },
-                "alpha/three.md": { size: 3 },
-                "beta/four.md": { size: 4 },
-            });
-            expect(ledger.transactionCountsForTest()).toEqual({ prepared: 0, watermarks: 0, finalized: 0 });
-            expect(open(root).read().files).toMatchObject({
-                "alpha/one.md": { size: 1 },
-                "beta/two.md": { size: 2 },
-                "alpha/three.md": { size: 3 },
-                "beta/four.md": { size: 4 },
-            });
-        });
-        it("returns the cached aggregate without refreshes, locks, appends, or recombination", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            ledger.append({ upserts: { "alpha/one.md": entry(1), "beta/two.md": entry(2) } });
-            expect(ledger.read().files).toMatchObject({ "alpha/one.md": { size: 1 }, "beta/two.md": { size: 2 } });
-            const refresh = vi.spyOn(StateStore.prototype, "refresh");
-            const append = vi.spyOn(StateStore.prototype, "append");
-            const replace = vi.spyOn(StateStore.prototype, "replaceStateWith");
-            const combine = vi.spyOn(ledger, "combine");
-            const cached = ledger.read();
-            expect(cached.files).toMatchObject({ "alpha/one.md": { size: 1 }, "beta/two.md": { size: 2 } });
-            expect(refresh).not.toHaveBeenCalled();
-            expect(append).not.toHaveBeenCalled();
-            expect(replace).not.toHaveBeenCalled();
-            expect(combine).not.toHaveBeenCalled();
-            cached.files["alpha/mutated.md"] = entry(3);
-            expect(ledger.read().files["alpha/mutated.md"]).toBeUndefined();
-        });
-        it("refreshes and re-materializes only changed stores in a 50-area cached ledger", () => {
-            const root = makeRoot();
-            const writer = openMany(root, 50);
-            for (let index = 0; index < 50; index++) {
-                writer.append({ upserts: { [`area-${index}/seed.md`]: entry(index) } });
-            }
-            const reader = openMany(root, 50);
-            expect(Object.keys(reader.read().files)).toHaveLength(50);
-            const refresh = vi.spyOn(StateStore.prototype, "refresh");
-            const combine = vi.spyOn(reader, "combine");
-            reader.read();
-            reader.read();
-            expect(refresh).not.toHaveBeenCalled();
-            expect(combine).not.toHaveBeenCalled();
-            writer.append({ upserts: { "area-17/changed.md": entry(99) } });
-            expect(reader.read().files["area-17/changed.md"]).toMatchObject({ size: 99 });
-            expect(refresh).toHaveBeenCalledTimes(1);
-            expect(combine).not.toHaveBeenCalled();
-        });
-        it("does not re-resolve every packed row for every area while rebuilding a phase-two aggregate", () => {
-            const root = makeRoot();
-            const areaCount = 50;
-            const rows = 2_000;
-            const areaIds = Array.from({ length: areaCount }, (_, index) => `root:area-${index}`);
-            let resolveCalls = 0;
-            const ledger = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds,
-                resolveArea: (key) => {
-                    resolveCalls += 1;
-                    const index = Number(/^area-(\d+)\//.exec(key)?.[1]);
-                    return Number.isSafeInteger(index) && areaIds[index] !== undefined ? areaIds[index] : undefined;
-                },
-            });
-            const upserts = {};
-            for (let index = 0; index < rows; index += 1) {
-                upserts[`area-${index % areaCount}/nested/entry-${index}.md`] = entry(index);
-            }
-            ledger.append({ upserts });
-            // The first build gives every area its packed facade. Rebuild from those
-            // facades to exercise the pass-open path that wedged phase two.
-            ledger.readCached();
-            resolveCalls = 0;
-            ledger.invalidateAggregateCache();
-            const aggregate = ledger.readCached().journal;
-            expect(Object.keys(aggregate.files)).toHaveLength(rows);
-            expect(resolveCalls).toBeLessThanOrEqual(rows + areaCount);
-            expect(resolveCalls).toBe(rows);
-        });
-        it("recovers a fully prepared cross-area transaction by writing the watermark last", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            setAreaLedgerTestHooksForTest({
-                afterDataBeforeWatermark: () => { throw new Error("simulated process crash"); },
-            });
-            expect(() => ledger.append({
-                upserts: { "alpha/one.md": entry(1), "beta/two.md": entry(2) },
-                metadata: { lastSync: "watermark", pulls: [] },
-            })).toThrow("simulated process crash");
-            setAreaLedgerTestHooksForTest(undefined);
-            expect(open(root).read()).toMatchObject({
-                lastSync: "watermark",
-                files: { "alpha/one.md": { size: 1 }, "beta/two.md": { size: 2 } },
-            });
-        });
-        it("keeps appenders correct while one area compacts off-lock", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            ledger.append({ upserts: { "alpha/one.md": entry(1) } });
-            ledger.append({ upserts: { "alpha/two.md": entry(2) } });
-            ledger.append({ upserts: { "beta/other.md": entry(3) } });
-            expect(open(root).read().files).toMatchObject({
-                "alpha/one.md": { size: 1 },
-                "alpha/two.md": { size: 2 },
-                "beta/other.md": { size: 3 },
-            });
-        });
-        it("matches the legacy aggregate journal fixture while keeping the legacy adapter opt-in default", () => {
-            const root = makeRoot();
-            const legacy = {
-                version: "2",
-                lastSync: "before",
-                files: { "alpha/one.md": entry(1), "beta/two.md": entry(2) },
-                pulls: [],
-            };
-            const ledger = open(root, legacy);
-            expect(ledger.read()).toEqual(legacy);
-            legacy.files["alpha/three.md"] = entry(3);
-            delete legacy.files["beta/two.md"];
-            legacy.lastSync = "after";
-            ledger.append({
-                upserts: { "alpha/three.md": entry(3) },
-                deletes: ["beta/two.md"],
-                metadata: { lastSync: "after", pulls: [] },
-            });
-            expect(ledger.read()).toEqual(legacy);
-        });
-        it("keeps @meta on ordinary rotation thresholds when the areas are given migration limits", () => {
-            const stateRoot = makeRoot();
-            // Exactly the thresholds AreaLedgerMigration holds while it projects a
-            // vault into areas. They are meant to keep a bulk area copy out of a
-            // compaction loop; @meta is transaction bookkeeping and must not inherit
-            // them, or its WAL grows for the life of the store. A controller reached
-            // 224 MB / 47,291 records this way, and every process that opened the
-            // vault replayed all of it before doing any work.
-            const ledger = AreaLedger.open({
-                rootDir: stateRoot,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha"],
-                resolveArea: (key) => (key.startsWith("alpha/") ? "root:alpha" : undefined),
-                maxRecordsBeforeCompaction: 1_000_000,
-                maxWalBytesBeforeCompaction: 256 * 1024 * 1024,
-            });
-            // Every real sync transaction carries metadata, and metadata is what puts
-            // a watermark/finalize pair into @meta. 150 transactions is 300 meta
-            // records, past StateStore's ordinary 256-record threshold.
-            for (let index = 1; index <= 150; index++) {
-                ledger.append({
-                    upserts: { [`alpha/${index}`]: entry(index) },
-                    metadata: { lastSync: `2026-08-27T00:00:${String(index % 60).padStart(2, "0")}.000Z` },
-                });
-            }
-            const metaDir = ledger.stateDirectoriesForTest().get("@meta");
-            expect(metaDir).toBeDefined();
-            const generationOf = (dir) => Math.max(...fs.readdirSync(dir)
-                .filter((name) => /^snapshot-\d+\.bin$/.test(name))
-                .map((name) => Number(/\d+/.exec(name)[0])));
-            const generation = generationOf(metaDir);
-            expect(generation).toBeGreaterThan(1);
-            // The live WAL holds only what accumulated since the last fold, not all
-            // 300 records.
-            expect(fs.statSync(path.join(metaDir, `wal-${generation}.bin`)).size).toBeLessThan(128 * 1024);
-        }, 120_000);
-        it("caps @meta pull history at MAX_PULLS_PER_COMPANY and keeps the most recent records", () => {
-            const root = makeRoot();
-            const ledger = open(root);
-            const pulls = [];
-            for (let index = 0; index < MAX_PULLS_PER_COMPANY + 10; index++) {
-                pulls.push(pullRecord(index));
-                ledger.append({ metadata: { lastSync: `t${index}`, pulls: [...pulls] } });
-            }
-            const stored = open(root).read().pulls ?? [];
-            expect(stored).toHaveLength(MAX_PULLS_PER_COMPANY);
-            expect(stored.map((record) => record.pullId)).toEqual(Array.from({ length: MAX_PULLS_PER_COMPANY }, (_, offset) => pullRecord(offset + 10).pullId));
-        });
-        it("trims an already-oversized @meta pulls array down to the cap on the next write", () => {
-            const root = makeRoot();
-            const oversized = Array.from({ length: MAX_PULLS_PER_COMPANY + 10 }, (_, index) => pullRecord(index));
-            const seeded = open(root, {
-                version: "2",
-                lastSync: "seeded",
-                files: {},
-                pulls: oversized,
-            });
-            expect(seeded.read().pulls).toHaveLength(MAX_PULLS_PER_COMPANY + 10);
-            seeded.append({ metadata: { lastSync: "healed", pulls: oversized } });
-            const stored = open(root).read().pulls ?? [];
-            expect(stored).toHaveLength(MAX_PULLS_PER_COMPANY);
-            expect(stored[0]?.pullId).toBe(pullRecord(10).pullId);
-            expect(stored.at(-1)?.pullId).toBe(pullRecord(MAX_PULLS_PER_COMPANY + 9).pullId);
-        });
-    });
-    describe("AreaLedger — one packed aggregate view, however many readers hold it", () => {
-        // THE MEMORY-CEILING BUG.
-        //
-        // A personal vault on this fleet has ~690k journal rows. The ledger used to
-        // deep-copy every one of them into each projection it built: the raw area
-        // state, the materialized per-area journal, and the combined aggregate —
-        // and every JournalStore session opened on top copied them all again. With
-        // the runner's cached targeted-pull session, the watcher's session and a
-        // pass-local session open at once, an outpost held five or six full copies,
-        // 4.2 GB live against Node's 4.3 GB default ceiling, and recycled or hard
-        // crashed every ~15 minutes.
-        //
-        // Area rows remain immutable and shared by their local projections. The
-        // aggregate owns the one packed representation; its record facade
-        // materializes frozen rows only at the caller's requested path.
-        function seed(root, rows) {
-            const ledger = open(root);
-            const upserts = {};
-            for (let index = 0; index < rows; index += 1)
-                upserts[`alpha/file-${index}.md`] = entry(index + 1);
-            ledger.append({ upserts });
-            return ledger;
-        }
-        it("builds the shared aggregate store directly instead of repacking a record", () => {
-            const root = makeRoot();
-            const ledger = AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : "root:beta",
-                sharedJournalRowsCacheKey: `area-ledger-direct-packed-aggregate-${root}`,
-            });
-            ledger.append({ upserts: { "alpha/one.md": entry(1), "beta/two.md": entry(2) } });
-            const repack = vi.spyOn(JournalRowStore.prototype, "replaceFromRecord");
-            try {
-                const aggregate = ledger.readCached().journal;
-                expect(aggregate.files["alpha/one.md"]).toMatchObject({ size: 1 });
-                expect(aggregate.files["beta/two.md"]).toMatchObject({ size: 2 });
-                expect(repack).not.toHaveBeenCalled();
-            }
-            finally {
-                repack.mockRestore();
-            }
-        });
-        it("reattaches cached area journals when adopting another bridge's shared rows", () => {
-            const root = makeRoot();
-            const sharedJournalRowsCacheKey = `area-ledger-shared-rows-${root}`;
-            const options = {
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : "root:beta",
-                sharedJournalRowsCacheKey,
-            };
-            const idleTargetedBridge = AreaLedger.open(options);
-            idleTargetedBridge.append({ upserts: { "alpha/changed.md": entry(1) } });
-            idleTargetedBridge.readCached();
-            // A released cached full-pass bridge drops its shared-store registration
-            // while this targeted bridge remains open with its original facade.
-            forgetSharedAreaJournalRows(sharedJournalRowsCacheKey);
-            const fullPassBridge = AreaLedger.open(options);
-            fullPassBridge.readCached();
-            // The targeted bridge adopts the new shared rows. Its per-area facades
-            // must move too, otherwise this direct append writes to its retired rows
-            // and the identity-preserving refresh leaves the new aggregate stale.
-            idleTargetedBridge.readCached();
-            idleTargetedBridge.append({ upserts: { "alpha/changed.md": entry(2) } });
-            expect(idleTargetedBridge.readCached().journal.files["alpha/changed.md"]).toMatchObject({ size: 2 });
-            expect(fullPassBridge.readCached().journal.files["alpha/changed.md"]).toMatchObject({ size: 2 });
-        });
-        it("does not materialize inherited initial journal rows", () => {
-            const files = Object.create({ "alpha/inherited.md": entry(99) });
-            files["alpha/owned.md"] = entry(1);
-            const ledger = open(makeRoot(), { version: "2", lastSync: "", files, pulls: [] });
-            expect(ledger.read().files).toEqual({ "alpha/owned.md": entry(1) });
-        });
-        it("materializes aggregate rows from the packed store instead of retaining area rows", () => {
-            const ledger = seed(makeRoot(), 50);
-            const aggregate = ledger.readCached().journal;
-            const raw = ledger.readRows(["alpha/file-7.md"])["alpha/file-7.md"];
-            expect(raw).toBeDefined();
-            expect(aggregate.files["alpha/file-7.md"]).toEqual(raw);
-            expect(aggregate.files["alpha/file-7.md"]).not.toBe(raw);
-        });
-        it("primes the aggregate without cloning rows", () => {
-            const ledger = seed(makeRoot(), 2_000);
-            const clone = vi.spyOn(globalThis, "structuredClone");
-            try {
-                const { journal } = ledger.readCached();
-                expect(Object.keys(journal.files)).toHaveLength(2_000);
-                // Metadata (pulls) may still be copied; rows must not be.
-                expect(clone.mock.calls.length).toBeLessThan(20);
-            }
-            finally {
-                clone.mockRestore();
-            }
-        });
-        it("updates packed aggregate rows on the incremental refresh path after another process appends", () => {
-            const root = makeRoot();
-            const ledger = seed(root, 20);
-            ledger.readCached();
-            open(root).append({ upserts: { "alpha/file-3.md": entry(300), "alpha/new.md": entry(301) } });
-            const clone = vi.spyOn(globalThis, "structuredClone");
-            let aggregate;
-            try {
-                aggregate = ledger.readCached().journal;
-                expect(clone.mock.calls.length).toBeLessThan(20);
-            }
-            finally {
-                clone.mockRestore();
-            }
-            expect(aggregate.files["alpha/file-3.md"]).toMatchObject({ size: 300 });
-            expect(aggregate.files["alpha/new.md"]).toEqual(ledger.readRows(["alpha/new.md"])["alpha/new.md"]);
-        });
-        it("collapses finalized overlays before a later direct append refreshes the shared aggregate", () => {
-            // A metadata-bearing write folds through a JournalRowOverlay. The next
-            // direct write from another process must reach the warm packed aggregate,
-            // not mutate that overlay behind an identity-preserving cache entry.
-            const root = makeRoot();
-            const reader = open(root);
-            reader.readCached();
-            const writer = open(root);
-            writer.append({
-                upserts: { "alpha/changed.md": entry(1) },
-                metadata: { lastSync: "folded", pulls: [] },
-            });
-            expect(reader.readCached().journal.files["alpha/changed.md"]).toMatchObject({ size: 1 });
-            writer.append({ upserts: { "alpha/changed.md": entry(2) } });
-            expect(reader.readCached().journal.files["alpha/changed.md"]).toMatchObject({ size: 2 });
-        });
-        it("freezes every shared row so an in-place mutation fails loudly", () => {
-            const ledger = seed(makeRoot(), 5);
-            const row = ledger.readCached().journal.files["alpha/file-1.md"];
-            expect(Object.isFrozen(row)).toBe(true);
-            expect(() => { row.size = 999; }).toThrow(TypeError);
-            expect(ledger.readRows(["alpha/file-1.md"])["alpha/file-1.md"]).toMatchObject({ size: 2 });
-        });
-        it("freezes nested row values too, so a delete intent cannot be rewritten in place", () => {
-            const root = makeRoot();
-            const ledger = seed(root, 2);
-            const intent = { version: 1, remoteEtag: "etag-1", localHash: "a".repeat(64), localKind: "file" };
-            ledger.append({ upserts: { "alpha/file-1.md": { ...entry(7), localDeleteIntent: intent } } });
-            const row = ledger.readCached().journal.files["alpha/file-1.md"];
-            expect(Object.isFrozen(row.localDeleteIntent)).toBe(true);
-            expect(() => { row.localDeleteIntent.remoteEtag = "changed"; }).toThrow(TypeError);
-            expect(ledger.readRows(["alpha/file-1.md"])["alpha/file-1.md"].localDeleteIntent).toEqual(intent);
-            // A fresh handle after the store is reopened is the same guarantee, not a
-            // one-off from the first materialization.
-            const reopened = open(root).readCached().journal.files["alpha/file-1.md"];
-            expect(Object.isFrozen(reopened.localDeleteIntent)).toBe(true);
-        });
-        it("keeps public overlay replacements and deletes detached from shared rows", () => {
-            const ledger = seed(makeRoot(), 5);
-            const snapshot = ledger.read();
-            snapshot.files["alpha/file-1.md"] = { ...snapshot.files["alpha/file-1.md"], size: 999 };
-            delete snapshot.files["alpha/file-2.md"];
-            expect(snapshot.files["alpha/file-1.md"]).toMatchObject({ size: 999 });
-            expect(snapshot.files["alpha/file-2.md"]).toBeUndefined();
-            expect(ledger.readCached().journal.files["alpha/file-1.md"]).toMatchObject({ size: 2 });
-            expect(ledger.readCached().journal.files["alpha/file-2.md"]).toMatchObject({ size: 3 });
-        });
-    });
-}
-if (!process.env.AREA_LEDGER_CHILD_ROOT) {
-    /**
-     * `append()` brings the warm aggregate current before its own delta, but the
-     * durable append that follows takes the area's lock and refreshes INSIDE it.
-     * A peer that committed in that window is folded into the area StateStore, yet
-     * the warm packed aggregate only ever receives this process's own partitioned
-     * delta. Recording the post-append identity on top of that made the peer's row
-     * permanently invisible: `hasChangedOnDisk` reports no change, so no later
-     * `readCached()` ever reconciles it.
-     */
-    describe("AreaLedger — a peer write inside the append window", () => {
-        function openStable(root) {
-            return AreaLedger.open({
-                rootDir: root,
-                journalSlug: "personal-vault",
-                layoutEpoch: 1,
-                areaIds: ["root:alpha", "root:beta"],
-                resolveArea: (key) => key.startsWith("alpha/") ? "root:alpha" : key.startsWith("beta/") ? "root:beta" : undefined,
-                // Low enough that the peer's own append publishes a new generation.
-                // That is the shape that actually loses the row: this process's durable
-                // append then refreshes by RECOVERY, which hands its area state a fresh
-                // row map detached from the warm packed aggregate, so the peer's record
-                // never writes through into it.
-                maxRecordsBeforeCompaction: 2,
-            });
-        }
-        /**
-         * Commit `peerDelta` from another ledger inside this process's own durable
-         * append — after `append()` has brought its warm aggregate current, before
-         * the area lock is taken. Both durable entry points are intercepted: a
-         * single-area delta appends directly, a metadata-bearing one batches.
-         */
-        function appendWithPeerWriteInFlight(ledger, peer, peerDelta, ownDelta) {
-            const originalAppend = StateStore.prototype.append;
-            const originalBatch = StateStore.appendBatch;
-            let injected = false;
-            const injectOnce = () => {
-                if (injected)
-                    return;
-                injected = true;
-                peer.append(peerDelta);
-            };
-            const appendSpy = vi.spyOn(StateStore.prototype, "append");
-            appendSpy.mockImplementation(function (type, payload, flags) {
-                injectOnce();
-                return originalAppend.call(this, type, payload, flags);
-            });
-            const batchSpy = vi.spyOn(StateStore, "appendBatch");
-            batchSpy.mockImplementation(((entries) => {
-                injectOnce();
-                return originalBatch.call(StateStore, entries);
-            }));
-            try {
-                ledger.append(ownDelta);
-            }
-            finally {
-                appendSpy.mockRestore();
-                batchSpy.mockRestore();
-            }
-            expect(injected).toBe(true);
-        }
-        it("keeps the peer's row in the same area visible to later reads", () => {
-            const root = makeRoot();
-            const ledger = openStable(root);
-            const peer = openStable(root);
-            ledger.append({ upserts: { "alpha/seed.md": entry(1) } });
-            // Warm the aggregate cache: the shortcut being tested only runs with one.
-            expect(ledger.read().files["alpha/seed.md"]).toMatchObject({ size: 1 });
-            appendWithPeerWriteInFlight(ledger, peer, { upserts: { "alpha/from-peer.md": entry(2) } }, { upserts: { "alpha/mine.md": entry(3) } });
-            const files = ledger.read().files;
-            expect(files["alpha/mine.md"]).toMatchObject({ size: 3 });
-            expect(files["alpha/from-peer.md"]).toMatchObject({ size: 2 });
-            // Another read must not need a second chance to see it.
-            expect(ledger.read().files["alpha/from-peer.md"]).toMatchObject({ size: 2 });
-            // And the peer row is genuinely durable, not a cache artefact.
-            expect(openStable(root).read().files["alpha/from-peer.md"]).toMatchObject({ size: 2 });
-        });
-        it("keeps a peer's delete of a row this process is not touching", () => {
-            const root = makeRoot();
-            const ledger = openStable(root);
-            const peer = openStable(root);
-            ledger.append({ upserts: { "alpha/seed.md": entry(1), "alpha/doomed.md": entry(4) } });
-            expect(ledger.read().files["alpha/doomed.md"]).toMatchObject({ size: 4 });
-            appendWithPeerWriteInFlight(ledger, peer, { deletes: ["alpha/doomed.md"] }, { upserts: { "alpha/mine.md": entry(3) } });
-            const files = ledger.read().files;
-            expect(files["alpha/mine.md"]).toMatchObject({ size: 3 });
-            expect(files["alpha/doomed.md"]).toBeUndefined();
-        });
-        it("keeps a peer's row when this process commits a metadata-bearing transaction", () => {
-            const root = makeRoot();
-            const ledger = openStable(root);
-            const peer = openStable(root);
-            ledger.append({ upserts: { "alpha/seed.md": entry(1) } });
-            expect(ledger.read().files["alpha/seed.md"]).toMatchObject({ size: 1 });
-            appendWithPeerWriteInFlight(ledger, peer, { upserts: { "alpha/from-peer-tx.md": entry(5) } }, { upserts: { "alpha/mine.md": entry(3) }, metadata: { lastSync: "t1" } });
-            const journal = ledger.read();
-            expect(journal.lastSync).toBe("t1");
-            expect(journal.files["alpha/mine.md"]).toMatchObject({ size: 3 });
-            expect(journal.files["alpha/from-peer-tx.md"]).toMatchObject({ size: 5 });
-        });
-    });
-}
-//# sourceMappingURL=area-ledger.test.js.map