@indigoai-us/hq-cloud 6.15.79 → 6.15.81

package/dist/sync/reconcile-cursor.test.js

@@ -0,0 +1,139 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ReconcileCursorStore, checkpointReconcileApply, takeBoundedReconcileSlice, } from "./reconcile-cursor.js";
+const roots = [];
+afterEach(() => {
+    for (const root of roots.splice(0))
+        fs.rmSync(root, { recursive: true, force: true });
+});
+function root() {
+    const value = fs.mkdtempSync(path.join(os.tmpdir(), "hq-reconcile-cursor-test-"));
+    roots.push(value);
+    return value;
+}
+function cursor(phase, overrides = {}) {
+    return { routerVersion: 1, epoch: "epoch-1", areaId: "root:notes", phase, ...overrides };
+}
+function open(dir) {
+    return ReconcileCursorStore.open({ rootDir: dir, journalSlug: "personal", layoutEpoch: 1, areaId: "root:notes" });
+}
+describe("ReconcileCursorStore", () => {
+    it("resumes each discovery phase and does not revisit a completed area", () => {
+        const dir = root();
+        const first = open(dir);
+        first.checkpointDiscovery(cursor("local-discovery", { localDirectoryStack: ["notes"], localAfterPath: "notes/a.md" }));
+        expect(open(dir).read().cursor).toMatchObject({ phase: "local-discovery", localAfterPath: "notes/a.md" });
+        open(dir).checkpointDiscovery(cursor("remote-list", { remotePrefix: "notes/", remoteContinuation: "page-2" }));
+        expect(open(dir).read().cursor).toMatchObject({ phase: "remote-list", remoteContinuation: "page-2" });
+        open(dir).checkpointDiscovery(cursor("diff", { journalAfterKey: "notes/a.md", remoteHighWater: "etag-9" }));
+        expect(open(dir).read().cursor).toMatchObject({ phase: "diff", journalAfterKey: "notes/a.md" });
+        open(dir).complete("epoch-1");
+        expect(open(dir).read()).toEqual({ format: 1, completedEpoch: "epoch-1" });
+    });
+    it("only advances apply after each delete/tombstone outcome is durable", () => {
+        const dir = root();
+        const store = open(dir);
+        expect(() => store.checkpointApply(cursor("apply", { journalAfterKey: "notes/deleted.md" }), [
+            { path: "notes/deleted.md", durable: false },
+        ])).toThrow("before every path outcome is durable");
+        expect(store.read().cursor).toBeUndefined();
+        store.checkpointApply(cursor("apply", { journalAfterKey: "notes/deleted.md" }), [
+            { path: "notes/deleted.md", durable: true },
+            { path: "notes/tombstone.md", durable: true },
+        ]);
+        expect(open(dir).read().cursor).toMatchObject({ phase: "apply", journalAfterKey: "notes/deleted.md" });
+    });
+    it("advances an entrypoint apply cursor only after the caller reports durable paths", () => {
+        const dir = root();
+        const store = open(dir);
+        checkpointReconcileApply({ store, cursor: cursor("apply", { journalAfterKey: "notes/tombstone.md" }) }, ["notes/upload.md", "notes/tombstone.md"]);
+        expect(open(dir).read().cursor).toMatchObject({ phase: "apply", journalAfterKey: "notes/tombstone.md" });
+    });
+    it("invalidates a remote continuation when a later inventory epoch supersedes it", () => {
+        const dir = root();
+        const store = open(dir);
+        store.checkpointDiscovery(cursor("remote-list", { remotePrefix: "notes/", remoteContinuation: "page-8", remoteHighWater: "old" }));
+        expect(store.invalidateRemoteContinuation("epoch-1", "new")).toMatchObject({
+            phase: "remote-list",
+            remoteHighWater: "new",
+        });
+        const resumed = open(dir).read().cursor;
+        expect(resumed).not.toHaveProperty("remoteContinuation");
+        expect(resumed.remoteHighWater).toBe("new");
+    });
+    it("keeps cursor state isolated per area", () => {
+        const dir = root();
+        const alpha = ReconcileCursorStore.open({ rootDir: dir, journalSlug: "personal", layoutEpoch: 1, areaId: "root:alpha" });
+        const beta = ReconcileCursorStore.open({ rootDir: dir, journalSlug: "personal", layoutEpoch: 1, areaId: "root:beta" });
+        alpha.checkpointDiscovery({ routerVersion: 1, epoch: "one", areaId: "root:alpha", phase: "diff" });
+        expect(beta.read().cursor).toBeUndefined();
+    });
+    it("ignores stale checkpoints and completion records from an older epoch", () => {
+        const dir = root();
+        const current = open(dir);
+        const stale = open(dir);
+        current.checkpointDiscovery(cursor("diff"));
+        current.complete("epoch-1");
+        current.checkpointDiscovery({ ...cursor("diff"), epoch: "epoch-2" });
+        stale.checkpointDiscovery(cursor("remote-list", { remoteContinuation: "late" }));
+        stale.complete("epoch-1");
+        expect(open(dir).read()).toMatchObject({
+            cursor: { epoch: "epoch-2", phase: "diff" },
+        });
+        current.complete("epoch-2");
+        expect(open(dir).read()).toEqual({ format: 1, completedEpoch: "epoch-2" });
+    });
+});
+describe("takeBoundedReconcileSlice", () => {
+    it("yields by count, bytes, and wall-clock without materializing the inventory", () => {
+        function* inventory() {
+            for (let index = 0; index < 562_000; index += 1)
+                yield { path: `notes/${index}.md`, bytes: 1 };
+        }
+        const largeInventoryResult = takeBoundedReconcileSlice(inventory(), { maxEntries: 512 });
+        expect(largeInventoryResult.entries).toHaveLength(512);
+        expect(largeInventoryResult).toMatchObject({ bytes: 512, yielded: true });
+        expect(takeBoundedReconcileSlice([{ path: "one", bytes: 8 }, { path: "two", bytes: 8 }], { maxBytes: 10 })).toMatchObject({ entries: [{ path: "one", bytes: 8 }], bytes: 8, yielded: true });
+        let time = 0;
+        const result = takeBoundedReconcileSlice([{ path: "one", bytes: 1 }, { path: "two", bytes: 1 }], {
+            maxWallClockMs: 50,
+            now: () => (time += 50),
+        });
+        expect(result).toMatchObject({ entries: [{ path: "one", bytes: 1 }], yielded: true });
+    });
+    it("checks cancellation between every file and returns the completed prefix", () => {
+        let checks = 0;
+        const result = takeBoundedReconcileSlice([
+            { path: "notes/one", bytes: 1 },
+            { path: "notes/two", bytes: 1 },
+        ], { isCancelled: () => ++checks === 2 });
+        expect(result).toEqual({
+            entries: [{ path: "notes/one", bytes: 1 }],
+            bytes: 1,
+            yielded: true,
+            cancelled: true,
+            deferred: { path: "notes/two", bytes: 1 },
+        });
+    });
+    it("retains a generator remainder after yielding a bounded slice", () => {
+        function* inventory() {
+            yield { path: "notes/one", bytes: 1 };
+            yield { path: "notes/two", bytes: 1 };
+            yield { path: "notes/three", bytes: 1 };
+        }
+        const source = inventory();
+        const first = takeBoundedReconcileSlice(source, { maxEntries: 1 });
+        expect(first.deferred).toEqual({ path: "notes/two", bytes: 1 });
+        function* resumed() {
+            yield first.deferred;
+            yield* source;
+        }
+        expect(takeBoundedReconcileSlice(resumed(), { maxEntries: 10 }).entries).toEqual([
+            { path: "notes/two", bytes: 1 },
+            { path: "notes/three", bytes: 1 },
+        ]);
+    });
+});
+//# sourceMappingURL=reconcile-cursor.test.js.map

