sliftutils 1.3.0 → 1.4.0

package/storage/BulkDatabase2/BulkDatabaseFormat.d.ts

@@ -2,22 +2,45 @@
 /// <reference types="node" />
 export declare const KEY_COLUMN = "key";
 export declare const EMPTY_BUFFER: Buffer;
-export declare function buildFileBuffer(rows: Record<string, unknown>[]): Buffer[];
+export declare const ABSENT: unique symbol;
+export declare const TARGET_FILE_BYTES: number;
+export declare function buildFileBuffer(rows: Record<string, unknown>[], times: number[], targetBytes?: number): Buffer[];
 export type BaseBulkDatabaseReader = {
     rowCount: number;
     totalBytes: number;
+    minTime: number;
+    maxTime: number;
+    minKey?: string;
+    maxKey?: string;
     keys: string[];
     columns: {
         column: string;
         byteSize: number;
     }[];
-    deletedKeys?: Set<string>;
+    keyTimes: Map<string, number>;
+    deleteTimes?: Map<string, number>;
     getColumn: (column: string) => Promise<{
         key: string;
         value: unknown;
+        time: number;
     }[]>;
-    getSingleField: (key: string, column: string) => Promise<unknown | undefined>;
+    getSingleField: (key: string, column: string) => Promise<{
+        value: unknown;
+        time: number;
+    } | typeof ABSENT>;
+};
+export type BulkHeaderInfo = {
+    rowCount: number;
+    minTime: number;
+    maxTime: number;
+    minKey?: string;
+    maxKey?: string;
+    columns: {
+        column: string;
+        byteSize: number;
+    }[];
 };
