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

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

@@ -1,930 +0,0 @@
-/**
- * Stat-walk benchmark for the manifest builder (US-002).
- *
- * The acceptance bar is a cost bar, not a correctness one: a 70,000-file HQ
- * root must be enumerable in under 2 seconds and under 64 MB of resident
- * growth, because this runs in the background on a laptop that is also
- * running the user's editor. A regression here does not break the audit — it
- * makes the machine feel slow, which is the failure mode that gets the whole
- * feature switched off.
- *
- * The measurement is deliberately narrow:
- *
- *   - the fixture is built ONCE in `beforeAll` and excluded from the timing;
- *   - files are empty, so the numbers describe directory traversal + `lstat`,
- *     not disk throughput;
- *   - `hashPolicy: "ledger-only"` guarantees not a single byte of content is
- *     read, so sha256 throughput cannot mask a walk regression;
- *   - only `walkStats.walkMs` is asserted — the builder's own measurement of
- *     the walk, not the harness's view of the whole call.
- */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { buildSyncManifest, DEFAULT_MANIFEST_YIELD_EVERY, setBuildManifestMemoryReferencesHookForTest, } from "./build-manifest.js";
-import { SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET, SYNC_MANIFEST_MAX_CHUNK_BYTES, assertSyncManifestPath, } from "./contract.js";
-import { createIgnoreFilter } from "../ignore.js";
-import { PERSONAL_VAULT_JOURNAL_SLUG, hashFile } from "../journal.js";
-import { collectGarbage, acquireGc as acquireMemoryGc, usedBytes } from "../journal-snapshot-memory-helpers.js";
-import { wrapFilterWithPersonalVaultDefaults } from "../personal-vault-exclusions.js";
-import { runManifestUploadPass } from "./upload-manifest.js";
-const FILE_COUNT = 70_000;
-const DIRECTORY_COUNT = 700;
-const WALK_RUN_COUNT = 7;
-const CONTROL_DIRECTORY_COUNT = 700;
-const CONTROL_FILE_COUNT = 70_000;
-/**
- * The cost gates are a paired walk/control ratio and resident-memory growth.
- * The control performs the production walk's entry preparation: filtering,
- * path canonicalisation, contract validation, metadata map and yield cadence,
- * but does not call the production walker. A genuine per-entry allocation,
- * syscall, or traversal step raises the ratio even when a slow runner makes
- * both workloads take longer.
- *
- * The paired-ratio gate supersedes the scaled wall-clock assertion. The ratio
- * is machine-independent; a wall-clock bound never was. A scaled wall-clock
- * budget needs a fixed reference control time; when this fixture changed, that
- * constant silently became stale and the assertion stopped constraining the
- * walk. This was a maintenance trap that already failed once. Absolute timings
- * remain in the output for diagnosis, but are not a product gate.
- *
- * Each of the seven trials starts by warming the fixture with the control,
- * then measures one control. The fixture is warmed the same way again before
- * measuring the production walk. That gives each side the same dentry and
- * page-cache condition, instead of silently giving the walk the control's
- * warm cache. The gate compares the median of the paired ratios: it neither
- * combines two different order statistics nor lets one unusually fast walk
- * hide a regression. The larger 70,000-file control keeps its timing noise
- * materially below the 15% regression this gate is intended to catch.
- *
- * A duplicate `lstat` of the path just walked is the Linux lower-bound control:
- * the old unpaired measurement made it look nearly free, but paired warm-cache
- * samples still distinguish it from healthy work. This file does NOT run in
- * `pnpm test`; `vitest.bench.config.ts` and the `manifest-bench` CI job run it
- * alone in one fork.
- */
-// Ubuntu 24.04 paired medians: healthy 1.04–1.07 (four samples); duplicate
-// lstat 1.16–1.21; different-path lstat 1.21–1.31; and redundant per-entry
-// path construction 1.14–1.18. Linux therefore uses 1.10: 2.8% above the
-// slowest healthy sample and 3.6% below the smallest claimed regression.
-// macOS retains its previous ceiling while Linux is tightened here; this
-// change makes no new cross-platform calibration claim.
-const MAX_WALK_TO_CONTROL_RATIO = process.platform === "linux" ? 1.1 : 2.3;
-const MAX_RSS_GROWTH_BYTES = 64 * 1024 * 1024;
-/**
- * Cold-ledger hash benchmark: how much does the FIRST pass after an upgrade
- * cost when the journal has no reusable hash for anything?
- *
- * This is the case that broke on a real machine. The personal vault held
- * ~690k files, the journal predated hashing, and the then-default `auto`
- * policy therefore READ every one of them: 9m40s and 2.9 GB peak RSS for a
- * step that runs after every sync cycle. The stat walk is not the problem —
- * opening files is.
- *
- * 5,000 files is enough to measure per-file open+read+digest cost honestly
- * while keeping the fixture buildable in CI; the numbers are printed so the
- * README can quote a measured figure rather than a guess.
- */
-const HASH_FILE_COUNT = 5_000;
-const HASH_FILE_BYTES = 4 * 1024;
-/**
- * `vitest.bench.config.ts` starts the single worker with `--expose-gc`, so each
- * RSS baseline follows a collection of the fixture-construction garbage. The
- * old VM-context fallback exposed a collector for a different global and did
- * not collect this worker's heap, which made macOS charge the fixture to the
- * walk.
- */
-function acquireGc() {
-    const exposed = globalThis.gc;
-    if (typeof exposed === "function")
-        return exposed;
-    throw new Error("manifest benchmark requires a worker started with --expose-gc");
-}
-let base;
-let hqRoot;
-let stateDir;
-let controlDirectories;
-let controlShouldSync;
-let fixtureBuildMs;
-async function measureWalkControl() {
-    const startedAt = performance.now();
-    const records = new Map();
-    let sinceYield = 0;
-    for (const directory of controlDirectories) {
-        const directoryPath = path.join(hqRoot, "bench", directory);
-        const relativeDirectory = `bench/${directory}`;
-        const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isFile())
-                continue;
-            const entryPath = path.join(directoryPath, entry.name);
-            if (!controlShouldSync(entryPath, false))
-                continue;
-            const manifestPath = relativeDirectory.concat("/", entry.name).normalize("NFC");
-            assertSyncManifestPath("path", manifestPath);
-            if (records.has(manifestPath))
-                continue;
-            const stats = fs.lstatSync(entryPath);
-            records.set(manifestPath, {
-                mtimeMs: Math.floor(stats.mtimeMs),
-                size: stats.size,
-                isSymlink: stats.isSymbolicLink(),
-            });
-            if (++sinceYield >= DEFAULT_MANIFEST_YIELD_EVERY) {
-                sinceYield = 0;
-                await new Promise((resolve) => setTimeout(resolve, 0));
-            }
-        }
-    }
-    expect(records.size).toBe(CONTROL_FILE_COUNT);
-    return performance.now() - startedAt;
-}
-async function measureBuildManifestWalk() {
-    const result = await buildSyncManifest({
-        scope: { kind: "personal" },
-        hqRoot,
-        stateDir,
-        installationId: "install-bench",
-        machineId: "machine-bench",
-        source: "cli",
-        sequence: 1,
-        hashPolicy: "ledger-only",
-        listJournalsImpl: () => [],
-        // Well above the budget: the assertion below is what fails on a
-        // regression, not a truncated walk that would silently "pass" fast.
-        maxWallMs: 120_000,
-        persistSnapshot: false,
-    });
-    expect(result.walkStats.truncated).toBe(false);
-    expect(result.walkStats.filesWalked).toBe(FILE_COUNT);
-    expect(result.walkStats.hashedFiles).toBe(0);
-    return result.walkStats.walkMs;
-}
-function median(values) {
-    const sorted = [...values].sort((left, right) => left - right);
-    return sorted[Math.floor(sorted.length / 2)];
-}
-describe("buildSyncManifest stat-walk benchmark", () => {
-    beforeAll(() => {
-        const fixtureStartedAt = performance.now();
-        base = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-bench-"));
-        hqRoot = path.join(base, "hq");
-        stateDir = path.join(base, "state");
-        fs.mkdirSync(stateDir, { recursive: true });
-        // 700 directories x 100 files: wide enough that per-directory `readdir`
-        // overhead is represented, shallow enough to stay realistic for an HQ root.
-        const perDirectory = FILE_COUNT / DIRECTORY_COUNT;
-        for (let dirIndex = 0; dirIndex < DIRECTORY_COUNT; dirIndex++) {
-            const dir = path.join(hqRoot, "bench", `d${dirIndex}`);
-            fs.mkdirSync(dir, { recursive: true });
-            for (let fileIndex = 0; fileIndex < perDirectory; fileIndex++) {
-                fs.writeFileSync(path.join(dir, `f${fileIndex}.md`), "");
-            }
-        }
-        controlDirectories = fs
-            .readdirSync(path.join(hqRoot, "bench"), { withFileTypes: true })
-            .filter((entry) => entry.isDirectory())
-            .slice(0, CONTROL_DIRECTORY_COUNT)
-            .map((entry) => entry.name);
-        expect(controlDirectories).toHaveLength(CONTROL_DIRECTORY_COUNT);
-        controlShouldSync = wrapFilterWithPersonalVaultDefaults(createIgnoreFilter(hqRoot), hqRoot, () => { });
-        fixtureBuildMs = performance.now() - fixtureStartedAt;
-    }, 300_000);
-    afterAll(() => {
-        fs.rmSync(base, { recursive: true, force: true });
-    });
-    it(`walks ${FILE_COUNT} files within budget`, async () => {
-        const forceGc = acquireGc();
-        const measurements = [];
-        let rssGrowth = 0;
-        let heapGrowth = 0;
-        for (let run = 0; run < WALK_RUN_COUNT; run += 1) {
-            // Run the same preparation before each side of the pair. Measuring a
-            // control and then timing the walk would make cache warmth a hidden,
-            // asymmetric input to the ratio.
-            forceGc();
-            await measureWalkControl();
-            forceGc();
-            const controlMs = await measureWalkControl();
-            forceGc();
-            await measureWalkControl();
-            forceGc();
-            const memoryBefore = run === 0 ? process.memoryUsage() : undefined;
-            const walkMs = await measureBuildManifestWalk();
-            if (memoryBefore !== undefined) {
-                forceGc();
-                const memoryAfter = process.memoryUsage();
-                rssGrowth = memoryAfter.rss - memoryBefore.rss;
-                heapGrowth = memoryAfter.heapUsed - memoryBefore.heapUsed;
-            }
-            measurements.push({ controlMs, walkMs });
-        }
-        const medianControlMs = median(measurements.map((measurement) => measurement.controlMs));
-        const medianWalkMs = median(measurements.map((measurement) => measurement.walkMs));
-        const ratios = measurements.map((measurement) => measurement.walkMs / measurement.controlMs);
-        const medianWalkToControlRatio = median(ratios);
-        // macOS's allocator retains mapped pages after a V8 collection, so its RSS
-        // delta includes allocator mappings left by the fixture even though the
-        // retained manifest heap is small. This stat-only walk owns no content
-        // buffers or native allocations; heap growth is therefore the comparable
-        // retained-code metric on macOS. Linux keeps the product's RSS gate.
-        const memoryGrowth = process.platform === "darwin" ? heapGrowth : rssGrowth;
-        const memoryMetric = process.platform === "darwin" ? "heap" : "RSS";
-        // Print every trial so a CI run records the machine-normalised evidence,
-        // rather than only a pass/fail verdict from its current runner pool.
-        process.stdout.write(`manifest stat-walk: fixture ${fixtureBuildMs.toFixed(1)}ms; ${measurements.map((measurement) => `${measurement.walkMs}ms/${measurement.controlMs.toFixed(1)}ms=${(measurement.walkMs / measurement.controlMs).toFixed(2)}`).join(", ")}; ` +
-            `median walk ${medianWalkMs}ms, median control ${medianControlMs.toFixed(1)}ms, ` +
-            `median paired ratio ${medianWalkToControlRatio.toFixed(2)}, ` +
-            `${(rssGrowth / (1024 * 1024)).toFixed(1)}MB RSS, ` +
-            `${(heapGrowth / (1024 * 1024)).toFixed(1)}MB heap; ` +
-            `${(memoryGrowth / (1024 * 1024)).toFixed(1)}MB ${memoryMetric} for ${FILE_COUNT} files\n`);
-        expect(medianWalkToControlRatio).toBeLessThan(MAX_WALK_TO_CONTROL_RATIO);
-        expect(memoryGrowth).toBeLessThan(MAX_RSS_GROWTH_BYTES);
-    }, 120_000);
-});
-// ─────────────────────────────────────────────────────────────────────────────
-// Resident manifest boundary (memory)
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * This is deliberately larger than the ordinary 70k walk fixture. The post-
- * sync full reconcile that motivated this gate retains the manifest result for
- * upload, so its graph scales with the whole scope rather than one chunk. A
- * 200k-file fixture keeps that cardinality (and every whole-scope map/object
- * shape) representative while fitting in the benchmark job's isolated runner.
- */
-const RESIDENT_FILE_COUNT = 200_000;
-const RESIDENT_DIRECTORY_COUNT = 2_000;
-const RESIDENT_FILES_PER_DIRECTORY = RESIDENT_FILE_COUNT / RESIDENT_DIRECTORY_COUNT;
-// Origin/main measured 123.2 MiB after three churned full builds. The 110 MiB
-// ceiling requires at least a 10.7% reduction while leaving ~14 MiB of
-// headroom over the expected post-change result on the benchmark runner.
-const MAX_RESIDENT_BOUNDARY_BYTES = 110 * 1024 * 1024;
-function bytesPerFile(bytes) {
-    return bytes / RESIDENT_FILE_COUNT;
-}
-describe("buildSyncManifest resident boundary", () => {
-    let residentBase;
-    let residentRoot;
-    let residentStateDir;
-    let residentEmptyHash;
-    let collect;
-    let residentReferencesForAttribution;
-    beforeAll(() => {
-        residentBase = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-resident-"));
-        residentRoot = path.join(residentBase, "hq");
-        residentStateDir = path.join(residentBase, "state");
-        fs.mkdirSync(residentStateDir, { recursive: true });
-        for (let directoryIndex = 0; directoryIndex < RESIDENT_DIRECTORY_COUNT; directoryIndex += 1) {
-            const directory = path.join(residentRoot, "resident", `d${directoryIndex}`);
-            fs.mkdirSync(directory, { recursive: true });
-            for (let fileIndex = 0; fileIndex < RESIDENT_FILES_PER_DIRECTORY; fileIndex += 1) {
-                fs.writeFileSync(path.join(directory, `f${fileIndex}.md`), "");
-            }
-        }
-        residentEmptyHash = hashFile(path.join(residentRoot, "resident", "d0", "f0.md"));
-        collect = acquireMemoryGc();
-    }, 600_000);
-    afterAll(() => {
-        setBuildManifestMemoryReferencesHookForTest(undefined);
-        fs.rmSync(residentBase, { recursive: true, force: true });
-    });
-    function ledgerFor(generation) {
-        const files = Object.create(null);
-        for (let directoryIndex = 0; directoryIndex < RESIDENT_DIRECTORY_COUNT; directoryIndex += 1) {
-            for (let fileIndex = 0; fileIndex < RESIDENT_FILES_PER_DIRECTORY; fileIndex += 1) {
-                const relative = `resident/d${directoryIndex}/f${fileIndex}.md`;
-                const stats = fs.lstatSync(path.join(residentRoot, relative));
-                files[relative] = {
-                    hash: residentEmptyHash,
-                    size: stats.size,
-                    mtimeMs: Math.floor(stats.mtimeMs),
-                    syncedAt: `2026-09-12T00:00:0${generation}.000Z`,
-                    direction: generation % 2 === 0 ? "up" : "down",
-                    remoteEtag: `resident-${generation}-${directoryIndex % 29}`,
-                };
-            }
-        }
-        let journal = {
-            version: "2",
-            lastSync: "2026-09-12T00:00:00.000Z",
-            files,
-            pulls: [],
-        };
-        return () => {
-            const current = journal;
-            journal = undefined;
-            if (!current)
-                throw new Error("resident benchmark ledger was read more than once");
-            return [{ slug: PERSONAL_VAULT_JOURNAL_SLUG, path: "/state/resident.json", journal: current }];
-        };
-    }
-    async function measureResidentBoundary(generation, retainReferences = false, options = {}) {
-        collectGarbage(collect);
-        const baseline = usedBytes();
-        let references;
-        let boundary = 0;
-        setBuildManifestMemoryReferencesHookForTest((sample) => {
-            references = sample;
-            if (retainReferences)
-                residentReferencesForAttribution = sample;
-            collectGarbage(collect);
-            boundary = usedBytes();
-        });
-        try {
-            const result = await buildSyncManifest({
-                scope: { kind: "personal" },
-                hqRoot: residentRoot,
-                stateDir: residentStateDir,
-                installationId: "resident-install",
-                machineId: "resident-machine",
-                source: "cli",
-                sequence: generation,
-                hashPolicy: "never",
-                forceFull: options.forceFull ?? true,
-                listJournalsImpl: options.listJournalsImpl ?? ledgerFor(generation),
-                maxWallMs: 600_000,
-                persistSnapshot: options.persistSnapshot ?? false,
-            });
-            if (options.forceFull !== false)
-                expect(result.mode).toBe("full");
-            expect(result.walkStats.filesWalked).toBe(options.expectedFilesWalked ?? RESIDENT_FILE_COUNT);
-        }
-        finally {
-            setBuildManifestMemoryReferencesHookForTest(undefined);
-        }
-        if (!references)
-            throw new Error("resident benchmark did not observe the manifest boundary");
-        return {
-            baseline,
-            boundary,
-            growth: boundary - baseline,
-            walkRecords: references.walkRecords.size,
-            ledgerEntries: references.ledgerEntries.size,
-            entries: references.entries.length,
-            snapshotEntries: Object.keys(references.snapshotEntries).length,
-            changed: references.changed?.length ?? 0,
-            present: references.present?.size ?? 0,
-            removed: references.removed?.length ?? 0,
-        };
-    }
-    function releasedBytes(release) {
-        const before = usedBytes();
-        release();
-        collectGarbage(collect);
-        return before - usedBytes();
-    }
-    function clearSnapshotEntries(entries) {
-        for (const key in entries)
-            delete entries[key];
-    }
-    function attributeFullBoundary() {
-        const references = residentReferencesForAttribution;
-        if (!references)
-            throw new Error("resident benchmark did not retain full-boundary references");
-        // Release in reverse dependency order. Strings shared by two structures are
-        // charged to the last owner, making this a reproducible retained-graph
-        // attribution rather than a double-counted object-size estimate.
-        const snapshotEntries = releasedBytes(() => clearSnapshotEntries(references.snapshotEntries));
-        const entries = releasedBytes(() => {
-            references.entries.length = 0;
-        });
-        const walkRecords = releasedBytes(() => {
-            references.walkRecords.clear();
-        });
-        const ledgerEntries = releasedBytes(() => {
-            references.ledgerEntries.clear();
-        });
-        return { walkRecords, ledgerEntries, entries, snapshotEntries, changed: 0, present: 0, removed: 0 };
-    }
-    async function attributeDeltaTransients() {
-        let baseResult = await buildSyncManifest({
-            scope: { kind: "personal" },
-            hqRoot: residentRoot,
-            stateDir: residentStateDir,
-            installationId: "resident-install",
-            machineId: "resident-machine",
-            source: "cli",
-            sequence: 5,
-            hashPolicy: "never",
-            forceFull: true,
-            listJournalsImpl: ledgerFor(5),
-            maxWallMs: 600_000,
-        });
-        expect(baseResult.mode).toBe("full");
-        // A previous full result is not part of the delta boundary. Release it
-        // before measuring so its entries cannot be mischarged to `changed`.
-        baseResult = undefined;
-        collectGarbage(collect);
-        const changedAt = new Date(Date.parse("2026-09-12T01:00:00.000Z"));
-        for (let directoryIndex = 0; directoryIndex < RESIDENT_DIRECTORY_COUNT; directoryIndex += 1) {
-            for (let fileIndex = 0; fileIndex < RESIDENT_FILES_PER_DIRECTORY; fileIndex += 1) {
-                fs.utimesSync(path.join(residentRoot, "resident", `d${directoryIndex}`, `f${fileIndex}.md`), changedAt, changedAt);
-            }
-        }
-        await measureResidentBoundary(6, true, { forceFull: false, persistSnapshot: true });
-        // The test hook runs while `buildSyncManifest` still has its source-journal
-        // call frame. Its compact LedgerIndex is retained through `references`,
-        // but the fabricated JournalSummary is not part of this delta boundary.
-        // Let that caller frame die before charging a release to one transient.
-        collectGarbage(collect);
-        const references = residentReferencesForAttribution;
-        if (!references?.changed) {
-            throw new Error("resident benchmark did not retain delta transients");
-        }
-        // `snapshotEntries` omits stat-only paths, so the old `present` set was
-        // not removable on its own. The builder now checks the walk-key set first
-        // and snapshot ownership second, then clears the key set at its last use.
-        // A new `present` allocation would recreate the whole-scope transient.
-        expect(references.present).toBeUndefined();
-        const present = 0;
-        const changed = releasedBytes(() => {
-            if (references.changed)
-                references.changed.length = 0;
-        });
-        return { changed, present };
-    }
-    async function attributeRemovedTransient() {
-        fs.rmSync(path.join(residentRoot, "resident"), { recursive: true, force: true });
-        await measureResidentBoundary(7, true, {
-            forceFull: false,
-            listJournalsImpl: () => [],
-            expectedFilesWalked: 0,
-        });
-        const references = residentReferencesForAttribution;
-        if (!references?.removed)
-            throw new Error("resident benchmark did not retain removed paths");
-        return releasedBytes(() => {
-            if (references.removed)
-                references.removed.length = 0;
-        });
-    }
-    it(`drops whole-scope walk records at the ${RESIDENT_FILE_COUNT}-file resident boundary`, async () => {
-        const seeded = await measureResidentBoundary(1);
-        // Rebuilding the same scope with distinct ledger metadata three times is
-        // the post-sync churn this result sees in production. Keep only the final
-        // result alive at each boundary; a prior pass must not leak into the next.
-        let churned = seeded;
-        for (let generation = 2; generation <= 4; generation += 1) {
-            churned = await measureResidentBoundary(generation, generation === 4);
-        }
-        const fullAttribution = attributeFullBoundary();
-        const deltaAttribution = await attributeDeltaTransients();
-        const removed = await attributeRemovedTransient();
-        process.stdout.write(`manifest resident boundary: ${RESIDENT_FILE_COUNT} files; ` +
-            `seeded ${(seeded.growth / (1024 * 1024)).toFixed(1)}MiB ` +
-            `(${bytesPerFile(seeded.growth).toFixed(1)}B/file); ` +
-            `churned ${(churned.growth / (1024 * 1024)).toFixed(1)}MiB ` +
-            `(${bytesPerFile(churned.growth).toFixed(1)}B/file); ` +
-            `seeded maps walk=${seeded.walkRecords} ledger=${seeded.ledgerEntries} ` +
-            `entries=${seeded.entries} snapshot=${seeded.snapshotEntries}; ` +
-            `churned maps walk=${churned.walkRecords} ledger=${churned.ledgerEntries} ` +
-            `entries=${churned.entries} snapshot=${churned.snapshotEntries}\n`);
-        for (const [name, bytes] of [
-            ["walk.records", fullAttribution.walkRecords],
-            ["ledger.entries", fullAttribution.ledgerEntries],
-            ["entries", fullAttribution.entries],
-            ["snapshotEntries", fullAttribution.snapshotEntries],
-            ["changed", deltaAttribution.changed],
-            ["present", deltaAttribution.present],
-            ["removed", removed],
-        ]) {
-            process.stdout.write(`manifest resident attribution: ${name} ${(bytes / (1024 * 1024)).toFixed(1)}MiB ` +
-                `(${bytesPerFile(bytes).toFixed(1)}B/file)\n`);
-        }
-        // The only consumer after the disk/ledger union needs membership, not the
-        // full record values. This assertion is intentionally red before the
-        // resident reduction: a non-empty map at this boundary is the retained
-        // whole-scope graph the test is here to eliminate.
-        expect(seeded.walkRecords).toBe(0);
-        expect(churned.walkRecords).toBe(0);
-        expect(seeded.growth).toBeLessThan(MAX_RESIDENT_BOUNDARY_BYTES);
-        expect(churned.growth).toBeLessThan(MAX_RESIDENT_BOUNDARY_BYTES);
-    }, 600_000);
-});
-/**
- * The cost of a COLD ledger, and the guarantee that the default never pays it.
- *
- * Separate fixture from the stat-walk bench above: that one uses empty files
- * (so it measures traversal), while this one needs real bytes to measure
- * open + read + sha256.
- */
-describe("buildSyncManifest cold-ledger hash cost", () => {
-    let hashBase;
-    let hashRoot;
-    let hashStateDir;
-    beforeAll(() => {
-        hashBase = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-hash-bench-"));
-        hashRoot = path.join(hashBase, "hq");
-        hashStateDir = path.join(hashBase, "state");
-        fs.mkdirSync(hashStateDir, { recursive: true });
-        const body = "x".repeat(HASH_FILE_BYTES);
-        const perDirectory = 100;
-        for (let index = 0; index < HASH_FILE_COUNT; index += 1) {
-            const dir = path.join(hashRoot, "bench", `d${Math.floor(index / perDirectory)}`);
-            fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(path.join(dir, `f${index}.md`), body);
-        }
-    }, 300_000);
-    afterAll(() => {
-        fs.rmSync(hashBase, { recursive: true, force: true });
-    });
-    function optionsFor(overrides) {
-        return {
-            scope: { kind: "personal" },
-            hqRoot: hashRoot,
-            stateDir: hashStateDir,
-            installationId: "install-bench",
-            machineId: "machine-bench",
-            source: "cli",
-            sequence: 1,
-            listJournalsImpl: () => [],
-            maxWallMs: 600_000,
-            persistSnapshot: false,
-            ...overrides,
-        };
-    }
-    it(`measures the unbounded first-pass hash cost for ${HASH_FILE_COUNT} cold files`, async () => {
-        const forceGc = acquireGc();
-        forceGc?.();
-        const rssBefore = process.memoryUsage().rss;
-        const startedAt = Date.now();
-        const result = await buildSyncManifest(optionsFor({ hashPolicy: "full" }));
-        const elapsedMs = Date.now() - startedAt;
-        forceGc?.();
-        const rssGrowthMb = (process.memoryUsage().rss - rssBefore) / (1024 * 1024);
-        // Recorded, not asserted as a budget: this measures the path the default
-        // deliberately avoids, and its absolute cost varies wildly by disk. The
-        // README quotes these numbers.
-        process.stdout.write(`manifest cold-ledger hash (hashPolicy="full"): ${HASH_FILE_COUNT} files: ` +
-            `${elapsedMs}ms / ${rssGrowthMb.toFixed(1)}MB RSS ` +
-            `(${((HASH_FILE_COUNT * HASH_FILE_BYTES) / (1024 * 1024)).toFixed(1)}MB read)\n`);
-        expect(result.walkStats.hashedFiles).toBe(HASH_FILE_COUNT);
-        expect(result.walkStats.unhashedFiles).toBe(0);
-    }, 600_000);
-    it("the DEFAULT policy reads nothing at all on the same cold fixture", async () => {
-        // The guarantee the fix rests on. Every file is still REPORTED — the
-        // manifest is complete — it is just stat-only, so the first pass after an
-        // upgrade costs a walk instead of a full read of the vault.
-        const startedAt = Date.now();
-        const result = await buildSyncManifest(optionsFor({}));
-        const elapsedMs = Date.now() - startedAt;
-        process.stdout.write(`manifest cold-ledger stat-only (default): ${HASH_FILE_COUNT} files: ${elapsedMs}ms\n`);
-        expect(result.walkStats.hashedFiles).toBe(0);
-        expect(result.walkStats.unhashedFiles).toBe(HASH_FILE_COUNT);
-        expect(result.walkStats.filesWalked).toBe(HASH_FILE_COUNT);
-        expect(result.chunks.flatMap((chunk) => chunk.entries)).toHaveLength(HASH_FILE_COUNT);
-    }, 300_000);
-    it("`auto` spreads the cost across passes instead of paying it all at once", async () => {
-        const result = await buildSyncManifest(optionsFor({ hashPolicy: "auto", maxHashedFiles: 500, maxHashMs: 60_000 }));
-        expect(result.walkStats.hashedFiles).toBe(500);
-        expect(result.walkStats.unhashedFiles).toBe(HASH_FILE_COUNT - 500);
-        // Bounded, but never lossy: the scope is still fully described.
-        expect(result.chunks.flatMap((chunk) => chunk.entries)).toHaveLength(HASH_FILE_COUNT);
-    }, 300_000);
-});
-// ─────────────────────────────────────────────────────────────────────────────
-// Ledger read cost (memory)
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * The manifest tail step's memory footprint, measured on the shape that
- * actually hurt: a vault whose JOURNAL is large.
- *
- * WHY THIS IS A GATE, NOT A REPORT
- * --------------------------------
- * On a real operator vault this step peaked at 1,112 MB of resident memory for
- * a 199k-entry personal scope. It is a background audit that runs after every
- * sync pass on a laptop that is also running the user's editor, so a gigabyte
- * is not a slow audit — it is the reason a user switches the feature off.
- *
- * FOUR CAUSES, ALL IN THE LEDGER READ, NONE IN THE WALK
- * -----------------------------------------------------
- * Measured on a 200,000-file synthetic tree, the walk itself costs ~220 MB and
- * the build's chunking and snapshot add ~10 MB. Everything else was spent
- * before the walk statted its first file:
- *
- *   1. `listJournals()` read and parsed EVERY journal shard on the machine to
- *      keep the one that describes this scope, and did it again for every
- *      scope in a fanout. `readLedger` now reads one shard, and
- *      `ledger-shard-isolation.test.ts` counts the journal files opened so
- *      that cannot quietly become "all of them" again.
- *   2. `readJournal()` deep-clones every journal it returns into the writer
- *      baseline WeakMap. A read-only caller pays double for a baseline it will
- *      never diff against. The read-only path skips it.
- *   3. Reading that one shard still cost its file size TWICE — once as a UTF-8
- *      string, once as a parsed object graph — before a single row was looked
- *      at. `streamJournalLedgerRows` scans the document in 256 KB chunks and
- *      parses each row on its own instead, so the transient set is bounded by
- *      a chunk rather than by the vault.
- *   4. The derived map retained the parsed `JournalEntry` objects, which pinned
- *      the whole parse result behind the index built FROM it. The index now
- *      holds a six-field projection with the repeated strings shared, so the
- *      parse is collectable the moment the read returns.
- *
- * (1) and (2) took a 200,000-FILE measurement from 1,113 MB to 599 MB. (3) and
- * (4) took the ledger read on this fixture from 113.6 MB to 24 MB of resident
- * growth, and the same 200,000-file measurement to ~437 MB peak — under the
- * 500 MB bar this step has to clear to be worth leaving switched on.
- *
- * IN-PROCESS, NOT A CHILD WITH `--max-old-space-size`
- * --------------------------------------------------
- * A heap ceiling would fail the run with an OOM abort, which reports "the
- * child died" rather than a number, and it bounds only V8's heap — while most
- * of the regression showed up as resident growth outside it. This file already
- * runs alone, in a single fork, on its own CI runner (see
- * `vitest.bench.config.ts`), which is the isolation a memory measurement needs;
- * sampling RSS there measures the thing the budget is actually about.
- */
-const LEDGER_ENTRY_COUNT = 200_000;
-const LEDGER_COMPANY_COUNT = 4;
-const LEDGER_COMPANY_ENTRY_COUNT = 50_000;
-const LEDGER_DISK_FILE_COUNT = 2_000;
-/**
- * 30 MB of resident growth for this fixture — the measurement plus 20%.
- *
- * Measured: 24.1, 24.2 and 24.1 MB across three isolated runs, which is the
- * spread this file's single-fork, own-CI-runner isolation buys. The previous
- * budget was 260 MB against a 113.6 MB measurement, and headroom that wide
- * stops being headroom: it would have absorbed every regression this gate
- * names without anyone noticing. Re-reading every shard (`listJournals()`)
- * puts this fixture back near 356 MB, materialising the shard whole puts it
- * near 114 MB, and both are now loudly out of budget rather than comfortably
- * inside it.
- *
- * If this trips on a slower or differently-sized CI runner, the honest fix is
- * to re-measure and move the number WITH a note saying what it measured — not
- * to widen it until it stops complaining.
- *
- * This fixture understates the whole-vault picture on purpose: it pairs a
- * 200k-entry ledger with a 2,000-file tree, because the walk's own cost is
- * already gated by the stat-walk bench above and does not need paying for
- * twice. On a real 200k-FILE vault the same code measures ~437 MB peak.
- */
-const MAX_LEDGER_RSS_GROWTH_BYTES = 30 * 1024 * 1024;
-describe("buildSyncManifest ledger read cost", () => {
-    let ledgerBase;
-    let ledgerRoot;
-    let ledgerStateDir;
-    let previousStateDir;
-    function writeLegacyJournal(stateDir, slug, entryCount) {
-        const files = {};
-        for (let index = 0; index < entryCount; index += 1) {
-            files[`ledger/d${Math.floor(index / 100)}/f${index}.md`] = {
-                hash: `sha256:${index.toString(16).padStart(64, "0")}`,
-                size: 1024 + index,
-                syncedAt: "2026-01-01T00:00:00.000Z",
-                direction: "up",
-            };
-        }
-        fs.writeFileSync(path.join(stateDir, `sync-journal.${slug}.json`), JSON.stringify({ version: "2", files, pulls: [] }), "utf8");
-    }
-    beforeAll(() => {
-        ledgerBase = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-ledger-bench-"));
-        ledgerRoot = path.join(ledgerBase, "hq");
-        ledgerStateDir = path.join(ledgerBase, "state");
-        fs.mkdirSync(ledgerStateDir, { recursive: true });
-        // The journal reader resolves its own state dir from the environment, so
-        // the fixture has to own it for the duration of this suite. Without this
-        // the bench would read the DEVELOPER'S real journals — which is how the
-        // original 1.1 GB measurement was first reproduced, and is not something a
-        // CI budget can be built on.
-        previousStateDir = process.env.HQ_STATE_DIR;
-        process.env.HQ_STATE_DIR = ledgerStateDir;
-        writeLegacyJournal(ledgerStateDir, PERSONAL_VAULT_JOURNAL_SLUG, LEDGER_ENTRY_COUNT);
-        // The other shards exist only to be NOT read. Before the fix they were
-        // parsed on every build, for every scope.
-        for (let index = 0; index < LEDGER_COMPANY_COUNT; index += 1) {
-            writeLegacyJournal(ledgerStateDir, `company-${index}`, LEDGER_COMPANY_ENTRY_COUNT);
-        }
-        const perDirectory = 100;
-        for (let index = 0; index < LEDGER_DISK_FILE_COUNT; index += 1) {
-            const dir = path.join(ledgerRoot, "ledger", `d${Math.floor(index / perDirectory)}`);
-            fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(path.join(dir, `f${index}.md`), "");
-        }
-    }, 600_000);
-    afterAll(() => {
-        if (previousStateDir === undefined)
-            delete process.env.HQ_STATE_DIR;
-        else
-            process.env.HQ_STATE_DIR = previousStateDir;
-        fs.rmSync(ledgerBase, { recursive: true, force: true });
-    });
-    it(`builds a ${LEDGER_ENTRY_COUNT}-entry ledger scope within the memory budget`, async () => {
-        const forceGc = acquireGc();
-        forceGc?.();
-        const rssBefore = process.memoryUsage().rss;
-        let peakRss = rssBefore;
-        const sampler = setInterval(() => {
-            peakRss = Math.max(peakRss, process.memoryUsage().rss);
-        }, 20);
-        let result;
-        try {
-            result = await buildSyncManifest({
-                scope: { kind: "personal" },
-                hqRoot: ledgerRoot,
-                stateDir: ledgerStateDir,
-                installationId: "install-bench",
-                machineId: "machine-bench",
-                source: "cli",
-                sequence: 1,
-                hashPolicy: "never",
-                // Deliberately NOT stubbed: reading the ledger off disk is the thing
-                // being measured.
-                maxWallMs: 600_000,
-                persistSnapshot: false,
-            });
-        }
-        finally {
-            clearInterval(sampler);
-        }
-        const peakGrowth = peakRss - rssBefore;
-        process.stdout.write(`manifest ledger read: ${LEDGER_ENTRY_COUNT} ledger entries + ` +
-            `${LEDGER_COMPANY_COUNT * LEDGER_COMPANY_ENTRY_COUNT} entries in other shards, ` +
-            `${LEDGER_DISK_FILE_COUNT} files on disk: ` +
-            `${(peakGrowth / (1024 * 1024)).toFixed(1)}MB peak RSS growth\n`);
-        // The scope is fully described — the budget is never met by reporting less.
-        expect(result.walkStats.truncated).toBe(false);
-        expect(result.walkStats.filesWalked).toBe(LEDGER_DISK_FILE_COUNT);
-        const reported = result.chunks.flatMap((chunk) => chunk.entries);
-        expect(reported.length).toBe(LEDGER_ENTRY_COUNT);
-        expect(reported.filter((entry) => entry.source === "ledger").length).toBe(LEDGER_ENTRY_COUNT - LEDGER_DISK_FILE_COUNT);
-        expect(peakGrowth).toBeLessThan(MAX_LEDGER_RSS_GROWTH_BYTES);
-    }, 600_000);
-});
-/**
- * Upload-pass memory benchmark: 200,000 entries, streamed.
- *
- * WHAT THIS GATES
- * ---------------
- * The upload half of the pass must stay inside the same 500 MB bar the build
- * half does — below it the audit is worth leaving switched on beside a user's
- * editor, above it the honest answer is to switch it off. The pass now mints
- * one `SyncManifestUpload` at a time from a `ManifestChunkPlan` instead of
- * materialising the whole chunk set before the first POST, and serialises the
- * local snapshot incrementally instead of through one `JSON.stringify` of
- * every entry. `peakLiveChunks` is asserted alongside the budget because it is
- * the STRUCTURAL property the budget rests on: a future edit that collects the
- * chunks again would still fit this fixture long before it fits a real vault.
- *
- * WHAT THIS DOES NOT CLAIM
- * ------------------------
- * Measured honestly, on this fixture and on a 200,000-FILE variant of it, the
- * streaming change does not move peak RSS: ~348 MB before and after. It should
- * not be quoted as the fix for the 642 MB seen on the operator's real 199k
- * scope. A chunk's `entries` is a `slice` — 200,000 POINTERS, ~1.6 MB — not a
- * copy of the entries, so the chunk set was never the term that dominates.
- * What does dominate is inherent to a single-pass build: the walk's records,
- * the entry objects, and the snapshot map, each O(entries) and each live at
- * once because the delta decision needs the whole set before the first chunk
- * can be sized. Cutting THAT needs a two-pass build, which is a separate
- * change; this gate exists so the upload half cannot quietly re-add a copy on
- * top of it.
- *
- * WHY IT MEASURES THE UPLOAD PASS AND NOT THE BUILDER
- * --------------------------------------------------
- * The builder alone never sees the chunk set — that is the point of the plan
- * being lazy — so benchmarking `buildSyncManifest` would report a number this
- * regression cannot move.
- */
-const STREAM_ENTRY_COUNT = 200_000;
-const STREAM_DISK_FILE_COUNT = 2_000;
-/**
- * 500 MB of peak HEAP growth for a 200,000-entry upload pass.
- *
- * The product bar, not a measurement plus headroom. Measured at ~90 MB on this
- * fixture across runs, so the gate is loose today — deliberately: it is the
- * BUDGET this step has to live inside, and tightening it to the current
- * measurement would fail the next legitimate entry-shape change rather than
- * the next regression. `peakLiveChunks` is the tight assertion here.
- */
-const MAX_STREAM_HEAP_GROWTH_BYTES = 500 * 1024 * 1024;
-describe("runManifestUploadPass streaming cost", () => {
-    let streamBase;
-    let streamRoot;
-    let streamStateDir;
-    let previousStateDir;
-    beforeAll(() => {
-        streamBase = fs.mkdtempSync(path.join(os.tmpdir(), "hq-manifest-stream-bench-"));
-        streamRoot = path.join(streamBase, "hq");
-        streamStateDir = path.join(streamBase, "state");
-        fs.mkdirSync(streamStateDir, { recursive: true });
-        previousStateDir = process.env.HQ_STATE_DIR;
-        process.env.HQ_STATE_DIR = streamStateDir;
-        const files = {};
-        for (let index = 0; index < STREAM_ENTRY_COUNT; index += 1) {
-            files[`ledger/d${Math.floor(index / 100)}/f${index}.md`] = {
-                hash: `sha256:${index.toString(16).padStart(64, "0")}`,
-                size: 1024 + index,
-                mtimeMs: 1_700_000_000_000 + index,
-                syncedAt: "2026-01-01T00:00:00.000Z",
-                direction: "up",
-            };
-        }
-        fs.writeFileSync(path.join(streamStateDir, `sync-journal.${PERSONAL_VAULT_JOURNAL_SLUG}.json`), JSON.stringify({ version: "2", lastSync: "", files, pulls: [] }), "utf8");
-        for (let index = 0; index < STREAM_DISK_FILE_COUNT; index += 1) {
-            const dir = path.join(streamRoot, "ledger", `d${Math.floor(index / 100)}`);
-            fs.mkdirSync(dir, { recursive: true });
-            fs.writeFileSync(path.join(dir, `f${index}.md`), "");
-        }
-    }, 600_000);
-    afterAll(() => {
-        if (previousStateDir === undefined)
-            delete process.env.HQ_STATE_DIR;
-        else
-            process.env.HQ_STATE_DIR = previousStateDir;
-        fs.rmSync(streamBase, { recursive: true, force: true });
-    });
-    it(`streams a ${STREAM_ENTRY_COUNT}-entry pass within the memory budget`, async () => {
-        const forceGc = acquireGc();
-        forceGc?.();
-        // HEAP, not RSS, for this one. The other benches in this file run first
-        // and leave the process holding hundreds of megabytes of resident pages
-        // that the allocator happily REUSES, so resident *growth* reads near zero
-        // whether the chunk set is streamed or materialised — it measures the page
-        // cache, not the code. `heapUsed` is what the duplicate chunk set actually
-        // consumed, and it is what a forced GC can honestly re-baseline.
-        const heapBefore = process.memoryUsage().heapUsed;
-        const rssBefore = process.memoryUsage().rss;
-        let peakHeap = heapBefore;
-        let peakRss = rssBefore;
-        const sampler = setInterval(() => {
-            const usage = process.memoryUsage();
-            peakHeap = Math.max(peakHeap, usage.heapUsed);
-            peakRss = Math.max(peakRss, usage.rss);
-        }, 20);
-        let liveChunks = 0;
-        let peakLiveChunks = 0;
-        let sentChunks = 0;
-        let sentEntries = 0;
-        // The canary metric. 6.16.21 put 15.9-17.9 MiB bodies on the wire here and
-        // nothing in this bench noticed, because the bench only ever asserted
-        // memory. Peak body size is now measured on the same run.
-        let maxBodyBytes = 0;
-        let result;
-        try {
-            result = await runManifestUploadPass({
-                scope: { kind: "personal" },
-                hqRoot: streamRoot,
-                stateDir: streamStateDir,
-                installationId: "install-bench",
-                machineId: "machine-bench",
-                source: "cli",
-                hashPolicy: "never",
-                maxWallMs: 600_000,
-                uploadWallMs: 600_000,
-                env: {},
-                transport: async (chunk) => {
-                    // Serialise exactly as a real transport would: the JSON of the chunk
-                    // in flight is part of the peak this budget covers.
-                    liveChunks += 1;
-                    peakLiveChunks = Math.max(peakLiveChunks, liveChunks);
-                    sentEntries += chunk.entries.length;
-                    sentChunks += 1;
-                    const body = JSON.stringify(chunk);
-                    if (body.length === 0)
-                        throw new Error("empty chunk body");
-                    maxBodyBytes = Math.max(maxBodyBytes, Buffer.byteLength(body, "utf8"));
-                    liveChunks -= 1;
-                    return {
-                        status: 200,
-                        body: {
-                            status: "accepted",
-                            snapshotId: "0123456789abcdef0123456789abcdef",
-                            completed: sentChunks === chunk.chunkCount,
-                            materialised: sentChunks === chunk.chunkCount,
-                        },
-                    };
-                },
-            });
-        }
-        finally {
-            clearInterval(sampler);
-        }
-        const peakHeapGrowth = peakHeap - heapBefore;
-        process.stdout.write(`manifest upload stream: ${STREAM_ENTRY_COUNT} entries in ${sentChunks} chunk(s): ` +
-            `${(peakHeapGrowth / (1024 * 1024)).toFixed(1)}MB peak heap growth, ` +
-            `${((peakRss - rssBefore) / (1024 * 1024)).toFixed(1)}MB peak RSS growth, ` +
-            `${(peakRss / (1024 * 1024)).toFixed(1)}MB absolute peak RSS, ` +
-            `${(maxBodyBytes / (1024 * 1024)).toFixed(2)}MiB largest chunk body\n`);
-        // The budget is never met by reporting less: the whole scope went out.
-        expect(result.status).toBe("uploaded");
-        expect(sentEntries).toBe(STREAM_ENTRY_COUNT);
-        expect(sentChunks).toBeGreaterThan(1);
-        // One chunk alive at a time — the property the budget actually rests on.
-        expect(peakLiveChunks).toBe(1);
-        expect(peakHeapGrowth).toBeLessThan(MAX_STREAM_HEAP_GROWTH_BYTES);
-        // THE 6.16.21 GATE. Every body the transport saw fits the client budget,
-        // which sits a full MiB under the server's `SYNC_MANIFEST_MAX_CHUNK_BYTES`
-        // and 6 MiB under API Gateway's own ceiling. Asserted on bodies rather
-        // than on the plan's self-report, because the plan's arithmetic is exactly
-        // what was wrong before.
-        expect(maxBodyBytes).toBeLessThanOrEqual(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET);
-        expect(SYNC_MANIFEST_DEFAULT_CHUNK_BYTE_BUDGET).toBeLessThan(SYNC_MANIFEST_MAX_CHUNK_BYTES);
-        // A byte budget necessarily means MORE, smaller chunks than the count
-        // bound alone would have planned. Pinned so a regression that silently
-        // stops splitting on bytes fails here too.
-        expect(sentChunks).toBeGreaterThan(Math.ceil(STREAM_ENTRY_COUNT / 50_000));
-    }, 600_000);
-});
-//# sourceMappingURL=build-manifest.bench.test.js.map