package/dist/sync/reconcile-cursor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-cursor.test.js","sourceRoot":"","sources":["../../src/sync/reconcile-cursor.test.ts"],"names":[],"mappings":"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"}

package/dist/sync/state-store.d.ts

@@ -80,6 +80,30 @@ export interface StateStoreRecoveryStats {
     /** Largest single snapshot payload or WAL frame buffered during recovery. */
     maxReadBytes: number;
 }
+/** A stable identity for one complete snapshot/WAL generation. */
+export interface StateStoreGenerationIdentity {
+    generation: number;
+    lastRecordSequence: number;
+    walBytes: number;
+}
+/**
+ * A durable lease on an immutable source generation.
+ *
+ * Rotation normally keeps only a short rollback history.  Migration uses this
+ * lease to make an older source generation part of that history until the
+ * copy/catch-up transaction has finished (or has explicitly been abandoned).
+ */
+export interface StateStoreGenerationPin {
+    readonly identity: StateStoreGenerationIdentity;
+    /** Durable pin file, persisted by long-running migration control state. */
+    readonly path: string;
+    release(): void;
+}
+/** One bounded value yielded from a keyed state projection. */
+export interface StateStoreStateEntry {
+    key: string;
+    value: unknown;
+}
 export interface StateStoreRepairResult {
     recoveredGeneration: number;
     recoveredWalBytes: number;
@@ -153,6 +177,19 @@ export declare class StateStore<T> {
     getGeneration(): number;
     getLastRecordSequence(): number;
     getRecoveryStats(): StateStoreRecoveryStats;
+    getGenerationIdentity(): StateStoreGenerationIdentity;
+    /**
+     * Persist a generation pin while holding append.lock.  The pin is a tiny
+     * checksummed file in the store directory, so a concurrent compactor sees it
+     * before deciding which immutable generations may be pruned.
+     */
+    pinCurrentGeneration(): StateStoreGenerationPin;
+    /**
+     * Iterate a keyed projection without exposing its mutable backing object.
+     * Each yielded row is cloned independently, allowing migration clients to
+     * keep projected WAL records bounded even when the source journal is huge.
+     */
+    iterateStateEntries(path: readonly string[]): IterableIterator<StateStoreStateEntry>;
     append(type: number, payload: unknown, flags?: number): StateStoreAppendResult;
     /**
      * Async lock acquisition for callback-originated work. The write itself

package/dist/sync/state-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/sync/state-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/sync/state-store.ts"],"names":[],"mappings":"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"}

package/dist/sync/state-store.js

@@ -434,6 +434,70 @@ export class StateStore {
     getRecoveryStats() {
         return { walBytes: this.walBytes, maxReadBytes: this.maxRecoveryReadBytes };
     }
+    getGenerationIdentity() {
+        return {
+            generation: this.generation,
+            lastRecordSequence: this.lastRecordSequence,
+            walBytes: this.walBytes,
+        };
+    }
+    /**
+     * Persist a generation pin while holding append.lock.  The pin is a tiny
+     * checksummed file in the store directory, so a concurrent compactor sees it
+     * before deciding which immutable generations may be pruned.
+     */
+    pinCurrentGeneration() {
+        while (true) {
+            const pin = withScopeLock(this.stateDir, () => {
+                const refresh = this.refreshFromDisk();
+                if (!refresh)
+                    return undefined;
+                const identity = this.getGenerationIdentity();
+                const pinPath = writeGenerationPin(this.stateDir, this.scopeDigest, identity);
+                let released = false;
+                return {
+                    identity,
+                    path: pinPath,
+                    release: () => {
+                        if (released)
+                            return;
+                        released = true;
+                        try {
+                            fs.unlinkSync(pinPath);
+                            fsyncDirectory(this.stateDir);
+                        }
+                        catch (error) {
+                            if (!isMissing(error))
+                                throw new Error(`state-store: cannot release generation pin ${pinPath}`, { cause: error });
+                        }
+                    },
+                };
+            });
+            if (pin)
+                return pin;
+            this.recoverNewestGenerationOutsideLock();
+        }
+    }
+    /**
+     * Iterate a keyed projection without exposing its mutable backing object.
+     * Each yielded row is cloned independently, allowing migration clients to
+     * keep projected WAL records bounded even when the source journal is huge.
+     */
+    *iterateStateEntries(path) {
+        let current = this.state;
+        for (const segment of path) {
+            if (typeof current !== "object" || current === null || Array.isArray(current) || !Object.hasOwn(current, segment)) {
+                throw new Error(`state-store: state path ${JSON.stringify(path)} is not an object map`);
+            }
+            current = current[segment];
+        }
+        if (typeof current !== "object" || current === null || Array.isArray(current)) {
+            throw new Error(`state-store: state path ${JSON.stringify(path)} is not an object map`);
+        }
+        for (const [key, value] of Object.entries(current)) {
+            yield { key, value: structuredClone(value) };
+        }
+    }
     append(type, payload, flags = 0) {
         assertUint16(type, "record type");
         assertUint16(flags, "record flags");
@@ -2172,7 +2236,7 @@ function retainedGenerationHistoryNeedsRepair(dir, newestGeneration, currentGene
     return false;
 }
 function pruneGenerations(dir, retain) {
-    const retained = new Set(retain);
+    const retained = new Set([...retain, ...pinnedGenerations(dir)]);
     for (const name of fs.readdirSync(dir)) {
         const match = /^(?:snapshot|wal)-(\d+)\.bin$/.exec(name);
         if (!match)
@@ -2189,6 +2253,50 @@ function pruneGenerations(dir, retain) {
     }
     fsyncDirectory(dir);
 }
+function writeGenerationPin(dir, scopeDigest, identity) {
+    const body = {
+        generation: identity.generation,
+        lastRecordSequence: identity.lastRecordSequence,
+        walBytes: identity.walBytes,
+        scopeDigest: scopeDigest.toString("hex"),
+    };
+    const checksum = sha256(Buffer.from(canonicalJson(body), "utf8")).toString("hex");
+    const pinPath = path.join(dir, `generation-pin-${process.pid}-${crypto.randomBytes(8).toString("hex")}.json`);
+    writeNewDurably(pinPath, Buffer.from(`${canonicalJson({ ...body, checksum })}\n`, "utf8"));
+    fsyncDirectory(dir);
+    return pinPath;
+}
+/** Invalid pins are retained conservatively: pruning is never allowed to win a crash race. */
+function pinnedGenerations(dir) {
+    const pins = new Set();
+    for (const name of fs.readdirSync(dir)) {
+        if (!/^generation-pin-[A-Za-z0-9-]+\.json$/.test(name))
+            continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+            const { checksum, ...body } = raw;
+            if (typeof checksum !== "string" ||
+                checksum !== sha256(Buffer.from(canonicalJson(body), "utf8")).toString("hex") ||
+                !Number.isSafeInteger(body.generation) ||
+                body.generation < 1) {
+                // A torn pin represents an in-flight migration; retain every local
+                // generation rather than guessing which source it meant to protect.
+                return fs.readdirSync(dir)
+                    .map((candidate) => /^(?:snapshot|wal)-(\d+)\.bin$/.exec(candidate)?.[1])
+                    .filter((value) => value !== undefined)
+                    .map(Number);
+            }
+            pins.add(body.generation);
+        }
+        catch {
+            return fs.readdirSync(dir)
+                .map((candidate) => /^(?:snapshot|wal)-(\d+)\.bin$/.exec(candidate)?.[1])
+                .filter((value) => value !== undefined)
+                .map(Number);
+        }
+    }
+    return [...pins];
+}
 function cleanupUnpublishedInitialGeneration(dir) {
     if (fs.existsSync(path.join(dir, "current")))
         return;