@indigoai-us/hq-cloud 6.15.75 → 6.15.76

package/dist/watcher.test.js

@@ -4,7 +4,7 @@ import * as os from "os";
 import * as path from "path";
 import { createHash } from "node:crypto";
 import { watch } from "chokidar";
-import { FakeClock, WatchPushDriver, TreeWatcher, ChokidarWatchBudget, createWatchPathFilter, toChokidarIgnored, PushEventEmitter, PUBLISH_OUTCOME_JOURNALD_CEILING_BYTES, PUBLISH_OUTCOME_SUCCESS_SAMPLE_CAP, resolveEventDebounceConfig, summarizePublishBatchOutcome, DEFAULT_EVENT_DEBOUNCE_MS, DEFAULT_EVENT_MAX_WAIT_MS, EVENT_DEBOUNCE_MS_ENV, EVENT_MAX_WAIT_MS_ENV, DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS, MAX_TREE_WATCHER_MAX_WATCHED_PATHS, TREE_WATCHER_MAX_WATCHED_PATHS_ENV, resolveMaxWatchedPaths, } from "./watcher.js";
+import { FakeClock, WatchPushDriver, TreeWatcher, ChokidarWatchBudget, createWatchPathFilter, toChokidarIgnored, PushEventEmitter, PUBLISH_OUTCOME_JOURNALD_CEILING_BYTES, PUBLISH_OUTCOME_SUCCESS_SAMPLE_CAP, resolveEventDebounceConfig, summarizePublishBatchOutcome, DEFAULT_EVENT_DEBOUNCE_MS, DEFAULT_EVENT_MAX_WAIT_MS, DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS, DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS, DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES, DEFAULT_PUBLISH_MIN_INTERVAL_MS, EVENT_DEBOUNCE_MS_ENV, EVENT_MAX_WAIT_MS_ENV, EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV, EVENT_SMALL_BATCH_MAX_PATHS_ENV, EVENT_SMALL_BATCH_MAX_BYTES_ENV, DEFAULT_TREE_WATCHER_MAX_WATCHED_PATHS, MAX_TREE_WATCHER_MAX_WATCHED_PATHS, TREE_WATCHER_MAX_WATCHED_PATHS_ENV, resolveMaxWatchedPaths, PUBLISH_MIN_INTERVAL_MS_ENV, resolvePublishMinIntervalMs, } from "./watcher.js";
 import { StaticFlagProvider } from "./sync/feature-flags.js";
 import { computePersonalVaultPaths } from "./personal-vault.js";
 /**
@@ -790,6 +790,167 @@ describe("US-002: TreeWatcher — debounce coalesce (FakeClock seam)", () => {
         clock.advance(1);
         expect(changed).toHaveBeenCalledTimes(1);
     });
+    it("flushes a quiet, known-small batch through the short debounce window", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-small-debounce-"));
+        try {
+            const small = path.join(dir, "small.md");
+            fs.writeFileSync(small, "sixteen-byte-doc");
+            const clock = new FakeClock();
+            const changed = vi.fn();
+            const watcher = new TreeWatcher({
+                hqRoot: dir,
+                debounceMs: 15_000,
+                smallBatchDebounceMs: 2_500,
+                smallBatchMaxPaths: 8,
+                smallBatchMaxBytes: 1024 * 1024,
+                clock,
+                pathFilter: () => true,
+            });
+            watcher.onChange(changed);
+            watcher.handleEvent(small);
+            clock.advance(2_499);
+            expect(changed).not.toHaveBeenCalled();
+            clock.advance(1);
+            expect(changed).toHaveBeenCalledTimes(1);
+            expect(changed.mock.calls[0][1].paths.get(small)).toBe("small.md");
+            watcher.dispose();
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("keeps a burst above the small-path cap on the 15s debounce", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-burst-debounce-"));
+        try {
+            const clock = new FakeClock();
+            const changed = vi.fn();
+            const watcher = new TreeWatcher({
+                hqRoot: dir,
+                debounceMs: 15_000,
+                smallBatchDebounceMs: 2_500,
+                smallBatchMaxPaths: 8,
+                smallBatchMaxBytes: 1024 * 1024,
+                clock,
+                pathFilter: () => true,
+            });
+            watcher.onChange(changed);
+            for (let index = 0; index < 9; index += 1) {
+                const file = path.join(dir, `burst-${index}.md`);
+                fs.writeFileSync(file, "small");
+                watcher.handleEvent(file);
+                clock.advance(100);
+            }
+            // The final event landed at t=800ms; the loop's final 100ms advance is
+            // outside the quiet window, so stop one millisecond before t=15_800ms.
+            clock.advance(14_899);
+            expect(changed).not.toHaveBeenCalled();
+            clock.advance(1);
+            expect(changed).toHaveBeenCalledTimes(1);
+            expect(changed.mock.calls[0][1].paths.size).toBe(9);
+            watcher.dispose();
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("preserves max-wait for a continuous small batch that never becomes quiet", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-small-max-wait-"));
+        try {
+            const file = path.join(dir, "continuous.md");
+            fs.writeFileSync(file, "small");
+            const clock = new FakeClock();
+            const changed = vi.fn();
+            const watcher = new TreeWatcher({
+                hqRoot: dir,
+                debounceMs: 15_000,
+                maxWaitMs: 120_000,
+                smallBatchDebounceMs: 2_500,
+                smallBatchMaxPaths: 8,
+                smallBatchMaxBytes: 1024 * 1024,
+                clock,
+                pathFilter: () => true,
+            });
+            watcher.onChange(changed);
+            for (let elapsed = 0; elapsed < 120_000; elapsed += 2_000) {
+                watcher.handleEvent(file);
+                if (elapsed < 118_000)
+                    clock.advance(2_000);
+            }
+            expect(changed).not.toHaveBeenCalled();
+            clock.advance(2_000);
+            expect(changed).toHaveBeenCalledTimes(1);
+            watcher.dispose();
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("keeps a duplicate directory delete out of the short debounce lane", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-delete-debounce-"));
+        try {
+            const deleted = path.join(dir, "deleted-directory");
+            const clock = new FakeClock();
+            const changed = vi.fn();
+            const watcher = new TreeWatcher({
+                hqRoot: dir,
+                debounceMs: 15_000,
+                smallBatchDebounceMs: 2_500,
+                smallBatchMaxPaths: 8,
+                smallBatchMaxBytes: 1024 * 1024,
+                clock,
+                pathFilter: () => true,
+            });
+            watcher.onChange(changed);
+            watcher.handleEvent(deleted, "unlinkDir");
+            watcher.handleEvent(deleted, "unlink");
+            clock.advance(2_500);
+            expect(changed).not.toHaveBeenCalled();
+            clock.advance(12_500);
+            expect(changed).toHaveBeenCalledTimes(1);
+            expect(changed.mock.calls[0][1].changes.get(deleted)).toMatchObject({
+                kind: "unlinkDir",
+            });
+            watcher.dispose();
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it("keeps an overflowed batch out of the short debounce lane", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watcher-overflow-debounce-"));
+        try {
+            const first = path.join(dir, "first.md");
+            const dropped = path.join(dir, "dropped.md");
+            fs.writeFileSync(first, "small");
+            fs.writeFileSync(dropped, "small");
+            const clock = new FakeClock();
+            const changed = vi.fn();
+            const watcher = new TreeWatcher({
+                hqRoot: dir,
+                debounceMs: 15_000,
+                smallBatchDebounceMs: 2_500,
+                smallBatchMaxPaths: 8,
+                smallBatchMaxBytes: 1024 * 1024,
+                maxPendingPaths: 1,
+                maxPendingBytes: 1024 * 1024,
+                clock,
+                pathFilter: () => true,
+                onBacklogOverflow: () => undefined,
+            });
+            watcher.onChange(changed);
+            watcher.handleEvent(first);
+            watcher.handleEvent(dropped);
+            clock.advance(2_500);
+            expect(changed).not.toHaveBeenCalled();
+            clock.advance(12_500);
+            expect(changed).toHaveBeenCalledTimes(1);
+            expect(changed.mock.calls[0][1]).toMatchObject({ overflowed: true });
+            watcher.dispose();
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
     it("does NOT emit for an ignored / excluded path", () => {
         const { clock, changed, watcher } = makeWatcher({ personalMode: true });
         watcher.handleEvent(path.join(ROOT, ".env"));
@@ -1249,9 +1410,11 @@ describe("PushEventEmitter — directory and delete tombstone handling", () => {
             transport,
             flagProvider: new StaticFlagProvider(["tenant-indigo"]),
             now: () => new Date("2026-06-18T12:00:00.000Z"),
+            clock: opts?.clock,
             getSequenceNumber: opts?.getSequenceNumber,
             onError: opts?.onError,
             lastPublishedContentHashMaxPaths: opts?.lastPublishedContentHashMaxPaths,
+            publishMinIntervalMs: opts?.publishMinIntervalMs ?? 0,
             ...(opts?.lastPublishedContentHashStateDir
                 ? { lastPublishedContentHashStateDir: opts.lastPublishedContentHashStateDir }
                 : {}),
@@ -1371,6 +1534,109 @@ describe("PushEventEmitter — directory and delete tombstone handling", () => {
         ]);
         expect(published[0].contentHash).not.toBe(published[1].contentHash);
     });
+    it("coalesces ten rewrites of one path into an immediate and trailing latest publish", async () => {
+        const clock = new FakeClock();
+        const published = [];
+        const rewritten = path.join(dir, "high-churn-prd.json");
+        const relativePath = "personal/projects/churn/prd.json";
+        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
+        const batch = { paths: new Map([[rewritten, relativePath]]) };
+        for (let version = 0; version < 10; version += 1) {
+            fs.writeFileSync(rewritten, `{"version":${version}}\n`);
+            await emitter.emitForBatch(batch);
+            if (version < 9)
+                clock.advance(5_000);
+        }
+        expect(published).toHaveLength(1);
+        clock.advance(15_000);
+        await emitter.emitForBatch({ paths: new Map() });
+        expect(published).toHaveLength(2);
+        expect(clock.pendingTimerCount()).toBe(0);
+        expect(published[1]).toMatchObject({ kind: "upsert", relativePath });
+        expect(published[1].contentHash).toBe(`sha256:${createHash("sha256").update('{"version":9}\n').digest("hex")}`);
+    });
+    it("publishes the uploaded deferred revision when the local file changes before flush", async () => {
+        const clock = new FakeClock();
+        const published = [];
+        const rewritten = path.join(dir, "captured-deferred-revision.json");
+        const relativePath = "personal/projects/captured/prd.json";
+        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
+        const batch = { paths: new Map([[rewritten, relativePath]]) };
+        fs.writeFileSync(rewritten, '{"revision":"uploaded"}\n');
+        await emitter.emitForBatch(batch);
+        fs.writeFileSync(rewritten, '{"revision":"deferred-uploaded"}\n');
+        await emitter.emitForBatch(batch);
+        const expectedHash = `sha256:${createHash("sha256")
+            .update('{"revision":"deferred-uploaded"}\n')
+            .digest("hex")}`;
+        // This local revision has not completed its scoped push yet. The trailing
+        // announcement must remain bound to the previously uploaded bytes.
+        fs.writeFileSync(rewritten, '{"revision":"newer-local"}\n');
+        clock.advance(60_000);
+        await emitter.emitForBatch({ paths: new Map() });
+        expect(published).toHaveLength(2);
+        expect(published[1]).toMatchObject({
+            kind: "upsert",
+            relativePath,
+            contentHash: expectedHash,
+        });
+        expect(published[1].contentHash).not.toBe(`sha256:${createHash("sha256")
+            .update('{"revision":"newer-local"}\n')
+            .digest("hex")}`);
+    });
+    it("skips the trailing publish when the final rewrite restores the last published hash", async () => {
+        const clock = new FakeClock();
+        const published = [];
+        const rewritten = path.join(dir, "reverted-prd.json");
+        const relativePath = "personal/projects/reverted/prd.json";
+        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
+        const batch = { paths: new Map([[rewritten, relativePath]]) };
+        fs.writeFileSync(rewritten, "A\n");
+        await emitter.emitForBatch(batch);
+        fs.writeFileSync(rewritten, "B\n");
+        await emitter.emitForBatch(batch);
+        fs.writeFileSync(rewritten, "A\n");
+        await emitter.emitForBatch(batch);
+        clock.advance(60_000);
+        await emitter.emitForBatch({ paths: new Map() });
+        expect(published).toHaveLength(1);
+        expect(clock.pendingTimerCount()).toBe(0);
+        expect(published[0]).toMatchObject({ kind: "upsert", relativePath });
+    });
+    it("publishes a delete immediately while an upsert is deferred", async () => {
+        const clock = new FakeClock();
+        const published = [];
+        const deleted = path.join(dir, "delete-during-quiet.jsonl");
+        const relativePath = "workspace/.session-logs/delete-during-quiet.jsonl";
+        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000, clock });
+        const batch = { paths: new Map([[deleted, relativePath]]) };
+        fs.writeFileSync(deleted, "A\n");
+        await emitter.emitForBatch(batch);
+        fs.writeFileSync(deleted, "B\n");
+        await emitter.emitForBatch(batch);
+        fs.rmSync(deleted);
+        await emitter.emitForBatch(batch);
+        expect(published.map((event) => event.kind)).toEqual(["upsert", "delete"]);
+        clock.advance(60_000);
+        await emitter.emitForBatch({ paths: new Map() });
+        expect(published).toHaveLength(2);
+    });
+    it("does not make a second path wait behind another path's quiet interval", async () => {
+        const published = [];
+        const first = path.join(dir, "first-high-churn.jsonl");
+        const second = path.join(dir, "independent.jsonl");
+        const emitter = makeEmitter({ published, publishMinIntervalMs: 60_000 });
+        fs.writeFileSync(first, "A\n");
+        fs.writeFileSync(second, "B\n");
+        await emitter.emitForBatch({ paths: new Map([[first, "workspace/.session-logs/first.jsonl"]]) });
+        fs.writeFileSync(first, "A2\n");
+        await emitter.emitForBatch({ paths: new Map([[first, "workspace/.session-logs/first.jsonl"]]) });
+        await emitter.emitForBatch({ paths: new Map([[second, "workspace/.session-logs/second.jsonl"]]) });
+        expect(published.map((event) => event.relativePath)).toEqual([
+            "workspace/.session-logs/first.jsonl",
+            "workspace/.session-logs/second.jsonl",
+        ]);
+    });
     it("publishes a content revert because it compares only with the last publication", async () => {
         const published = [];
         const reverted = path.join(dir, "reverted-session-log.jsonl");
@@ -1395,6 +1661,7 @@ describe("PushEventEmitter — directory and delete tombstone handling", () => {
             originTenantId: "tenant-indigo",
             originDeviceId: "device-a",
             flagProvider: new StaticFlagProvider(["tenant-indigo"]),
+            publishMinIntervalMs: 0,
             transport: {
                 start: async () => { },
                 dispose: async () => { },
@@ -1758,7 +2025,13 @@ describe("TreeWatcher deferred delete snapshots", () => {
 // Event-pass debounce configuration (HQ_SYNC_EVENT_DEBOUNCE_MS / _MAX_WAIT_MS)
 // ---------------------------------------------------------------------------
 describe("resolveEventDebounceConfig", () => {
-    const ENV_KEYS = [EVENT_DEBOUNCE_MS_ENV, EVENT_MAX_WAIT_MS_ENV];
+    const ENV_KEYS = [
+        EVENT_DEBOUNCE_MS_ENV,
+        EVENT_MAX_WAIT_MS_ENV,
+        EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV,
+        EVENT_SMALL_BATCH_MAX_PATHS_ENV,
+        EVENT_SMALL_BATCH_MAX_BYTES_ENV,
+    ];
     let saved;
     beforeEach(() => {
         saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
@@ -1777,6 +2050,9 @@ describe("resolveEventDebounceConfig", () => {
         expect(resolveEventDebounceConfig()).toEqual({
             debounceMs: DEFAULT_EVENT_DEBOUNCE_MS,
             maxWaitMs: DEFAULT_EVENT_MAX_WAIT_MS,
+            smallBatchDebounceMs: DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS,
+            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
+            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
         });
         expect(DEFAULT_EVENT_DEBOUNCE_MS).toBe(15_000);
         expect(DEFAULT_EVENT_MAX_WAIT_MS).toBe(120_000);
@@ -1784,9 +2060,15 @@ describe("resolveEventDebounceConfig", () => {
     it("honors env overrides", () => {
         process.env[EVENT_DEBOUNCE_MS_ENV] = "5000";
         process.env[EVENT_MAX_WAIT_MS_ENV] = "30000";
+        process.env[EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV] = "2000";
+        process.env[EVENT_SMALL_BATCH_MAX_PATHS_ENV] = "6";
+        process.env[EVENT_SMALL_BATCH_MAX_BYTES_ENV] = "4096";
         expect(resolveEventDebounceConfig()).toEqual({
             debounceMs: 5000,
             maxWaitMs: 30_000,
+            smallBatchDebounceMs: 2000,
+            smallBatchMaxPaths: 6,
+            smallBatchMaxBytes: 4096,
         });
     });
     it("treats 0, negative, and non-numeric values as unset (defaults)", () => {
@@ -1796,6 +2078,9 @@ describe("resolveEventDebounceConfig", () => {
             expect(resolveEventDebounceConfig()).toEqual({
                 debounceMs: DEFAULT_EVENT_DEBOUNCE_MS,
                 maxWaitMs: DEFAULT_EVENT_MAX_WAIT_MS,
+                smallBatchDebounceMs: DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS,
+                smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
+                smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
             });
         }
     });
@@ -1805,13 +2090,36 @@ describe("resolveEventDebounceConfig", () => {
         expect(resolveEventDebounceConfig()).toEqual({
             debounceMs: 60_000,
             maxWaitMs: 60_000,
+            smallBatchDebounceMs: DEFAULT_EVENT_SMALL_BATCH_DEBOUNCE_MS,
+            smallBatchMaxPaths: DEFAULT_EVENT_SMALL_BATCH_MAX_PATHS,
+            smallBatchMaxBytes: DEFAULT_EVENT_SMALL_BATCH_MAX_BYTES,
         });
     });
     it("accepts an injected env record without touching process.env", () => {
         expect(resolveEventDebounceConfig({
             [EVENT_DEBOUNCE_MS_ENV]: "1000",
             [EVENT_MAX_WAIT_MS_ENV]: "2000",
-        })).toEqual({ debounceMs: 1000, maxWaitMs: 2000 });
+            [EVENT_SMALL_BATCH_DEBOUNCE_MS_ENV]: "750",
+            [EVENT_SMALL_BATCH_MAX_PATHS_ENV]: "4",
+            [EVENT_SMALL_BATCH_MAX_BYTES_ENV]: "1024",
+        })).toEqual({
+            debounceMs: 1000,
+            maxWaitMs: 2000,
+            smallBatchDebounceMs: 750,
+            smallBatchMaxPaths: 4,
+            smallBatchMaxBytes: 1024,
+        });
+    });
+});
+describe("resolvePublishMinIntervalMs", () => {
+    it("defaults to 60 seconds, accepts zero to disable coalescing, and rejects invalid values", () => {
+        expect(resolvePublishMinIntervalMs({})).toBe(DEFAULT_PUBLISH_MIN_INTERVAL_MS);
+        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "0" })).toBe(0);
+        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "invalid" })).toBe(DEFAULT_PUBLISH_MIN_INTERVAL_MS);
+        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "-1" })).toBe(DEFAULT_PUBLISH_MIN_INTERVAL_MS);
+    });
+    it("uses the environment override in milliseconds", () => {
+        expect(resolvePublishMinIntervalMs({ [PUBLISH_MIN_INTERVAL_MS_ENV]: "1234.9" })).toBe(1234);
     });
 });
 //# sourceMappingURL=watcher.test.js.map