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

package/dist/manifest/build-manifest.test.js

@@ -1,1217 +0,0 @@
-/**
- * Unit tests for the client manifest generator (US-002).
- *
- * The suite is organised around the four things that make a manifest useful:
- * the ledger/disk UNION (and its three `source` verdicts), the COST controls
- * (stat-only walk, abort, wall clock), the DELTA machinery, and the wire
- * safety rails (contract validity, NFC paths, tenant isolation).
- */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-/**
- * `node:fs` is an ESM namespace, so `vi.spyOn(fs, …)` cannot redefine it. The
- * stat/hash race needs exactly one observable behaviour change — the SECOND
- * `lstatSync` of a given path reporting a moved mtime — so the module is
- * mocked once, delegating to the real implementation unless a test installs a
- * hook. Every other test in this file therefore still runs against real files.
- */
-const fsHooks = vi.hoisted(() => ({
-    onLstat: null,
-    /**
-     * Same seam, for `readdirSync`. It exists for exactly one thing the
-     * filesystem will not do for us: hand the walk TWO directory entries whose
-     * names differ on disk but collapse onto one NFC key. macOS is
-     * normalization-insensitive, so the NFC and NFD spellings of `café.md`
-     * cannot both exist as real files there — the listing has to be forged.
-     */
-    onReaddir: null,
-}));
-vi.mock("node:fs", async (importOriginal) => {
-    const actual = await importOriginal();
-    return {
-        ...actual,
-        default: actual,
-        lstatSync: ((target, options) => {
-            const stats = actual.lstatSync(target, options);
-            return fsHooks.onLstat ? fsHooks.onLstat(String(target), stats) : stats;
-        }),
-        readdirSync: ((target, options) => {
-            const result = actual.readdirSync(target, options);
-            if (!fsHooks.onReaddir || !Array.isArray(result))
-                return result;
-            return fsHooks.onReaddir(String(target), result);
-        }),
-    };
-});
-import { PERSONAL_VAULT_JOURNAL_SLUG, hashFile, hashSymlinkTarget, openJournalStoreSession, } from "../journal.js";
-import { buildSyncManifest, chunkManifest, classifyManifestUploadResponse, planManifestChunks, } from "./build-manifest.js";
-import { SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET, SYNC_MANIFEST_MAX_CHUNK_BYTES, SYNC_MANIFEST_MAX_CHUNK_COUNT, SYNC_MANIFEST_MAX_ENTRIES_PER_CHUNK, validateSyncManifestUpload, } from "./contract.js";
-import { manifestSnapshotPath, readManifestSnapshot, writeManifestSnapshot, } from "./snapshot-store.js";
-const NOW_MS = Date.parse("2026-09-04T12:00:00.000Z");
-let hqRoot;
-let stateDir;
-beforeEach(() => {
-    const base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-"));
-    hqRoot = path.join(base, "hq");
-    stateDir = path.join(base, "state");
-    fs.mkdirSync(hqRoot, { recursive: true });
-    fs.mkdirSync(stateDir, { recursive: true });
-});
-afterEach(() => {
-    fsHooks.onLstat = null;
-    fsHooks.onReaddir = null;
-    vi.restoreAllMocks();
-});
-function writeFileAt(relPath, contents) {
-    const abs = path.join(hqRoot, relPath);
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, contents, "utf8");
-    return abs;
-}
-function journalEntryFor(absPath, overrides = {}) {
-    const stats = fs.lstatSync(absPath);
-    return {
-        hash: stats.isSymbolicLink() ? hashSymlinkTarget(fs.readlinkSync(absPath)) : hashFile(absPath),
-        size: stats.size,
-        syncedAt: "2026-09-01T00:00:00.000Z",
-        direction: "up",
-        mtimeMs: Math.floor(stats.mtimeMs),
-        ...overrides,
-    };
-}
-function journalWith(files) {
-    return { version: "2", lastSync: "2026-09-01T00:00:00.000Z", files, pulls: [] };
-}
-function summaries(slug, files) {
-    return [{ slug, path: `/state/sync-journal.${slug}.json`, journal: journalWith(files) }];
-}
-function baseOptions(overrides = {}) {
-    return {
-        scope: { kind: "personal" },
-        hqRoot,
-        stateDir,
-        installationId: "install-abc123",
-        machineId: "machine-abc123",
-        source: "cli",
-        sequence: 7,
-        now: NOW_MS,
-        listJournalsImpl: () => [],
-        // These suites predate the stat-only default and assert on computed
-        // hashes throughout. `full` preserves exactly what they were written to
-        // exercise; the stat-only DEFAULT gets its own dedicated coverage below.
-        hashPolicy: "full",
-        ...overrides,
-    };
-}
-describe("buildSyncManifest — ledger/disk union", () => {
-    it("reports a file the journal never tracked as disk-only", async () => {
-        writeFileAt("notes/untracked.md", "hello");
-        const result = await buildSyncManifest(baseOptions());
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/untracked.md");
-        expect(entry?.source).toBe("disk");
-        expect(entry?.hash).toBe(hashFile(path.join(hqRoot, "notes/untracked.md")));
-        expect(result.walkStats.hashedFiles).toBe(1);
-    });
-    it("reports an agreeing ledger row as `both` and never opens the file", async () => {
-        const abs = writeFileAt("notes/tracked.md", "hello");
-        const ledgerEntry = journalEntryFor(abs, { remoteEtag: "etag-1" });
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries("__hq_personal_vault__", { "notes/tracked.md": ledgerEntry }),
-        }));
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/tracked.md");
-        expect(entry?.source).toBe("both");
-        expect(entry?.ledgerRemoteEtag).toBe("etag-1");
-        expect(entry?.ledgerDirection).toBe("up");
-        expect(entry?.pendingPush).toBeUndefined();
-        // The whole point of the stat pair: an agreeing ledger row costs zero reads.
-        expect(result.walkStats.hashedFiles).toBe(0);
-    });
-    it("re-hashes and flags pendingPush when the stat pair disagrees", async () => {
-        const abs = writeFileAt("notes/edited.md", "new contents");
-        const stale = journalEntryFor(abs, { hash: "0".repeat(64), size: 1 });
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries("__hq_personal_vault__", { "notes/edited.md": stale }),
-        }));
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/edited.md");
-        expect(entry?.source).toBe("both");
-        expect(entry?.hash).toBe(hashFile(abs));
-        expect(entry?.pendingPush).toBe(true);
-        expect(result.walkStats.hashedFiles).toBe(1);
-    });
-    it("still emits a ledger row whose local file has vanished", async () => {
-        writeFileAt("notes/present.md", "here");
-        const gone = {
-            hash: "a".repeat(64),
-            size: 12,
-            syncedAt: "2026-09-01T00:00:00.000Z",
-            direction: "down",
-            mtimeMs: NOW_MS - 5_000,
-        };
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries("__hq_personal_vault__", { "notes/vanished.md": gone }),
-        }));
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/vanished.md");
-        expect(entry?.source).toBe("ledger");
-        expect(entry?.hash).toBe("a".repeat(64));
-        expect(entry?.ledgerDirection).toBe("down");
-    });
-    it("does not resurrect tombstoned ledger rows as vanished files", async () => {
-        const tombstoned = {
-            hash: "b".repeat(64),
-            size: 3,
-            syncedAt: "2026-09-01T00:00:00.000Z",
-            direction: "down",
-            removedAt: "2026-09-02T00:00:00.000Z",
-            removedReason: "scope_shrink",
-        };
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries("__hq_personal_vault__", { "notes/pruned.md": tombstoned }),
-        }));
-        expect(result.chunks[0].entries).toHaveLength(0);
-    });
-    it("emits a disk-only manifest with ledgerUnavailable instead of throwing", async () => {
-        writeFileAt("notes/a.md", "a");
-        const abs = writeFileAt("notes/b.md", "b");
-        const ledgerEntry = journalEntryFor(abs);
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => {
-                throw new TypeError("journal state store is locked");
-            },
-        }));
-        expect(result.chunks[0].ledgerUnavailable).toEqual({ errorClass: "TypeError" });
-        expect(result.chunks[0].entries.every((entry) => entry.source === "disk")).toBe(true);
-        expect(ledgerEntry.hash).toBeTruthy();
-    });
-    it("treats a missing shard as an empty ledger, not an unavailable one", async () => {
-        writeFileAt("notes/a.md", "a");
-        const result = await buildSyncManifest(baseOptions({ listJournalsImpl: () => summaries("other-co", {}) }));
-        expect(result.chunks[0].ledgerUnavailable).toBeUndefined();
-        expect(result.chunks[0].entries[0].source).toBe("disk");
-    });
-    it("hashes a symlink by its target, not by following it", async () => {
-        writeFileAt("notes/real.md", "real");
-        const link = path.join(hqRoot, "notes", "link.md");
-        fs.symlinkSync("real.md", link);
-        const result = await buildSyncManifest(baseOptions());
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/link.md");
-        expect(entry?.hash).toBe(hashSymlinkTarget("real.md"));
-    });
-    it("marks a symlink entry `symlink: true`, and a regular file not at all", async () => {
-        // The reconciler cannot compare a symlink against its vault object: the
-        // local `size` is the length of the TARGET STRING, the vault object is the
-        // resolved file. Without this flag it read 1,480 rows of the first real
-        // audit run as `hash_drift` (`.codex/claude`, `.agents/skills`, `AGENTS.md`).
-        writeFileAt("notes/real.md", "real");
-        fs.symlinkSync("real.md", path.join(hqRoot, "notes", "link.md"));
-        const result = await buildSyncManifest(baseOptions());
-        const byPath = new Map(result.chunks[0].entries.map((e) => [e.path, e]));
-        expect(byPath.get("notes/link.md")?.symlink).toBe(true);
-        // Absent, not `false`: a regular file's entry stays byte-identical to what
-        // an older client shipped.
-        expect(byPath.get("notes/real.md")).not.toHaveProperty("symlink");
-        // And the flag must survive the shared wire contract.
-        for (const chunk of result.chunks) {
-            expect(() => validateSyncManifestUpload(chunk)).not.toThrow();
-        }
-    });
-});
-describe("buildSyncManifest — wire safety", () => {
-    it("produces chunks the shared contract validator accepts, extra walkStats field and all", async () => {
-        writeFileAt("notes/a.md", "a");
-        const result = await buildSyncManifest(baseOptions());
-        expect(result.walkStats.truncated).toBe(false);
-        for (const chunk of result.chunks) {
-            expect(() => validateSyncManifestUpload(chunk)).not.toThrow();
-        }
-        expect(result.chunks[0].chunkIndex).toBe(0);
-        expect(result.chunks[0].chunkCount).toBe(1);
-    });
-    it("always emits at least one chunk for an empty scope", async () => {
-        const result = await buildSyncManifest(baseOptions());
-        expect(result.chunks).toHaveLength(1);
-        expect(result.chunks[0].entries).toEqual([]);
-        expect(() => validateSyncManifestUpload(result.chunks[0])).not.toThrow();
-    });
-    it("normalizes NFD filenames to NFC on the wire", async () => {
-        const nfd = "notes/café.md";
-        writeFileAt(nfd, "coffee");
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks[0].entries.map((entry) => entry.path);
-        expect(paths).toContain("notes/café.md".normalize("NFC"));
-        expect(paths.every((candidate) => candidate.normalize("NFC") === candidate)).toBe(true);
-    });
-    it("skips and counts a path the contract cannot represent", async () => {
-        writeFileAt("notes/ok.md", "ok");
-        // A right-to-left override renders `evil.fdp.md` as `evil.md.pdf`; the
-        // contract rejects it outright, and so must the walk.
-        writeFileAt("notes/evil\u202Edm.dp.md", "spoofed");
-        const result = await buildSyncManifest(baseOptions());
-        expect(result.unrepresentablePaths).toBe(1);
-        expect(result.chunks[0].entries.map((entry) => entry.path)).toEqual(["notes/ok.md"]);
-    });
-    it("keeps a personal manifest free of any company identifier", async () => {
-        writeFileAt("notes/a.md", "a");
-        const result = await buildSyncManifest(
-        // A caller that wrongly stuffs a slug into a personal scope must not have
-        // it leak onto the wire.
-        baseOptions({ scope: { kind: "personal", slug: "acme" } }));
-        expect(result.chunks[0].scope).toEqual({ kind: "personal" });
-        expect(JSON.stringify(result.chunks[0].scope)).not.toContain("acme");
-    });
-    it("rejects a personal scope carrying a companyUid", async () => {
-        await expect(buildSyncManifest(baseOptions({ scope: { kind: "personal", companyUid: "co-1" } }))).rejects.toThrow(/must not carry a companyUid/);
-    });
-    it("walks only the company root and reports the uid, never the slug", async () => {
-        writeFileAt("companies/acme/deal.md", "acme");
-        writeFileAt("companies/other/secret.md", "other");
-        const result = await buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "co-acme", slug: "acme" } }));
-        expect(result.chunks[0].scope).toEqual({
-            kind: "company",
-            companyUid: "co-acme",
-            companySlug: "acme",
-            scopeRoot: "companies/acme",
-        });
-        expect(result.chunks[0].entries.map((entry) => entry.path)).toEqual(["deal.md"]);
-    });
-});
-describe("buildSyncManifest — ignore rules", () => {
-    it("applies the layered ignore filter and reports the rules it used", async () => {
-        writeFileAt("notes/keep.md", "keep");
-        writeFileAt("node_modules/pkg/index.js", "junk");
-        writeFileAt(".env", "SECRET=1");
-        fs.writeFileSync(path.join(hqRoot, ".hqignore"), "scratch/\n# a comment\n", "utf8");
-        writeFileAt("scratch/draft.md", "draft");
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks[0].entries.map((entry) => entry.path);
-        expect(paths).toContain("notes/keep.md");
-        expect(paths).not.toContain("node_modules/pkg/index.js");
-        expect(paths).not.toContain(".env");
-        expect(paths).not.toContain("scratch/draft.md");
-        expect(result.chunks[0].ignoreRules).toContain("node_modules/");
-        expect(result.chunks[0].ignoreRules).toContain("scratch/");
-        expect(result.chunks[0].ignoreRules).not.toContain("# a comment");
-        expect(result.walkStats.ignoredFiles).toBeGreaterThan(0);
-    });
-    it("skips the push-only sessions prefix exactly as the pull scope does", async () => {
-        writeFileAt("companies/acme/deal.md", "acme");
-        writeFileAt("companies/acme/sessions/p-1/log.jsonl", "{}");
-        const result = await buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "co-acme", slug: "acme" } }));
-        expect(result.chunks[0].entries.map((entry) => entry.path)).toEqual(["deal.md"]);
-        expect(result.chunks[0].ignoreRules).toContain("sessions/");
-    });
-});
-describe("buildSyncManifest — cost controls", () => {
-    it("marks the manifest truncated and skips the snapshot when aborted", async () => {
-        for (let index = 0; index < 20; index++)
-            writeFileAt(`notes/f${index}.md`, `${index}`);
-        const controller = new AbortController();
-        controller.abort();
-        const result = await buildSyncManifest(baseOptions({ abortSignal: controller.signal }));
-        expect(result.walkStats.truncated).toBe(true);
-        expect(fs.existsSync(manifestSnapshotPath(stateDir, "personal"))).toBe(false);
-        expect(() => validateSyncManifestUpload(result.chunks[0])).not.toThrow();
-    });
-    it("stops at the wall-clock cap rather than finishing the tree", async () => {
-        for (let index = 0; index < 40; index++)
-            writeFileAt(`notes/f${index}.md`, `${index}`);
-        const result = await buildSyncManifest(baseOptions({ maxWallMs: -1 }));
-        expect(result.walkStats.truncated).toBe(true);
-        expect(result.walkStats.filesWalked).toBe(0);
-    });
-    it("yields to the event loop while walking", async () => {
-        for (let index = 0; index < 12; index++)
-            writeFileAt(`notes/f${index}.md`, `${index}`);
-        let ticks = 0;
-        const timer = setInterval(() => {
-            ticks += 1;
-        }, 1);
-        try {
-            await buildSyncManifest(baseOptions({ yieldEvery: 1 }));
-        }
-        finally {
-            clearInterval(timer);
-        }
-        expect(ticks).toBeGreaterThan(0);
-    });
-    it("drops an entry whose file changed while it was being hashed", async () => {
-        const abs = writeFileAt("notes/racing.md", "before");
-        let seen = 0;
-        fsHooks.onLstat = (target, stats) => {
-            if (target !== abs)
-                return stats;
-            seen += 1;
-            // The second observation IS the post-hash re-stat.
-            if (seen === 1)
-                return stats;
-            return { ...stats, mtimeMs: stats.mtimeMs + 5_000 };
-        };
-        const result = await buildSyncManifest(baseOptions());
-        expect(result.droppedStatRaces).toBe(1);
-        expect(result.chunks[0].entries).toHaveLength(0);
-    });
-    it("yields to the event loop during the HASH phase, not just the walk", async () => {
-        // Regression: the hash phase opens files and is at least as expensive as
-        // the walk, but used to run as one uninterrupted synchronous block —
-        // freezing the daemon for the whole of a first-ever sync.
-        //
-        // The walk yields too, so ticks alone prove nothing. The walk lstats each
-        // path ONCE and the hash phase lstats it a SECOND time (the post-hash
-        // re-stat), so a second observation of any path marks the hash phase; the
-        // assertion is that the tick count GROWS after that point.
-        const total = 24;
-        for (let index = 0; index < total; index++)
-            writeFileAt(`notes/f${index}.md`, `${index}`);
-        let ticks = 0;
-        let ticksAtHashStart = null;
-        const seenOnce = new Set();
-        fsHooks.onLstat = (target, stats) => {
-            if (target.endsWith(".md")) {
-                if (seenOnce.has(target)) {
-                    if (ticksAtHashStart === null)
-                        ticksAtHashStart = ticks;
-                }
-                else {
-                    seenOnce.add(target);
-                }
-            }
-            return stats;
-        };
-        const timer = setInterval(() => {
-            ticks += 1;
-        }, 1);
-        try {
-            await buildSyncManifest(baseOptions({ yieldEvery: 2 }));
-        }
-        finally {
-            clearInterval(timer);
-        }
-        const hashStart = ticksAtHashStart;
-        expect(hashStart).not.toBeNull();
-        expect(ticks).toBeGreaterThan(hashStart ?? Number.POSITIVE_INFINITY);
-    });
-    it("stops hashing when the signal aborts and marks the manifest truncated", async () => {
-        // The abort must fire in the HASH phase, not the walk — otherwise the
-        // pre-existing walk-abort path would satisfy this test on a broken
-        // implementation. A second lstat of a path only happens post-hash.
-        const total = 40;
-        for (let index = 0; index < total; index++)
-            writeFileAt(`notes/f${index}.md`, `${index}`);
-        const controller = new AbortController();
-        const seenOnce = new Set();
-        let rehashed = 0;
-        fsHooks.onLstat = (target, stats) => {
-            if (target.endsWith(".md")) {
-                if (seenOnce.has(target)) {
-                    if (++rehashed >= 4)
-                        controller.abort();
-                }
-                else {
-                    seenOnce.add(target);
-                }
-            }
-            return stats;
-        };
-        const result = await buildSyncManifest(baseOptions({ abortSignal: controller.signal, yieldEvery: 2 }));
-        // The walk completed (that is what makes this a hash-phase abort), but the
-        // hash phase stopped early, so the manifest is partial and unsafe to
-        // persist as a delta base.
-        expect(result.walkStats.filesWalked).toBe(total);
-        expect(result.walkStats.truncated).toBe(true);
-        expect(result.walkStats.hashedFiles).toBeLessThan(total);
-        expect(fs.existsSync(manifestSnapshotPath(stateDir, "personal"))).toBe(false);
-        expect(() => validateSyncManifestUpload(result.chunks[0])).not.toThrow();
-    });
-    it("computes no hashes at all under the ledger-only hash policy", async () => {
-        writeFileAt("notes/a.md", "a");
-        const result = await buildSyncManifest(baseOptions({ hashPolicy: "ledger-only" }));
-        expect(result.walkStats.filesWalked).toBe(1);
-        expect(result.walkStats.hashedFiles).toBe(0);
-        expect(result.skippedUnhashed).toBe(1);
-        expect(result.chunks[0].entries).toEqual([]);
-    });
-});
-describe("buildSyncManifest — delta mode", () => {
-    it("emits a full manifest when no snapshot exists, then a delta of the change", async () => {
-        writeFileAt("notes/a.md", "a");
-        writeFileAt("notes/b.md", "b");
-        const first = await buildSyncManifest(baseOptions());
-        expect(first.mode).toBe("full");
-        expect(first.chunks[0].baseSnapshotId).toBeUndefined();
-        writeFileAt("notes/b.md", "b-changed");
-        writeFileAt("notes/c.md", "c");
-        fs.rmSync(path.join(hqRoot, "notes/a.md"));
-        const second = await buildSyncManifest(baseOptions({ sequence: 8 }));
-        expect(second.mode).toBe("delta");
-        expect(second.chunks[0].baseSnapshotId).toBe(first.snapshot.snapshotId);
-        expect(second.chunks[0].entries.map((entry) => entry.path).sort()).toEqual([
-            "notes/b.md",
-            "notes/c.md",
-        ]);
-        expect(second.chunks[0].removedPaths).toEqual(["notes/a.md"]);
-        expect(() => validateSyncManifestUpload(second.chunks[0])).not.toThrow();
-    });
-    it("forces a full manifest when the caller asks (server resend_full)", async () => {
-        writeFileAt("notes/a.md", "a");
-        await buildSyncManifest(baseOptions());
-        const forced = await buildSyncManifest(baseOptions({ forceFull: true, sequence: 9 }));
-        expect(forced.mode).toBe("full");
-        expect(forced.chunks[0].entries.map((entry) => entry.path)).toEqual(["notes/a.md"]);
-        expect(forced.chunks[0].removedPaths).toEqual([]);
-    });
-    it("re-baselines when the snapshot is older than seven days", async () => {
-        writeFileAt("notes/a.md", "a");
-        await buildSyncManifest(baseOptions());
-        const later = await buildSyncManifest(baseOptions({ now: NOW_MS + 8 * 24 * 60 * 60 * 1000, sequence: 10 }));
-        expect(later.mode).toBe("full");
-    });
-    it("does not report a file as removed just because it raced during hashing", async () => {
-        // Regression: a file the user is actively SAVING fails its post-hash
-        // re-stat and is dropped from the manifest. It is still on disk, so
-        // reporting it in `removedPaths` would tell the audit the local copy
-        // vanished — a finding raised against every file being edited.
-        const abs = writeFileAt("notes/racing.md", "before");
-        writeFileAt("notes/stable.md", "stable");
-        await buildSyncManifest(baseOptions());
-        writeFileAt("notes/racing.md", "after");
-        let seen = 0;
-        fsHooks.onLstat = (target, stats) => {
-            if (target !== abs)
-                return stats;
-            seen += 1;
-            if (seen === 1)
-                return stats;
-            return { ...stats, mtimeMs: stats.mtimeMs + 5_000 };
-        };
-        const second = await buildSyncManifest(baseOptions({ sequence: 8 }));
-        expect(second.mode).toBe("delta");
-        expect(second.droppedStatRaces).toBe(1);
-        expect(second.chunks[0].removedPaths).toEqual([]);
-    });
-    it("asserts no removals at all while the ledger is unreadable", async () => {
-        // With the ledger unreadable the `ledger`-source loop is skipped, so every
-        // ledger-only path in the base would otherwise surface as a deletion.
-        const abs = writeFileAt("notes/vanishing.md", "v");
-        const journal = { "notes/vanishing.md": journalEntryFor(abs) };
-        const readable = () => summaries(PERSONAL_VAULT_JOURNAL_SLUG, journal);
-        await buildSyncManifest(baseOptions({ listJournalsImpl: readable }));
-        fs.rmSync(abs);
-        const second = await buildSyncManifest(baseOptions({
-            sequence: 8,
-            listJournalsImpl: () => {
-                throw new Error("journal locked");
-            },
-        }));
-        expect(second.chunks[0].ledgerUnavailable?.errorClass).toBe("Error");
-        expect(second.chunks[0].removedPaths).toEqual([]);
-    });
-    it("never persists a truncated walk as the delta base", async () => {
-        writeFileAt("notes/a.md", "a");
-        await buildSyncManifest(baseOptions());
-        const before = readManifestSnapshot(stateDir, "personal");
-        await buildSyncManifest(baseOptions({ maxWallMs: -1, sequence: 11 }));
-        expect(readManifestSnapshot(stateDir, "personal")?.snapshotId).toBe(before?.snapshotId);
-    });
-});
-describe("snapshot store", () => {
-    it("round-trips through an atomic write and leaves no temp files", async () => {
-        const snapshot = {
-            snapshotId: "snap-deadbeef",
-            generatedAt: "2026-09-04T12:00:00.000Z",
-            sequence: 3,
-            entries: { "a.md": { hash: "c".repeat(64), size: 1, mtimeMs: 5 } },
-        };
-        expect(writeManifestSnapshot(stateDir, "company:co-1", snapshot)).toBe(true);
-        expect(readManifestSnapshot(stateDir, "company:co-1")).toEqual(snapshot);
-        const dir = path.dirname(manifestSnapshotPath(stateDir, "company:co-1"));
-        expect(fs.readdirSync(dir).filter((name) => name.endsWith(".tmp"))).toEqual([]);
-        // The colon is sanitized out of the filename rather than reaching the FS,
-        // and a digest of the RAW scope key keeps two tenants whose uids sanitize
-        // alike (`acme.eu` vs `acme:eu`) off the same file.
-        expect(fs.readdirSync(dir)).toEqual([path.basename(manifestSnapshotPath(stateDir, "company:co-1"))]);
-        expect(fs.readdirSync(dir)[0]).toMatch(/^company_co-1-[0-9a-f]{16}\.json$/);
-    });
-    it("returns null for missing and corrupt snapshots instead of throwing", () => {
-        expect(readManifestSnapshot(stateDir, "personal")).toBeNull();
-        const target = manifestSnapshotPath(stateDir, "personal");
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(target, "{ not json", "utf8");
-        expect(readManifestSnapshot(stateDir, "personal")).toBeNull();
-        fs.writeFileSync(target, JSON.stringify({ snapshotId: 4 }), "utf8");
-        expect(readManifestSnapshot(stateDir, "personal")).toBeNull();
-    });
-    it("drops individual malformed rows without discarding the snapshot", () => {
-        const target = manifestSnapshotPath(stateDir, "personal");
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(target, JSON.stringify({
-            snapshotId: "snap-1",
-            generatedAt: "2026-09-04T12:00:00.000Z",
-            sequence: 1,
-            entries: { good: { hash: "d".repeat(64), size: 1, mtimeMs: 2 }, bad: { hash: 5 } },
-        }), "utf8");
-        const snapshot = readManifestSnapshot(stateDir, "personal");
-        expect(Object.keys(snapshot?.entries ?? {})).toEqual(["good"]);
-    });
-});
-describe("classifyManifestUploadResponse", () => {
-    it("treats 404 as a soft skip so an older server is never an error", () => {
-        expect(classifyManifestUploadResponse(404)).toEqual({ outcome: "soft_skip" });
-    });
-    it("classifies success, resend_full, and genuine failures", () => {
-        expect(classifyManifestUploadResponse(200)).toEqual({ outcome: "ok" });
-        expect(classifyManifestUploadResponse(202)).toEqual({ outcome: "ok" });
-        expect(classifyManifestUploadResponse(409)).toEqual({ outcome: "resend_full" });
-        expect(classifyManifestUploadResponse(200, { action: "resend_full" })).toEqual({
-            outcome: "resend_full",
-        });
-        expect(classifyManifestUploadResponse(400, { resendFull: true })).toEqual({
-            outcome: "resend_full",
-        });
-        expect(classifyManifestUploadResponse(500)).toEqual({ outcome: "error" });
-        expect(classifyManifestUploadResponse(403)).toEqual({ outcome: "error" });
-    });
-});
-// ─── Codex review regressions ────────────────────────────────────────────────
-/**
- * These cover the five ways the builder could previously state something FALSE
- * about a scope — a wrong tree, an invisible subtree, a newly-ignored file, a
- * corrupt snapshot key, and a normalization collision — plus the chunk-boundary
- * arithmetic that had no coverage at all.
- */
-describe("buildSyncManifest — company slug is a tenant boundary", () => {
-    it("refuses a slug that escapes companies/", async () => {
-        fs.mkdirSync(path.join(hqRoot, "companies", "acme"), { recursive: true });
-        writeFileAt("personal/secret.md", "not acme's");
-        await expect(buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "co_acme", slug: "../personal" } }))).rejects.toThrow(/direct child of companies/);
-    });
-    it.each(["..", ".", "nested/slug", "sub\\slug", "__proto__"])("refuses the unsafe slug %j", async (slug) => {
-        await expect(buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "co_acme", slug } }))).rejects.toThrow(/direct child of companies/);
-    });
-    it("still accepts an ordinary slug", async () => {
-        writeFileAt("companies/acme/deal.md", "hello");
-        const result = await buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "co_acme", slug: "acme" } }));
-        expect(result.chunks[0].entries.map((entry) => entry.path)).toEqual(["deal.md"]);
-    });
-});
-describe("buildSyncManifest — a directory it cannot read is invisible, not empty", () => {
-    const chmodded = [];
-    function makeUnreadable(relDir) {
-        const abs = path.join(hqRoot, relDir);
-        fs.chmodSync(abs, 0o000);
-        chmodded.push(abs);
-        return abs;
-    }
-    afterEach(() => {
-        for (const abs of chmodded.splice(0)) {
-            try {
-                fs.chmodSync(abs, 0o700);
-            }
-            catch {
-                // Already gone; the tmpdir cleanup does not care either way.
-            }
-        }
-    });
-    it("does not report a file under an unreadable directory as vanished", async () => {
-        const abs = writeFileAt("locked/tracked.md", "hello");
-        const ledgerEntry = journalEntryFor(abs);
-        writeFileAt("open/visible.md", "hi");
-        makeUnreadable("locked");
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries(PERSONAL_VAULT_JOURNAL_SLUG, { "locked/tracked.md": ledgerEntry }),
-        }));
-        const paths = result.chunks[0].entries.map((entry) => entry.path);
-        // The whole point: it must NOT appear as `source: "ledger"` (= "the local
-        // copy is gone") merely because we were not allowed to look.
-        expect(paths).not.toContain("locked/tracked.md");
-        // ...while the readable half of the tree is still fully reported.
-        expect(paths).toContain("open/visible.md");
-        expect(result.walkStats.unreadableDirs).toBe(1);
-        // Scoped suppression, not a blanket bail-out: the rest of the manifest is
-        // still trustworthy enough to persist as a delta base.
-        expect(result.walkStats.truncated).toBe(false);
-    });
-    it("does not report a file under an unreadable directory as removed", async () => {
-        const abs = writeFileAt("locked/tracked.md", "hello");
-        writeFileAt("open/visible.md", "hi");
-        const base = await buildSyncManifest(baseOptions());
-        expect(base.snapshot.entries["locked/tracked.md"]).toBeDefined();
-        expect(fs.existsSync(abs)).toBe(true);
-        makeUnreadable("locked");
-        const result = await buildSyncManifest(baseOptions({ sequence: 8 }));
-        expect(result.mode).toBe("delta");
-        expect(result.chunks[0].removedPaths).toEqual([]);
-    });
-});
-describe("buildSyncManifest — a newly ignored path is not our business", () => {
-    it("does not synthesize a ledger-only entry for a path that is now ignored", async () => {
-        const abs = writeFileAt("drafts/artifact.md", "hello");
-        const ledgerEntry = journalEntryFor(abs);
-        fs.writeFileSync(path.join(hqRoot, ".hqignore"), "drafts/\n", "utf8");
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries(PERSONAL_VAULT_JOURNAL_SLUG, { "drafts/artifact.md": ledgerEntry }),
-        }));
-        // The file is still right there on disk. Reporting it as `ledger` would
-        // claim it vanished, which is the opposite of true.
-        expect(fs.existsSync(abs)).toBe(true);
-        expect(result.chunks[0].entries.map((entry) => entry.path)).not.toContain("drafts/artifact.md");
-    });
-    it("does not report a newly ignored path as removed", async () => {
-        writeFileAt("drafts/artifact.md", "hello");
-        writeFileAt("notes/keep.md", "hi");
-        const base = await buildSyncManifest(baseOptions());
-        expect(base.snapshot.entries["drafts/artifact.md"]).toBeDefined();
-        fs.writeFileSync(path.join(hqRoot, ".hqignore"), "drafts/\n", "utf8");
-        const result = await buildSyncManifest(baseOptions({ sequence: 8 }));
-        expect(result.mode).toBe("delta");
-        expect(result.chunks[0].removedPaths).toEqual([]);
-    });
-});
-describe("buildSyncManifest — NFC is a wire key, not a file locator", () => {
-    const NFD_NAME = "café.md"; // e + combining acute
-    const NFC_NAME = "café.md";
-    it("reports an NFD filename under its NFC path and hashes the real file", async () => {
-        const abs = writeFileAt(`notes/${NFD_NAME}`, "hello");
-        expect(fs.existsSync(abs)).toBe(true);
-        const result = await buildSyncManifest(baseOptions());
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path.startsWith("notes/"));
-        expect(entry?.path).toBe(`notes/${NFC_NAME}`);
-        expect(entry?.hash).toBe(hashFile(abs));
-        expect(result.unrepresentablePaths).toBe(0);
-    });
-    it("drops both spellings when two raw names collide on one NFC key", async () => {
-        writeFileAt(`notes/${NFC_NAME}`, "hello");
-        writeFileAt("notes/plain.md", "hi");
-        // Forge the second spelling into the listing (see fsHooks.onReaddir). On
-        // macOS both spellings lstat to the same real file, which is exactly the
-        // ambiguity the builder must refuse to guess at.
-        fsHooks.onReaddir = (absDir, dirents) => {
-            if (path.basename(absDir) !== "notes")
-                return dirents;
-            const real = dirents.find((dirent) => dirent.name === NFC_NAME);
-            if (!real)
-                return dirents;
-            const alias = Object.create(Object.getPrototypeOf(real));
-            Object.assign(alias, real);
-            alias.name = NFD_NAME;
-            return [...dirents, alias];
-        };
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks[0].entries.map((entry) => entry.path);
-        expect(paths).not.toContain(`notes/${NFC_NAME}`);
-        // Unaffected siblings still report normally — one ambiguous name must not
-        // cost the directory.
-        expect(paths).toContain("notes/plain.md");
-        expect(result.unrepresentablePaths).toBe(2);
-        expect(result.walkStats.filesWalked).toBe(1);
-    });
-    it("counts the collision even when the second spelling does not resolve", async () => {
-        // The platform-portability half, and a real CI failure: the test above
-        // passes on macOS for the wrong reason. There, both spellings `lstat` to
-        // the same file, so a collision check placed AFTER the stat still sees the
-        // duplicate. On Linux the NFD spelling of a file stored as NFC resolves to
-        // nothing, the stat throws, and the ambiguity vanishes silently — on
-        // exactly the platform where the two listing entries really are two
-        // different files, and where publishing one's content under the other's
-        // name is therefore a live risk.
-        //
-        // Forcing the alias `lstat` to throw reproduces the byte-exact filesystem
-        // on any host, so this pins the rule rather than the platform.
-        writeFileAt(`notes/${NFC_NAME}`, "hello");
-        writeFileAt("notes/plain.md", "hi");
-        fsHooks.onReaddir = (absDir, dirents) => {
-            if (path.basename(absDir) !== "notes")
-                return dirents;
-            const real = dirents.find((dirent) => dirent.name === NFC_NAME);
-            if (!real)
-                return dirents;
-            const alias = Object.create(Object.getPrototypeOf(real));
-            Object.assign(alias, real);
-            alias.name = NFD_NAME;
-            return [...dirents, alias];
-        };
-        fsHooks.onLstat = (absPath, stats) => {
-            if (absPath.endsWith(NFD_NAME) && !absPath.endsWith(NFC_NAME)) {
-                throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
-            }
-            return stats;
-        };
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks[0].entries.map((entry) => entry.path);
-        expect(paths).not.toContain(`notes/${NFC_NAME}`);
-        expect(paths).toContain("notes/plain.md");
-        expect(result.unrepresentablePaths).toBe(2);
-        expect(result.walkStats.filesWalked).toBe(1);
-    });
-});
-describe("chunkManifest — boundary arithmetic", () => {
-    const walkStats = {
-        filesWalked: 0,
-        walkMs: 1,
-        hashedFiles: 0,
-        ignoredFiles: 0,
-        truncated: false,
-        unreadableDirs: 0,
-    };
-    /**
-     * Synthetic entries, built once and shared. The per-chunk maximum is 50k, so
-     * every test here is inherently large; rebuilding the array per test is a
-     * second of CPU that this file does not need to spend (and that the walk
-     * benchmark, running in a sibling worker, would rather have). `chunkManifest`
-     * only ever slices, so sharing the objects is safe.
-     */
-    const entryCache = new Map();
-    function syntheticEntries(count) {
-        const cached = entryCache.get(count);
-        if (cached)
-            return cached;
-        const entries = new Array(count);
-        for (let index = 0; index < count; index++) {
-            entries[index] = {
-                path: `notes/file-${index}.md`,
-                hash: "a".repeat(64),
-                size: 1,
-                mtimeMs: NOW_MS,
-                source: "disk",
-            };
-        }
-        entryCache.set(count, entries);
-        return entries;
-    }
-    /**
-     * `perChunk` defaults WELL below the contract ceiling because these cases
-     * are about the ENTRY bound in isolation, and 50,000 of these entries is
-     * ~6.5 MB of JSON — past the byte budget, which would now (correctly) cut
-     * first and make an entry-boundary assertion measure the wrong bound. The
-     * byte bound gets its own cases below.
-     */
-    const ENTRY_BOUNDARY_PER_CHUNK = 1_000;
-    function chunk(entryCount, removedPaths = [], overrides = {}) {
-        return chunkManifest({
-            entries: syntheticEntries(entryCount),
-            removedPaths,
-            walkStats,
-            ignoreRules: [],
-            mode: removedPaths.length > 0 ? "delta" : "full",
-            generatedAt: new Date(NOW_MS).toISOString(),
-            installationId: "install-abc123",
-            machineId: "machine-abc123",
-            scope: { kind: "personal" },
-            source: "cli",
-            sequence: 7,
-            maxEntriesPerChunk: overrides.maxEntriesPerChunk ?? ENTRY_BOUNDARY_PER_CHUNK,
-            chunkByteBudget: overrides.chunkByteBudget ?? SYNC_MANIFEST_MAX_CHUNK_BYTES,
-        });
-    }
-    it("emits one chunk at exactly the per-chunk maximum", () => {
-        const uploads = chunk(ENTRY_BOUNDARY_PER_CHUNK);
-        expect(uploads).toHaveLength(1);
-        expect(uploads[0].chunkIndex).toBe(0);
-        expect(uploads[0].chunkCount).toBe(1);
-        expect(uploads[0].entries).toHaveLength(ENTRY_BOUNDARY_PER_CHUNK);
-    });
-    it("spills a single extra entry into a second chunk", () => {
-        const uploads = chunk(ENTRY_BOUNDARY_PER_CHUNK + 1);
-        expect(uploads).toHaveLength(2);
-        expect(uploads.map((upload) => upload.chunkIndex)).toEqual([0, 1]);
-        expect(uploads.every((upload) => upload.chunkCount === 2)).toBe(true);
-        expect(uploads[0].entries).toHaveLength(ENTRY_BOUNDARY_PER_CHUNK);
-        expect(uploads[1].entries).toHaveLength(1);
-        // No entry is duplicated or lost across the seam.
-        expect(uploads[1].entries[0].path).toBe(`notes/file-${ENTRY_BOUNDARY_PER_CHUNK}.md`);
-    });
-    /**
-     * THE CANARY, AS A TEST.
-     *
-     * @indigoai-us/hq-cloud 6.16.21 planned the operator's 199,394-entry
-     * personal scope as four COUNT-sized chunks of 15.9-17.9 MiB and API Gateway
-     * refused chunk 0 with a 413 before the handler ever ran. The shape that
-     * produced it is the only thing that matters here — realistic entry counts
-     * and realistic path lengths — so this builds the same order of magnitude
-     * and asserts on SERIALISED bytes rather than on entry counts.
-     */
-    it("cuts 200k realistic entries on bytes, with no chunk over the budget", () => {
-        const ENTRY_COUNT = 200_000;
-        const TARGET_PATH_BYTES = 120;
-        const entries = new Array(ENTRY_COUNT);
-        for (let index = 0; index < ENTRY_COUNT; index++) {
-            // ~120 bytes of path, the way a real vault produces them: nested
-            // directories and long human-authored file names, not `f-1.md`.
-            const suffix = `${index}`.padStart(7, "0");
-            const stem = `companies/acme/knowledge/quarterly-planning/${suffix}/meeting-notes-and-action-items`;
-            const path = `${stem.padEnd(TARGET_PATH_BYTES - 8, "x")}-${suffix}.md`;
-            entries[index] = {
-                path,
-                hash: "a".repeat(64),
-                size: 4096 + index,
-                mtimeMs: NOW_MS,
-                source: "both",
-            };
-        }
-        const plan = planManifestChunks({
-            entries,
-            removedPaths: [],
-            walkStats,
-            ignoreRules: [],
-            mode: "full",
-            generatedAt: new Date(NOW_MS).toISOString(),
-            installationId: "install-abc123",
-            machineId: "machine-abc123",
-            scope: { kind: "personal" },
-            source: "cli",
-            sequence: 7,
-        });
-        expect(plan.chunkByteBudget).toBe(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET);
-        // The count bound ALONE would have planned 4 chunks here. It planned many
-        // more, which is the fix: bytes are what the gateway counts.
-        expect(plan.chunkCount).toBeGreaterThan(Math.ceil(ENTRY_COUNT / SYNC_MANIFEST_MAX_ENTRIES_PER_CHUNK));
-        expect(plan.chunkCount).toBeLessThanOrEqual(SYNC_MANIFEST_MAX_CHUNK_COUNT);
-        // Serialise EVERY chunk and measure it the way the server does
-        // (`Buffer.byteLength(rawBody, "utf8")`), rather than trusting the
-        // planner's own arithmetic — the bug being fixed was precisely a plan
-        // whose arithmetic bore no relation to the bytes on the wire.
-        let observedMax = 0;
-        let seenEntries = 0;
-        for (let index = 0; index < plan.chunkCount; index++) {
-            const chunkUpload = plan.chunk(index);
-            const bytes = Buffer.byteLength(JSON.stringify(chunkUpload), "utf8");
-            expect(bytes).toBeLessThanOrEqual(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET);
-            expect(chunkUpload.entries.length).toBeLessThanOrEqual(SYNC_MANIFEST_MAX_ENTRIES_PER_CHUNK);
-            expect(chunkUpload.chunkCount).toBe(plan.chunkCount);
-            expect(chunkUpload.chunkIndex).toBe(index);
-            // Every chunk must also be one the SERVER's validator accepts, not
-            // merely one that fits: a byte-sized chunk that trips a different bound
-            // is no better than an oversized one.
-            expect(() => validateSyncManifestUpload(JSON.parse(JSON.stringify(chunkUpload)))).not.toThrow();
-            seenEntries += chunkUpload.entries.length;
-            observedMax = Math.max(observedMax, bytes);
-        }
-        // Nothing lost or duplicated across the byte-chosen seams.
-        expect(seenEntries).toBe(ENTRY_COUNT);
-        expect(plan.chunk(0).entries[0].path).toBe(entries[0].path);
-        const last = plan.chunk(plan.chunkCount - 1);
-        expect(last.entries[last.entries.length - 1].path).toBe(entries[ENTRY_COUNT - 1].path);
-        // The plan's own self-report must agree with the measurement, and must not
-        // be so conservative that it wastes most of the budget.
-        expect(plan.maxChunkBytes).toBeGreaterThanOrEqual(observedMax);
-        expect(observedMax).toBeGreaterThan(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET * 0.9);
-    }, 120_000);
-    it("still honours the contract entry ceiling when the byte budget is not the binding bound", () => {
-        // Tiny entries, so 50,001 of them stay under the byte budget and the
-        // ENTRY bound is what cuts. Guards the ceiling itself, which the cases
-        // above deliberately stopped exercising.
-        const entries = new Array(SYNC_MANIFEST_MAX_ENTRIES_PER_CHUNK + 1);
-        for (let index = 0; index < entries.length; index++) {
-            entries[index] = { path: `n/${index}`, size: 1, mtimeMs: NOW_MS, source: "disk" };
-        }
-        const plan = planManifestChunks({
-            entries,
-            removedPaths: [],
-            walkStats,
-            ignoreRules: [],
-            mode: "full",
-            generatedAt: new Date(NOW_MS).toISOString(),
-            installationId: "install-abc123",
-            machineId: "machine-abc123",
-            scope: { kind: "personal" },
-            source: "cli",
-            sequence: 7,
-            chunkByteBudget: SYNC_MANIFEST_MAX_CHUNK_BYTES,
-        });
-        expect(plan.chunkCount).toBe(2);
-        expect(plan.chunk(0).entries).toHaveLength(SYNC_MANIFEST_MAX_ENTRIES_PER_CHUNK);
-        expect(plan.chunk(1).entries).toHaveLength(1);
-    });
-    it("puts removedPaths on the first chunk only, never repeated", () => {
-        const removedPaths = ["notes/gone-a.md", "notes/gone-b.md"];
-        const uploads = chunk(ENTRY_BOUNDARY_PER_CHUNK + 1, removedPaths);
-        expect(uploads).toHaveLength(2);
-        expect(uploads[0].removedPaths).toEqual(removedPaths);
-        // A removal repeated across chunks would make the server de-duplicate, and
-        // a removal on a LATER chunk would be lost if chunk 0 were retried alone.
-        for (const upload of uploads.slice(1)) {
-            expect(upload.removedPaths).toEqual([]);
-        }
-        expect(uploads.flatMap((upload) => upload.removedPaths)).toEqual(removedPaths);
-    });
-    it("emits a valid, chunk-consistent upload for every chunk", () => {
-        const uploads = chunk(SYNC_MANIFEST_MAX_ENTRIES_PER_CHUNK + 1, ["notes/gone.md"]);
-        for (const upload of uploads) {
-            expect(() => validateSyncManifestUpload(upload)).not.toThrow();
-        }
-    });
-});
-/**
- * The personal manifest must describe exactly what the personal PUSH leg
- * ships — no more.
- *
- * The builder previously walked the entire HQ root for a personal scope, while
- * `sync-runner-company.ts` starts the personal share() at
- * `computePersonalVaultPaths()`, which excludes `companies/` for every
- * cloud-backed slug (plus `repos/`, `workspace/` and `.git`). The gap is not
- * cosmetic: it reports one tenant's whole file list under another vault's
- * scope, on every pass, and the server would then chase "missing" objects that
- * the personal bucket was never meant to hold.
- */
-describe("buildSyncManifest — the personal scope walks the personal vault, not the HQ root", () => {
-    /** Mark a slug cloud-backed the way the routing source-of-truth does. */
-    function writeCompaniesManifest(cloudSlugs) {
-        const body = cloudSlugs.map((slug) => `  ${slug}:\n    cloud_uid: cmp_${slug}0000\n`).join("");
-        writeFileAt("companies/manifest.yaml", `companies:\n${body}`);
-    }
-    it("emits zero personal entries under a cloud-backed company directory", async () => {
-        writeCompaniesManifest(["northwind"]);
-        writeFileAt("companies/northwind/deals/secret.md", "tenant content");
-        writeFileAt("personal/notes.md", "mine");
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks.flatMap((chunk) => chunk.entries.map((entry) => entry.path));
-        expect(paths).toContain("personal/notes.md");
-        expect(paths.filter((candidate) => candidate.startsWith("companies/northwind/"))).toEqual([]);
-    });
-    it("still carries companies/manifest.yaml, the one companies/ file the vault needs", async () => {
-        // The routing source-of-truth must travel with the personal vault so a
-        // fresh install can enumerate expected companies before its first pull —
-        // it is a deliberate single-FILE carve-out through an excluded parent, and
-        // a walk that only ever seeds directories would silently drop it.
-        writeCompaniesManifest(["northwind"]);
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks.flatMap((chunk) => chunk.entries.map((entry) => entry.path));
-        expect(paths).toContain("companies/manifest.yaml");
-    });
-    it("keeps a LOCAL (non-cloud) company, which does sync to the personal vault", async () => {
-        writeCompaniesManifest(["northwind"]);
-        writeFileAt("companies/sidequest/plan.md", "local company");
-        const result = await buildSyncManifest(baseOptions());
-        const paths = result.chunks.flatMap((chunk) => chunk.entries.map((entry) => entry.path));
-        expect(paths).toContain("companies/sidequest/plan.md");
-    });
-    it("excludes a slug named in teamSyncedSlugs even with no manifest marker", async () => {
-        writeFileAt("companies/northwind/deals/secret.md", "tenant content");
-        const result = await buildSyncManifest(baseOptions({ teamSyncedSlugs: new Set(["northwind"]) }));
-        const paths = result.chunks.flatMap((chunk) => chunk.entries.map((entry) => entry.path));
-        expect(paths.filter((candidate) => candidate.startsWith("companies/northwind/"))).toEqual([]);
-    });
-    it("does not report a path outside every walk root as removed", async () => {
-        writeFileAt("companies/northwind/deals/secret.md", "tenant content");
-        const base = await buildSyncManifest(baseOptions());
-        expect(base.snapshot.entries["companies/northwind/deals/secret.md"]).toBeDefined();
-        const result = await buildSyncManifest(baseOptions({ sequence: 8, teamSyncedSlugs: new Set(["northwind"]) }));
-        expect(result.mode).toBe("delta");
-        expect(result.chunks[0].removedPaths).toEqual([]);
-    });
-    it("does not report a ledger row under a carved-out company as a vanished file", async () => {
-        // The other half of the carve-out. A path this leg no longer walks is not
-        // a path that disappeared: synthesising a `ledger`-source entry for it
-        // would manufacture one false finding per file of every designated
-        // company, forever.
-        writeCompaniesManifest(["northwind"]);
-        const abs = writeFileAt("companies/northwind/deals/secret.md", "tenant content");
-        const ledgerRow = journalEntryFor(abs);
-        fs.rmSync(abs);
-        const result = await buildSyncManifest(baseOptions({
-            listJournalsImpl: () => summaries(PERSONAL_VAULT_JOURNAL_SLUG, { "companies/northwind/deals/secret.md": ledgerRow }),
-        }));
-        const paths = result.chunks.flatMap((chunk) => chunk.entries.map((entry) => entry.path));
-        expect(paths).not.toContain("companies/northwind/deals/secret.md");
-    });
-    it("leaves the COMPANY scope walking its own root, unchanged", async () => {
-        writeFileAt("companies/northwind/deals/one.md", "one");
-        const result = await buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "cmp_northwind", slug: "northwind" } }));
-        const paths = result.chunks.flatMap((chunk) => chunk.entries.map((entry) => entry.path));
-        expect(paths).toEqual(["deals/one.md"]);
-    });
-});
-/**
- * A post-sync tail step on a laptop may STAT the tree. It may not READ it.
- *
- * Measured on a real personal vault: 690k files, 9m40s, 2.9 GB peak RSS, all
- * of it content hashing, because the journal predated hashing and so had no
- * reusable hash for any file. That cost is not payable after every sync cycle,
- * and the previous `auto` default charged it unconditionally.
- */
-describe("buildSyncManifest — hash policy", () => {
-    it("defaults to stat-only: entries ship WITHOUT a hash rather than being dropped", async () => {
-        writeFileAt("notes/a.md", "hello");
-        const result = await buildSyncManifest(baseOptions({ hashPolicy: undefined }));
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/a.md");
-        // Present, and honest about what it does not know. Dropping it would have
-        // reported a file the client holds as one it does not — the exact false
-        // finding this audit exists to avoid.
-        expect(entry).toBeDefined();
-        expect(entry?.hash).toBeUndefined();
-        expect(entry?.size).toBe(5);
-        expect(result.walkStats.hashedFiles).toBe(0);
-        expect(result.walkStats.unhashedFiles).toBe(1);
-        expect(result.skippedUnhashed).toBe(0);
-    });
-    it("never flags pendingPush from an absent hash", async () => {
-        const abs = writeFileAt("notes/a.md", "hello");
-        const stale = journalEntryFor(abs, { hash: "f".repeat(64), size: 999 });
-        const result = await buildSyncManifest(baseOptions({
-            hashPolicy: "never",
-            listJournalsImpl: () => summaries(PERSONAL_VAULT_JOURNAL_SLUG, { "notes/a.md": stale }),
-        }));
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/a.md");
-        // "The ledger's hash differs from mine" is not a claim a stat-only pass can
-        // make. Asserting it would flag every file on every pass.
-        expect(entry?.pendingPush).toBeUndefined();
-    });
-    it("still reuses a journal hash when the stat pair matches — stat-only is not hash-free", async () => {
-        const abs = writeFileAt("notes/a.md", "hello");
-        const result = await buildSyncManifest(baseOptions({
-            hashPolicy: "never",
-            listJournalsImpl: () => summaries(PERSONAL_VAULT_JOURNAL_SLUG, { "notes/a.md": journalEntryFor(abs) }),
-        }));
-        const entry = result.chunks[0].entries.find((candidate) => candidate.path === "notes/a.md");
-        expect(entry?.hash).toBe(hashFile(abs));
-        expect(result.walkStats.hashedFiles).toBe(0);
-        expect(result.walkStats.unhashedFiles).toBe(0);
-    });
-    it("caps how many files one `auto` pass may read, and ships the rest unhashed", async () => {
-        for (let index = 0; index < 10; index += 1)
-            writeFileAt(`notes/f${index}.md`, `body-${index}`);
-        const result = await buildSyncManifest(baseOptions({ hashPolicy: "auto", maxHashedFiles: 3 }));
-        const entries = result.chunks.flatMap((chunk) => chunk.entries);
-        expect(entries).toHaveLength(10);
-        expect(result.walkStats.hashedFiles).toBe(3);
-        expect(result.walkStats.unhashedFiles).toBe(7);
-        // Nothing is dropped: the picture is complete, some of it is just unverified.
-        expect(result.skippedUnhashed).toBe(0);
-    });
-    it("`full` hashes everything the journal cannot cover", async () => {
-        for (let index = 0; index < 5; index += 1)
-            writeFileAt(`notes/f${index}.md`, `body-${index}`);
-        const result = await buildSyncManifest(baseOptions({ hashPolicy: "full" }));
-        expect(result.walkStats.hashedFiles).toBe(5);
-        expect(result.walkStats.unhashedFiles).toBe(0);
-    });
-    it("does not re-send an unhashed entry whose stat pair is unchanged since the base", async () => {
-        // Base erosion guard: a stat-only pass has no hash to store, so a naive
-        // implementation drops the path from the snapshot it persists and the NEXT
-        // pass re-sends the whole scope as "changed" — a delta wearing a full
-        // manifest's clothes.
-        const abs = writeFileAt("notes/a.md", "hello");
-        const stats = fs.lstatSync(abs);
-        writeManifestSnapshot(stateDir, "personal", {
-            snapshotId: "snap-base",
-            generatedAt: new Date(NOW_MS - 1000).toISOString(),
-            sequence: 1,
-            entries: {
-                "notes/a.md": { hash: hashFile(abs), size: stats.size, mtimeMs: Math.floor(stats.mtimeMs) },
-            },
-        });
-        const result = await buildSyncManifest(baseOptions({ hashPolicy: "never", sequence: 2 }));
-        expect(result.mode).toBe("delta");
-        expect(result.chunks[0].entries).toEqual([]);
-        expect(result.chunks[0].removedPaths).toEqual([]);
-        // The hash survived into the new base rather than being dropped.
-        expect(result.snapshot.entries["notes/a.md"]?.hash).toBe(hashFile(abs));
-    });
-    it("never reports an unhashed entry as removed on the next delta", async () => {
-        const abs = writeFileAt("notes/a.md", "hello");
-        const stats = fs.lstatSync(abs);
-        writeManifestSnapshot(stateDir, "personal", {
-            snapshotId: "snap-base",
-            generatedAt: new Date(NOW_MS - 1000).toISOString(),
-            sequence: 1,
-            entries: {
-                // Different hash AND different stat pair: the file has changed, so it
-                // cannot be carried forward — but it is still very much present.
-                "notes/a.md": { hash: "a".repeat(64), size: 1, mtimeMs: 1 },
-            },
-        });
-        const result = await buildSyncManifest(baseOptions({ hashPolicy: "never", sequence: 2 }));
-        expect(result.chunks[0].removedPaths).toEqual([]);
-        expect(result.chunks[0].entries.map((entry) => entry.path)).toContain("notes/a.md");
-        expect(stats.size).toBe(5);
-    });
-});
-/**
- * The operator's machine, reproduced against the REAL journal reader.
- *
- * No `listJournalsImpl` stub here on purpose: the incident lived in the seam
- * the stub bypasses. Every v3 generation (`snapshot-*.bin`, `wal-*.bin`) was
- * truncated and no legacy shard remained, the ledger read answered `null`, the
- * builder coalesced that `null` to an empty Map, and 188,997 files were
- * reported as on-disk-never-tracked with no `ledgerUnavailable` marker to warn
- * anyone.
- */
-describe("buildSyncManifest — unreadable v3 ledger", () => {
-    let previousStateDir;
-    beforeEach(() => {
-        previousStateDir = process.env.HQ_STATE_DIR;
-        process.env.HQ_STATE_DIR = stateDir;
-    });
-    afterEach(() => {
-        if (previousStateDir === undefined)
-            delete process.env.HQ_STATE_DIR;
-        else
-            process.env.HQ_STATE_DIR = previousStateDir;
-    });
-    /** Promote a legacy shard into a v3 store, then drop the legacy locator. */
-    function seedV3OnlyLedger(files) {
-        fs.writeFileSync(path.join(stateDir, `sync-journal.${PERSONAL_VAULT_JOURNAL_SLUG}.json`), JSON.stringify(journalWith(files)), "utf8");
-        openJournalStoreSession(PERSONAL_VAULT_JOURNAL_SLUG).dispose();
-        fs.rmSync(path.join(stateDir, `sync-journal.${PERSONAL_VAULT_JOURNAL_SLUG}.json`));
-    }
-    function truncateEveryGeneration() {
-        const root = path.join(stateDir, "sync-state-v3");
-        let truncated = 0;
-        for (const scope of fs.readdirSync(root)) {
-            const dir = path.join(root, scope);
-            if (!fs.statSync(dir).isDirectory())
-                continue;
-            for (const name of fs.readdirSync(dir)) {
-                if (!/^(?:snapshot|wal)-\d+\.bin$/.test(name))
-                    continue;
-                fs.writeFileSync(path.join(dir, name), "");
-                truncated += 1;
-            }
-        }
-        expect(truncated).toBeGreaterThan(0);
-    }
-    it("marks the manifest ledgerUnavailable instead of reporting every file as untracked", async () => {
-        const abs = writeFileAt("notes/tracked.md", "hello");
-        seedV3OnlyLedger({ "notes/tracked.md": journalEntryFor(abs) });
-        truncateEveryGeneration();
-        const result = await buildSyncManifest(baseOptions({ listJournalsImpl: undefined, persistSnapshot: false }));
-        // THE assertion. Without it the pass looks exactly like a healthy machine
-        // that has never tracked anything, and uploads on that basis.
-        expect(result.chunks[0].ledgerUnavailable).toEqual({ errorClass: "StateStoreCorruptionError" });
-        // The disk picture is still reported — the audit wants it, and every entry
-        // honestly says "ledger unknown" rather than "ledger says no".
-        expect(result.chunks[0].entries.map((entry) => entry.path)).toEqual(["notes/tracked.md"]);
-        expect(result.chunks[0].entries.every((entry) => entry.source === "disk")).toBe(true);
-    });
-    it("reads a healthy v3 store that has no legacy shard beside it", async () => {
-        const abs = writeFileAt("notes/tracked.md", "hello");
-        seedV3OnlyLedger({ "notes/tracked.md": journalEntryFor(abs) });
-        const result = await buildSyncManifest(baseOptions({ listJournalsImpl: undefined, persistSnapshot: false }));
-        // The other half of the same bug: the pre-fix gate only enumerated LEGACY
-        // locator files, so a fully-migrated scope read as "no ledger" even when
-        // its store was perfectly healthy.
-        expect(result.chunks[0].ledgerUnavailable).toBeUndefined();
-        expect(result.chunks[0].entries[0].source).toBe("both");
-    });
-    it("treats a fresh install with no ledger artifacts as an EMPTY ledger, not an unavailable one", async () => {
-        writeFileAt("notes/new.md", "hello");
-        const result = await buildSyncManifest(baseOptions({ listJournalsImpl: undefined, persistSnapshot: false }));
-        expect(result.chunks[0].ledgerUnavailable).toBeUndefined();
-        expect(result.chunks[0].entries[0].source).toBe("disk");
-    });
-});
-describe("buildSyncManifest — company anchor in the wire scope", () => {
-    it("ships the slug and scope root it actually walked for a company scope", async () => {
-        writeFileAt("companies/acme/deal.md", "acme");
-        const result = await buildSyncManifest(baseOptions({ scope: { kind: "company", companyUid: "co-acme", slug: "acme" } }));
-        expect(result.chunks[0].scope.companySlug).toBe("acme");
-        expect(result.chunks[0].scope.scopeRoot).toBe("companies/acme");
-    });
-    it("ships neither anchor field for a personal scope", async () => {
-        writeFileAt("notes/keep.md", "keep");
-        const result = await buildSyncManifest(baseOptions());
-        expect(result.chunks[0].scope.companySlug).toBeUndefined();
-        expect(result.chunks[0].scope.scopeRoot).toBeUndefined();
-    });
-});
-//# sourceMappingURL=build-manifest.test.js.map