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

package/dist/sync/event-sync.test.js

@@ -1,1714 +0,0 @@
-/**
- * Phase 3 event-sync tests (US-017/US-018/US-019).
- *
- * - resolveEventSync: exact-email gate semantics + env-override precedence.
- * - subscribeSyncReceive: request shape, response validation, failure surface.
- * - sqsClientFromAwsSdk: command mapping + abort-signal forwarding.
- * - createRefreshingSqsClient: proactive skew refresh, reactive retry-once on
- *   expiry-class errors, non-expiry errors propagate, concurrent refresh
- *   collapse.
- * - startEventSync: happy-path handle wiring (self-echo filter, publish leg),
- *   poll-only degradation on subscribe/tenant failure.
- */
-import { describe, expect, it, vi } from "vitest";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { resolveEventSync, subscribeSyncReceive, sqsClientFromAwsSdk, createRefreshingSqsClient, createUnifiedRealtimeScheduler, startEventSync, } from "./event-sync.js";
-import { RealtimeUnavailableError, SyncDeviceLimitError, } from "./push-transport.js";
-import { hashFile } from "../journal.js";
-import { FakeClock } from "../watcher.js";
-function subscribeResponse(overrides = {}, queueUrl = "https://sqs.us-east-1.amazonaws.com/000000000000/sync-push-prs_t-dev1") {
-    return {
-        queueUrl,
-        region: "us-east-1",
-        credentials: {
-            accessKeyId: "AKIA-1",
-            secretAccessKey: "sec-1",
-            sessionToken: "tok-1",
-            expiration: "2026-06-10T13:00:00.000Z",
-            ...overrides,
-        },
-    };
-}
-// ─── resolveEventSync (US-019) ──────────────────────────────────────────────
-describe("resolveEventSync — local disable only", () => {
-    it.each(["0", "false", "no", "off"])("override %j keeps the event path dormant", (override) => expect(resolveEventSync(override)).toBe(false));
-    it.each([undefined, "", "1", "true", "yes", "on", "indigo"])("override %j cannot grant authority", (override) => expect(resolveEventSync(override)).toBe(true));
-});
-describe("createUnifiedRealtimeScheduler", () => {
-    it("coalesces watcher, wake, reconnect, retry, and high-water through one guard", async () => {
-        let active = 0;
-        let maximumActive = 0;
-        let drains = 0;
-        const firstState = { release: null };
-        const first = new Promise((resolve) => { firstState.release = resolve; });
-        const scheduler = createUnifiedRealtimeScheduler({
-            runGuarded: async (drain) => {
-                active += 1;
-                maximumActive = Math.max(maximumActive, active);
-                try {
-                    await drain();
-                }
-                finally {
-                    active -= 1;
-                }
-            },
-            drain: async () => {
-                drains += 1;
-                if (drains === 1)
-                    await first;
-            },
-            checkHighWater: async () => true,
-        });
-        scheduler.signal("watcher");
-        scheduler.signal("wake");
-        scheduler.signal("reconnect");
-        scheduler.signal("retry");
-        await Promise.resolve();
-        expect(drains).toBe(1);
-        await scheduler.checkHighWater();
-        firstState.release?.();
-        for (let i = 0; i < 8; i++)
-            await Promise.resolve();
-        expect(maximumActive).toBe(1);
-        // The four signals and high-water collapse into one post-drain pass.
-        expect(drains).toBe(2);
-        await scheduler.dispose();
-    });
-    it("recovers all-lost wakes through high-water without a V1 callback", async () => {
-        const drain = vi.fn().mockResolvedValue(undefined);
-        const scheduler = createUnifiedRealtimeScheduler({
-            runGuarded: async (work) => work(),
-            drain,
-            checkHighWater: async () => true,
-        });
-        await scheduler.checkHighWater();
-        for (let i = 0; i < 4; i++)
-            await Promise.resolve();
-        expect(drain).toHaveBeenCalledOnce();
-        await scheduler.dispose();
-    });
-    it("disposes the old receiver and drops its pending wakes when identity changes", async () => {
-        const firstState = { listener: null };
-        const secondState = { listener: null };
-        const first = { start: (listener) => { firstState.listener = listener; }, dispose: vi.fn() };
-        const second = { start: (listener) => { secondState.listener = listener; }, dispose: vi.fn() };
-        const drain = vi.fn().mockResolvedValue(undefined);
-        const scheduler = createUnifiedRealtimeScheduler({ runGuarded: async (work) => work(), drain });
-        await scheduler.replaceIdentity("identity-a", first);
-        // The reconnect signal may drain, isolate the old-wake assertion below.
-        await Promise.resolve();
-        drain.mockClear();
-        await scheduler.replaceIdentity("identity-b", second);
-        expect(first.dispose).toHaveBeenCalledOnce();
-        // The new receiver's reconnect check is its own bounded drain. Isolate
-        // delivery below so this assertion specifically proves the old listener
-        // could not enqueue work after identity disposal.
-        for (let i = 0; i < 4; i++)
-            await Promise.resolve();
-        drain.mockClear();
-        firstState.listener?.(JSON.stringify({ contractVersion: 2, eventType: "vault.changed", scopeHandle: "scope_a", cursor: "old_cursor" }));
-        secondState.listener?.(JSON.stringify({ contractVersion: 2, eventType: "vault.changed", scopeHandle: "scope_b", cursor: "new_cursor" }));
-        for (let i = 0; i < 4; i++)
-            await Promise.resolve();
-        expect(drain).toHaveBeenCalledOnce();
-        await scheduler.dispose();
-        expect(second.dispose).toHaveBeenCalledOnce();
-    });
-    it("quiesces an in-flight old-identity drain before starting its replacement", async () => {
-        const drainState = { release: null };
-        const drainGate = new Promise((resolve) => { drainState.release = resolve; });
-        const first = { start: () => undefined, dispose: vi.fn() };
-        const second = { start: vi.fn(), dispose: vi.fn() };
-        const scheduler = createUnifiedRealtimeScheduler({
-            runGuarded: async (work) => work(),
-            drain: async () => drainGate,
-        });
-        await scheduler.replaceIdentity("identity-a", first);
-        const replacement = scheduler.replaceIdentity("identity-b", second);
-        await Promise.resolve();
-        expect(first.dispose).toHaveBeenCalledOnce();
-        expect(second.start).not.toHaveBeenCalled();
-        drainState.release?.();
-        await replacement;
-        expect(second.start).toHaveBeenCalledOnce();
-        await scheduler.dispose();
-    });
-    it("retains a failed drain bit for its bounded retry", async () => {
-        vi.useFakeTimers();
-        try {
-            const drain = vi
-                .fn()
-                .mockRejectedValueOnce(new Error("temporary"))
-                .mockResolvedValueOnce(undefined);
-            const scheduler = createUnifiedRealtimeScheduler({
-                runGuarded: async (work) => work(),
-                drain,
-                retryDelayMs: 0,
-                onError: () => undefined,
-            });
-            scheduler.signal("wake");
-            await Promise.resolve();
-            await vi.advanceTimersByTimeAsync(0);
-            expect(drain).toHaveBeenCalledTimes(2);
-            await scheduler.dispose();
-        }
-        finally {
-            vi.useRealTimers();
-        }
-    });
-    it("cleans up a partially started replacement receiver", async () => {
-        const sourceState = { callback: null };
-        const source = {
-            start: (listener) => {
-                sourceState.callback = listener;
-                throw new Error("startup failed");
-            },
-            dispose: vi.fn(),
-        };
-        const drain = vi.fn().mockResolvedValue(undefined);
-        const scheduler = createUnifiedRealtimeScheduler({ runGuarded: async (work) => work(), drain });
-        await expect(scheduler.replaceIdentity("identity-a", source)).rejects.toThrow(/startup failed/);
-        expect(source.dispose).toHaveBeenCalledOnce();
-        sourceState.callback?.(JSON.stringify({ contractVersion: 2, eventType: "vault.changed", scopeHandle: "scope_a", cursor: "cursor_a" }));
-        await Promise.resolve();
-        expect(drain).not.toHaveBeenCalled();
-        await scheduler.dispose();
-    });
-});
-// ─── subscribeSyncReceive ───────────────────────────────────────────────────
-describe("subscribeSyncReceive", () => {
-    it("POSTs deviceId with a Bearer token and parses the response", async () => {
-        const calls = [];
-        const resp = subscribeResponse();
-        const result = await subscribeSyncReceive({
-            apiUrl: "https://api.example.com/",
-            authToken: async () => "jwt-123",
-            deviceId: "dev1",
-            fetchImpl: async (url, init) => {
-                calls.push({ url, init: init });
-                return { ok: true, status: 200, text: async () => JSON.stringify(resp) };
-            },
-        });
-        expect(result).toEqual(resp);
-        expect(calls).toHaveLength(1);
-        expect(calls[0].url).toBe("https://api.example.com/v1/sync/subscribe");
-        const init = calls[0].init;
-        expect(init.headers.Authorization).toBe("Bearer jwt-123");
-        expect(JSON.parse(init.body)).toEqual({ deviceId: "dev1" });
-    });
-    it("throws with status + body excerpt on non-2xx", async () => {
-        await expect(subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "dev1",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 503,
-                text: async () => "subscribe exploded",
-            }),
-        })).rejects.toThrow(/503.*subscribe exploded/s);
-    });
-    it("throws a non-retryable typed error for the coded realtime denial", async () => {
-        const error = await subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "dev1",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 403,
-                text: async () => JSON.stringify({
-                    error: "realtime-unavailable",
-                    code: "REALTIME_UNAVAILABLE",
-                    retryable: false,
-                }),
-            }),
-        }).then(() => undefined, (reason) => reason);
-        expect(error).toBeInstanceOf(RealtimeUnavailableError);
-        expect(error).toMatchObject({ retryable: false, status: 403 });
-    });
-    it("throws a typed error for the coded sync device limit denial", async () => {
-        const error = await subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "dev1",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 429,
-                text: async () => JSON.stringify({
-                    error: "sync-device-limit-exceeded",
-                    code: "SYNC_DEVICE_LIMIT_EXCEEDED",
-                }),
-            }),
-        }).then(() => undefined, (reason) => reason);
-        expect(error).toBeInstanceOf(Error);
-        expect(error).toMatchObject({
-            code: "SYNC_DEVICE_LIMIT_EXCEEDED",
-            retryable: false,
-            status: 429,
-        });
-        expect(error.name).toBe("SyncDeviceLimitError");
-    });
-    it("rejects a response missing credentials (old server) loudly", async () => {
-        await expect(subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "dev1",
-            fetchImpl: async () => ({
-                ok: true,
-                status: 200,
-                text: async () => JSON.stringify({ queueUrl: "https://q", region: "us-east-1" }),
-            }),
-        })).rejects.toThrow(/credentials\.accessKeyId/);
-    });
-});
-// ─── sqsClientFromAwsSdk ────────────────────────────────────────────────────
-describe("sqsClientFromAwsSdk", () => {
-    it("requests and parses SQS system attributes while mapping commands and forwarding abort", async () => {
-        const sent = [];
-        const fakeSdk = {
-            send: async (cmd, opts) => {
-                sent.push({ input: cmd.input, opts });
-                if (sent.length === 4) {
-                    return {
-                        Failed: [{
-                                Id: "entry-two",
-                                Code: "ReceiptHandleIsInvalid",
-                                Message: "one receipt was rejected",
-                                SenderFault: true,
-                            }],
-                    };
-                }
-                return {
-                    Messages: [{
-                            Body: "b",
-                            ReceiptHandle: "rh",
-                            MessageId: "m1",
-                            Attributes: {
-                                ApproximateReceiveCount: "3",
-                                SentTimestamp: "1712345",
-                            },
-                        }],
-                };
-            },
-        };
-        const adapted = sqsClientFromAwsSdk(fakeSdk);
-        const ac = new AbortController();
-        const out = await adapted.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 5,
-            waitTimeSeconds: 20,
-            visibilityTimeoutSeconds: 600,
-            signal: ac.signal,
-        });
-        expect(out.messages).toEqual([
-            {
-                Body: "b",
-                ReceiptHandle: "rh",
-                MessageId: "m1",
-                approximateReceiveCount: 3,
-                sentTimestampMs: 1712345,
-            },
-        ]);
-        expect(sent[0].input).toMatchObject({
-            QueueUrl: "https://q",
-            MaxNumberOfMessages: 5,
-            WaitTimeSeconds: 20,
-            VisibilityTimeout: 600,
-            MessageSystemAttributeNames: ["ApproximateReceiveCount", "SentTimestamp"],
-        });
-        expect(sent[0].opts).toEqual({ abortSignal: ac.signal });
-        await adapted.deleteMessage({ queueUrl: "https://q", receiptHandle: "rh" });
-        expect(sent[1].input).toMatchObject({
-            QueueUrl: "https://q",
-            ReceiptHandle: "rh",
-        });
-        await adapted.changeMessageVisibility({
-            queueUrl: "https://q",
-            receiptHandle: "rh",
-            visibilityTimeoutSeconds: 0,
-        });
-        expect(sent[2].input).toMatchObject({
-            QueueUrl: "https://q",
-            ReceiptHandle: "rh",
-            VisibilityTimeout: 0,
-        });
-        const batchResult = await adapted.changeMessageVisibilityBatch({
-            queueUrl: "https://q",
-            entries: [
-                { id: "entry-one", receiptHandle: "rh-one" },
-                { id: "entry-two", receiptHandle: "rh-two" },
-            ],
-            visibilityTimeoutSeconds: 600,
-        });
-        expect(sent[3].input).toMatchObject({
-            QueueUrl: "https://q",
-            Entries: [
-                { Id: "entry-one", ReceiptHandle: "rh-one", VisibilityTimeout: 600 },
-                { Id: "entry-two", ReceiptHandle: "rh-two", VisibilityTimeout: 600 },
-            ],
-        });
-        expect(batchResult).toEqual({
-            failedEntries: [{
-                    id: "entry-two",
-                    code: "ReceiptHandleIsInvalid",
-                    message: "one receipt was rejected",
-                    senderFault: true,
-                }],
-        });
-    });
-    it("returns an empty list when the SDK omits Messages", async () => {
-        const adapted = sqsClientFromAwsSdk({
-            send: async () => ({}),
-        });
-        const out = await adapted.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: new AbortController().signal,
-        });
-        expect(out.messages).toEqual([]);
-    });
-});
-// ─── createRefreshingSqsClient ──────────────────────────────────────────────
-function expiringError(name) {
-    const e = new Error(name);
-    e.name = name;
-    return e;
-}
-function recordingSqs() {
-    const client = {
-        receives: 0,
-        async receiveMessage() {
-            client.receives += 1;
-            return { messages: [] };
-        },
-        async deleteMessage() { },
-        async changeMessageVisibility() { },
-        async changeMessageVisibilityBatch() { return { failedEntries: [] }; },
-    };
-    return client;
-}
-describe("createRefreshingSqsClient", () => {
-    const T0 = Date.parse("2026-06-10T12:00:00.000Z");
-    it("uses the initial client while creds are fresh (no refresh)", async () => {
-        const subscribe = vi.fn();
-        const built = [];
-        const client = createRefreshingSqsClient({
-            initial: subscribeResponse(), // expires 13:00
-            subscribe,
-            buildSqs: () => {
-                const c = recordingSqs();
-                built.push(c);
-                return c;
-            },
-            now: () => T0, // 60 min before expiry — outside the 2-min skew window
-        });
-        await client.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: new AbortController().signal,
-        });
-        expect(subscribe).not.toHaveBeenCalled();
-        expect(built).toHaveLength(1);
-    });
-    it("proactively re-vends inside the expiry skew window", async () => {
-        const subscribe = vi
-            .fn()
-            .mockResolvedValue(subscribeResponse({ expiration: "2026-06-10T15:00:00.000Z" }));
-        const built = [];
-        const client = createRefreshingSqsClient({
-            initial: subscribeResponse(), // expires 13:00
-            subscribe,
-            buildSqs: () => {
-                const c = recordingSqs();
-                built.push(c);
-                return c;
-            },
-            now: () => Date.parse("2026-06-10T12:59:30.000Z"), // inside 2-min skew
-        });
-        await client.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: new AbortController().signal,
-        });
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        expect(built).toHaveLength(2); // initial + rebuilt
-    });
-    it("reactively re-vends ONCE on an expiry-class error, then retries", async () => {
-        const subscribe = vi
-            .fn()
-            .mockResolvedValue(subscribeResponse({ expiration: "2026-06-10T15:00:00.000Z" }));
-        const failing = {
-            async receiveMessage() {
-                throw expiringError("ExpiredTokenException");
-            },
-            async deleteMessage() { },
-            async changeMessageVisibility() { },
-            async changeMessageVisibilityBatch() { return { failedEntries: [] }; },
-        };
-        const fresh = recordingSqs();
-        let builds = 0;
-        const client = createRefreshingSqsClient({
-            initial: subscribeResponse(),
-            subscribe,
-            // First build (construction) returns the always-failing client; the
-            // refresh-triggered rebuild returns the fresh one.
-            buildSqs: () => (builds++ === 0 ? failing : fresh),
-            now: () => T0,
-        });
-        const out = await client.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: new AbortController().signal,
-        });
-        expect(out.messages).toEqual([]);
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        expect(fresh.receives).toBe(1);
-    });
-    it("non-expiry errors propagate untouched (receiver backoff owns them)", async () => {
-        const subscribe = vi.fn();
-        const client = createRefreshingSqsClient({
-            initial: subscribeResponse(),
-            subscribe,
-            buildSqs: () => ({
-                async receiveMessage() {
-                    throw expiringError("AccessDeniedException");
-                },
-                async deleteMessage() { },
-                async changeMessageVisibility() { },
-                async changeMessageVisibilityBatch() { return { failedEntries: [] }; },
-            }),
-            now: () => T0,
-        });
-        await expect(client.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: new AbortController().signal,
-        })).rejects.toThrow("AccessDeniedException");
-        expect(subscribe).not.toHaveBeenCalled();
-    });
-    it("collapses concurrent refreshes onto one subscribe call", async () => {
-        // Indirection object (not a nullable local) so TS doesn't narrow the
-        // callback assignment from inside the promise executor to `never`.
-        const sub = {};
-        const subscribe = vi.fn(() => new Promise((res) => {
-            sub.resolve = res;
-        }));
-        const client = createRefreshingSqsClient({
-            initial: subscribeResponse(),
-            subscribe,
-            buildSqs: () => recordingSqs(),
-            now: () => Date.parse("2026-06-10T13:30:00.000Z"), // past expiry
-        });
-        const sig = new AbortController().signal;
-        const p1 = client.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: sig,
-        });
-        const p2 = client.receiveMessage({
-            queueUrl: "https://q",
-            maxMessages: 1,
-            waitTimeSeconds: 1,
-            signal: sig,
-        });
-        // Let both calls hit ensureFresh before resolving the vend.
-        await new Promise((r) => setTimeout(r, 0));
-        sub.resolve?.(subscribeResponse({ expiration: "2026-06-10T15:00:00.000Z" }));
-        await Promise.all([p1, p2]);
-        expect(subscribe).toHaveBeenCalledTimes(1);
-    });
-});
-// ─── startEventSync ─────────────────────────────────────────────────────────
-function pushEvent(overrides = {}) {
-    return {
-        relativePath: "companies/indigo/docs/a.md",
-        kind: "upsert",
-        contentHash: `sha256:${"a".repeat(64)}`,
-        mtime: "2026-06-10T12:00:00.000Z",
-        originDeviceId: "peer-device",
-        originTenantId: "prs_tenant",
-        sequenceNumber: 1,
-        eventTimestamp: "2026-06-10T12:00:00.000Z",
-        ...overrides,
-    };
-}
-describe("startEventSync", () => {
-    function happyOpts(syncCalls) {
-        return {
-            hqRoot: "/tmp/hq",
-            apiUrl: "https://api.example.com",
-            authToken: async () => "jwt",
-            deviceId: "this-device",
-            resolveTenantId: async () => "prs_tenant",
-            syncBatchFn: async (ctx) => {
-                syncCalls.push(...ctx.events);
-            },
-            subscribe: async () => subscribeResponse(),
-            buildSqs: () => ({
-                // Parks the receiver's poll loop, but honors the abort signal (the
-                // SqsClientLike contract) so dispose() doesn't block on the drain
-                // deadline.
-                receiveMessage: ({ signal }) => new Promise((resolve) => {
-                    signal.addEventListener("abort", () => resolve({ messages: [] }), {
-                        once: true,
-                    });
-                }),
-                deleteMessage: async () => { },
-                changeMessageVisibility: async () => { },
-                changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-            }),
-            log: () => { },
-        };
-    }
-    it("logs one receiver.drain JSON line and drops receiver debug records", async () => {
-        const syncCalls = [];
-        const logs = [];
-        let firstReceive = true;
-        const queueSqs = {
-            receiveMessage: ({ signal, waitTimeSeconds }) => {
-                if (firstReceive && waitTimeSeconds > 1) {
-                    firstReceive = false;
-                    return Promise.resolve({
-                        messages: [{
-                                Body: JSON.stringify(pushEvent()),
-                                ReceiptHandle: "rh-drain-log",
-                            }],
-                    });
-                }
-                if (waitTimeSeconds <= 1)
-                    return Promise.resolve({ messages: [] });
-                return new Promise((resolve) => {
-                    signal.addEventListener("abort", () => resolve({ messages: [] }), {
-                        once: true,
-                    });
-                });
-            },
-            deleteMessage: async () => { },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        };
-        const handles = await startEventSync({
-            ...happyOpts(syncCalls),
-            buildSqs: () => queueSqs,
-            log: (line) => logs.push(line),
-        });
-        try {
-            await vi.waitFor(() => {
-                expect(logs.some((line) => {
-                    try {
-                        return JSON.parse(line).event === "receiver.drain";
-                    }
-                    catch {
-                        return false;
-                    }
-                })).toBe(true);
-            });
-            const receiverDrainLines = logs.filter((line) => {
-                try {
-                    const record = JSON.parse(line);
-                    return record.type === "receiver" && record.event === "receiver.drain";
-                }
-                catch {
-                    return false;
-                }
-            });
-            expect(receiverDrainLines).toHaveLength(1);
-            expect(JSON.parse(receiverDrainLines[0])).toEqual(expect.objectContaining({
-                type: "receiver",
-                event: "receiver.drain",
-                tenantId: "prs_tenant",
-                received: 1,
-                coalesced: 1,
-                processed: 1,
-                deleted: 1,
-                released: 0,
-                remaining: 0,
-                msg: "push receiver drain completed",
-            }));
-            expect(receiverDrainLines[0]).not.toContain("\n");
-            expect(logs.some((line) => line.includes("receiver.sync.start"))).toBe(false);
-        }
-        finally {
-            await handles?.dispose();
-        }
-    });
-    it("forwards receiver sync failures to the log seam as receiver JSON lines", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-event-sync-retry-log-"));
-        const logs = [];
-        let delivered = false;
-        const queueSqs = {
-            receiveMessage: ({ signal, waitTimeSeconds }) => {
-                if (!delivered && waitTimeSeconds > 1) {
-                    delivered = true;
-                    return Promise.resolve({
-                        messages: [{
-                                Body: JSON.stringify(pushEvent({ relativePath: "personal/policies/retry.md" })),
-                                ReceiptHandle: "rh-sync-failed",
-                                MessageId: "message-sync-failed",
-                            }],
-                    });
-                }
-                if (waitTimeSeconds <= 1)
-                    return Promise.resolve({ messages: [] });
-                return new Promise((resolve) => {
-                    signal.addEventListener("abort", () => resolve({ messages: [] }), { once: true });
-                });
-            },
-            deleteMessage: async () => { },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        };
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            hqRoot,
-            syncBatchFn: async () => {
-                throw new Error("targeted pull failed");
-            },
-            buildSqs: () => queueSqs,
-            log: (line) => logs.push(line),
-        });
-        try {
-            await vi.waitFor(() => {
-                const line = logs.find((value) => {
-                    try {
-                        const record = JSON.parse(value);
-                        return record.type === "receiver" && record.event === "receiver.sync.failed";
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-                expect(line).toBeDefined();
-            });
-            const line = logs.find((value) => {
-                try {
-                    const record = JSON.parse(value);
-                    return record.type === "receiver" && record.event === "receiver.sync.failed";
-                }
-                catch {
-                    return false;
-                }
-            });
-            expect(JSON.parse(line)).toMatchObject({
-                type: "receiver",
-                event: "receiver.sync.failed",
-                tenantId: "prs_tenant",
-                pathCount: 1,
-                err: { message: "targeted pull failed" },
-            });
-        }
-        finally {
-            await handles?.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    async function startWithCapturedPublishTransport(overrideFactory) {
-        const watcherModule = await import("../watcher.js");
-        let publishTransport;
-        class CapturingPushEventEmitter extends watcherModule.PushEventEmitter {
-            constructor(options) {
-                super(options);
-                publishTransport = options.transport;
-            }
-        }
-        vi.doMock("../watcher.js", () => ({
-            ...watcherModule,
-            PushEventEmitter: CapturingPushEventEmitter,
-        }));
-        vi.resetModules();
-        try {
-            const eventSyncModule = await import("./event-sync.js");
-            const pushTransportModule = await import("./push-transport.js");
-            const handles = await eventSyncModule.startEventSync({
-                ...happyOpts([]),
-                now: () => Date.parse("2026-06-10T12:00:00.000Z"),
-                ...overrideFactory(pushTransportModule),
-            });
-            if (!publishTransport) {
-                await handles.dispose();
-                throw new Error("event-sync did not construct its publish transport");
-            }
-            return {
-                handles,
-                publishTransport,
-                pushTransportModule,
-                async cleanup() {
-                    try {
-                        await handles.dispose();
-                    }
-                    finally {
-                        vi.doUnmock("../watcher.js");
-                        vi.resetModules();
-                    }
-                },
-            };
-        }
-        catch (error) {
-            vi.doUnmock("../watcher.js");
-            vi.resetModules();
-            throw error;
-        }
-    }
-    const nonScopePublishErrors = [
-        ["network error", () => new Error("push network unavailable")],
-        ["HTTP 500", () => Object.assign(new Error("push server failed"), { status: 500 })],
-        ["untyped 403", () => Object.assign(new Error("not a scope denial"), { status: 403 })],
-    ];
-    it("brings up publish + receive, self-echo-filters, and logs receiver origins", async () => {
-        const syncCalls = [];
-        const logs = [];
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-event-sync-origin-"));
-        fs.mkdirSync(path.join(hqRoot, ".hq"), { recursive: true });
-        fs.writeFileSync(path.join(hqRoot, ".hq", "config.json"), JSON.stringify({ sync: { logReceiverOrigins: true } }));
-        const opts = {
-            ...happyOpts(syncCalls),
-            hqRoot,
-            log: (message) => logs.push(message),
-        };
-        const receiverLogRecords = () => logs.flatMap((message) => {
-            try {
-                const record = JSON.parse(message);
-                return record && typeof record === "object" && !Array.isArray(record)
-                    ? [record]
-                    : [];
-            }
-            catch {
-                return [];
-            }
-        });
-        // The wrapped syncFn is private to the receiver — exercise the filter
-        // through a receiver-visible seam instead: deliver one own-device and one
-        // peer message through the (fake) queue.
-        const delivered = [];
-        let deliverNext = null;
-        const queueSqs = {
-            receiveMessage: ({ signal, waitTimeSeconds }) => new Promise((resolve) => {
-                if (waitTimeSeconds === 0)
-                    return resolve({ messages: [] });
-                if (waitTimeSeconds === 1) {
-                    const t = setTimeout(() => resolve({ messages: [] }), 1);
-                    signal.addEventListener("abort", () => {
-                        clearTimeout(t);
-                        resolve({ messages: [] });
-                    }, { once: true });
-                    return;
-                }
-                signal.addEventListener("abort", () => resolve({ messages: [] }), {
-                    once: true,
-                });
-                deliverNext = (body) => {
-                    deliverNext = null; // consumed — re-armed on the next poll
-                    delivered.push(body);
-                    resolve({ messages: [{ Body: body, ReceiptHandle: "rh" }] });
-                };
-            }),
-            deleteMessage: async () => { },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        };
-        const handles = await startEventSync({
-            ...opts,
-            buildSqs: () => queueSqs,
-        });
-        expect(handles).not.toBeNull();
-        expect(handles.ownDeviceId).toBe("this-device");
-        const waitForPoll = () => vi.waitFor(() => {
-            if (!deliverNext)
-                throw new Error("receiver not polling yet");
-        });
-        try {
-            // Own-device event → filtered out (no syncFn call).
-            await waitForPoll();
-            deliverNext(JSON.stringify(pushEvent({ originDeviceId: "this-device" })));
-            await vi.waitFor(() => expect(delivered).toHaveLength(1));
-            await vi.waitFor(() => expect(receiverLogRecords()).toEqual(expect.arrayContaining([
-                expect.objectContaining({
-                    event: "receiver.drain",
-                    origins: { "this-device": 1 },
-                }),
-            ])));
-            // Peer event → bridged into syncFn.
-            await waitForPoll();
-            deliverNext(JSON.stringify(pushEvent({ originDeviceId: "peer-device", sequenceNumber: 2 })));
-            await vi.waitFor(() => expect(syncCalls).toHaveLength(1));
-            expect(syncCalls[0].originDeviceId).toBe("peer-device");
-            await vi.waitFor(() => expect(receiverLogRecords()).toEqual(expect.arrayContaining([
-                expect.objectContaining({
-                    event: "fanout.receive",
-                    originDeviceId: "peer-device",
-                }),
-            ])));
-            // The own-device event was delivered but never bridged.
-            expect(syncCalls.every((e) => e.originDeviceId === "peer-device")).toBe(true);
-            // Peer delete tombstone → bridged into syncFn. The runner handles safety by
-            // running a targeted pull; it does not unlink directly from this payload.
-            await waitForPoll();
-            deliverNext(JSON.stringify({
-                relativePath: "companies/indigo/deleted.md",
-                kind: "delete",
-                originDeviceId: "peer-device",
-                originTenantId: "prs_tenant",
-                sequenceNumber: 3,
-                eventTimestamp: "2026-06-10T12:01:00.000Z",
-            }));
-            await vi.waitFor(() => expect(syncCalls).toHaveLength(2));
-            expect(syncCalls[1]).toMatchObject({
-                kind: "delete",
-                relativePath: "companies/indigo/deleted.md",
-            });
-        }
-        finally {
-            await handles?.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("drops retired overlay events before a pull pass and emits one batch diagnostic", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-event-sync-"));
-        for (const relativePath of [
-            "personal/policies/legacy-rule.md",
-            "personal/policies/removed-rule.md",
-        ]) {
-            const absolutePath = path.join(hqRoot, relativePath);
-            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-            fs.writeFileSync(absolutePath, "fixture\n");
-        }
-        const syncCalls = [];
-        const logs = [];
-        const messages = [
-            { Body: JSON.stringify(pushEvent({ relativePath: "personal/policies/new-rule.md", sequenceNumber: 1 })), ReceiptHandle: "rh-valid" },
-            { Body: JSON.stringify(pushEvent({ relativePath: "core/policies/legacy-rule.md", contentHash: `sha256:${hashFile(path.join(hqRoot, "personal/policies/legacy-rule.md"))}`, sequenceNumber: 2 })), ReceiptHandle: "rh-retired-upsert" },
-            { Body: JSON.stringify(pushEvent({ relativePath: "core/policies/removed-rule.md", kind: "delete", sequenceNumber: 3 })), ReceiptHandle: "rh-retired-delete" },
-        ];
-        const deleted = [];
-        const queueSqs = {
-            receiveMessage: ({ signal, waitTimeSeconds }) => {
-                if (messages.length > 0 && waitTimeSeconds > 1) {
-                    return Promise.resolve({ messages: messages.splice(0) });
-                }
-                if (waitTimeSeconds <= 1)
-                    return Promise.resolve({ messages: [] });
-                return new Promise((resolve) => {
-                    signal.addEventListener("abort", () => resolve({ messages: [] }), { once: true });
-                });
-            },
-            deleteMessage: async ({ receiptHandle }) => {
-                deleted.push(receiptHandle);
-            },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        };
-        const handles = await startEventSync({
-            ...happyOpts(syncCalls),
-            hqRoot,
-            buildSqs: () => queueSqs,
-            log: (message) => logs.push(message),
-        });
-        try {
-            await vi.waitFor(() => expect(deleted).toHaveLength(3));
-            expect(syncCalls.map((event) => event.relativePath)).toEqual([
-                "personal/policies/new-rule.md",
-            ]);
-            expect(logs.filter((line) => line.includes("event-sync-unsyncable-events-dropped"))).toEqual([
-                JSON.stringify({
-                    type: "event-sync-unsyncable-events-dropped",
-                    diagnostic: true,
-                    count: 2,
-                    samplePaths: ["core/policies/legacy-rule.md", "core/policies/removed-rule.md"],
-                    originDeviceId: "peer-device",
-                    originDeviceIds: ["peer-device"],
-                }),
-            ]);
-        }
-        finally {
-            await handles.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("processes release-shipped and new paths that are not retired mirrors", async () => {
-        const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-event-sync-"));
-        for (const relativePath of [
-            "personal/policies/bar.md",
-            "core/policies/bar.md",
-            "core/policies/baz.md",
-        ]) {
-            const absolutePath = path.join(hqRoot, relativePath);
-            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-            fs.writeFileSync(absolutePath, "fixture\n");
-        }
-        const syncCalls = [];
-        const logs = [];
-        const messages = [
-            { Body: JSON.stringify(pushEvent({ relativePath: "core/policies/bar.md", sequenceNumber: 1 })), ReceiptHandle: "rh-collision" },
-            { Body: JSON.stringify(pushEvent({ relativePath: "core/policies/baz.md", sequenceNumber: 2 })), ReceiptHandle: "rh-release" },
-            { Body: JSON.stringify(pushEvent({ relativePath: "core/policies/new.md", sequenceNumber: 3 })), ReceiptHandle: "rh-new-core" },
-            { Body: JSON.stringify(pushEvent({ relativePath: "knowledge/notes/new.md", sequenceNumber: 4 })), ReceiptHandle: "rh-new-valid-area" },
-        ];
-        const deleted = [];
-        const queueSqs = {
-            receiveMessage: ({ signal, waitTimeSeconds }) => {
-                if (messages.length > 0 && waitTimeSeconds > 1) {
-                    return Promise.resolve({ messages: messages.splice(0) });
-                }
-                if (waitTimeSeconds <= 1)
-                    return Promise.resolve({ messages: [] });
-                return new Promise((resolve) => {
-                    signal.addEventListener("abort", () => resolve({ messages: [] }), { once: true });
-                });
-            },
-            deleteMessage: async ({ receiptHandle }) => {
-                deleted.push(receiptHandle);
-            },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        };
-        const handles = await startEventSync({
-            ...happyOpts(syncCalls),
-            hqRoot,
-            buildSqs: () => queueSqs,
-            log: (message) => logs.push(message),
-        });
-        try {
-            await vi.waitFor(() => expect(deleted).toHaveLength(4));
-            expect(syncCalls.map((event) => event.relativePath)).toEqual([
-                "core/policies/bar.md",
-                "core/policies/baz.md",
-                "core/policies/new.md",
-                "knowledge/notes/new.md",
-            ]);
-            expect(logs.filter((line) => line.includes("event-sync-unsyncable-events-dropped"))).toEqual([]);
-        }
-        finally {
-            await handles.dispose();
-            fs.rmSync(hqRoot, { recursive: true, force: true });
-        }
-    });
-    it("R-F18: disables receive metrics when subscribe omits CloudWatch credentials", async () => {
-        const oldMetricEnv = {
-            region: process.env.HQ_SYNC_CLOUDWATCH_REGION,
-            accessKeyId: process.env.HQ_SYNC_CLOUDWATCH_ACCESS_KEY_ID,
-            secretAccessKey: process.env.HQ_SYNC_CLOUDWATCH_SECRET_ACCESS_KEY,
-            sessionToken: process.env.HQ_SYNC_CLOUDWATCH_SESSION_TOKEN,
-        };
-        delete process.env.HQ_SYNC_CLOUDWATCH_REGION;
-        delete process.env.HQ_SYNC_CLOUDWATCH_ACCESS_KEY_ID;
-        delete process.env.HQ_SYNC_CLOUDWATCH_SECRET_ACCESS_KEY;
-        delete process.env.HQ_SYNC_CLOUDWATCH_SESSION_TOKEN;
-        const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
-        const syncCalls = [];
-        let deliverNext = null;
-        const queueSqs = {
-            receiveMessage: ({ signal, waitTimeSeconds }) => new Promise((resolve) => {
-                if (waitTimeSeconds === 0)
-                    return resolve({ messages: [] });
-                if (waitTimeSeconds === 1) {
-                    const t = setTimeout(() => resolve({ messages: [] }), 1);
-                    signal.addEventListener("abort", () => {
-                        clearTimeout(t);
-                        resolve({ messages: [] });
-                    }, { once: true });
-                    return;
-                }
-                signal.addEventListener("abort", () => resolve({ messages: [] }), {
-                    once: true,
-                });
-                deliverNext = (body) => {
-                    deliverNext = null;
-                    resolve({ messages: [{ Body: body, ReceiptHandle: "rh" }] });
-                };
-            }),
-            deleteMessage: async () => { },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        };
-        let handles = null;
-        try {
-            handles = await startEventSync({
-                ...happyOpts(syncCalls),
-                buildSqs: () => queueSqs,
-            });
-            expect(handles).not.toBeNull();
-            await vi.waitFor(() => {
-                if (!deliverNext)
-                    throw new Error("receiver not polling yet");
-            });
-            deliverNext(JSON.stringify(pushEvent({ originDeviceId: "peer-device" })));
-            await vi.waitFor(() => expect(syncCalls).toHaveLength(1));
-            await new Promise((resolve) => setTimeout(resolve, 0));
-            expect(consoleSpy).not.toHaveBeenCalled();
-        }
-        finally {
-            await handles?.dispose();
-            consoleSpy.mockRestore();
-            if (oldMetricEnv.region === undefined) {
-                delete process.env.HQ_SYNC_CLOUDWATCH_REGION;
-            }
-            else {
-                process.env.HQ_SYNC_CLOUDWATCH_REGION = oldMetricEnv.region;
-            }
-            if (oldMetricEnv.accessKeyId === undefined) {
-                delete process.env.HQ_SYNC_CLOUDWATCH_ACCESS_KEY_ID;
-            }
-            else {
-                process.env.HQ_SYNC_CLOUDWATCH_ACCESS_KEY_ID = oldMetricEnv.accessKeyId;
-            }
-            if (oldMetricEnv.secretAccessKey === undefined) {
-                delete process.env.HQ_SYNC_CLOUDWATCH_SECRET_ACCESS_KEY;
-            }
-            else {
-                process.env.HQ_SYNC_CLOUDWATCH_SECRET_ACCESS_KEY =
-                    oldMetricEnv.secretAccessKey;
-            }
-            if (oldMetricEnv.sessionToken === undefined) {
-                delete process.env.HQ_SYNC_CLOUDWATCH_SESSION_TOKEN;
-            }
-            else {
-                process.env.HQ_SYNC_CLOUDWATCH_SESSION_TOKEN =
-                    oldMetricEnv.sessionToken;
-            }
-        }
-    });
-    it("keeps a poll-only handle then retries startup into a live receiver", async () => {
-        const logged = [];
-        const clock = new FakeClock();
-        const published = [];
-        const receiveMessage = vi.fn(({ signal }) => new Promise((resolve) => {
-            signal.addEventListener("abort", () => resolve({ messages: [] }), {
-                once: true,
-            });
-        }));
-        const subscribe = vi
-            .fn()
-            .mockRejectedValueOnce(new Error("queue tags still converging"))
-            .mockResolvedValue(subscribeResponse());
-        const postTelemetryEvents = vi.fn().mockResolvedValue({ accepted: 1 });
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            buildSqs: () => ({
-                receiveMessage,
-                deleteMessage: async () => { },
-                changeMessageVisibility: async () => { },
-                changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-            }),
-            transport: {
-                connected: true,
-                start: async () => { },
-                dispose: async () => { },
-                publish: async (event) => {
-                    published.push(event);
-                },
-            },
-            telemetryClient: { postTelemetryEvents },
-            clock,
-            now: () => Date.parse("2026-06-10T12:00:00.000Z"),
-            retryRandom: () => 1,
-            log: (m) => logged.push(m),
-        });
-        expect(handles.receiver.connected).toBe(false);
-        handles.publishBatch({ paths: new Map() });
-        expect(published).toHaveLength(0);
-        clock.advance(30_000);
-        for (let i = 0; i < 8; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(2);
-        expect(receiveMessage).toHaveBeenCalledOnce();
-        expect(handles.receiver.connected).toBe(true);
-        const abs = new URL(import.meta.url).pathname;
-        handles.publishBatch({ paths: new Map([[abs, "docs/retried.ts"]]) });
-        await vi.waitFor(() => expect(published).toHaveLength(1));
-        expect(logged.join("\n")).toContain("event-sync: startup failed, continuing poll-only");
-        expect(logged.join("\n")).toContain("next retry in 30000ms");
-        expect(logged.join("\n")).toContain("event-sync: live");
-        await vi.waitFor(() => expect(postTelemetryEvents).toHaveBeenCalledTimes(2));
-        expect(postTelemetryEvents.mock.calls.map(([batch]) => batch.events[0]?.properties?.startupResult)).toEqual(["poll_only", "live"]);
-        await handles.dispose();
-    });
-    it("stays poll-only and schedules only the long recheck after the coded subscribe denial", async () => {
-        const logged = [];
-        const clock = new FakeClock();
-        const subscribe = vi.fn(() => subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "this-device",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 403,
-                text: async () => JSON.stringify({
-                    error: "realtime-unavailable",
-                    code: "REALTIME_UNAVAILABLE",
-                    retryable: false,
-                }),
-            }),
-        }));
-        const postTelemetryEvents = vi.fn().mockResolvedValue({ accepted: 1 });
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            clock,
-            retryInitialMs: 30_000,
-            retryMaxMs: 60_000,
-            retryRandom: () => 1,
-            telemetryClient: { postTelemetryEvents },
-            log: (message) => logged.push(message),
-        });
-        expect(handles.receiver.connected).toBe(false);
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        expect(clock.pendingTimerCount()).toBe(1);
-        expect(logged).toEqual([
-            "event-sync: realtime unavailable for this account; staying poll-only, recheck in 6h",
-        ]);
-        clock.advance(30_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        clock.advance(6 * 60 * 60 * 1000 - 30_000);
-        for (let i = 0; i < 8; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(2);
-        await vi.waitFor(() => expect(clock.pendingTimerCount()).toBe(1));
-        expect(logged).not.toContain(expect.stringMatching(/startup retry/));
-        await vi.waitFor(() => expect(postTelemetryEvents).toHaveBeenCalledTimes(1));
-        expect(postTelemetryEvents.mock.calls[0]?.[0]).toMatchObject({
-            events: [{ properties: { startupResult: "realtime_unavailable" } }],
-        });
-        await handles.dispose();
-    });
-    it("quiesces a receiver when its credential refresh is denied and uses the long recheck", async () => {
-        const clock = new FakeClock();
-        const logged = [];
-        const subscribe = vi
-            .fn()
-            .mockResolvedValueOnce(subscribeResponse({ expiration: "2026-06-10T13:00:00.000Z" }))
-            .mockRejectedValueOnce(new RealtimeUnavailableError({ status: 403, operation: "refresh subscribe" }))
-            .mockResolvedValue(subscribeResponse({ expiration: "2026-06-10T15:00:00.000Z" }));
-        const postTelemetryEvents = vi.fn().mockResolvedValue({ accepted: 1 });
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            buildSqs: () => ({
-                receiveMessage: ({ signal }) => new Promise((resolve) => {
-                    signal.addEventListener("abort", () => resolve({ messages: [] }), {
-                        once: true,
-                    });
-                }),
-                deleteMessage: async () => { },
-                changeMessageVisibility: async () => { },
-                changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-            }),
-            now: () => Date.parse("2026-06-10T12:59:30.000Z"),
-            clock,
-            retryRandom: () => 1,
-            realtimeUnavailableRecheckMs: 60_000,
-            telemetryClient: { postTelemetryEvents },
-            log: (message) => logged.push(message),
-        });
-        await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(2));
-        await vi.waitFor(() => expect(handles.receiver.connected).toBe(false));
-        expect(clock.pendingTimerCount()).toBe(1);
-        expect(logged).toContain("event-sync: realtime unavailable for this account; staying poll-only, recheck in 6h");
-        clock.advance(30_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(2);
-        clock.advance(30_000);
-        await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(3));
-        await handles.dispose();
-    });
-    it("stays poll-only after a device-cap denial and reports the transition once", async () => {
-        const logged = [];
-        const clock = new FakeClock();
-        const subscribe = vi.fn(() => subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "this-device",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 429,
-                text: async () => JSON.stringify({
-                    error: "sync-device-limit-exceeded",
-                    code: "SYNC_DEVICE_LIMIT_EXCEEDED",
-                }),
-            }),
-        }));
-        const postTelemetryEvents = vi.fn().mockResolvedValue({ accepted: 1 });
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            clock,
-            retryInitialMs: 30_000,
-            retryMaxMs: 60_000,
-            retryRandom: () => 1,
-            deviceIdAgeBucket: "<1h",
-            deviceIdFileFreshlyCreatedThisRun: true,
-            telemetryClient: { postTelemetryEvents },
-            log: (message) => logged.push(message),
-        });
-        expect(handles.receiver.connected).toBe(false);
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        expect(clock.pendingTimerCount()).toBe(1);
-        expect(logged).toEqual([
-            "event-sync: sync device limit exceeded for device this-device; staying poll-only, recheck in 6h",
-        ]);
-        await vi.waitFor(() => expect(postTelemetryEvents).toHaveBeenCalledTimes(1));
-        expect(postTelemetryEvents.mock.calls[0]?.[0]).toMatchObject({
-            events: [{
-                    properties: {
-                        startupResult: "sync_device_limit",
-                        sync_device_limit: "true",
-                        device_id_age_bucket: "lt-1h",
-                        device_id_freshly_created: "true",
-                    },
-                }],
-        });
-        clock.advance(30_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        clock.advance(6 * 60 * 60 * 1000 - 30_000);
-        for (let i = 0; i < 8; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(2);
-        expect(logged).toHaveLength(1);
-        expect(postTelemetryEvents).toHaveBeenCalledTimes(1);
-        await handles.dispose();
-    });
-    it("never rechecks a device-limit denial before half the window on a zero jitter draw", async () => {
-        const logged = [];
-        const clock = new FakeClock();
-        const subscribe = vi.fn(() => subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "this-device",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 429,
-                text: async () => JSON.stringify({
-                    error: "sync-device-limit-exceeded",
-                    code: "SYNC_DEVICE_LIMIT_EXCEEDED",
-                }),
-            }),
-        }));
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            clock,
-            retryRandom: () => 0,
-            log: (message) => logged.push(message),
-        });
-        expect(handles.receiver.connected).toBe(false);
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        expect(logged).toEqual([
-            "event-sync: sync device limit exceeded for device this-device; staying poll-only, recheck in 6h",
-        ]);
-        expect(logged.join("\n")).not.toContain("startup retry");
-        clock.advance(60_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        clock.advance(3 * 60 * 60 * 1000 - 60_001);
-        for (let i = 0; i < 8; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(1);
-        clock.advance(1);
-        for (let i = 0; i < 8; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(2);
-        expect(logged).toHaveLength(1);
-        await handles.dispose();
-    });
-    it("keeps an uncoded 429 on the existing short startup retry", async () => {
-        const logged = [];
-        const clock = new FakeClock();
-        const subscribe = vi.fn(() => subscribeSyncReceive({
-            apiUrl: "https://api.example.com",
-            authToken: "jwt",
-            deviceId: "this-device",
-            fetchImpl: async () => ({
-                ok: false,
-                status: 429,
-                text: async () => JSON.stringify({
-                    error: "other-rate-limit",
-                    code: "OTHER_429",
-                }),
-            }),
-        }));
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            clock,
-            retryRandom: () => 1,
-            log: (message) => logged.push(message),
-        });
-        expect(handles.receiver.connected).toBe(false);
-        expect(clock.pendingTimerCount()).toBe(1);
-        expect(logged[0]).toContain("startup failed, continuing poll-only");
-        expect(logged[1]).toContain("next retry in 30000ms");
-        clock.advance(30_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(2);
-        await handles.dispose();
-    });
-    it("quiesces realtime publishing when the push endpoint returns a device-limit denial", async () => {
-        const clock = new FakeClock();
-        const logged = [];
-        const postTelemetryEvents = vi.fn().mockResolvedValue({ accepted: 1 });
-        const publish = vi.fn(async () => {
-            throw new SyncDeviceLimitError({ status: 429, operation: "publish" });
-        });
-        const transport = {
-            connected: true,
-            start: async () => { },
-            dispose: async () => { },
-            publish,
-        };
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            clock,
-            transport: transport,
-            deviceIdAgeBucket: "<1h",
-            deviceIdFileFreshlyCreatedThisRun: true,
-            telemetryClient: { postTelemetryEvents },
-            log: (message) => logged.push(message),
-        });
-        expect(handles.receiver.connected).toBe(true);
-        const abs = new URL(import.meta.url).pathname;
-        handles.publishBatch({ paths: new Map([[abs, "docs/publish-denied.ts"]]) });
-        await vi.waitFor(() => expect(logged).toContain("event-sync: sync device limit exceeded for device this-device; staying poll-only, recheck in 6h"));
-        await vi.waitFor(() => expect(handles.receiver.connected).toBe(false));
-        expect(clock.pendingTimerCount()).toBe(1);
-        const deviceLimitTelemetry = () => postTelemetryEvents.mock.calls
-            .flatMap(([batch]) => batch.events)
-            .filter((event) => event.properties?.startupResult === "sync_device_limit");
-        await vi.waitFor(() => expect(deviceLimitTelemetry()).toHaveLength(1));
-        expect(deviceLimitTelemetry()[0]).toMatchObject({
-            properties: {
-                startupResult: "sync_device_limit",
-                sync_device_limit: "true",
-                device_id_age_bucket: "lt-1h",
-                device_id_freshly_created: "true",
-            },
-        });
-        handles.publishBatch({ paths: new Map([[abs, "docs/publish-denied-again.ts"]]) });
-        await new Promise((resolve) => setImmediate(resolve));
-        expect(publish).toHaveBeenCalledOnce();
-        await handles.dispose();
-    });
-    it("reports a retry-discovered realtime denial exactly once", async () => {
-        const clock = new FakeClock();
-        const logged = [];
-        const postTelemetryEvents = vi.fn().mockResolvedValue({ accepted: 1 });
-        const subscribe = vi
-            .fn()
-            .mockRejectedValueOnce(new Error("initial subscription failed"))
-            .mockRejectedValueOnce(new RealtimeUnavailableError({ status: 403, operation: "retry subscribe" }))
-            .mockRejectedValue(new RealtimeUnavailableError({ status: 403, operation: "recheck subscribe" }));
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            clock,
-            retryRandom: () => 1,
-            realtimeUnavailableRecheckMs: 60_000,
-            telemetryClient: { postTelemetryEvents },
-            log: (message) => logged.push(message),
-        });
-        clock.advance(30_000);
-        await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(2));
-        await vi.waitFor(() => expect(postTelemetryEvents).toHaveBeenCalledTimes(2));
-        expect(logged.filter((message) => message.includes("realtime unavailable for this account")))
-            .toHaveLength(1);
-        expect(postTelemetryEvents.mock.calls.map(([batch]) => batch.events[0]?.properties?.startupResult)).toEqual(["poll_only", "realtime_unavailable"]);
-        expect(clock.pendingTimerCount()).toBe(1);
-        clock.advance(60_000);
-        await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(3));
-        expect(logged.filter((message) => message.includes("realtime unavailable for this account")))
-            .toHaveLength(1);
-        await handles.dispose();
-    });
-    it("caps repeated startup retries and cancels the pending retry on dispose", async () => {
-        const logged = [];
-        const clock = new FakeClock();
-        const subscribe = vi.fn(async () => {
-            throw new Error("subscribe unavailable");
-        });
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            subscribe,
-            clock,
-            retryInitialMs: 30_000,
-            retryMaxMs: 60_000,
-            retryRandom: () => 1,
-            log: (m) => logged.push(m),
-        });
-        expect(handles.receiver.connected).toBe(false);
-        expect(clock.pendingTimerCount()).toBe(1);
-        clock.advance(30_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        clock.advance(60_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        clock.advance(60_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(4);
-        expect(logged.filter((line) => line.includes("next retry in 60000ms"))).toHaveLength(3);
-        expect(clock.pendingTimerCount()).toBe(1);
-        await handles.dispose();
-        expect(clock.pendingTimerCount()).toBe(0);
-        clock.advance(10 * 60_000);
-        for (let i = 0; i < 6; i++)
-            await Promise.resolve();
-        expect(subscribe).toHaveBeenCalledTimes(4);
-    });
-    it("awaits an in-flight startup retry before disposal completes", async () => {
-        const clock = new FakeClock();
-        const syncCalls = [];
-        let releaseSubscribe = null;
-        const blockedSubscribe = new Promise((resolve) => {
-            releaseSubscribe = resolve;
-        });
-        const subscribe = vi
-            .fn()
-            .mockRejectedValueOnce(new Error("initial subscribe unavailable"))
-            .mockImplementationOnce(() => blockedSubscribe);
-        const receiveMessage = vi.fn(async () => ({
-            messages: [{ Body: JSON.stringify(pushEvent()), ReceiptHandle: "retry-receipt" }],
-        }));
-        const buildSqs = vi.fn(() => ({
-            receiveMessage,
-            deleteMessage: async () => { },
-            changeMessageVisibility: async () => { },
-            changeMessageVisibilityBatch: async () => ({ failedEntries: [] }),
-        }));
-        const handles = await startEventSync({
-            ...happyOpts(syncCalls),
-            subscribe,
-            buildSqs,
-            clock,
-            retryRandom: () => 1,
-            log: () => { },
-        });
-        clock.advance(30_000);
-        await vi.waitFor(() => expect(subscribe).toHaveBeenCalledTimes(2));
-        let disposalComplete = false;
-        const disposing = handles.dispose().then(() => {
-            disposalComplete = true;
-        });
-        await Promise.resolve();
-        expect(disposalComplete).toBe(false);
-        releaseSubscribe(subscribeResponse());
-        await disposing;
-        expect(handles.receiver.connected).toBe(false);
-        expect(buildSqs).toHaveBeenCalled();
-        for (let i = 0; i < 4; i++)
-            await Promise.resolve();
-        expect(syncCalls).toHaveLength(0);
-    });
-    it("keeps the immediate-success path live without scheduling a retry", async () => {
-        const handles = await startEventSync({
-            ...happyOpts([]),
-        });
-        expect(handles.receiver.connected).toBe(true);
-        await new Promise((resolve) => setImmediate(resolve));
-        await handles.dispose();
-    });
-    it("stops later publishes after refresh discovers a different tenant", async () => {
-        const subscribe = vi
-            .fn()
-            .mockResolvedValueOnce({ ...subscribeResponse(), tenantId: "prs_original" })
-            .mockResolvedValueOnce({ ...subscribeResponse(), tenantId: "prs_refreshed" });
-        const transportPublish = vi.fn(async (_event) => { });
-        const transport = {
-            connected: true,
-            start: async () => { },
-            dispose: async () => { },
-            publish: transportPublish,
-        };
-        const { publishTransport, pushTransportModule, cleanup } = await startWithCapturedPublishTransport((pushTransport) => {
-            transportPublish.mockRejectedValue(new pushTransport.PushScopeForbiddenError({
-                status: 403,
-                operation: "HttpPushTransport: POST /v1/sync/push",
-                companyScope: "docs",
-            }));
-            return { subscribe, transport: transport };
-        });
-        try {
-            await expect(publishTransport.publish(pushEvent({ originTenantId: "prs_original" }))).rejects.toBeInstanceOf(pushTransportModule.RealtimeUnavailableError);
-            expect(transportPublish).toHaveBeenCalledOnce();
-            expect(subscribe).toHaveBeenCalledTimes(2);
-            await expect(publishTransport.publish(pushEvent({ originTenantId: "prs_original", relativePath: "docs/second.md" }))).rejects.toBeInstanceOf(pushTransportModule.RealtimeUnavailableError);
-            expect(transportPublish).toHaveBeenCalledOnce();
-            expect(subscribe).toHaveBeenCalledTimes(2);
-        }
-        finally {
-            await cleanup();
-        }
-    });
-    it.each(nonScopePublishErrors)("does not refresh after a non-scope %s publish error and rethrows that same error", async (_label, makeError) => {
-        const error = makeError();
-        const subscribe = vi
-            .fn()
-            .mockResolvedValueOnce({ ...subscribeResponse(), tenantId: "prs_tenant" });
-        const transportPublish = vi.fn(async (_event) => { });
-        transportPublish.mockRejectedValue(error);
-        const transport = {
-            connected: true,
-            start: async () => { },
-            dispose: async () => { },
-            publish: transportPublish,
-        };
-        const { publishTransport, cleanup } = await startWithCapturedPublishTransport(() => ({ subscribe, transport: transport }));
-        try {
-            await expect(publishTransport.publish(pushEvent())).rejects.toBe(error);
-            expect(transportPublish).toHaveBeenCalledOnce();
-            expect(subscribe).toHaveBeenCalledOnce();
-        }
-        finally {
-            await cleanup();
-        }
-    });
-    it("keeps a poll-only handle when identity resolution initially fails", async () => {
-        const clock = new FakeClock();
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            resolveTenantId: async () => {
-                throw new Error("no canonical person entity for this account");
-            },
-            clock,
-            log: () => { },
-        });
-        expect(handles.receiver.connected).toBe(false);
-        await handles.dispose();
-    });
-    it("publishBatch ships one event per changed path AFTER being invoked (publish leg)", async () => {
-        const published = [];
-        const fakeTransport = {
-            connected: true,
-            start: async () => { },
-            dispose: async () => { },
-            publish: async (e) => {
-                published.push(e);
-            },
-        };
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            transport: fakeTransport,
-            now: () => 1765372800000,
-        });
-        expect(handles).not.toBeNull();
-        // NOTE: paths must exist for content hashing — use this test file itself.
-        const abs = new URL(import.meta.url).pathname;
-        handles.publishBatch({ paths: new Map([[abs, "docs/self.ts"]]) });
-        await vi.waitFor(() => expect(published).toHaveLength(1));
-        const ev = published[0];
-        expect(ev.relativePath).toBe("docs/self.ts");
-        expect(ev.kind).toBe("upsert");
-        expect(ev.originDeviceId).toBe("this-device");
-        expect(ev.originTenantId).toBe("prs_tenant");
-        // Wall-clock sequence numbers (restart-safe monotonicity).
-        expect(ev.sequenceNumber).toBe(1765372800000);
-        expect(ev.contentHash).toMatch(/^sha256:[0-9a-f]{64}$/);
-        await handles.dispose();
-    });
-    it("disposal clears a deferred publish before tearing down its transport", async () => {
-        const clock = new FakeClock();
-        const published = [];
-        const publish = vi.fn(async (event) => {
-            published.push(event);
-        });
-        const disposeTransport = vi.fn(async () => { });
-        const fakeTransport = {
-            connected: true,
-            start: async () => { },
-            dispose: disposeTransport,
-            publish,
-        };
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "event-sync-dispose-"));
-        const file = path.join(dir, "deferred.md");
-        const batch = { paths: new Map([[file, "docs/deferred.md"]]) };
-        try {
-            fs.writeFileSync(file, "first\n");
-            const handles = await startEventSync({
-                ...happyOpts([]),
-                transport: fakeTransport,
-                clock,
-                publishMinIntervalMs: 60_000,
-            });
-            expect(handles).not.toBeNull();
-            handles.publishBatch(batch);
-            await vi.waitFor(() => expect(published).toHaveLength(1));
-            fs.writeFileSync(file, "deferred\n");
-            handles.publishBatch(batch);
-            await vi.waitFor(() => expect(clock.pendingTimerCount()).toBe(1));
-            await handles.dispose();
-            expect(clock.pendingTimerCount()).toBe(0);
-            expect(disposeTransport).toHaveBeenCalledOnce();
-            clock.advance(60_000);
-            await Promise.resolve();
-            expect(publish).toHaveBeenCalledTimes(1);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("keeps the publish batch fire-and-forget when a transport publish rejects", async () => {
-        const logged = [];
-        const rejection = new Error("publish unavailable", {
-            cause: new Error("socket reset"),
-        });
-        const transport = {
-            connected: true,
-            start: async () => { },
-            dispose: async () => { },
-            publish: async () => {
-                throw rejection;
-            },
-        };
-        const handles = await startEventSync({
-            ...happyOpts([]),
-            transport: transport,
-            log: (message) => logged.push(message),
-        });
-        expect(handles).not.toBeNull();
-        const unhandled = vi.fn();
-        process.on("unhandledRejection", unhandled);
-        try {
-            const abs = new URL(import.meta.url).pathname;
-            expect(() => handles.publishBatch({ paths: new Map([[abs, "docs/rejected.ts"]]) })).not.toThrow();
-            await vi.waitFor(() => expect(logged.find((line) => line.startsWith("event-sync: publish outcome "))).toBeDefined());
-            await new Promise((resolve) => setImmediate(resolve));
-            expect(unhandled).not.toHaveBeenCalled();
-            const line = logged.find((entry) => entry.startsWith("event-sync: publish outcome "));
-            expect(JSON.parse(line.slice("event-sync: publish outcome ".length))).toMatchObject({
-                attempted: 1,
-                succeeded: 0,
-                failed: 1,
-                successfulElapsedMs: null,
-                omitted: 0,
-                attempts: [
-                    {
-                        error: {
-                            name: "Error",
-                            message: "publish unavailable",
-                            cause: { message: "socket reset" },
-                        },
-                    },
-                ],
-            });
-        }
-        finally {
-            process.off("unhandledRejection", unhandled);
-            await handles?.dispose();
-        }
-    });
-});
-//# sourceMappingURL=event-sync.test.js.map