sliftutils 1.6.0 → 1.6.2

package/index.d.ts

@@ -797,9 +797,9 @@ declare module "sliftutils/render-utils/observer" {
 }
 
 declare module "sliftutils/storage/BulkDatabase2/BulkDatabase2" {
-    import { BulkDatabaseBase, ReactiveDeps, BulkDatabase2Config, BulkFileInfoListing } from "./BulkDatabaseBase";
+    import { BulkDatabaseBase, ReactiveDeps, BulkDatabase2Config, BulkFileInfoListing, MergeAttemptResult } from "./BulkDatabaseBase";
     export { BulkDatabaseBase, noopReactiveDeps, bulkDatabase2Timing } from "./BulkDatabaseBase";
-    export type { ReactiveDeps, StorageFactory, BulkDatabase2Config, BulkFileDetails, BulkFileEntry, BulkFileInfoListing } from "./BulkDatabaseBase";
+    export type { ReactiveDeps, StorageFactory, BulkDatabase2Config, BulkFileDetails, BulkFileEntry, BulkFileInfoListing, MergeAttemptResult, MergeSkipReason } from "./BulkDatabaseBase";
     /** Per-column on-disk size info, as reported by getColumnInfo/getReaderInfo. */
     export type BulkColumnInfo = {
         column: string;
@@ -915,8 +915,13 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabase2" {
          * size/fragmentation and deciding whether to call tryMergeNow()/compact().
          */
         getFileInfo(): Promise<BulkFileInfoListing>;
-        /** Consolidate on-disk files. Optional to call; the database also does this in the background. */
-        compact(): Promise<void>;
+        /**
+         * Consolidate on-disk files. Optional to call; the database also does this in the background.
+         * Returns whether anything was merged, or (via skipReason) why the pass never ran — another merge
+         * in flight, another tab/process holding the merge lock (with who holds it and when the lock
+         * expires), or nothing on disk to compact.
+         */
+        compact(): Promise<MergeAttemptResult>;
         /**
          * Whether this collection's storage is served over the network (a remote server) rather than local
          * disk. Apps can branch on this to adapt to the higher latency. Note: over the network the database
@@ -934,10 +939,11 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabase2" {
         /**
          * Run one merge pass now (the same policy the database runs on a timer): consolidate recent
          * fragmentation and dedup a key range if it's worth it. Returns whether it merged anything and
-         * whether it bailed because another tab/process holds the merge lock — so a scheduler can call this
-         * (e.g. every 30 minutes) and tell "nothing to do" from "someone else is already merging".
+         * whether it bailed because another tab/process holds the merge lock (including the lock's holder
+         * and expiry) — so a scheduler can call this (e.g. every 30 minutes) and tell "nothing to do" from
+         * "someone else is already merging".
          */
-        tryMergeNow(): Promise<void>;
+        tryMergeNow(): Promise<MergeAttemptResult>;
         /** Rewrite everything written in [timeLo, timeHi] into fresh key-sorted bulk file(s). Low-level;
          * most callers want compact() or tryMergeNow(). */
         merge(timeLo: number, timeHi: number): Promise<void>;
@@ -989,6 +995,13 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabaseBase" {
     export type BulkDatabase2Config = {
         maxTriggerThrottleMs?: number;
     };
+    export type MergeSkipReason = "mergeInFlight" | "tabLockHeld" | "fileLockHeld" | "nothingToMerge";
+    export type MergeAttemptResult = {
+        merged: boolean;
+        skipReason?: MergeSkipReason;
+        lockHolderId?: string;
+        lockExpiresInMs?: number;
+    };
     export declare class BulkDatabaseBase<T extends {
         key: string;
     }> {
@@ -1012,6 +1025,7 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabaseBase" {
         private currentStreamFileName;
         private currentStreamFileBytes;
         private mergeInFlight;
+        private lastMergeSkipLogMs;
         private streamRowsOnDisk;
         private streamBytesOnDisk;
         private fileSetPollTimer;
@@ -1062,8 +1076,11 @@ declare module "sliftutils/storage/BulkDatabase2/BulkDatabaseBase" {
         private processMarkers;
         private writeBulkFile;
         private maybeMerge;
-        tryMergeNow: () => Promise<void>;
-        compact(): Promise<void>;
+        private mergeSkip;
+        private runLockedMerge;
+        private tryMergeThrottled;
+        tryMergeNow(): Promise<MergeAttemptResult>;
+        compact(): Promise<MergeAttemptResult>;
         merge(timeLo: number, timeHi: number): Promise<void>;
         private readBulkHeader;
         private fileLogicalSize;
@@ -1563,8 +1580,14 @@ declare module "sliftutils/storage/BulkDatabase2/blockCache" {
 
 declare module "sliftutils/storage/BulkDatabase2/mergeLock" {
     import type { FileStorage } from "../FileFolderAPI";
+    export type MergeLockInfo = {
+        holderId: string;
+        expiresInMs: number;
+    };
     export declare function tryAcquireMergeLock(collection: string, holderId: string): boolean;
+    export declare function peekMergeLock(collection: string): MergeLockInfo | undefined;
     export declare function releaseMergeLock(collection: string, holderId: string): void;
+    export declare function peekMergeFileLock(storage: FileStorage): Promise<MergeLockInfo | undefined>;
     export declare function tryAcquireMergeFileLock(storage: FileStorage, holderId: string): Promise<boolean>;
     export declare function startMergeFileLockHeartbeat(storage: FileStorage, holderId: string): () => void;
     export declare function releaseMergeFileLock(storage: FileStorage, holderId: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sliftutils",
-    "version": "1.6.0",
+    "version": "1.6.2",
     "main": "index.js",
     "license": "MIT",
     "files": [
@@ -56,7 +56,7 @@
         "node-forge": "https://github.com/sliftist/forge#e618181b469b07bdc70b968b0391beb8ef5fecd6",
         "preact-old-types": "^10.28.1",
         "shell-quote": "^1.8.3",
-        "socket-function": "^1.1.42",
+        "socket-function": "^1.1.48",
         "typenode": "*",
         "typesafecss": "*",
         "ws": "^8.18.3",

package/storage/BulkDatabase2/BulkDatabase2.d.ts

@@ -1,6 +1,6 @@
-import { BulkDatabaseBase, ReactiveDeps, BulkDatabase2Config, BulkFileInfoListing } from "./BulkDatabaseBase";
+import { BulkDatabaseBase, ReactiveDeps, BulkDatabase2Config, BulkFileInfoListing, MergeAttemptResult } from "./BulkDatabaseBase";
 export { BulkDatabaseBase, noopReactiveDeps, bulkDatabase2Timing } from "./BulkDatabaseBase";
-export type { ReactiveDeps, StorageFactory, BulkDatabase2Config, BulkFileDetails, BulkFileEntry, BulkFileInfoListing } from "./BulkDatabaseBase";
+export type { ReactiveDeps, StorageFactory, BulkDatabase2Config, BulkFileDetails, BulkFileEntry, BulkFileInfoListing, MergeAttemptResult, MergeSkipReason } from "./BulkDatabaseBase";
 /** Per-column on-disk size info, as reported by getColumnInfo/getReaderInfo. */
 export type BulkColumnInfo = {
     column: string;
@@ -116,8 +116,13 @@ export interface IBulkDatabase2<T extends {
      * size/fragmentation and deciding whether to call tryMergeNow()/compact().
      */
     getFileInfo(): Promise<BulkFileInfoListing>;
-    /** Consolidate on-disk files. Optional to call; the database also does this in the background. */
-    compact(): Promise<void>;
+    /**
+     * Consolidate on-disk files. Optional to call; the database also does this in the background.
+     * Returns whether anything was merged, or (via skipReason) why the pass never ran — another merge
+     * in flight, another tab/process holding the merge lock (with who holds it and when the lock
+     * expires), or nothing on disk to compact.
+     */
+    compact(): Promise<MergeAttemptResult>;
     /**
      * Whether this collection's storage is served over the network (a remote server) rather than local
      * disk. Apps can branch on this to adapt to the higher latency. Note: over the network the database
@@ -135,10 +140,11 @@ export interface IBulkDatabase2<T extends {
     /**
      * Run one merge pass now (the same policy the database runs on a timer): consolidate recent
      * fragmentation and dedup a key range if it's worth it. Returns whether it merged anything and
-     * whether it bailed because another tab/process holds the merge lock — so a scheduler can call this
-     * (e.g. every 30 minutes) and tell "nothing to do" from "someone else is already merging".
+     * whether it bailed because another tab/process holds the merge lock (including the lock's holder
+     * and expiry) — so a scheduler can call this (e.g. every 30 minutes) and tell "nothing to do" from
+     * "someone else is already merging".
      */
-    tryMergeNow(): Promise<void>;
+    tryMergeNow(): Promise<MergeAttemptResult>;
     /** Rewrite everything written in [timeLo, timeHi] into fresh key-sorted bulk file(s). Low-level;
      * most callers want compact() or tryMergeNow(). */
     merge(timeLo: number, timeHi: number): Promise<void>;

package/storage/BulkDatabase2/BulkDatabase2.ts

@@ -1,9 +1,9 @@
 import { getFileStorageNested2 } from "../FileFolderAPI";
 import { observable, runInAction, onBecomeObserved, onBecomeUnobserved } from "../../render-utils/mobxTyped";
-import { BulkDatabaseBase, ReactiveDeps, BulkDatabase2Config, BulkFileInfoListing } from "./BulkDatabaseBase";
+import { BulkDatabaseBase, ReactiveDeps, BulkDatabase2Config, BulkFileInfoListing, MergeAttemptResult } from "./BulkDatabaseBase";
 
 export { BulkDatabaseBase, noopReactiveDeps, bulkDatabase2Timing } from "./BulkDatabaseBase";
-export type { ReactiveDeps, StorageFactory, BulkDatabase2Config, BulkFileDetails, BulkFileEntry, BulkFileInfoListing } from "./BulkDatabaseBase";
+export type { ReactiveDeps, StorageFactory, BulkDatabase2Config, BulkFileDetails, BulkFileEntry, BulkFileInfoListing, MergeAttemptResult, MergeSkipReason } from "./BulkDatabaseBase";
 
 /** Per-column on-disk size info, as reported by getColumnInfo/getReaderInfo. */
 export type BulkColumnInfo = { column: string; byteSize: number };
@@ -106,8 +106,13 @@ export interface IBulkDatabase2<T extends { key: string }> {
      */
     getFileInfo(): Promise<BulkFileInfoListing>;
 
-    /** Consolidate on-disk files. Optional to call; the database also does this in the background. */
-    compact(): Promise<void>;
+    /**
+     * Consolidate on-disk files. Optional to call; the database also does this in the background.
+     * Returns whether anything was merged, or (via skipReason) why the pass never ran — another merge
+     * in flight, another tab/process holding the merge lock (with who holds it and when the lock
+     * expires), or nothing on disk to compact.
+     */
+    compact(): Promise<MergeAttemptResult>;
 
     /**
      * Whether this collection's storage is served over the network (a remote server) rather than local
@@ -128,10 +133,11 @@ export interface IBulkDatabase2<T extends { key: string }> {
     /**
      * Run one merge pass now (the same policy the database runs on a timer): consolidate recent
      * fragmentation and dedup a key range if it's worth it. Returns whether it merged anything and
-     * whether it bailed because another tab/process holds the merge lock — so a scheduler can call this
-     * (e.g. every 30 minutes) and tell "nothing to do" from "someone else is already merging".
+     * whether it bailed because another tab/process holds the merge lock (including the lock's holder
+     * and expiry) — so a scheduler can call this (e.g. every 30 minutes) and tell "nothing to do" from
+     * "someone else is already merging".
      */
-    tryMergeNow(): Promise<void>;
+    tryMergeNow(): Promise<MergeAttemptResult>;
 
     /** Rewrite everything written in [timeLo, timeHi] into fresh key-sorted bulk file(s). Low-level;
      * most callers want compact() or tryMergeNow(). */

package/storage/BulkDatabase2/BulkDatabaseBase.d.ts

@@ -27,6 +27,13 @@ export type StorageFactory = (path: string) => Promise<FileStorage>;
 export type BulkDatabase2Config = {
     maxTriggerThrottleMs?: number;
 };
+export type MergeSkipReason = "mergeInFlight" | "tabLockHeld" | "fileLockHeld" | "nothingToMerge";
+export type MergeAttemptResult = {
+    merged: boolean;
+    skipReason?: MergeSkipReason;
+    lockHolderId?: string;
+    lockExpiresInMs?: number;
+};
 export declare class BulkDatabaseBase<T extends {
     key: string;
 }> {
@@ -50,6 +57,7 @@ export declare class BulkDatabaseBase<T extends {
     private currentStreamFileName;
     private currentStreamFileBytes;
     private mergeInFlight;
+    private lastMergeSkipLogMs;
     private streamRowsOnDisk;
     private streamBytesOnDisk;
     private fileSetPollTimer;
@@ -100,8 +108,11 @@ export declare class BulkDatabaseBase<T extends {
     private processMarkers;
     private writeBulkFile;
     private maybeMerge;
-    tryMergeNow: () => Promise<void>;
-    compact(): Promise<void>;
+    private mergeSkip;
+    private runLockedMerge;
+    private tryMergeThrottled;
+    tryMergeNow(): Promise<MergeAttemptResult>;
+    compact(): Promise<MergeAttemptResult>;
     merge(timeLo: number, timeHi: number): Promise<void>;
     private readBulkHeader;
     private fileLogicalSize;

package/storage/BulkDatabase2/BulkDatabaseBase.ts

@@ -18,7 +18,7 @@ import { blue, magenta } from "socket-function/src/formatting/logColors";
 import { STREAM_EXTENSION, frameDeletes, frameRows, streamReaderFromEntries } from "./streamLog";
 import { broadcast as syncBroadcast, broadcastSeal as syncBroadcastSeal, connect as syncConnect, isSyncSupported, RemoteWrite } from "./syncClient";
 import { DELETED } from "./WriteOverlay";
-import { releaseMergeFileLock, releaseMergeLock, startMergeFileLockHeartbeat, tryAcquireMergeFileLock, tryAcquireMergeLock } from "./mergeLock";
+import { MergeLockInfo, peekMergeFileLock, peekMergeLock, releaseMergeFileLock, releaseMergeLock, startMergeFileLockHeartbeat, tryAcquireMergeFileLock, tryAcquireMergeLock } from "./mergeLock";
 import { markerExclusions, processDeleteMarkers, readDeleteMarkers, writeDeleteMarker } from "./mergeMarkers";
 import {
     BulkFileInfo,
@@ -49,6 +49,9 @@ const DUP_THRESHOLD = 0.4;
 const DEDUP_TRIGGER_BYTES = 512 * 1024 * 1024;
 const DEDUP_TRIGGER_FRACTION = 0.5;
 const WRITE_FLUSH_FIRST_STEP_MS = 250;
+// Skip logs are throttled per collection: the background write path retries merges about once a second,
+// so an unthrottled log would repeat for the whole duration of another tab's merge.
+const MERGE_SKIP_LOG_INTERVAL_MS = 30 * 1000;
 
 export const bulkDatabase2Timing = {
     streamSealAgeMs: 10 * 60 * 60 * 1000,
@@ -67,7 +70,7 @@ export const bulkDatabase2Timing = {
     // the whole stream file per write.
     writeFlushMaxDelayMs: isNode() ? 0 : 15 * 1000,
     fileSetPollIntervalMs: 30 * 60 * 1000,
-    memoryFlushHeapBytes: 1500 * 1024 * 1024,
+    memoryFlushHeapBytes: 5 * 1024 * 1024 * 1024,
     memoryFlushMinCollectionBytes: 100 * 1024 * 1024,
     memoryFlushThrottleMs: 15 * 60 * 1000,
 };
@@ -104,6 +107,26 @@ export type BulkDatabase2Config = {
     maxTriggerThrottleMs?: number;
 };
 
+export type MergeSkipReason =
+    // This instance is already mid-merge.
+    | "mergeInFlight"
+    // Another same-origin tab holds the localStorage merge lock.
+    | "tabLockHeld"
+    // Another process holds the cross-process .merge-lock file (or won the settle race for it).
+    | "fileLockHeld"
+    // compact() only: the collection has no files on disk.
+    | "nothingToMerge";
+
+// What a compact()/tryMergeNow() call did. skipReason is set when the pass never ran; for the lock
+// reasons, lockHolderId/lockExpiresInMs report who holds the lock and how long until it goes stale
+// (so a scheduler knows when retrying could succeed).
+export type MergeAttemptResult = {
+    merged: boolean;
+    skipReason?: MergeSkipReason;
+    lockHolderId?: string;
+    lockExpiresInMs?: number;
+};
+
 let networkCompactionEnabled = false;
 
 let fileNameCounter = 0;
@@ -237,6 +260,7 @@ export class BulkDatabaseBase<T extends { key: string }> {
     // tryMergeNow calls) return immediately instead of queueing. Keeps the visibility-timer firings
     // from stacking behind a long merge.
     private mergeInFlight = false;
+    private lastMergeSkipLogMs = 0;
     // Running counters of stream-tier rows + bytes on disk. Seeded from each LoadedIndex build, then
     // incremented per flush so the fold-trigger checks current data without an extra directory listing.
     private streamRowsOnDisk = 0;
@@ -614,58 +638,77 @@ export class BulkDatabaseBase<T extends { key: string }> {
         if (!await this.automaticCompactionAllowed()) return;
         if (opts.onlyIfStreamHeavy && !this.streamNeedsFold()) return;
         try {
-            await this.tryMergeNow();
+            await this.tryMergeThrottled();
         } catch (e) {
             console.warn(`${this.name}: background merge failed: ${(e as Error).message}`);
         }
     }
 
-    // Returns immediately with { lockFailed: true } if another call is already in flight (same
-    // instance), if the localStorage lock is held by another tab, or if the cross-process file lock
-    // says another process owns it. Otherwise: acquires both locks, runs testMerge, releases.
-    public tryMergeNow = throttleFunction(1000, async () => {
-        if (this.mergeInFlight) return;
-        if (!tryAcquireMergeLock(this.name, writerId)) return;
+    // Build the "we didn't merge" result and log it (throttled — see MERGE_SKIP_LOG_INTERVAL_MS). For
+    // lock reasons the log and result include the holder and time until the lock goes stale.
+    private async mergeSkip(reason: MergeSkipReason): Promise<MergeAttemptResult> {
+        let lock: MergeLockInfo | undefined;
+        if (reason === "tabLockHeld") {
+            lock = peekMergeLock(this.name);
+        } else if (reason === "fileLockHeld") {
+            lock = await peekMergeFileLock(await this.storage());
+        }
+        if (Date.now() - this.lastMergeSkipLogMs >= MERGE_SKIP_LOG_INTERVAL_MS) {
+            this.lastMergeSkipLogMs = Date.now();
+            const detail = lock && ` (held by ${lock.holderId}, expires in ${formatTime(Math.max(0, lock.expiresInMs))})` || "";
+            console.log(`${blue(this.name)} ${magenta("merge")} skipped: ${reason}${detail}`);
+        }
+        return { merged: false, skipReason: reason, lockHolderId: lock?.holderId, lockExpiresInMs: lock?.expiresInMs };
+    }
+
+    // Acquire both merge locks (same-tab mergeInFlight, cross-tab localStorage, cross-process file),
+    // run the pass, release. Skips (with the reason) instead of waiting when any of them is held.
+    private async runLockedMerge(run: () => Promise<MergeAttemptResult>): Promise<MergeAttemptResult> {
+        if (this.mergeInFlight) return await this.mergeSkip("mergeInFlight");
+        if (!tryAcquireMergeLock(this.name, writerId)) return await this.mergeSkip("tabLockHeld");
         const storage = await this.storage();
         const haveFileLock = await tryAcquireMergeFileLock(storage, writerId);
         if (!haveFileLock) {
             releaseMergeLock(this.name, writerId);
-            return;
+            return await this.mergeSkip("fileLockHeld");
         }
         this.mergeInFlight = true;
         const stopHeartbeat = startMergeFileLockHeartbeat(storage, writerId);
         try {
-            await this.testMergeINTERNAL_DO_NOT_CALL();
+            return await run();
         } finally {
             stopHeartbeat();
             await releaseMergeFileLock(storage, writerId);
             releaseMergeLock(this.name, writerId);
             this.mergeInFlight = false;
         }
+    }
+
+    // The background path (maybeMerge) goes through this so write bursts coalesce; explicit callers use
+    // tryMergeNow directly and get the per-call result.
+    private tryMergeThrottled = throttleFunction(1000, async () => {
+        await this.tryMergeNow();
     });
 
-    public async compact(): Promise<void> {
-        if (this.mergeInFlight) return;
-        if (!tryAcquireMergeLock(this.name, writerId)) return;
-        const storage = await this.storage();
-        const haveFileLock = await tryAcquireMergeFileLock(storage, writerId);
-        if (!haveFileLock) { releaseMergeLock(this.name, writerId); return; }
-        this.mergeInFlight = true;
-        const stopHeartbeat = startMergeFileLockHeartbeat(storage, writerId);
-        try {
+    public async tryMergeNow(): Promise<MergeAttemptResult> {
+        return await this.runLockedMerge(async () => {
+            const merged = await this.testMergeINTERNAL_DO_NOT_CALL();
+            return { merged };
+        });
+    }
+
+    public async compact(): Promise<MergeAttemptResult> {
+        return await this.runLockedMerge(async () => {
             await this.flushPending();
             syncBroadcastSeal(this.name);
             this.streamFileName = undefined;
             const { bulkFiles, streamFiles } = await this.listFiles();
+            if (bulkFiles.length + streamFiles.length < 1) return await this.mergeSkip("nothingToMerge");
             // compact() folds every file → no older data survives outside it → surviving tombstones
             // can be dropped (nothing left to suppress).
-            if (bulkFiles.length + streamFiles.length >= 1) await this.mergeFileSet(bulkFiles, streamFiles, true);
-        } finally {
-            stopHeartbeat();
-            await releaseMergeFileLock(storage, writerId);
-            releaseMergeLock(this.name, writerId);
-            this.mergeInFlight = false;
-        }
+            const merged = await this.mergeFileSet(bulkFiles, streamFiles, true);
+            return { merged };
+        });
     }
 
     public async merge(timeLo: number, timeHi: number): Promise<void> {

package/storage/BulkDatabase2/mergeLock.d.ts

@@ -1,6 +1,12 @@
 import type { FileStorage } from "../FileFolderAPI";
+export type MergeLockInfo = {
+    holderId: string;
+    expiresInMs: number;
+};
 export declare function tryAcquireMergeLock(collection: string, holderId: string): boolean;
+export declare function peekMergeLock(collection: string): MergeLockInfo | undefined;
 export declare function releaseMergeLock(collection: string, holderId: string): void;
+export declare function peekMergeFileLock(storage: FileStorage): Promise<MergeLockInfo | undefined>;
 export declare function tryAcquireMergeFileLock(storage: FileStorage, holderId: string): Promise<boolean>;
 export declare function startMergeFileLockHeartbeat(storage: FileStorage, holderId: string): () => void;
 export declare function releaseMergeFileLock(storage: FileStorage, holderId: string): Promise<void>;

package/storage/BulkDatabase2/mergeLock.ts

@@ -17,6 +17,16 @@ import type { FileStorage } from "../FileFolderAPI";
 
 const LOCK_TTL_MS = 30 * 1000;
 
+export type MergeLockInfo = { holderId: string; expiresInMs: number };
+
+function parseLockToken(token: string): { holderId: string; time: number } | undefined {
+    const colon = token.lastIndexOf(":");
+    if (colon < 0) return undefined;
+    const time = parseInt(token.slice(colon + 1), 10);
+    if (!Number.isFinite(time)) return undefined;
+    return { holderId: token.slice(0, colon), time };
+}
+
 function getLocalStorage(): Storage | undefined {
     try {
         return typeof localStorage !== "undefined" ? localStorage : undefined;
@@ -40,8 +50,8 @@ export function tryAcquireMergeLock(collection: string, holderId: string): boole
     const now = Date.now();
     const existing = ls.getItem(key);
     if (existing && !existing.startsWith(holderId + ":")) {
-        const t = parseInt(existing.slice(existing.lastIndexOf(":") + 1), 10);
-        if (Number.isFinite(t) && now - t < LOCK_TTL_MS) return false;
+        const parsed = parseLockToken(existing);
+        if (parsed && now - parsed.time < LOCK_TTL_MS) return false;
     }
     const token = holderId + ":" + now;
     ls.setItem(key, token);
@@ -49,6 +59,18 @@ export function tryAcquireMergeLock(collection: string, holderId: string): boole
     return ls.getItem(key) === token;
 }
 
+// Non-mutating look at the tab lock: who holds it and how long until it goes stale (negative = already
+// stale). For logging why a merge was skipped.
+export function peekMergeLock(collection: string): MergeLockInfo | undefined {
+    const ls = getLocalStorage();
+    if (!ls) return undefined;
+    const existing = ls.getItem(lockKey(collection));
+    if (!existing) return undefined;
+    const parsed = parseLockToken(existing);
+    if (!parsed) return undefined;
+    return { holderId: parsed.holderId, expiresInMs: parsed.time + LOCK_TTL_MS - Date.now() };
+}
+
 export function releaseMergeLock(collection: string, holderId: string): void {
     const ls = getLocalStorage();
     if (!ls) return;
@@ -63,19 +85,21 @@ const FILE_LOCK_TTL_MS = 5 * 60 * 1000;
 const FILE_LOCK_SETTLE_MS = 15 * 1000;
 const FILE_LOCK_HEARTBEAT_MS = 2 * 60 * 1000;
 
-async function readMergeFileLock(storage: FileStorage): Promise<{ id: string; time: number } | undefined> {
+async function readMergeFileLock(storage: FileStorage): Promise<{ holderId: string; time: number } | undefined> {
     try {
         const buf = await storage.get(FILE_LOCK_KEY);
         if (!buf) return undefined;
-        const s = buf.toString("utf8");
-        const colon = s.lastIndexOf(":");
-        if (colon < 0) return undefined;
-        const time = parseInt(s.slice(colon + 1), 10);
-        if (!Number.isFinite(time)) return undefined;
-        return { id: s.slice(0, colon), time };
+        return parseLockToken(buf.toString("utf8"));
     } catch { return undefined; }
 }
 
+// Non-mutating look at the cross-process lock file (see peekMergeLock).
+export async function peekMergeFileLock(storage: FileStorage): Promise<MergeLockInfo | undefined> {
+    const existing = await readMergeFileLock(storage);
+    if (!existing) return undefined;
+    return { holderId: existing.holderId, expiresInMs: existing.time + FILE_LOCK_TTL_MS - Date.now() };
+}
+
 async function writeMergeFileLock(storage: FileStorage, holderId: string, time: number): Promise<void> {
     await storage.set(FILE_LOCK_KEY, Buffer.from(`${holderId}:${time}`, "utf8") as Buffer);
 }
@@ -86,11 +110,11 @@ async function writeMergeFileLock(storage: FileStorage, holderId: string, time:
 export async function tryAcquireMergeFileLock(storage: FileStorage, holderId: string): Promise<boolean> {
     const now = Date.now();
     const existing = await readMergeFileLock(storage);
-    if (existing && existing.id !== holderId && now - existing.time < FILE_LOCK_TTL_MS) return false;
+    if (existing && existing.holderId !== holderId && now - existing.time < FILE_LOCK_TTL_MS) return false;
     await writeMergeFileLock(storage, holderId, now);
     await new Promise(r => setTimeout(r, FILE_LOCK_SETTLE_MS));
     const after = await readMergeFileLock(storage);
-    return !!after && after.id === holderId;
+    return !!after && after.holderId === holderId;
 }
 
 // Keep the lock fresh. The merge might run longer than FILE_LOCK_TTL_MS; without periodic re-stamping,
@@ -107,6 +131,6 @@ export function startMergeFileLockHeartbeat(storage: FileStorage, holderId: stri
 export async function releaseMergeFileLock(storage: FileStorage, holderId: string): Promise<void> {
     try {
         const existing = await readMergeFileLock(storage);
-        if (existing && existing.id === holderId) await storage.remove(FILE_LOCK_KEY);
+        if (existing && existing.holderId === holderId) await storage.remove(FILE_LOCK_KEY);
     } catch { /* ignore */ }
 }

package/storage/remoteFileServer.ts

@@ -627,8 +627,13 @@ export async function autocompactBulkDatabases(root: string): Promise<void> {
         const start = Date.now();
         console.log(`  [autocompact] ${at} ${name}: starting merge`);
         try {
-            await getCompactor(baseDir, name).tryMergeNow();
-            console.log(`  [autocompact] ${at} ${name}: done (${Date.now() - start}ms)`);
+            const result = await getCompactor(baseDir, name).tryMergeNow();
+            let outcome = result.merged && "merged" || "nothing to merge";
+            if (result.skipReason) {
+                outcome = `skipped: ${result.skipReason}`;
+                if (result.lockExpiresInMs !== undefined) outcome += ` (lock held by ${result.lockHolderId}, expires in ${Math.max(0, Math.round(result.lockExpiresInMs / 1000))}s)`;
+            }
+            console.log(`  [autocompact] ${at} ${name}: done (${outcome}, ${Date.now() - start}ms)`);
         } catch (e) {
             console.warn(`  [autocompact] ${at} ${name}: failed after ${Date.now() - start}ms - ${(e as Error).message}`);
         }

package/yarn.lock

@@ -1944,10 +1944,10 @@ slash@^3.0.0:
   resolved "https://registry.yarnpkg.com/slash/-/slash-3.0.0.tgz#6539be870c165adbd5240220dbe361f1bc4d4634"
   integrity sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==
 
-socket-function@^1.1.42:
-  version "1.1.47"
-  resolved "https://registry.yarnpkg.com/socket-function/-/socket-function-1.1.47.tgz#45cb508b4f402ae37c3053eb8b7cabe1cefaa011"
-  integrity sha512-DT+TWWcr6GPQ6E/f8o3p+3UZlHfgnLPCJ6baSY+7jOOm5EdoPXcaCF5L4j4cna4OV4Tpw3ny85b4BqvixXP4sQ==
+socket-function@^1.1.48:
+  version "1.1.48"
+  resolved "https://registry.yarnpkg.com/socket-function/-/socket-function-1.1.48.tgz#26266a635847497e726ca49061bc604b4ba0abb1"
+  integrity sha512-kKniLUzh3ZneNcNLFxQiiR1TCSAGeyJgHs5S0643s9SmaVZCyEdYTKYgV+u7jzDSjz81wTQVdv/DChVOQNNH3w==
   dependencies:
     "@types/pako" "^2.0.3"
     "@types/ws" "^8.5.3"