+export declare function loadBulkHeader(getRange: (start: number, end: number) => Promise<Buffer>, totalBytes: number): Promise<BulkHeaderInfo>;
 export declare function loadBulkDatabase(config: {
     totalBytes: number;
     getRange: (start: number, end: number) => Promise<Buffer>;

package/storage/BulkDatabase2/BulkDatabaseFormat.ts

@@ -20,6 +20,10 @@ const TYPE_INT32_ARRAY = 10;
 const TYPE_UINT32_ARRAY = 11;
 const TYPE_FLOAT32_ARRAY = 12;
 const TYPE_FLOAT64_ARRAY = 13;
+// A cell whose row never set this column at all — as opposed to TYPE_UNDEFINED, an explicitly stored
+// undefined. On read, ABSENT falls through to older readers for that column; a stored undefined stops
+// the fall-through (it's a real value that clears the column).
+const TYPE_ABSENT = 14;
 
 const TYPED_ARRAY_TYPES: { type: number; ctor: { new(buffer: ArrayBuffer): ArrayBufferView; BYTES_PER_ELEMENT: number; name: string } }[] = [
     { type: TYPE_INT8_ARRAY, ctor: Int8Array },
@@ -35,12 +39,33 @@ const TYPED_ARRAY_TYPES: { type: number; ctor: { new(buffer: ArrayBuffer): Array
 
 export const EMPTY_BUFFER = Buffer.alloc(0) as Buffer;
 
+// Sentinel a reader returns for a cell whose row never set this column, so the join can fall through
+// to an older reader for that column. Distinct from a stored undefined, which is a real clearing value.
+export const ABSENT = Symbol("absent");
+
+// Hidden per-row column holding each row's write-time (so reads can resolve a key to its latest value
+// by actual time). NUL-prefixed so it can't collide with a user column; excluded from `columns`.
+const TIME_COLUMN = String.fromCharCode(0) + "t";
+
 type FileHeader = {
     rowCount: number;
     columns: { name: string; offset: number; length: number }[];
+    // Oldest/newest write-time of the data in this file (from the stream entries it was folded from,
+    // carried through merges). Lets the merge planner pick files overlapping a time range. Absent (0)
+    // in files written before this existed.
+    minTime?: number;
+    maxTime?: number;
+    // Lexicographically smallest/largest key in this file (rows are stored key-sorted). Lets the merge
+    // planner group/dedup by key range and lets a single-key read skip files whose range excludes the
+    // key. Absent (undefined) in files written before this existed — treated as "spans all keys".
+    minKey?: string;
+    maxKey?: string;
 };
 
 function encodeValue(value: unknown): { type: number; bytes: Buffer } {
+    if (value === ABSENT) {
+        return { type: TYPE_ABSENT, bytes: EMPTY_BUFFER };
+    }
     if (value === undefined || value === null) {
         return { type: TYPE_UNDEFINED, bytes: EMPTY_BUFFER };
     }
@@ -90,6 +115,7 @@ function decodeValue(type: number, bytes: Buffer): unknown {
         return bytes[0] === 1;
     }
     if (type === TYPE_OBJECT) return JSON.parse(bytes.toString("utf8"));
+    if (type === TYPE_ABSENT) return ABSENT;
     const entry = TYPED_ARRAY_TYPES.find(t => t.type === type);
     if (!entry) {
         throw new Error(`Expected a valid type tag, was ${type}`);
@@ -134,12 +160,12 @@ function decodeBulkData(blob: Buffer, rowCount: number): unknown[] {
     return values;
 }
 
-// Past this estimated logical size a single rows array is split across multiple files, so no one
-// file (and therefore no single column blob, and no single Buffer.concat) ever approaches the
-// ~2GB Buffer length limit. The cap is deliberately the same as the merge cap: 800MB is the most
-// we'll ever hold for one file. The estimate is rough on purpose — it only needs to keep each
-// chunk comfortably under the limit, not be exact.
-const FILE_SPLIT_BYTES = 800 * 1024 * 1024;
+// Target logical (uncompressed) size of one bulk file. A rows array bigger than this is split across
+// multiple key-contiguous files, so files stay around this size (the merge policy's target) and no
+// single column blob / Buffer.concat ever approaches the ~2GB Buffer length limit. The estimate is
+// rough on purpose — it only needs to keep each chunk near the target, not be exact. A single row
+// bigger than the target still becomes its own (oversized) file, since we never split within a key.
+export const TARGET_FILE_BYTES = 256 * 1024 * 1024;
 
 // Per-value on-disk overhead: a 4-byte offset entry plus a 1-byte type tag.
 const PER_VALUE_OVERHEAD = 5;
@@ -162,7 +188,7 @@ function estimateRowBytes(row: Record<string, unknown>): number {
     return total;
 }
 
-function buildOneFile(rows: Record<string, unknown>[]): Buffer {
+function buildOneFile(rows: Record<string, unknown>[], times: number[]): Buffer {
     const columnNames: string[] = [];
     const columnSet = new Set<string>();
     for (const row of rows) {
@@ -172,58 +198,110 @@ function buildOneFile(rows: Record<string, unknown>[]): Buffer {
             columnNames.push(field);
         }
     }
-    const blobs = columnNames.map(col => encodeBulkData(rows.map(row => row[col])));
+    // A row that doesn't include a column stores ABSENT (fall-through), not undefined (a real value).
+    const blobs = columnNames.map(col => encodeBulkData(rows.map(row => col in row ? row[col] : ABSENT)));
+    // The hidden per-row time column.
+    columnNames.push(TIME_COLUMN);
+    blobs.push(encodeBulkData(times));
     let offset = 0;
     const columns = columnNames.map((name, i) => {
         const entry = { name, offset, length: blobs[i].length };
         offset += blobs[i].length;
         return entry;
     });
-    const header: FileHeader = { rowCount: rows.length, columns };
+    let minTime = times.length ? times[0] : 0;
+    let maxTime = minTime;
+    for (const t of times) { if (t < minTime) minTime = t; if (t > maxTime) maxTime = t; }
+    let minKey: string | undefined;
+    let maxKey: string | undefined;
+    for (const row of rows) {
+        const key = row[KEY_COLUMN] as string;
+        if (minKey === undefined || key < minKey) minKey = key;
+        if (maxKey === undefined || key > maxKey) maxKey = key;
+    }
+    const header: FileHeader = { rowCount: rows.length, columns, minTime, maxTime, minKey, maxKey };
     const headerBuf = Buffer.from(JSON.stringify(header), "utf8");
     const lengthPrefix = Buffer.alloc(4);
     lengthPrefix.writeUInt32LE(headerBuf.length, 0);
     return Buffer.concat([lengthPrefix, headerBuf, ...blobs]);
 }
 
-// Returns one complete, independent file buffer per chunk of rows. When the caller hands us more
-// rows than fit comfortably in one file we partition by row range — each returned buffer is exactly
-// what buildOneFile would produce if called with that subset, so the chunks have disjoint keys and
-// the caller just writes each as its own file. A normal-sized write returns a single buffer.
-export function buildFileBuffer(rows: Record<string, unknown>[]): Buffer[] {
-    if (rows.length === 0) return [buildOneFile([])];
+// Returns one complete, independent file buffer per chunk of rows. Rows are first sorted by key, then
+// partitioned into key-contiguous chunks of ~targetBytes each — so every returned file is key-sorted
+// (tight minKey/maxKey for the read-skip + merge planner) and stays near the target size, and no
+// single column blob / Buffer.concat approaches the ~2GB limit. The chunks have disjoint key ranges,
+// so the caller just writes each as its own file. A normal-sized write returns a single buffer.
+// `times[i]` is row i's write-time, stored per row so reads resolve a key to its latest value by time.
+export function buildFileBuffer(rows: Record<string, unknown>[], times: number[], targetBytes = TARGET_FILE_BYTES): Buffer[] {
+    if (rows.length === 0) return [buildOneFile([], [])];
+    // Sort rows + their times together by key so each output file is key-contiguous.
+    const order = rows.map((_, i) => i).sort((a, b) => {
+        const ka = rows[a][KEY_COLUMN] as string;
+        const kb = rows[b][KEY_COLUMN] as string;
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    const sortedRows = order.map(i => rows[i]);
+    const sortedTimes = order.map(i => times[i]);
     const result: Buffer[] = [];
     let chunkStart = 0;
     let chunkBytes = 0;
-    for (let i = 0; i < rows.length; i++) {
-        const rowBytes = estimateRowBytes(rows[i]);
-        if (i > chunkStart && chunkBytes + rowBytes > FILE_SPLIT_BYTES) {
-            result.push(buildOneFile(rows.slice(chunkStart, i)));
+    for (let i = 0; i < sortedRows.length; i++) {
+        const rowBytes = estimateRowBytes(sortedRows[i]);
+        if (i > chunkStart && chunkBytes + rowBytes > targetBytes) {
+            result.push(buildOneFile(sortedRows.slice(chunkStart, i), sortedTimes.slice(chunkStart, i)));
             chunkStart = i;
             chunkBytes = 0;
         }
         chunkBytes += rowBytes;
     }
-    result.push(buildOneFile(rows.slice(chunkStart)));
+    result.push(buildOneFile(sortedRows.slice(chunkStart), sortedTimes.slice(chunkStart)));
     return result;
 }
 
 export type BaseBulkDatabaseReader = {
     rowCount: number;
     totalBytes: number;
+    // Write-time bounds of this reader's data (0 if unknown — old bulk files).
+    minTime: number;
+    maxTime: number;
+    // Key-range bounds (undefined for old files / the stream reader — treat as "spans all keys").
+    minKey?: string;
+    maxKey?: string;
     // Keys is special, it's always automatically decoded, even though it is stored as a normal column
     keys: string[];
     columns: { column: string; byteSize: number }[];
-    // Keys this reader tombstones (deleted). A newer reader's deletion suppresses the key in all
-    // older readers. Bulk readers never set this; the tier-0 stream reader does.
-    deletedKeys?: Set<string>;
-    getColumn: (column: string) => Promise<{
-        key: string;
-        value: unknown;
-    }[]>;
-    getSingleField: (key: string, column: string) => Promise<unknown | undefined>;
+    // Each key's row write-time (the time of its newest write in this reader). The join compares these
+    // across readers to resolve a key to its latest value.
+    keyTimes: Map<string, number>;
+    // Per-key tombstone time: the key was deleted at this time. The join treats a delete like any other
+    // event — a delete only wins if it's newer than every set for the key. Only the stream reader sets it.
+    deleteTimes?: Map<string, number>;
+    // Each key's value for the column plus the row's write-time. value may be ABSENT (the row never set
+    // this column — the join then falls through to an older reader for that key/column).
+    getColumn: (column: string) => Promise<{ key: string; value: unknown; time: number }[]>;
+    // The value + write-time for (key, column), or ABSENT if this reader has no such cell.
+    getSingleField: (key: string, column: string) => Promise<{ value: unknown; time: number } | typeof ABSENT>;
 };
 
+// Reads just the file header (the 4-byte length + header JSON) — no column data. Used by the merge
+// planner to get each file's row count, time range, and key range cheaply across many files.
+export type BulkHeaderInfo = { rowCount: number; minTime: number; maxTime: number; minKey?: string; maxKey?: string; columns: { column: string; byteSize: number }[] };
+export async function loadBulkHeader(getRange: (start: number, end: number) => Promise<Buffer>, totalBytes: number): Promise<BulkHeaderInfo> {
+    const headerLength = (await getRange(0, 4)).readUInt32LE(0);
+    if (headerLength <= 0 || headerLength > totalBytes) {
+        throw new Error(`Expected header length in (0, ${totalBytes}], was ${headerLength}`);
+    }
+    const header = JSON.parse((await getRange(4, 4 + headerLength)).toString("utf8")) as FileHeader;
+    return {
+        rowCount: header.rowCount,
+        minTime: header.minTime || 0,
+        maxTime: header.maxTime || 0,
+        minKey: header.minKey,
+        maxKey: header.maxKey,
+        columns: header.columns.filter(c => c.name !== TIME_COLUMN).map(c => ({ column: c.name, byteSize: c.length })),
+    };
+}
+
 export async function loadBulkDatabase(config: {
     totalBytes: number;
     getRange: (start: number, end: number) => Promise<Buffer>;
@@ -254,20 +332,31 @@ export async function loadBulkDatabase(config: {
     });
     const keyIndex = new Map(keys.map((key, i) => [key, i]));
 
+    // Per-row write-times. Old files (written before this column existed) fall back to the file's header
+    // time (or 0) for every row — fine, since such files predate concurrent-time resolution.
+    const times: number[] = colByName.has(TIME_COLUMN)
+        ? (await readWholeColumn(TIME_COLUMN)).map(v => typeof v === "number" ? v : 0)
+        : keys.map(() => header.maxTime || 0);
+
     return {
         rowCount,
         totalBytes: config.totalBytes,
+        minTime: header.minTime || 0,
+        maxTime: header.maxTime || 0,
+        minKey: header.minKey,
+        maxKey: header.maxKey,
         keys,
-        columns: header.columns.map(c => ({ column: c.name, byteSize: c.length })),
+        keyTimes: new Map(keys.map((key, i) => [key, times[i]])),
+        columns: header.columns.filter(c => c.name !== TIME_COLUMN).map(c => ({ column: c.name, byteSize: c.length })),
         async getColumn(column) {
             const values = await readWholeColumn(column);
-            return keys.map((key, i) => ({ key, value: values[i] }));
+            return keys.map((key, i) => ({ key, value: values[i], time: times[i] }));
         },
         async getSingleField(key, column) {
             const row = keyIndex.get(key);
-            if (row === undefined) return undefined;
+            if (row === undefined) return ABSENT;
             const col = colByName.get(column);
-            if (!col) return undefined;
+            if (!col) return ABSENT;
             const colBase = dataBase + col.offset;
             const offsetsBuf = await config.getRange(colBase + 4 * row, colBase + 4 * row + 8);
             const start = offsetsBuf.readUInt32LE(0);
@@ -279,7 +368,9 @@ export async function loadBulkDatabase(config: {
             if (end > start) {
                 bytes = await config.getRange(dataStart + start, dataStart + end);
             }
-            return decodeValue(typeBuf[0], bytes);
+            const value = decodeValue(typeBuf[0], bytes);
+            if (value === ABSENT) return ABSENT;
+            return { value, time: times[row] };
         },
     };
 }

package/storage/BulkDatabase2/mergeLock.d.ts

@@ -0,0 +1,2 @@
+export declare function tryAcquireMergeLock(collection: string, holderId: string): boolean;
+export declare function releaseMergeLock(collection: string, holderId: string): void;

package/storage/BulkDatabase2/mergeLock.ts

@@ -0,0 +1,48 @@
+// Best-effort "only one tab merges this collection at a time" guard. This is purely an efficiency
+// measure: correctness does NOT depend on it. Reads resolve by per-row write-time, merges write new
+// files before deleting consumed ones, and a duplicate-heavy region gets re-merged — so two tabs
+// merging at once only waste work and briefly duplicate data, never corrupt or lose it. The lock just
+// stops that wasted work. It uses localStorage (shared across same-origin tabs) and is a no-op where
+// localStorage is unavailable (Node) — there concurrent merges are harmless, which the Node stress
+// tests exercise. localStorage has no atomic compare-and-swap, so we write-then-reread to shrink the
+// race window, and a TTL frees a lock left behind by a tab that crashed or closed mid-merge.
+
+const LOCK_TTL_MS = 30 * 1000;
+
+function getLocalStorage(): Storage | undefined {
+    try {
+        return typeof localStorage !== "undefined" ? localStorage : undefined;
+    } catch {
+        return undefined; // accessing localStorage can throw (e.g. disabled cookies)
+    }
+}
+
+function lockKey(collection: string): string {
+    return "bulkDatabase2-merge:" + collection;
+}
+
+// Returns true if we now hold the lock (or there's no localStorage to coordinate through, in which
+// case we proceed and rely on the manifest backstop). Returns false if another tab holds a fresh lock.
+export function tryAcquireMergeLock(collection: string, holderId: string): boolean {
+    const ls = getLocalStorage();
+    if (!ls) return true;
+    const key = lockKey(collection);
+    const now = Date.now();
+    const existing = ls.getItem(key);
+    if (existing) {
+        const t = parseInt(existing.slice(existing.lastIndexOf(":") + 1), 10);
+        if (Number.isFinite(t) && now - t < LOCK_TTL_MS) return false;
+    }
+    const token = holderId + ":" + now;
+    ls.setItem(key, token);
+    // Re-read to catch a racing setItem from another tab (best-effort, not atomic).
+    return ls.getItem(key) === token;
+}
+
+export function releaseMergeLock(collection: string, holderId: string): void {
+    const ls = getLocalStorage();
+    if (!ls) return;
+    const key = lockKey(collection);
+    const existing = ls.getItem(key);
+    if (existing && existing.startsWith(holderId + ":")) ls.removeItem(key);
+}

package/storage/BulkDatabase2/streamLog.ts

@@ -1,5 +1,5 @@
 import cborx from "cbor-x";
-import { BaseBulkDatabaseReader } from "./BulkDatabaseFormat";
+import { ABSENT, BaseBulkDatabaseReader } from "./BulkDatabaseFormat";
 
 // Tier-0 streaming format: an append log of whole-row writes and deletes (row-format, not columnar),
 // so small mutations are a single cheap append instead of rewriting a columnar file. Each block is:
@@ -64,10 +64,12 @@ export function parseStream(buffer: Buffer): { entries: StreamEntry[]; badBytes:
     return { entries, badBytes: buffer.length - pos };
 }
 
-// Wraps streamed entries (already ordered oldest-first) as a BaseBulkDatabaseReader. Applies
-// set/delete newest-wins: later entries overwrite earlier ones, and a delete tombstones the key
-// (exposed via deletedKeys so the join suppresses it in older bulk readers). Also returns the latest
-// timestamp seen per key (live or deleted), used for cross-tab conflict resolution.
+// Wraps streamed entries (already ordered oldest-first) as a BaseBulkDatabaseReader. Each set MERGES
+// its fields onto the key's current row (so a partial write/update only changes the columns it
+// includes); a delete tombstones the key (exposed via deletedKeys so the join suppresses it in older
+// bulk readers) and resets the merge. A column the merged row never set reads as ABSENT, so the join
+// falls through to older readers for it. Also returns the latest timestamp seen per key (live or
+// deleted), used for cross-tab conflict resolution.
 export function streamReaderFromEntries(entries: StreamEntry[], totalBytes: number): { reader: BaseBulkDatabaseReader; times: Map<string, number> } {
     let byKey = new Map<string, Record<string, unknown>>();
     let deletedKeys = new Set<string>();
@@ -79,7 +81,7 @@ export function streamReaderFromEntries(entries: StreamEntry[], totalBytes: numb
             times.set(entry.deletedKey, entry.time);
         } else if (entry.row) {
             let key = entry.row.key as string;
-            byKey.set(key, entry.row);
+            byKey.set(key, { ...byKey.get(key), ...entry.row });
             deletedKeys.delete(key);
             times.set(key, entry.time);
         }
@@ -95,21 +97,31 @@ export function streamReaderFromEntries(entries: StreamEntry[], totalBytes: numb
         }
     }
     let columns = columnNames.map(column => ({ column, byteSize: 0 }));
+    // Per-key tombstone times for the join's delete resolution.
+    let deleteTimes = new Map<string, number>();
+    for (let key of deletedKeys) deleteTimes.set(key, times.get(key) || 0);
+    let timeValues = [...times.values()];
     let reader: BaseBulkDatabaseReader = {
         totalBytes,
         rowCount: keys.length,
+        minTime: timeValues.length ? Math.min(...timeValues) : 0,
+        maxTime: timeValues.length ? Math.max(...timeValues) : 0,
         keys,
+        keyTimes: new Map(keys.map(key => [key, times.get(key) || 0])),
         columns,
-        deletedKeys,
+        deleteTimes,
+        // A key's time is its latest write across all columns (per-key, not per-column). For a column
+        // it never set we return ABSENT so the join falls through to an older reader.
         async getColumn(column) {
             return keys.map(key => {
                 let row = byKey.get(key);
-                return { key, value: row && row[column] };
+                return { key, value: row && column in row ? row[column] : ABSENT, time: times.get(key) || 0 };
             });
         },
         async getSingleField(key, column) {
             let row = byKey.get(key);
-            return row && row[column];
+            if (!row || !(column in row)) return ABSENT;
+            return { value: row[column], time: times.get(key) || 0 };
         },
     };
     return { reader, times };

package/storage/BulkDatabase2/syncClient.d.ts

@@ -5,5 +5,6 @@ export type RemoteWrite = {
     value?: unknown;
 };
 export declare function isSyncSupported(): boolean;
-export declare function connect(collection: string, onWrite: (write: RemoteWrite) => void): Promise<RemoteWrite[]>;
+export declare function connect(collection: string, onWrite: (write: RemoteWrite) => void, onSeal?: () => void): Promise<RemoteWrite[]>;
 export declare function broadcast(collection: string, write: RemoteWrite): void;
+export declare function broadcastSeal(collection: string): void;

package/storage/BulkDatabase2/syncClient.ts

@@ -15,6 +15,8 @@ const RECENT_WINDOW_MS = 60_000;
 type Channel = {
     bc: BroadcastChannel;
     subscribers: ((write: RemoteWrite) => void)[];
+    // Called when a peer asks everyone to seal (stop appending to) their current stream file.
+    sealSubscribers: (() => void)[];
     // This tab's own recent writes, kept so it can answer another tab's "hello".
     recent: RemoteWrite[];
 };
@@ -41,7 +43,7 @@ function ensure(collection: string): Channel | undefined {
     // BroadcastChannel never delivers a message back to the instance that sent it, so a tab never
     // hears its own writes — only the other open tabs do.
     const bc = new BroadcastChannel(`bulkDatabase2:${collection}`);
-    const created: Channel = { bc, subscribers: [], recent: [] };
+    const created: Channel = { bc, subscribers: [], sealSubscribers: [], recent: [] };
     bc.onmessage = (event: MessageEvent) => {
         const msg = event.data as { type: string; write?: RemoteWrite; writes?: RemoteWrite[] };
         if (!msg) return;
@@ -49,6 +51,10 @@ function ensure(collection: string): Channel | undefined {
             deliver(created, msg.write);
         } else if (msg.type === "recent" && msg.writes) {
             for (const write of msg.writes) deliver(created, write);
+        } else if (msg.type === "seal") {
+            // A peer is about to fold recent data; stop appending to our current stream file so it
+            // becomes complete and the merge can fold it whole. Our next write starts a fresh file.
+            for (const sub of created.sealSubscribers) sub();
         } else if (msg.type === "hello") {
             // Another tab just started; replay our recent writes so it doesn't miss any. The reply goes
             // to every tab, but peers that already have a write ignore it (its timestamp isn't newer
@@ -64,10 +70,11 @@ function ensure(collection: string): Channel | undefined {
 // Subscribe to remote writes for a collection. Recent writes from already-open tabs arrive through the
 // same onWrite callback (as the reply to our hello), so the returned array is always empty — it's kept
 // only for API compatibility with callers that await it.
-export function connect(collection: string, onWrite: (write: RemoteWrite) => void): Promise<RemoteWrite[]> {
+export function connect(collection: string, onWrite: (write: RemoteWrite) => void, onSeal?: () => void): Promise<RemoteWrite[]> {
     const channel = ensure(collection);
     if (!channel) return Promise.resolve([]);
     channel.subscribers.push(onWrite);
+    if (onSeal) channel.sealSubscribers.push(onSeal);
     channel.bc.postMessage({ type: "hello" });
     return Promise.resolve([]);
 }
@@ -79,3 +86,13 @@ export function broadcast(collection: string, write: RemoteWrite): void {
     pruneRecent(channel);
     channel.bc.postMessage({ type: "write", write });
 }
+
+// Ask every other open tab of this collection to seal (stop appending to) its current stream file, so
+// a merge can fold recent data up to the present without racing an append. Best-effort: no-op in Node,
+// and a peer that misses it just keeps appending — worst case the merge folds a prefix and the rest
+// folds later (duplication, resolved by write-time), never data loss.
+export function broadcastSeal(collection: string): void {
+    const channel = ensure(collection);
+    if (!channel) return;
+    channel.bc.postMessage({ type: "seal" });
+}

package/storage/FileFolderAPI.tsx

@@ -183,7 +183,12 @@ export class NodeJSDirectoryHandleWrapper implements DirectoryWrapper {
             // Create the file
             await fs.promises.writeFile(filePath, Buffer.alloc(0));
         } else if (!exists) {
-            throw new Error(`File not found: ${filePath}`);
+            // Tag as ENOENT so readWithRetry treats it as a genuinely-missing file (return undefined now)
+            // rather than a transient read failure to retry 6× with backoff — missing files are normal
+            // (a concurrent merge deletes a file mid-read), and retrying them is catastrophically slow.
+            const err = new Error(`File not found: ${filePath}`) as Error & { code?: string };
+            err.code = "ENOENT";
+            throw err;
         }
 
         return new NodeJSFileHandleWrapper(filePath);