@indigoai-us/hq-cloud 6.15.78 → 6.15.80

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

@@ -20,6 +20,8 @@ export declare function setStateStorePositionalWriteForTest(write: ((fd: number,
 export declare function setStateStoreRotationClaimWriteHookForTest(hook: (() => void) | undefined): void;
 /** Test-only seam for proving same-process async lock waiters queue cooperatively. */
 export declare function setStateStoreScopeLockAcquiredHookForTest(hook: (() => void | Promise<void>) | undefined): void;
+/** Test-only seam for a failure after a batch lock file has been created. */
+export declare function setStateStoreScopeLockWriteHookForTest(hook: (() => void) | undefined): void;
 /** Test-only seam for exercising async lock deadlines without a minute-long wait. */
 export declare function setStateStoreAsyncLockTimeoutForTest(timeoutMs: number | undefined): void;
 /** Test-only seam for exercising synchronous lock contention without a five-second wait. */
@@ -55,12 +57,53 @@ export interface StateStoreRefreshResult {
 export interface StateStoreAppendResult extends StateStoreRecord {
     refresh: StateStoreRefreshResult;
 }
+/**
+ * One durable append participating in a short, ordered multi-scope commit.
+ *
+ * This is deliberately an internal-storage primitive rather than a general
+ * transaction manager: callers still own their recovery protocol.  It gives
+ * them one important invariant that a sequence of `append()` calls cannot:
+ * every live lock is acquired in a stable order and a contender releases all
+ * acquired locks before waiting to retry.
+ */
+export interface StateStoreBatchAppend<T> {
+    /** Stable caller-owned order key. `@meta` is always acquired last. */
+    areaId: string;
+    store: StateStore<T>;
+    type: number;
+    payload: unknown;
+    flags?: number;
+}
 export interface StateStoreRecoveryStats {
     /** Bytes in the selected generation's WAL, including its header. */
     walBytes: number;
     /** 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;
@@ -112,6 +155,17 @@ export declare class StateStore<T> {
     static open<T>(options: StateStoreOptions<T>): StateStore<T>;
     /** Yielding first-open variant for callback-originated projections. */
     static openAsync<T>(options: StateStoreOptions<T>): Promise<StateStore<T>>;
+    /**
+     * Append one record to each independent store under lexical, all-or-none
+     * locks.  The caller's `areaId` is the stable order key; hashed on-disk
+     * directories must never decide lock order.  `@meta` intentionally follows
+     * all data areas so a watermark can only publish after its data is durable.
+     *
+     * A process death between records is still possible, by design.  Consumers
+     * that need cross-area atomic visibility must use a data-first recovery
+     * protocol (AreaLedger does this with prepare records and a meta watermark).
+     */
+    static appendBatch<T>(entries: readonly StateStoreBatchAppend<T>[]): StateStoreAppendResult[];
     /**
      * Repair an over-budget generation without making appenders wait for snapshot
      * I/O.  Recovery captures a stable generation while holding the scope lock,
@@ -123,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
@@ -147,6 +214,15 @@ export declare class StateStore<T> {
      * and retain the prior compact copy.
      */
     replaceState(nextState: T): void;
+    /**
+     * Atomically derive a compact replacement from the newest durable state.
+     *
+     * Callers that fold a projection must not calculate their replacement before
+     * taking the append lock: another writer could otherwise be lost between the
+     * read and publication.  The transform runs under that lock and publication
+     * still validates the source generation after the off-lock snapshot stage.
+     */
+    replaceStateWith(transform: (state: T) => T): void;
     private replaceStateAttempt;
     /** Create G+1 without ever merging two generations during recovery. */
     compact(): void;

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":"AAmEA,wBAAgB,2CAA2C,IAAI,IAAI,CAElE;AAED,wBAAgB,yCAAyC,IAAI,MAAM,CAElE;AAED,wBAAgB,kDAAkD,IAAI,IAAI,CAEzE;AAED,wBAAgB,gDAAgD,IAAI,MAAM,CAEzE;AAED,wBAAgB,yCAAyC,IAAI,IAAI,CAEhE;AAED,wBAAgB,uCAAuC,IAAI,MAAM,CAEhE;AAED,6EAA6E;AAC7E,wBAAgB,qCAAqC,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAE1F;AAED,kFAAkF;AAClF,wBAAgB,oCAAoC,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAEzF;AAED,2EAA2E;AAC3E,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAEpF;AAED,oFAAoF;AACpF,wBAAgB,4CAA4C,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAEjG;AAED,0EAA0E;AAC1E,wBAAgB,mCAAmC,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAExF;AAED,2DAA2D;AAC3D,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,GAC3G,IAAI,CAEN;AAED,4DAA4D;AAC5D,wBAAgB,0CAA0C,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAE/F;AAED,sFAAsF;AACtF,wBAAgB,yCAAyC,CACvD,IAAI,EAAE,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,GAC7C,IAAI,CAEN;AAED,qFAAqF;AACrF,wBAAgB,oCAAoC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAExF;AAED,4FAA4F;AAC5F,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEvF;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,CAAC;CACZ;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,CAAC,CAAC;IAChB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,gBAAgB,KAAK,CAAC,CAAC;IAClD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACpD,4DAA4D;IAC5D,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,gFAAgF;IAChF,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,OAAO,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,2BAA2B,GACnC;IAAE,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;CAAE,GACpC,CAAC;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GAAG,sBAAsB,CAAC,CAAC;AAEtD,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;CAC1D;AAiCD,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,MAAM,MAAM,yBAAyB,GAAG,yBAAyB,CAAC;AAElE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;gBAEhC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG;QAAE,MAAM,CAAC,EAAE,yBAAyB,CAAA;KAAE;CAK7F;AAYD,+DAA+D;AAC/D,qBAAa,UAAU,CAAC,CAAC;IAarB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZ1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,iCAAiC,CAAS;IAElD,OAAO;IAiBP,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAUxD,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IA+B5D,uEAAuE;WAC1D,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IA+BhF;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,CAAC,EACrB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAC7B,WAAW,GAAE,4BAAiC,GAC7C,2BAA2B;IAqG9B,QAAQ,IAAI,CAAC;IAIb,aAAa,IAAI,MAAM;IAIvB,qBAAqB,IAAI,MAAM;IAI/B,gBAAgB,IAAI,uBAAuB;IAI3C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,sBAAsB;IA4BzE;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA4B7F,iEAAiE;IAC3D,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,OAAO,EAC3B,KAAK,SAAI,GACR,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IA6B9C,sEAAsE;IACtE,OAAO,IAAI,uBAAuB;IAUlC,6DAA6D;IACvD,YAAY,IAAI,OAAO,CAAC,uBAAuB,CAAC;IAUtD,OAAO,CAAC,cAAc;IAiCtB;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAAE,CAAC,GAAG,IAAI;IAShC,OAAO,CAAC,mBAAmB;IA+D3B,uEAAuE;IACvE,OAAO,IAAI,IAAI;IAmBf,OAAO,CAAC,eAAe;IA+BvB,OAAO,CAAC,kCAAkC;YAU5B,uCAAuC;IAUrD,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,cAAc;IAqBtB,gFAAgF;IAChF,OAAO,CAAC,qBAAqB;IAsB7B,OAAO,CAAC,iBAAiB;CAS1B"}
+{"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

@@ -60,6 +60,7 @@ let reflinkCopyHookForTest;
 let positionalWriteForTest;
 let rotationClaimWriteHookForTest;
 let scopeLockAcquiredHookForTest;
+let scopeLockWriteHookForTest;
 let asyncLockTimeoutMsForTest;
 let syncLockTimeoutMsForTest;
 export function resetStateStoreSnapshotRecoveryCountForTest() {
@@ -112,6 +113,10 @@ export function setStateStoreRotationClaimWriteHookForTest(hook) {
 export function setStateStoreScopeLockAcquiredHookForTest(hook) {
     scopeLockAcquiredHookForTest = hook;
 }
+/** Test-only seam for a failure after a batch lock file has been created. */
+export function setStateStoreScopeLockWriteHookForTest(hook) {
+    scopeLockWriteHookForTest = hook;
+}
 /** Test-only seam for exercising async lock deadlines without a minute-long wait. */
 export function setStateStoreAsyncLockTimeoutForTest(timeoutMs) {
     asyncLockTimeoutMsForTest = timeoutMs;
@@ -245,6 +250,80 @@ export class StateStore {
                 return created;
         }
     }
+    /**
+     * Append one record to each independent store under lexical, all-or-none
+     * locks.  The caller's `areaId` is the stable order key; hashed on-disk
+     * directories must never decide lock order.  `@meta` intentionally follows
+     * all data areas so a watermark can only publish after its data is durable.
+     *
+     * A process death between records is still possible, by design.  Consumers
+     * that need cross-area atomic visibility must use a data-first recovery
+     * protocol (AreaLedger does this with prepare records and a meta watermark).
+     */
+    static appendBatch(entries) {
+        if (entries.length === 0)
+            return [];
+        const seenAreas = new Set();
+        const seenStores = new Set();
+        const ordered = entries.map((entry, index) => {
+            if (!entry.areaId)
+                throw new Error("state-store: batch areaId is required");
+            if (seenAreas.has(entry.areaId))
+                throw new Error(`state-store: duplicate batch area ${entry.areaId}`);
+            if (seenStores.has(entry.store.stateDir))
+                throw new Error(`state-store: duplicate batch state directory ${entry.store.stateDir}`);
+            seenAreas.add(entry.areaId);
+            seenStores.add(entry.store.stateDir);
+            assertUint16(entry.type, "record type");
+            assertUint16(entry.flags ?? 0, "record flags");
+            return { ...entry, index };
+        }).sort((left, right) => {
+            if (left.areaId === "@meta")
+                return right.areaId === "@meta" ? 0 : 1;
+            if (right.areaId === "@meta")
+                return -1;
+            return left.areaId.localeCompare(right.areaId);
+        });
+        let recovered = false;
+        while (true) {
+            const result = withScopeLocks(ordered.map((entry) => entry.store.stateDir), () => {
+                // Refresh every participant before appending any record.  If a
+                // generation changed, release the full set and recover off-lock; a
+                // partial batch must never retry and duplicate an earlier append.
+                const refreshes = new Map();
+                for (const entry of ordered) {
+                    const refresh = entry.store.refreshFromDisk();
+                    if (!refresh)
+                        return undefined;
+                    refreshes.set(entry, refresh);
+                }
+                const appended = [];
+                for (const entry of ordered) {
+                    appended.push({
+                        entry,
+                        result: entry.store.appendUnlocked(entry.type, entry.payload, entry.flags ?? 0, recovered ? { records: [], recovered: true } : refreshes.get(entry)),
+                    });
+                }
+                return appended;
+            });
+            if (!result) {
+                for (const entry of ordered)
+                    entry.store.recoverNewestGenerationOutsideLock();
+                recovered = true;
+                continue;
+            }
+            const compact = new Set();
+            for (const { entry } of result)
+                if (entry.store.needsCompaction())
+                    compact.add(entry.store);
+            for (const store of compact)
+                store.compact();
+            const byIndex = [];
+            for (const appended of result)
+                byIndex[appended.entry.index] = appended.result;
+            return byIndex;
+        }
+    }
     /**
      * Repair an over-budget generation without making appenders wait for snapshot
      * I/O.  Recovery captures a stable generation while holding the scope lock,
@@ -355,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");
@@ -494,16 +637,28 @@ export class StateStore {
      * and retain the prior compact copy.
      */
     replaceState(nextState) {
+        this.replaceStateWith(() => nextState);
+    }
+    /**
+     * Atomically derive a compact replacement from the newest durable state.
+     *
+     * Callers that fold a projection must not calculate their replacement before
+     * taking the append lock: another writer could otherwise be lost between the
+     * read and publication.  The transform runs under that lock and publication
+     * still validates the source generation after the off-lock snapshot stage.
+     */
+    replaceStateWith(transform) {
         for (let attempt = 0; attempt < REPLACE_STATE_MAX_ATTEMPTS; attempt++) {
-            if (this.replaceStateAttempt(nextState))
+            if (this.replaceStateAttempt(transform))
                 return;
         }
         throw new StateStoreLockError(`cannot replace state after ${REPLACE_STATE_MAX_ATTEMPTS} concurrent writes`);
     }
-    replaceStateAttempt(nextState) {
+    replaceStateAttempt(transform) {
         const plan = withScopeLock(this.stateDir, () => {
             if (!this.refreshFromDisk())
                 return undefined;
+            const nextState = transform(this.state);
             const previousGeneration = this.generation;
             const previousWalHasRecords = this.walBytes > WAL_HEADER_BYTES;
             const first = {
@@ -1542,6 +1697,121 @@ function withScopeLock(dir, action) {
         throw actionError;
     return result;
 }
+/**
+ * Acquire every scope lock in caller-provided stable order, or acquire none.
+ *
+ * Waiting while holding an earlier lock would create the classic A→B/B→A
+ * deadlock across independent StateStores.  This optimistic loop instead
+ * drops the partial set and retries after the ordinary bounded backoff.  It is
+ * only for tiny durable publication sections; staging, recovery, callbacks,
+ * and network work remain outside these locks.
+ */
+function withScopeLocks(dirs, action) {
+    const deadline = Date.now() + (syncLockTimeoutMsForTest ?? SYNC_LOCK_TIMEOUT_MS);
+    const acquired = [];
+    while (true) {
+        let unavailable = false;
+        try {
+            for (const dir of dirs) {
+                const held = tryAcquireScopeLock(dir);
+                if (!held) {
+                    unavailable = true;
+                    break;
+                }
+                acquired.push(held);
+            }
+            if (!unavailable)
+                break;
+        }
+        catch (error) {
+            releaseScopeLocks(acquired);
+            throw error;
+        }
+        releaseScopeLocks(acquired);
+        if (Date.now() >= deadline) {
+            throw new StateStoreLockError("timed out acquiring ordered scope locks");
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+    }
+    let result;
+    let actionError;
+    try {
+        result = action();
+    }
+    catch (error) {
+        actionError = error;
+    }
+    releaseScopeLocks(acquired);
+    if (actionError !== undefined)
+        throw actionError;
+    return result;
+}
+function tryAcquireScopeLock(dir) {
+    const lockPath = path.join(dir, "append.lock");
+    if (inProcessAsyncScopeLocks.has(path.resolve(dir))) {
+        throw new StateStoreLockError(`in-process async holder for ${lockPath}`, {
+            reason: "in-process-async-holder",
+        });
+    }
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, "wx");
+        scopeLockWriteHookForTest?.();
+        fs.writeFileSync(fd, String(process.pid));
+        fs.fdatasyncSync(fd);
+        return { lockPath, fd };
+    }
+    catch (error) {
+        // `openSync(..., "wx")` has already made this process the lock owner.
+        // A failed PID write or sync must not leave that live-PID lock behind,
+        // because no stale breaker will remove it while this process remains up.
+        if (fd !== undefined) {
+            let cleanupError;
+            try {
+                fs.closeSync(fd);
+            }
+            catch (closeError) {
+                cleanupError = closeError;
+            }
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch (unlinkError) {
+                if (!isMissing(unlinkError))
+                    cleanupError ??= unlinkError;
+            }
+            if (cleanupError !== undefined)
+                throw new StateStoreLockError(`cannot clean up ${lockPath}`, { cause: cleanupError });
+        }
+        if (!isAlreadyExists(error)) {
+            throw new StateStoreLockError(`cannot acquire ${lockPath}`, { cause: error });
+        }
+        if (removeDeadLock(lockPath))
+            return tryAcquireScopeLock(dir);
+        return undefined;
+    }
+}
+function releaseScopeLocks(acquired) {
+    let releaseError;
+    while (acquired.length > 0) {
+        const held = acquired.pop();
+        try {
+            fs.closeSync(held.fd);
+        }
+        catch (error) {
+            releaseError ??= error;
+        }
+        try {
+            fs.unlinkSync(held.lockPath);
+        }
+        catch (error) {
+            releaseError ??= error;
+        }
+    }
+    if (releaseError !== undefined) {
+        throw new StateStoreLockError("cannot release ordered scope locks", { cause: releaseError });
+    }
+}
 /**
  * A best-effort, non-blocking claim for off-lock snapshot materialisation.
  * Appenders deliberately ignore it; it only prevents several stale handles
@@ -1966,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)
@@ -1983,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;