@indigoai-us/hq-cloud 6.18.44-alpha.48 → 6.18.44-alpha.49

package/dist/journal-store.test.js

@@ -0,0 +1,1227 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getJournalPath, journalDeltaForTest, journalRows, listJournals, openJournalStoreSession, openJournalStoreSessionAsync, PERSONAL_VAULT_JOURNAL_SLUG, JournalStore, openJournalStateStoreForMigration, readJournal, readJournalForPass, readJournalScoped, disposeScopedJournalStores, repairJournalState, closeCachedAreaJournalMigration, writeJournal, setJournalSnapshotEncoderForTest, } from "./journal.js";
+import { decodeV3JournalSnapshot } from "./journal-snapshot-decoder.js";
+import { JournalRowStore } from "./journal-row-store.js";
+import { acquireGc, collectGarbage, usedBytes } from "./journal-snapshot-memory-helpers.js";
+import { getStateStoreSnapshotRecoveryCountForTest, resetStateStoreSnapshotRecoveryCountForTest, StateStoreCorruptionError, } from "./sync/state-store.js";
+import { AreaLedgerMigration, areaLayoutManifestPath, readAreaLayoutState, setAreaLedgerMigrationTestHooksForTest } from "./sync/area-ledger-migration.js";
+import { AreaResolver } from "./sync/area-resolver.js";
+let stateDir = "";
+function entry(size = 1) {
+    return {
+        hash: `${size}`.repeat(64),
+        size,
+        syncedAt: "2026-08-25T00:00:00.000Z",
+        direction: "down",
+        remoteEtag: `etag-${size}`,
+        kind: "file",
+    };
+}
+/** Deterministic PRNG so a failing packed-session sequence can be replayed from its seed. */
+function rng(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let value = state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+    };
+}
+function packedEntry(index) {
+    const entryValue = {
+        hash: index.toString(16).padStart(64, "0"),
+        size: index * 17.25,
+        syncedAt: new Date(1_700_000_000_000 + index).toISOString(),
+        direction: index % 2 === 0 ? "up" : "down",
+        remoteEtag: index.toString(16).padStart(32, "f"),
+        kind: index % 3 === 0 ? "symlink" : "file",
+        mtimeMs: 1_700_000_000_000 + index,
+        ctimeMs: 1_700_000_100_000 + index,
+    };
+    if (index % 4 === 0) {
+        entryValue.localDeleteIntent = {
+            version: 1,
+            remoteEtag: "e".repeat(32),
+            localHash: (index + 7).toString(16).padStart(64, "0"),
+            localKind: "file",
+        };
+    }
+    if (index % 5 === 0)
+        entryValue.localDiverges = true;
+    return entryValue;
+}
+function scanReference(rows, prefix) {
+    const normalizedPrefix = prefix.replace(/\/+$/, "");
+    return [...rows.entries()].filter(([key]) => (normalizedPrefix === "" || key === normalizedPrefix || key.startsWith(`${normalizedPrefix}/`)));
+}
+function journal(files) {
+    return { version: "2", lastSync: "initial", files, pulls: [] };
+}
+function generatedSnapshotJournal(seed) {
+    const random = rng(seed);
+    const files = {};
+    for (let index = 0; index < 48; index += 1) {
+        const canonicalHash = index % 2 === 0;
+        const canonicalEtag = index % 3 !== 0;
+        const canonicalSyncedAt = index % 5 !== 0;
+        const row = {
+            hash: canonicalHash ? `${seed.toString(16)}${index.toString(16)}`.padStart(64, "0") : `short-${seed}-${index}`,
+            size: Math.round(random() * 10_000) + index / 10,
+            syncedAt: canonicalSyncedAt
+                ? new Date(1_700_000_000_000 + seed * 1_000 + index).toISOString()
+                : `not-an-iso-${seed}-${index}`,
+            direction: index % 2 === 0 ? "up" : "down",
+        };
+        if (index % 2 === 0)
+            row.kind = index % 4 === 0 ? "symlink" : "file";
+        if (index % 3 === 0)
+            row.createdBySub = `author-${seed}-${index}`;
+        if (index % 4 === 0)
+            row.remoteEtag = canonicalEtag ? `${index}`.padStart(32, "a") : `multipart-${seed}-${index}-7`;
+        if (index % 5 === 0)
+            row.mtimeMs = 1_700_000_000_000 + index;
+        if (index % 6 === 0)
+            row.ctimeMs = 1_700_000_100_000 + index;
+        if (index % 7 === 0) {
+            row.removedAt = new Date(1_700_000_200_000 + index).toISOString();
+            row.removedReason = index % 14 === 0 ? "local-delete" : "scope_shrink";
+        }
+        if (index % 8 === 0) {
+            row.localDeleteIntent = {
+                version: 1,
+                remoteEtag: `${index}`.padStart(32, "b"),
+                localHash: `${seed}${index}`.padStart(64, "c"),
+                localKind: index % 16 === 0 ? "symlink" : "file",
+            };
+        }
+        if (index % 9 === 0)
+            row.outOfScopeProtected = index % 18 === 0;
+        if (index % 10 === 0)
+            row.skillMetadataPending = index % 20 === 0;
+        if (index % 11 === 0)
+            row.localDiverges = index % 22 === 0;
+        files[`scope-${seed}/nested-${index % 6}/row-${index}.md`] = row;
+    }
+    return {
+        version: "2",
+        lastSync: new Date(1_700_001_000_000 + seed).toISOString(),
+        files,
+        pulls: [{
+                pullId: `pull-${seed}`,
+                companyUid: `company-${seed}`,
+                startedAt: new Date(1_700_001_500_000 + seed).toISOString(),
+                completedAt: new Date(1_700_002_000_000 + seed).toISOString(),
+                syncMode: "all",
+                prefixSet: [`scope-${seed}`],
+                scopeChangeDetected: seed % 2 === 0,
+                orphansRemoved: seed,
+                orphansBlocked: seed + 1,
+            }],
+    };
+}
+function parseSnapshotWithWholePayloadJson(store) {
+    const snapshotPath = path.join(store.stateDir, `snapshot-${store.getGeneration()}.bin`);
+    const bytes = fs.readFileSync(snapshotPath);
+    const payloadLength = bytes.readUInt32BE(16);
+    return JSON.parse(bytes.subarray(52, 52 + payloadLength).toString("utf8"));
+}
+function rewriteJournalSnapshotPayload(store, payload) {
+    const snapshotPath = path.join(store.stateDir, `snapshot-${store.getGeneration()}.bin`);
+    const existing = fs.readFileSync(snapshotPath);
+    const header = Buffer.from(existing.subarray(0, 52));
+    header.writeUInt32BE(payload.length, 16);
+    const checksum = crypto.createHash("sha256").update(header).update(payload).digest();
+    fs.writeFileSync(snapshotPath, Buffer.concat([header, payload, checksum]));
+}
+function decodeSnapshotPayload(payload) {
+    const bytes = Buffer.from(payload, "utf8");
+    return decodeV3JournalSnapshot(Object.assign([bytes], { byteLength: bytes.length }));
+}
+function canonicalJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string" || typeof value === "number") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+}
+function writeLayoutState(state, slug) {
+    const body = canonicalJson(state);
+    const envelope = { checksum: crypto.createHash("sha256").update(body).digest("hex"), state };
+    fs.writeFileSync(areaLayoutManifestPath(stateDir, slug), `${canonicalJson(envelope)}\n`);
+}
+function manyAreaLayout(count) {
+    return {
+        format: 1,
+        routerVersion: 1,
+        areas: [
+            ...Array.from({ length: count }, (_, index) => ({ id: `root:area-${index}`, prefixes: [`area-${index}`], paths: [] })),
+            { id: "root:@files", prefixes: [], paths: [], rootFiles: true },
+        ],
+    };
+}
+const areaLayout = {
+    format: 1,
+    routerVersion: 1,
+    areas: [
+        { id: "root:alpha", prefixes: ["alpha"], paths: [] },
+        { id: "root:beta", prefixes: ["beta"], paths: [] },
+        { id: "root:@files", prefixes: [], paths: [], rootFiles: true },
+    ],
+};
+beforeEach(() => {
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-journal-store-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    resetStateStoreSnapshotRecoveryCountForTest();
+    setAreaLedgerMigrationTestHooksForTest({ now: () => 0 });
+});
+afterEach(() => {
+    setAreaLedgerMigrationTestHooksForTest(undefined);
+    closeCachedAreaJournalMigration("area-cache");
+    disposeScopedJournalStores();
+    delete process.env.HQ_STATE_DIR;
+    fs.rmSync(stateDir, { recursive: true, force: true });
+});
+describe("JournalStore", () => {
+    it.each([
+        ["a root object trailing comma", '{"lastRecordSequence":0,}'],
+        ["a nested journal object trailing comma", '{"lastRecordSequence":0,"state":{"journal":{"version":"2",}}}'],
+        ["a files entry trailing comma", '{"lastRecordSequence":0,"state":{"journal":{"version":"2","files":{"a.md":{"hash":"1111111111111111111111111111111111111111111111111111111111111111","size":1,"syncedAt":"2026-08-25T00:00:00.000Z","direction":"down",}}}}}'],
+        ["a pulls array trailing comma", '{"lastRecordSequence":0,"state":{"journal":{"version":"2","files":{},"pulls":[{},]}}}'],
+        ["an uncaptured array trailing comma", '{"lastRecordSequence":0,"metadata":[1,]}'],
+        ["an empty object comma", "{,}"],
+        ["an empty array comma", "[,]"],
+    ])("rejects %s with the same SyntaxError as JSON.parse", (_name, payload) => {
+        expect(() => JSON.parse(payload)).toThrow(SyntaxError);
+        expect(() => decodeSnapshotPayload(payload)).toThrow(SyntaxError);
+    });
+    it("accepts empty objects and arrays as property values", () => {
+        const emptyObjectPayload = '{"lastRecordSequence":0,"state":{"journal":{"version":"2","files":{},"metadata":{}}}}';
+        const emptyArrayPayload = '{"lastRecordSequence":0,"state":{"journal":{"version":"2","files":{},"pulls":[]}}}';
+        expect(() => decodeSnapshotPayload(emptyObjectPayload)).not.toThrow();
+        expect(JSON.parse(JSON.stringify(decodeSnapshotPayload(emptyArrayPayload)))).toEqual(JSON.parse(emptyArrayPayload));
+    });
+    it("round-trips a well-formed snapshot through the streaming decoder", () => {
+        const expected = {
+            lastRecordSequence: 0,
+            state: { journal: generatedSnapshotJournal(65) },
+        };
+        const payload = JSON.stringify(expected);
+        expect(JSON.parse(JSON.stringify(decodeSnapshotPayload(payload)))).toEqual(expected);
+    });
+    it("streams v3 snapshots into packed rows with parity against whole-payload JSON.parse", () => {
+        setJournalSnapshotEncoderForTest(null);
+        try {
+            for (let seed = 1; seed <= 64; seed += 1) {
+                const slug = `snapshot-parity-${seed}`;
+                writeJournal(slug, generatedSnapshotJournal(seed));
+                const writer = openJournalStateStoreForMigration(slug);
+                writer.compact();
+                const oldPayload = parseSnapshotWithWholePayloadJson(writer);
+                const decoded = readJournal(slug);
+                expect(JSON.parse(JSON.stringify(decoded)), `seed ${seed}`).toEqual(oldPayload.state.journal);
+            }
+        }
+        finally {
+            setJournalSnapshotEncoderForTest(undefined);
+        }
+    }, 60_000);
+    it.each([
+        ["invalid JSON", (store) => {
+                rewriteJournalSnapshotPayload(store, Buffer.from('{"lastRecordSequence":0,"state":{"journal":{"files":{"a":', "utf8"));
+            }],
+        ["invalid state payload", (store) => {
+                rewriteJournalSnapshotPayload(store, Buffer.from('{"lastRecordSequence":0,"state":{"journal":{"files":[]}}}', "utf8"));
+            }],
+        ["torn payload", (store) => {
+                fs.truncateSync(path.join(store.stateDir, `snapshot-${store.getGeneration()}.bin`), 53);
+            }],
+        ["bad checksum", (store) => {
+                const snapshotPath = path.join(store.stateDir, `snapshot-${store.getGeneration()}.bin`);
+                const bytes = fs.readFileSync(snapshotPath);
+                bytes[bytes.length - 1] ^= 0xff;
+                fs.writeFileSync(snapshotPath, bytes);
+            }],
+        ["scope digest mismatch", (store) => {
+                const snapshotPath = path.join(store.stateDir, `snapshot-${store.getGeneration()}.bin`);
+                const bytes = fs.readFileSync(snapshotPath);
+                bytes[20] ^= 0xff;
+                fs.writeFileSync(snapshotPath, bytes);
+            }],
+    ])("keeps streamed v3 %s classified as StateStoreCorruptionError", (_name, corrupt) => {
+        const slug = "streamed-snapshot-corruption";
+        writeJournal(slug, generatedSnapshotJournal(1));
+        const store = openJournalStateStoreForMigration(slug);
+        store.compact();
+        for (const name of fs.readdirSync(store.stateDir)) {
+            if (!/^(snapshot|wal)-\d+\.bin$/.test(name))
+                continue;
+            if (name === `snapshot-${store.getGeneration()}.bin` || name === `wal-${store.getGeneration()}.bin`)
+                continue;
+            fs.rmSync(path.join(store.stateDir, name));
+        }
+        corrupt(store);
+        expect(() => readJournal(slug)).toThrow(StateStoreCorruptionError);
+    });
+    it("routes committed area authority through reverse-shadowed sessions and writers", () => {
+        writeJournal("personal-vault", journal({ "alpha/before.md": entry(1) }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: "personal-vault",
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration("personal-vault"),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        const session = openJournalStoreSession("personal-vault");
+        const concurrent = openJournalStoreSession("personal-vault");
+        session.applyDelta({ upserts: { "beta/from-session.md": entry(2) } });
+        concurrent.applyDelta({ upserts: { "alpha/from-concurrent-session.md": entry(4) } });
+        const writer = readJournal("personal-vault");
+        writer.files["alpha/from-writer.md"] = entry(3);
+        writeJournal("personal-vault", writer);
+        expect(readJournal("personal-vault").files).toMatchObject({
+            "alpha/before.md": { size: 1 },
+            "beta/from-session.md": { size: 2 },
+            "alpha/from-writer.md": { size: 3 },
+            "alpha/from-concurrent-session.md": { size: 4 },
+        });
+        // The old shard remains a rollback mirror, not an unobserved divergent copy.
+        expect(openJournalStateStoreForMigration("personal-vault").getState().journal.files)
+            .toMatchObject({
+            "beta/from-session.md": { size: 2 },
+            "alpha/from-writer.md": { size: 3 },
+            "alpha/from-concurrent-session.md": { size: 4 },
+        });
+    });
+    it("shares one area bridge across repeated opens and invalidates it on layout, phase, and explicit close", () => {
+        const slug = "area-cache";
+        const layout = manyAreaLayout(100);
+        writeJournal(slug, journal({ "area-0/seed.md": entry(1) }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(layout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver(10_000).phase).toBe("area-authoritative");
+        const opened = [];
+        setAreaLedgerMigrationTestHooksForTest({ afterOpen: (bridge) => opened.push(bridge) });
+        resetStateStoreSnapshotRecoveryCountForTest();
+        expect(readJournal(slug).files["area-0/seed.md"]).toMatchObject({ size: 1 });
+        expect(openJournalStoreSession(slug).get("area-0/seed.md")).toMatchObject({ size: 1 });
+        const recoveriesAfterColdOpen = getStateStoreSnapshotRecoveryCountForTest();
+        // The bridge opens the 101 data areas, the always-configured overflow area
+        // (UNROUTED_AREA_ID — one per ledger, whether or not anything lands in it),
+        // and @meta. It must not also retain a full legacy journal StateStore
+        // merely to serve post-cutover reads.
+        expect(recoveriesAfterColdOpen).toBe(103);
+        expect(readJournal(slug).files["area-0/seed.md"]).toMatchObject({ size: 1 });
+        // A warm open does no new snapshot recovery whether the layout is small
+        // or contains 100 areas: it reuses the bridge opened above.
+        expect(getStateStoreSnapshotRecoveryCountForTest()).toBe(recoveriesAfterColdOpen);
+        // One bridge means each of the 101 data areas, the overflow area, and @meta
+        // is opened only once, instead of reopening all 103 scopes for every
+        // journal call.
+        expect(opened).toHaveLength(1);
+        expect(opened[0].openedAreaStoresForTest()).toHaveLength(103);
+        const first = opened[0];
+        const beforeLayoutChange = readAreaLayoutState(stateDir, slug);
+        writeLayoutState({ ...beforeLayoutChange, activeLayoutEpoch: "next-layout-epoch" }, slug);
+        readJournal(slug);
+        expect(opened).toHaveLength(2);
+        expect(opened[1]).not.toBe(first);
+        closeCachedAreaJournalMigration(slug);
+        readJournal(slug);
+        expect(opened).toHaveLength(3);
+        const beforePhaseChange = readAreaLayoutState(stateDir, slug);
+        writeLayoutState({ ...beforePhaseChange, phase: "legacy-authoritative" }, slug);
+        expect(readJournal(slug).files["area-0/seed.md"]).toMatchObject({ size: 1 });
+        expect(opened).toHaveLength(3);
+        writeLayoutState(beforePhaseChange, slug);
+        readJournal(slug);
+        expect(opened).toHaveLength(4);
+        closeCachedAreaJournalMigration(slug);
+    }, 60_000);
+    it("reads only K detached rows for an area-authoritative scoped pass", () => {
+        const slug = "area-scoped-snapshot";
+        const files = Object.fromEntries(Array.from({ length: 1_000 }, (_, index) => [`alpha/unselected-${index}.md`, entry(index)]));
+        files["alpha/selected.md"] = entry(1_001);
+        files["beta/selected.md"] = entry(1_002);
+        writeJournal(slug, journal(files));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver(10_000).phase).toBe("area-authoritative");
+        const clone = vi.spyOn(globalThis, "structuredClone");
+        const scoped = readJournalScoped(slug, ["alpha/selected.md", "beta/selected.md"]);
+        // Metadata/recovery bookkeeping has a small fixed cost; cloned row maps
+        // and clone calls remain bounded by K, never the 1,000 unrelated rows.
+        const selectedKeys = ["alpha/selected.md", "beta/selected.md"];
+        expect(clone.mock.calls.length).toBeLessThanOrEqual(4 + 4 * selectedKeys.length);
+        for (const [value] of clone.mock.calls) {
+            if (typeof value !== "object" || value === null)
+                continue;
+            const object = value;
+            expect(Object.keys(object.files ?? object.journal?.files ?? {}).length)
+                .toBeLessThanOrEqual(selectedKeys.length);
+        }
+        expect(Object.keys(scoped.files).sort()).toEqual([
+            "alpha/selected.md",
+            "beta/selected.md",
+        ]);
+        scoped.files["alpha/selected.md"] = { ...scoped.files["alpha/selected.md"], size: 99_999 };
+        clone.mockRestore();
+        // The caller owns the scoped snapshot; mutating it cannot alter ledger
+        // state or the next scoped reader.
+        expect(readJournalScoped(slug, ["alpha/selected.md"]).files["alpha/selected.md"])
+            .toMatchObject({ size: 1_001 });
+        closeCachedAreaJournalMigration(slug);
+    }, 30_000);
+    it("adds descendants of scoped delete roots without opening unrelated areas", () => {
+        const slug = "area-scoped-delete-root";
+        writeJournal(slug, journal({
+            "alpha/deleted/one.md": entry(1),
+            "alpha/deleted/nested/two.md": entry(2),
+            "alpha/sibling.md": entry(3),
+            "beta/untouched.md": entry(4),
+        }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        const opened = [];
+        setAreaLedgerMigrationTestHooksForTest({ afterOpen: (bridge) => opened.push(bridge) });
+        const scoped = readJournalScoped(slug, [], ["alpha/deleted"]);
+        expect(Object.keys(scoped.files).sort()).toEqual([
+            "alpha/deleted/nested/two.md",
+            "alpha/deleted/one.md",
+        ]);
+        expect(opened).toHaveLength(1);
+        expect(opened[0].openedAreaStoresForTest()).toEqual(["@meta", "root:alpha"]);
+        closeCachedAreaJournalMigration(slug);
+    });
+    describe("legacy aggregate store scoped reads", () => {
+        // A watch-mode scoped push reads K named rows plus the descendants of its
+        // delete roots. On the legacy (pre-area) store this used to walk every
+        // aggregate row and test each one against every delete root, and it also
+        // re-baselined (deep-cloned) the whole aggregate on the way in. With a
+        // 73k-row personal vault and a 10,000-path warm-up catch-up batch that is
+        // rows x roots = ~7e8 prefix tests per pass — the runner sat at 60% CPU for
+        // an hour after every start on the affected Mac. Both costs must be bounded
+        // by K + roots, with a single linear pass over rows only when roots exist.
+        it("clones only the named rows and never re-baselines the whole aggregate", () => {
+            const slug = "legacy-scoped-keys";
+            const files = Object.fromEntries(Array.from({ length: 20_000 }, (_, index) => [`alpha/row-${index}.md`, entry(index)]));
+            files["alpha/selected.md"] = entry(20_001);
+            files["beta/selected.md"] = entry(20_002);
+            writeJournal(slug, journal(files));
+            readJournal(slug); // warm, the way a running daemon holds it
+            const clone = vi.spyOn(globalThis, "structuredClone");
+            const scoped = readJournalScoped(slug, [
+                "alpha/selected.md",
+                "beta/selected.md",
+                "alpha/selected.md",
+                "gamma/missing.md",
+            ]);
+            const selectedKeys = ["alpha/selected.md", "beta/selected.md"];
+            expect(clone.mock.calls.length).toBeLessThanOrEqual(4 + 2 * selectedKeys.length);
+            for (const [value] of clone.mock.calls) {
+                if (typeof value !== "object" || value === null)
+                    continue;
+                const object = value;
+                expect(Object.keys(object.files ?? object.journal?.files ?? {}).length)
+                    .toBeLessThanOrEqual(selectedKeys.length);
+            }
+            clone.mockRestore();
+            expect(Object.keys(scoped.files).sort()).toEqual(selectedKeys);
+            scoped.files["alpha/selected.md"] = { ...scoped.files["alpha/selected.md"], size: 5 };
+            expect(readJournal(slug).files["alpha/selected.md"]).toMatchObject({ size: 20_001 });
+            expect(readJournalScoped(slug, ["alpha/selected.md"]).files["alpha/selected.md"])
+                .toMatchObject({ size: 20_001 });
+        });
+        it("isolates the retained scoped projection from uncommitted full-pass rows", () => {
+            const slug = "legacy-scoped-full-pass-isolation";
+            writeJournal(slug, journal({
+                "scope/durable-delete.md": entry(1),
+                "scope/scoped-writer.md": entry(2),
+            }));
+            const fullPass = readJournal(slug);
+            fullPass.files["scope/uncommitted-upsert.md"] = entry(3);
+            delete fullPass.files["scope/durable-delete.md"];
+            const fullPassDelta = journalDeltaForTest(fullPass);
+            const scoped = readJournalScoped(slug, [
+                "scope/durable-delete.md",
+                "scope/uncommitted-upsert.md",
+                "scope/scoped-writer.md",
+            ]);
+            // A scoped reader sees only what reached durable storage, never a
+            // full-pass writer's private, uncommitted overlay.
+            expect(scoped.files["scope/durable-delete.md"]).toMatchObject({ size: 1 });
+            expect(scoped.files["scope/uncommitted-upsert.md"]).toBeUndefined();
+            scoped.files["scope/scoped-writer.md"] = entry(4);
+            writeJournal(slug, scoped);
+            // A cached scoped commit must not alter either the live full pass's rows
+            // or the dirty log that describes its still-uncommitted mutation.
+            expect(fullPass.files["scope/uncommitted-upsert.md"]).toMatchObject({ size: 3 });
+            expect(fullPass.files["scope/durable-delete.md"]).toBeUndefined();
+            expect(fullPass.files["scope/scoped-writer.md"]).toMatchObject({ size: 2 });
+            expect(journalDeltaForTest(fullPass)).toEqual(fullPassDelta);
+        });
+        it("keeps the personal scoped projection hot across a multi-locator warm-up", () => {
+            const personalKey = "personal/warm-target.md";
+            const warmupSlugs = [
+                PERSONAL_VAULT_JOURNAL_SLUG,
+                "personal",
+                "indigo",
+                "companyx",
+                "companyy",
+                "companyz",
+            ];
+            for (const slug of warmupSlugs) {
+                writeJournal(slug, journal({
+                    [slug === PERSONAL_VAULT_JOURNAL_SLUG ? personalKey : `${slug}/seed.md`]: entry(1),
+                }));
+            }
+            // The preceding full pass has already paid for the personal projection.
+            readJournal(PERSONAL_VAULT_JOURNAL_SLUG);
+            listJournals(); // The watcher warm-up enumerates every locator.
+            resetStateStoreSnapshotRecoveryCountForTest();
+            const scoped = readJournalScoped(PERSONAL_VAULT_JOURNAL_SLUG, [personalKey]);
+            scoped.files[personalKey] = entry(2);
+            writeJournal(PERSONAL_VAULT_JOURNAL_SLUG, scoped);
+            expect(getStateStoreSnapshotRecoveryCountForTest()).toBe(0);
+            expect(readJournalScoped(PERSONAL_VAULT_JOURNAL_SLUG, [personalKey]).files[personalKey])
+                .toMatchObject({ size: 2 });
+        });
+        it("releases a retained legacy projection after its slug becomes area-authoritative", () => {
+            const slug = "legacy-projection-area-cutover";
+            writeJournal(slug, journal({ "alpha/seed.md": entry(1) }));
+            readJournal(slug); // Retain the legacy keyed projection.
+            const dispose = vi.spyOn(JournalStore.prototype, "dispose");
+            try {
+                const migration = new AreaLedgerMigration({
+                    rootDir: stateDir,
+                    journalSlug: slug,
+                    resolver: new AreaResolver(areaLayout),
+                    legacyStore: openJournalStateStoreForMigration(slug),
+                });
+                expect(migration.cutOver().phase).toBe("area-authoritative");
+                // Entering the authoritative read path releases the now-stale v3
+                // projection instead of retaining it alongside area storage.
+                expect(readJournal(slug).files["alpha/seed.md"]).toMatchObject({ size: 1 });
+                expect(dispose).toHaveBeenCalledTimes(1);
+            }
+            finally {
+                dispose.mockRestore();
+            }
+        });
+        it("persists lastSync and pulls through a cached scoped write after reopen", () => {
+            const slug = "legacy-scoped-metadata";
+            const key = "scope/selected.md";
+            writeJournal(slug, journal({ [key]: entry(1) }));
+            readJournal(slug); // Establish the cached delta writer.
+            const scoped = readJournalScoped(slug, [key]);
+            const expected = generatedSnapshotJournal(97);
+            scoped.files[key] = entry(2);
+            scoped.lastSync = expected.lastSync;
+            scoped.pulls = expected.pulls;
+            writeJournal(slug, scoped);
+            disposeScopedJournalStores();
+            const reopened = readJournal(slug);
+            expect(reopened.files[key]).toMatchObject({ size: 2 });
+            expect(reopened.lastSync).toBe(expected.lastSync);
+            expect(reopened.pulls).toEqual(expected.pulls);
+        });
+        it("matches delete roots by ancestor lookup instead of testing every row against every root", () => {
+            const slug = "legacy-scoped-roots";
+            const files = Object.fromEntries(Array.from({ length: 5_000 }, (_, index) => [`alpha/keep-${index}.md`, entry(index)]));
+            files["alpha/deleted"] = entry(1);
+            files["alpha/deleted/one.md"] = entry(2);
+            files["alpha/deleted/nested/two.md"] = entry(3);
+            files["alpha/deleted-sibling.md"] = entry(4); // shares the prefix, not the directory
+            files["beta/gone/file.md"] = entry(5); // a file named directly as a delete root
+            files["beta/gone/file.md.bak"] = entry(6);
+            writeJournal(slug, journal(files));
+            readJournal(slug);
+            const roots = [
+                "alpha/deleted",
+                "beta/gone/file.md",
+                ...Array.from({ length: 1_998 }, (_, index) => `zeta/never-${index}`),
+            ];
+            let rootReads = 0;
+            const observedRoots = new Proxy(roots, {
+                get(target, property, receiver) {
+                    rootReads += 1;
+                    return Reflect.get(target, property, receiver);
+                },
+            });
+            const scoped = readJournalScoped(slug, ["alpha/keep-1.md"], observedRoots);
+            expect(Object.keys(scoped.files).sort()).toEqual([
+                "alpha/deleted",
+                "alpha/deleted/nested/two.md",
+                "alpha/deleted/one.md",
+                "alpha/keep-1.md",
+                "beta/gone/file.md",
+            ]);
+            // Old shape: 5,006 rows x 2,000 roots = ~1e7 reads. Reading the root list
+            // a handful of times over is fine; reading it once per row is not.
+            expect(rootReads).toBeLessThan(roots.length * 8);
+        });
+        it("still treats the empty delete root as the whole aggregate", () => {
+            const slug = "legacy-scoped-all";
+            writeJournal(slug, journal({
+                "alpha/one.md": entry(1),
+                "beta/two.md": entry(2),
+            }));
+            const scoped = readJournalScoped(slug, [], ["", "alpha"]);
+            expect(Object.keys(scoped.files).sort()).toEqual(["alpha/one.md", "beta/two.md"]);
+            scoped.files["beta/two.md"] = { ...scoped.files["beta/two.md"], size: 9 };
+            expect(readJournal(slug).files["beta/two.md"]).toMatchObject({ size: 2 });
+        });
+        it("refreshes a retained scoped store after an external append and preserves rows outside its baseline", () => {
+            const slug = "legacy-scoped-external-writer";
+            writeJournal(slug, journal({
+                "scope/selected.md": entry(1),
+                "scope/external-delete.md": entry(2),
+                "scope/outside-baseline.md": entry(3),
+            }));
+            readJournal(slug); // Retain the runner projection before another process writes.
+            // This writer owns a separate in-memory projection, as another hq
+            // process would. It publishes an upsert and a delete while the retained
+            // runner projection is idle.
+            const external = openJournalStoreSession(slug);
+            external.applyDelta({
+                upserts: { "scope/from-external.md": entry(4) },
+                deletes: ["scope/external-delete.md"],
+            });
+            const scoped = readJournalScoped(slug, [
+                "scope/selected.md",
+                "scope/external-delete.md",
+                "scope/from-external.md",
+            ]);
+            expect(scoped.files["scope/from-external.md"]).toMatchObject({ size: 4 });
+            expect(scoped.files["scope/external-delete.md"]).toBeUndefined();
+            scoped.files["scope/selected.md"] = entry(5);
+            // A targeted baseline only owns its named rows. Its delta must never
+            // turn the omitted row into a delete merely because the scoped caller
+            // did not receive it.
+            expect(journalDeltaForTest(scoped).deletes).toEqual([]);
+            writeJournal(slug, scoped);
+            const reopened = openJournalStoreSession(slug);
+            expect(reopened.get("scope/selected.md")).toMatchObject({ size: 5 });
+            expect(reopened.get("scope/from-external.md")).toMatchObject({ size: 4 });
+            expect(reopened.get("scope/external-delete.md")).toBeUndefined();
+            expect(reopened.get("scope/outside-baseline.md")).toMatchObject({ size: 3 });
+        });
+    });
+    it("keeps a warm area-authoritative observer fresh after an independent writer commits", () => {
+        const slug = "area-writer-freshness";
+        writeJournal(slug, journal({ "alpha/before.md": entry(1) }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        const observer = openJournalStoreSession(slug);
+        expect(observer.get("alpha/before.md")).toMatchObject({ size: 1 });
+        // Constructing the writer directly ensures it owns a separate in-memory
+        // AreaLedger from the bridge cached by the observing JournalStore.
+        const independentWriter = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        independentWriter.reverseShadow({
+            upserts: { "beta/from-independent-writer.md": entry(2) },
+            deletes: [],
+        });
+        observer.refresh();
+        expect(observer.get("beta/from-independent-writer.md")).toMatchObject({ size: 2 });
+        expect(readJournal(slug).files["beta/from-independent-writer.md"]).toMatchObject({ size: 2 });
+        closeCachedAreaJournalMigration(slug);
+    });
+    // openJournalStoreSessionAsync is the open a watcher's filesystem callback
+    // may start. The callback returns as soon as the call does, so nothing the
+    // open reads — the area layout, the aggregate of every area ledger, a
+    // legacy journal to seed from — may happen before the first yield. A write
+    // committed right after the call, before the caller yields, proves the
+    // order: only an open that has not read anything yet can see it.
+    it("openJournalStoreSessionAsync yields before it reads an authoritative area ledger", async () => {
+        const slug = "area-async-open-yields";
+        writeJournal(slug, journal({ "alpha/before.md": entry(1) }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        const opening = openJournalStoreSessionAsync(slug);
+        const independentWriter = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        independentWriter.reverseShadow({
+            upserts: { "beta/committed-after-the-call.md": entry(2) },
+            deletes: [],
+        });
+        const session = await opening;
+        expect(session.get("alpha/before.md")).toMatchObject({ size: 1 });
+        expect(session.get("beta/committed-after-the-call.md")).toMatchObject({ size: 2 });
+        session.dispose();
+        closeCachedAreaJournalMigration(slug);
+    });
+    it("openJournalStoreSessionAsync yields before it seeds from a legacy journal file", async () => {
+        const slug = "legacy-async-open-yields";
+        const legacyPath = getJournalPath(slug);
+        fs.mkdirSync(path.dirname(legacyPath), { recursive: true });
+        fs.writeFileSync(legacyPath, JSON.stringify(journal({ "alpha/before.md": entry(1) })));
+        const opening = openJournalStoreSessionAsync(slug);
+        fs.writeFileSync(legacyPath, JSON.stringify(journal({
+            "alpha/before.md": entry(1),
+            "beta/written-after-the-call.md": entry(2),
+        })));
+        const session = await opening;
+        expect(session.get("beta/written-after-the-call.md")).toMatchObject({ size: 2 });
+        session.dispose();
+    });
+    it("does not rebuild a warm area-authoritative keyed projection when the aggregate is unchanged", () => {
+        const slug = "area-warm-refresh";
+        const files = Object.fromEntries(Array.from({ length: 1_000 }, (_, index) => [`alpha/${index}.md`, entry(index)]));
+        writeJournal(slug, journal(files));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver(10_000).phase).toBe("area-authoritative");
+        const session = openJournalStoreSession(slug);
+        const replace = vi.spyOn(session, "replaceFromJournal");
+        const clone = vi.spyOn(globalThis, "structuredClone");
+        session.refresh();
+        expect(replace).not.toHaveBeenCalled();
+        expect(clone).not.toHaveBeenCalled();
+        clone.mockRestore();
+        replace.mockRestore();
+    }, 30_000);
+    it("does not rebuild its keyed projection after its own area-authoritative delta", () => {
+        const slug = "area-local-write-refresh";
+        writeJournal(slug, journal({ "alpha/seed.md": entry(1) }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        const session = openJournalStoreSession(slug);
+        session.applyDelta({ upserts: { "beta/local.md": entry(2) } });
+        const replace = vi.spyOn(session, "replaceFromJournal");
+        const clone = vi.spyOn(globalThis, "structuredClone");
+        session.refresh();
+        expect(replace).not.toHaveBeenCalled();
+        expect(clone).not.toHaveBeenCalled();
+        clone.mockRestore();
+        replace.mockRestore();
+        expect(session.get("beta/local.md")).toMatchObject({ size: 2 });
+        closeCachedAreaJournalMigration(slug);
+    });
+    it("refreshes an area-backed session after a local delta and independent append", () => {
+        const slug = "area-local-then-independent-refresh";
+        writeJournal(slug, journal({ "alpha/seed.md": entry(1) }));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        const session = openJournalStoreSession(slug);
+        session.applyDelta({ upserts: { "beta/local.md": entry(2) } });
+        const independentWriter = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        independentWriter.reverseShadow({ upserts: { "alpha/from-independent-writer.md": entry(3) } });
+        session.refresh();
+        expect(session.get("beta/local.md")).toMatchObject({ size: 2 });
+        expect(session.get("alpha/from-independent-writer.md")).toMatchObject({ size: 3 });
+        closeCachedAreaJournalMigration(slug);
+    });
+    it("uses one cold recovery for a 40-unlink keyed fixture, then only keyed deltas", () => {
+        const files = Object.fromEntries(Array.from({ length: 40 }, (_, index) => [`knowledge/${index}.md`, entry(index + 1)]));
+        writeJournal("acme", journal(files));
+        resetStateStoreSnapshotRecoveryCountForTest();
+        const session = openJournalStoreSession("acme");
+        expect(getStateStoreSnapshotRecoveryCountForTest()).toBe(1);
+        for (let index = 0; index < 40; index++) {
+            session.refresh();
+            const key = `knowledge/${index}.md`;
+            const prior = session.get(key);
+            expect(prior).toBeDefined();
+            session.applyDelta({ upserts: { [key]: { ...prior, localDeleteIntent: {
+                            version: 1,
+                            remoteEtag: prior.remoteEtag,
+                            localHash: prior.hash,
+                            localKind: "file",
+                        } } } });
+        }
+        expect(getStateStoreSnapshotRecoveryCountForTest()).toBe(1);
+        expect(Object.values(readJournal("acme").files).every((row) => row.localDeleteIntent)).toBe(true);
+    });
+    it("interoperates with the existing writeJournal push/pull writer in both directions", () => {
+        writeJournal("acme", journal({ "a.md": entry(1) }));
+        const session = openJournalStoreSession("acme");
+        const pushWriter = readJournal("acme");
+        pushWriter.files["from-push.md"] = entry(2);
+        writeJournal("acme", pushWriter);
+        session.refresh();
+        expect(session.get("from-push.md")).toMatchObject({ size: 2 });
+        session.applyDelta({ upserts: { "from-session.md": entry(3) } });
+        expect(readJournal("acme").files["from-session.md"]).toMatchObject({ size: 3 });
+    });
+    it("falls back across a published generation change and heals a durable external append", () => {
+        writeJournal("acme", journal({ "a.md": entry(1) }));
+        const session = openJournalStoreSession("acme");
+        repairJournalState("acme");
+        const external = readJournal("acme");
+        external.files["after-generation.md"] = entry(4);
+        writeJournal("acme", external);
+        session.refresh();
+        expect(session.get("after-generation.md")).toMatchObject({ size: 4 });
+    });
+    it("rebuilds its projection before committing after another writer publishes a generation", () => {
+        writeJournal("acme", journal({ "before.md": entry(1) }));
+        const reader = openJournalStoreSession("acme");
+        const writer = openJournalStoreSession("acme");
+        writer.applyDelta({ upserts: { "before-compaction.md": entry(2) } });
+        repairJournalState("acme");
+        writer.applyDelta({ upserts: { "after-compaction.md": entry(3) } });
+        reader.applyDelta({ upserts: { "reader-commit.md": entry(4) } });
+        expect(reader.get("before-compaction.md")).toMatchObject({ size: 2 });
+        expect(reader.get("after-compaction.md")).toMatchObject({ size: 3 });
+        expect(reader.get("reader-commit.md")).toMatchObject({ size: 4 });
+    });
+    it("returns frozen rows and scans exact descendants without leaking its backing store", () => {
+        writeJournal("acme", journal({
+            "dir/a.md": entry(1),
+            "dir/nested/b.md": entry(2),
+            "other.md": entry(3),
+        }));
+        const session = openJournalStoreSession("acme");
+        const row = session.get("dir/a.md");
+        expect(Object.isFrozen(row)).toBe(true);
+        expect(() => { row.size = 99; }).toThrow(TypeError);
+        expect(session.get("dir/a.md")).toMatchObject({ size: 1 });
+        const scanned = session.scanPrefix("dir");
+        const scannedRows = Array.from(scanned);
+        expect(scannedRows.map(([key]) => key)).toEqual(["dir/a.md", "dir/nested/b.md"]);
+        expect(Object.isFrozen(scannedRows[0][1])).toBe(true);
+        expect(() => { scannedRows[0][1].size = 99; }).toThrow(TypeError);
+        expect(session.get("dir/a.md")).toMatchObject({ size: 1 });
+        session.applyDelta({ upserts: { "dir/a.md": { ...entry(1), localDeleteIntent: {
+                        version: 1, remoteEtag: "etag-1", localHash: "1".repeat(64), localKind: "file",
+                    } } } });
+        const nested = session.get("dir/a.md");
+        expect(() => { nested.localDeleteIntent.remoteEtag = "mutated"; }).toThrow();
+        expect(session.get("dir/a.md")?.localDeleteIntent?.remoteEtag).toBe("etag-1");
+    });
+    it("streams a 59,020-row full-pass scan without eagerly retaining every entry", () => {
+        const rowCount = 59_020;
+        const files = {};
+        for (let index = 0; index < rowCount; index += 1) {
+            files[`full-pass/${index % 400}/entry-${index}.md`] = packedEntry(index);
+        }
+        writeJournal("full-pass-streaming", journal(files));
+        const session = openJournalStoreSession("full-pass-streaming");
+        const materialize = vi.spyOn(JournalRowStore.prototype, "materialize");
+        try {
+            const scanned = session.scanPrefix("");
+            // A full-pass consumer must be able to begin work before every row has
+            // been materialized. The old array-returning API reached 59,020 calls
+            // here before returning control to its caller.
+            expect(materialize).toHaveBeenCalledTimes(0);
+            let count = 0;
+            for (const [key, row] of scanned) {
+                expect(key).toMatch(/^full-pass\//);
+                expect(row.size).toBeGreaterThanOrEqual(0);
+                count += 1;
+            }
+            expect(count).toBe(rowCount);
+            expect(session.rowCount()).toBe(rowCount);
+        }
+        finally {
+            materialize.mockRestore();
+            session.dispose();
+        }
+    }, 120_000);
+    it("releases full-pass scan entries after churn while preserving every no-op row", () => {
+        const rowCount = 59_020;
+        const slug = "full-pass-streaming-churn";
+        const files = {};
+        for (let index = 0; index < rowCount; index += 1) {
+            files[`full-pass/${index % 400}/entry-${index}.md`] = packedEntry(index);
+        }
+        writeJournal(slug, journal(files));
+        const collect = acquireGc();
+        collectGarbage(collect);
+        const baseline = usedBytes();
+        for (let pass = 0; pass < 3; pass += 1) {
+            const session = openJournalStoreSession(slug);
+            let seen = 0;
+            for (const _row of session.scanPrefix(""))
+                seen += 1;
+            expect(seen).toBe(rowCount);
+            session.dispose();
+        }
+        // Keep a pass alive after its first bounded unit of work, then measure
+        // again after every reference to that pass has been dropped.
+        let activeSession = openJournalStoreSession(slug);
+        let activeScan = activeSession.scanPrefix("");
+        let activeIterator = activeScan[Symbol.iterator]();
+        for (let index = 0; index < 32; index += 1) {
+            expect(activeIterator.next().done).toBe(false);
+        }
+        collectGarbage(collect);
+        const aliveBytes = usedBytes();
+        const aliveRetainedBytes = aliveBytes - baseline;
+        activeIterator = undefined;
+        activeScan = undefined;
+        activeSession.dispose();
+        activeSession = undefined;
+        collectGarbage(collect);
+        const releasedBytes = usedBytes();
+        const releasedRetainedBytes = releasedBytes - baseline;
+        console.info(`full-pass-scan-memory rows=${rowCount} churnPasses=3` +
+            ` baselineBytes=${baseline}` +
+            ` aliveBytes=${aliveBytes}` +
+            ` aliveRetainedBytes=${aliveRetainedBytes}` +
+            ` releasedBytes=${releasedBytes}` +
+            ` releasedRetainedBytes=${releasedRetainedBytes}`);
+        expect(releasedRetainedBytes).toBeLessThan(aliveRetainedBytes);
+        const noOpPass = readJournalForPass(slug);
+        const expectedKeys = new Set(journalRows(noOpPass).keys());
+        expect(expectedKeys.size).toBe(rowCount);
+        expect(journalDeltaForTest(noOpPass).deletes).toEqual([]);
+        writeJournal(slug, noOpPass);
+        const reopenedKeys = new Set(journalRows(readJournal(slug)).keys());
+        expect(reopenedKeys).toEqual(expectedKeys);
+        expect(reopenedKeys.size).toBe(rowCount);
+    }, 120_000);
+    it("materializes only rows whose paths match a prefix scan", () => {
+        writeJournal("acme", journal({
+            "docs/guide.md": entry(1),
+            "docs/nested/plan.md": entry(2),
+            "docs": entry(3),
+            "docsx/guide.md": entry(4),
+            "other.md": entry(5),
+            "notes/meeting.md": entry(6),
+        }));
+        const materialize = vi.spyOn(JournalRowStore.prototype, "materialize");
+        const pathForRow = vi.spyOn(JournalRowStore.prototype, "pathForRow");
+        try {
+            const session = openJournalStoreSession("acme");
+            expect(Array.from(session.scanPrefix("docs")).map(([key]) => key)).toEqual([
+                "docs",
+                "docs/guide.md",
+                "docs/nested/plan.md",
+            ]);
+            expect(materialize).toHaveBeenCalledTimes(3);
+            expect(pathForRow).toHaveBeenCalledTimes(3);
+        }
+        finally {
+            pathForRow.mockRestore();
+            materialize.mockRestore();
+        }
+    });
+    it("keeps watcher filter compatibility lazy until the bulk classifier consumes it", () => {
+        writeJournal("acme", journal({
+            "docs/guide.md": entry(1),
+            "docs/nested/plan.md": entry(2),
+            "docs": entry(3),
+            "docsx/guide.md": entry(4),
+            "other.md": entry(5),
+        }));
+        const materialize = vi.spyOn(JournalRowStore.prototype, "materialize");
+        try {
+            const session = openJournalStoreSession("acme");
+            const covered = session.scanPrefix("docs");
+            expect(materialize).not.toHaveBeenCalled();
+            const stampable = covered.filter(([, row]) => row.remoteEtag !== undefined);
+            expect(stampable.map(([key]) => key)).toEqual([
+                "docs",
+                "docs/guide.md",
+                "docs/nested/plan.md",
+            ]);
+            expect(materialize).toHaveBeenCalledTimes(3);
+        }
+        finally {
+            materialize.mockRestore();
+        }
+    });
+    it("reiterates one streamed prefix scan with the complete row set", () => {
+        writeJournal("acme", journal({
+            "docs/guide.md": entry(1),
+            "docs/nested/plan.md": entry(2),
+            "other/ignored.md": entry(3),
+        }));
+        const session = openJournalStoreSession("acme");
+        const scan = session.scanPrefix("docs");
+        const firstPass = Array.from(scan);
+        const secondPass = Array.from(scan);
+        expect(firstPass.map(([key]) => key)).toEqual(["docs/guide.md", "docs/nested/plan.md"]);
+        expect(secondPass).toEqual(firstPass);
+        session.dispose();
+    });
+    it("preserves prefix-boundary scan behavior and frozen rows", () => {
+        writeJournal("acme", journal({
+            "docs/guide.md": entry(1),
+            "docs/nested/plan.md": entry(2),
+            "docs": entry(3),
+            "docsx/guide.md": entry(4),
+            "other.md": entry(5),
+        }));
+        const session = openJournalStoreSession("acme");
+        const expectations = [
+            ["", ["docs", "docs/guide.md", "docs/nested/plan.md", "docsx/guide.md", "other.md"]],
+            ["docs/guide.md", ["docs/guide.md"]],
+            ["docs/", ["docs", "docs/guide.md", "docs/nested/plan.md"]],
+            ["docs", ["docs", "docs/guide.md", "docs/nested/plan.md"]],
+            ["missing", []],
+        ];
+        for (const [prefix, expectedPaths] of expectations) {
+            const scanned = Array.from(session.scanPrefix(prefix));
+            expect(scanned.map(([key]) => key), prefix).toEqual(expectedPaths);
+            for (const [key, row] of scanned) {
+                expect(Object.isFrozen(row), prefix).toBe(true);
+                expect(row).toEqual(session.get(key));
+            }
+        }
+    });
+    it("matches a Map reference through seeded packed-session delta sequences", () => {
+        const paths = [
+            "root.md",
+            "unicode/\ud800",
+            "unicode/�",
+            "unicode/café.md",
+            "unicode/cafe\u0301.md",
+            "nested/alpha.md",
+            "nested/deeper/beta.md",
+            "very/deep/path/with/many/segments/entry.md",
+        ];
+        const prefixes = ["", "unicode", "unicode/", "nested", "very/deep/path/with/many/segments", "missing"];
+        const reference = new Map();
+        writeJournal("packed-session-parity", journal({}));
+        const session = openJournalStoreSession("packed-session-parity");
+        try {
+            for (let seed = 1; seed <= 300; seed++) {
+                const random = rng(seed);
+                const sequenceLength = 1 + Math.floor(random() * 5);
+                for (let step = 0; step < sequenceLength; step++) {
+                    const chosenPath = paths[Math.floor(random() * paths.length)];
+                    const action = random();
+                    if (action < 0.2) {
+                        session.applyDelta({ deletes: [chosenPath] });
+                        reference.delete(chosenPath);
+                    }
+                    else if (action < 0.35) {
+                        const absentPath = `missing/${seed}/${step}.md`;
+                        session.applyDelta({ deletes: [absentPath] });
+                        reference.delete(absentPath);
+                    }
+                    else if (action < 0.5) {
+                        session.applyDelta({ metadata: { lastSync: `sync-${seed}-${step}` } });
+                    }
+                    else {
+                        const prior = reference.get(chosenPath);
+                        const next = prior !== undefined && action < 0.7
+                            ? structuredClone(prior)
+                            : packedEntry(seed * 1_000 + step);
+                        session.applyDelta({ upserts: { [chosenPath]: next } });
+                        reference.set(chosenPath, next);
+                    }
+                    const label = `seed ${seed}, step ${step}`;
+                    expect(session.rowCount(), label).toBe(reference.size);
+                    for (const samplePath of [...paths, `missing/${seed}/${step}.md`]) {
+                        expect(session.get(samplePath), `${label}, get ${JSON.stringify(samplePath)}`)
+                            .toEqual(reference.get(samplePath));
+                    }
+                    for (const prefix of prefixes) {
+                        expect(Array.from(session.scanPrefix(prefix)), `${label}, scan ${JSON.stringify(prefix)}`)
+                            .toEqual(scanReference(reference, prefix));
+                    }
+                }
+            }
+        }
+        finally {
+            session.dispose();
+        }
+    }, 60_000);
+    it("releases each completed keyed projection instead of retaining one full journal per watch pass", () => {
+        const files = Object.fromEntries(Array.from({ length: 64 }, (_value, index) => [`docs/${index}.md`, entry(index)]));
+        writeJournal("release-after-pass", journal(files));
+        const completed = [];
+        for (let cycle = 0; cycle < 20; cycle += 1) {
+            const session = openJournalStoreSession("release-after-pass");
+            expect(session.rowCount()).toBe(64);
+            session.dispose();
+            completed.push(session);
+        }
+        expect(completed.map((session) => session.rowCount())).toEqual(Array(20).fill(0));
+    });
+});
+describe("JournalStore packed rows", () => {
+    // Companion to the AreaLedger "one object per row" tests. On a 690k-row
+    // vault the runner keeps up to three sessions open at once (cached targeted
+    // pull, watcher, pass-local); each used to structuredClone every row on
+    // open, which is what pushed the outposts over Node's default heap ceiling.
+    function seedAuthoritative(slug, rows) {
+        const files = {};
+        for (let index = 0; index < rows; index += 1)
+            files[`alpha/file-${index}.md`] = entry(index + 1);
+        writeJournal(slug, journal(files));
+        const migration = new AreaLedgerMigration({
+            rootDir: stateDir,
+            journalSlug: slug,
+            resolver: new AreaResolver(areaLayout),
+            legacyStore: openJournalStateStoreForMigration(slug),
+        });
+        expect(migration.cutOver().phase).toBe("area-authoritative");
+        return migration;
+    }
+    it("opens a session without cloning rows", () => {
+        seedAuthoritative("personal-vault", 2_000);
+        const clone = vi.spyOn(globalThis, "structuredClone");
+        try {
+            const session = openJournalStoreSession("personal-vault");
+            expect(session.rowCount()).toBe(2_000);
+            expect(clone.mock.calls.length).toBeLessThan(20);
+        }
+        finally {
+            clone.mockRestore();
+        }
+    });
+    it("packs independent row values instead of retaining ledger row objects", () => {
+        seedAuthoritative("personal-vault", 10);
+        const opened = [];
+        setAreaLedgerMigrationTestHooksForTest({ afterOpen: (bridge) => opened.push(bridge) });
+        const session = openJournalStoreSession("personal-vault");
+        expect(opened).toHaveLength(1);
+        const ledgerRow = opened[0].readAreaJournalCached().journal.files["alpha/file-4.md"];
+        expect(ledgerRow).toBeDefined();
+        const sessionRows = session.files;
+        expect(sessionRows.get("alpha/file-4.md")).not.toBe(ledgerRow);
+    });
+    it("still returns detached frozen rows to callers", () => {
+        seedAuthoritative("personal-vault", 3);
+        const session = openJournalStoreSession("personal-vault");
+        const row = session.get("alpha/file-1.md");
+        expect(Object.isFrozen(row)).toBe(true);
+        expect(() => { row.size = 999; }).toThrow(TypeError);
+        expect(session.get("alpha/file-1.md")).toMatchObject({ size: 2 });
+        expect(readJournal("personal-vault").files["alpha/file-1.md"]).toMatchObject({ size: 2 });
+    });
+    it("keeps the long-lived projection free of unwired row-store changes", () => {
+        writeJournal("packed-session-dirty-log", journal({}));
+        const session = openJournalStoreSession("packed-session-dirty-log");
+        try {
+            for (let round = 0; round < 180; round += 1) {
+                const path = `churn/${round % 24}.md`;
+                session.applyDelta({ upserts: { [path]: packedEntry(round) } });
+                if (round % 5 === 0)
+                    session.applyDelta({ deletes: [path] });
+            }
+            const dirtyLog = session.files.dirtyLog;
+            expect(dirtyLog).toEqual([]);
+        }
+        finally {
+            session.dispose();
+        }
+    });
+});
+/**
+ * A retained scoped projection is a SNAPSHOT. Its cached metadata goes stale
+ * the moment another writer advances the journal's `lastSync` or appends to
+ * its pull history, and `writeJournal` used to fill whichever metadata field
+ * the delta did not carry from that stale snapshot — republishing it over the
+ * concurrent writer's durable value. The reducer already preserves a field the
+ * delta omits, so the delta must omit it.
+ */
+describe("writeJournal metadata through a retained scoped session", () => {
+    function pull(index) {
+        const at = new Date(Date.UTC(2026, 8, 18, 0, 0, index)).toISOString();
+        return {
+            pullId: `pull-${index}`,
+            companyUid: "cmp_indigo",
+            startedAt: at,
+            completedAt: at,
+            syncMode: "all",
+            prefixSet: [],
+            scopeChangeDetected: false,
+            orphansRemoved: 0,
+            orphansBlocked: 0,
+        };
+    }
+    it("keeps a concurrent writer's pull history when the delta only advances lastSync", () => {
+        const slug = "metadata-race-pulls";
+        writeJournal(slug, { version: "2", lastSync: "t0", files: { "a.md": entry(1) }, pulls: [] });
+        // Retain the projection the way a scoped pass does, capturing its baseline.
+        const scoped = readJournalScoped(slug, ["a.md"]);
+        expect(scoped.pulls).toEqual([]);
+        // Another writer records a completed pull after this session's snapshot.
+        const concurrent = openJournalStoreSession(slug);
+        concurrent.applyDelta({ metadata: { pulls: [pull(1)] } });
+        concurrent.dispose();
+        scoped.lastSync = "t1";
+        writeJournal(slug, scoped);
+        const durable = readJournal(slug);
+        expect(durable.lastSync).toBe("t1");
+        expect(durable.pulls).toEqual([pull(1)]);
+    });
+    it("keeps a concurrent writer's lastSync when the delta only records a pull", () => {
+        const slug = "metadata-race-last-sync";
+        writeJournal(slug, { version: "2", lastSync: "t0", files: { "a.md": entry(1) }, pulls: [] });
+        const scoped = readJournalScoped(slug, ["a.md"]);
+        expect(scoped.lastSync).toBe("t0");
+        const concurrent = openJournalStoreSession(slug);
+        concurrent.applyDelta({ metadata: { lastSync: "t9" } });
+        concurrent.dispose();
+        scoped.pulls = [pull(2)];
+        writeJournal(slug, scoped);
+        const durable = readJournal(slug);
+        expect(durable.pulls).toEqual([pull(2)]);
+        expect(durable.lastSync).toBe("t9");
+    });
+    it("still publishes both fields when the delta carries both", () => {
+        const slug = "metadata-race-both";
+        writeJournal(slug, { version: "2", lastSync: "t0", files: { "a.md": entry(1) }, pulls: [] });
+        const scoped = readJournalScoped(slug, ["a.md"]);
+        scoped.lastSync = "t5";
+        scoped.pulls = [pull(3)];
+        writeJournal(slug, scoped);
+        const durable = readJournal(slug);
+        expect(durable.lastSync).toBe("t5");
+        expect(durable.pulls).toEqual([pull(3)]);
+    });
+});
+//# sourceMappingURL=journal-store.test.js.map