@moyodb/sdk 1.0.0 → 1.1.0

package/dist/engine/moyodb_engine.js

@@ -1,5 +1,5 @@
 /* @ts-self-types="./moyodb_engine.d.ts" */
-import { opfsCleanupInactiveEntries, opfsCloseSession, opfsDbDirectorySize, opfsFlush, opfsLen, opfsOpenActiveDb, opfsOpenGenerationDb, opfsPrepareRebuildTarget, opfsReadActiveGeneration, opfsReadAt, opfsRemoveDb, opfsSwapActiveGeneration, opfsTruncate, opfsWriteAt } from './snippets/moyodb-engine-8ebe6af0cc2e81b7/js/opfs_shim.js';
+import { opfsAppendOffset, opfsCleanupInactiveEntries, opfsCloseSession, opfsDbDirectorySize, opfsFlush, opfsLen, opfsOpenActiveDb, opfsOpenGenerationDb, opfsPrepareRebuildTarget, opfsReadActiveGeneration, opfsReadAtInto, opfsRemoveDb, opfsSwapActiveGeneration, opfsTruncate, opfsWriteAt } from './snippets/moyodb-engine-8ebe6af0cc2e81b7/js/opfs_shim.js';
 
 
 export class WasmEngine {
@@ -54,8 +54,8 @@ export class WasmEngine {
         }
     }
     /**
-     * Returns one byte per op: for puts whether the key existed before,
-     * for deletes whether a key was deleted. The op kinds are the caller's.
+     * Returns one byte per operation in input order. For puts, 1 means
+     * the key existed before the write. For deletes, 1 means it was deleted.
      * @param {bigint} tx_id
      * @param {string} store
      * @param {Uint8Array} ops
@@ -175,8 +175,8 @@ export class WasmEngine {
         }
     }
     /**
-     * Checkpoints (when healthy) and closes. The handle is released even
-     * when closing fails, so a retry never reuses a half-closed engine.
+     * Checkpoints a healthy engine and closes it. Releases the binding
+     * handle even on error so a retry cannot reuse a partially closed engine.
      */
     close() {
         try {
@@ -211,8 +211,8 @@ export class WasmEngine {
         }
     }
     /**
-     * Streams this database into `target`, a freshly opened empty
-     * generation. Returns the txid the target was published at.
+     * Streams this database into a new, empty target generation.
+     * Returns the target txid. The caller must activate the generation.
      * @param {WasmEngine} target
      * @returns {bigint}
      */
@@ -232,6 +232,29 @@ export class WasmEngine {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Omits the named internal stores during a rebuild. Compaction
+     * also omits the change log and retains the other stores.
+     * @param {WasmEngine} target
+     * @param {any} skip_stores
+     * @returns {bigint}
+     */
+    compact_into_skipping_stores(target, skip_stores) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            _assertClass(target, WasmEngine);
+            wasm.wasmengine_compact_into_skipping_stores(retptr, this.__wbg_ptr, target.__wbg_ptr, addHeapObject(skip_stores));
+            var r0 = getDataViewMemory0().getBigInt64(retptr + 8 * 0, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            if (r3) {
+                throw takeObject(r2);
+            }
+            return BigInt.asUintN(64, r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * @param {bigint} tx_id
      * @param {string} name
@@ -418,9 +441,9 @@ export class WasmEngine {
         }
     }
     /**
-     * Keys arrive packed; values leave packed as
-     * `u32 count | count x u32 length (u32::MAX = missing) | bytes`,
-     * one buffer instead of one JS array per value.
+     * Returns packed values as
+     * `u32 count | count x u32 length (u32::MAX = missing) | bytes`.
+     * All integers are little-endian.
      * @param {bigint} tx_id
      * @param {string} store
      * @param {Uint8Array} keys
@@ -491,6 +514,30 @@ export class WasmEngine {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Checks existence using one TTL timestamp without loading value bodies.
+     * @param {bigint} tx_id
+     * @param {string} store
+     * @param {any} keys
+     * @returns {any}
+     */
+    has_many(tx_id, store, keys) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(store, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.wasmengine_has_many(retptr, this.__wbg_ptr, tx_id, ptr0, len0, addHeapObject(keys));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * @returns {any}
      */
@@ -845,8 +892,7 @@ export class WasmEngine {
 if (Symbol.dispose) WasmEngine.prototype[Symbol.dispose] = WasmEngine.prototype.free;
 
 /**
- * `"debug"` or `"release"`; benchmark reports record which build they
- * measured instead of trusting the build script that was supposed to run.
+ * Returns `"debug"` or `"release"` for the loaded WASM build.
  * @returns {string}
  */
 export function buildProfile() {
@@ -911,8 +957,9 @@ export function prepareRebuildTarget(name) {
 }
 
 /**
- * Active generation from the control file, or `null` for the legacy
- * layout. A corrupt control file is an error, never `null`.
+ * Returns the active generation, or `null` for the legacy layout.
+ * A corrupt control file permits legacy fallback only while legacy data
+ * files remain. Otherwise it is an error.
  * @param {string} name
  * @returns {Promise<any>}
  */
@@ -924,10 +971,9 @@ export function readActiveGeneration(name) {
 }
 
 /**
- * Publishes `generation_name` as the active generation. With
- * `expected_current` set, the swap fails unless the control file still
- * names that generation (or is absent, for `null`), and the written
- * control file is read back and verified before this resolves.
+ * Publishes `generation_name` only if the active generation matches
+ * `expected_current`. `None` requires no active generation.
+ * Verifies the written control file before returning.
  * @param {string} name
  * @param {string} generation_name
  * @param {string | null} [expected_current]
@@ -1145,7 +1191,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_680(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_736(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -1172,6 +1218,10 @@ function __wbg_get_imports() {
             const ret = Date.now();
             return ret;
         },
+        __wbg_opfsAppendOffset_8c38ddb12af5281b: function() { return handleError(function (arg0, arg1) {
+            const ret = opfsAppendOffset(arg0 >>> 0, arg1 >>> 0);
+            return ret;
+        }, arguments) ?? 0n; },
         __wbg_opfsCleanupInactiveEntries_e761ad3f373325fd: function() { return handleError(function (arg0, arg1) {
             const ret = opfsCleanupInactiveEntries(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
@@ -1206,9 +1256,9 @@ function __wbg_get_imports() {
             const ret = opfsReadActiveGeneration(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
         }, arguments); },
-        __wbg_opfsReadAt_e446074c3bbf69d1: function() { return handleError(function (arg0, arg1, arg2, arg3) {
-            const ret = opfsReadAt(arg0 >>> 0, arg1 >>> 0, BigInt.asUintN(64, arg2), arg3 >>> 0);
-            return addHeapObject(ret);
+        __wbg_opfsReadAtInto_11f57c26cf06d807: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+            const ret = opfsReadAtInto(arg0 >>> 0, arg1 >>> 0, BigInt.asUintN(64, arg2), getArrayU8FromWasm0(arg3, arg4));
+            return ret;
         }, arguments); },
         __wbg_opfsRemoveDb_7e05aef0688d4c5a: function() { return handleError(function (arg0, arg1) {
             const ret = opfsRemoveDb(getStringFromWasm0(arg0, arg1));
@@ -1283,8 +1333,8 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_generic_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 106, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_665);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 109, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_721);
             return addHeapObject(ret);
         },
         __wbindgen_generic_0000000000000002: function(arg0) {
@@ -1326,14 +1376,14 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_680(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_680(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_736(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_736(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
-function __wasm_bindgen_func_elem_665(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_721(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_665(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_721(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {

package/dist/engine/moyodb_engine_bg.wasm.d.ts

@@ -20,6 +20,7 @@ export const wasmengine_clear_store: (a: number, b: number, c: bigint, d: number
 export const wasmengine_close: (a: number, b: number) => void;
 export const wasmengine_commit_tx: (a: number, b: number, c: bigint) => void;
 export const wasmengine_compact_into: (a: number, b: number, c: number) => void;
+export const wasmengine_compact_into_skipping_stores: (a: number, b: number, c: number, d: number) => void;
 export const wasmengine_create_store: (a: number, b: number, c: bigint, d: number, e: number, f: number) => void;
 export const wasmengine_delete: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number) => void;
 export const wasmengine_delete_many: (a: number, b: number, c: bigint, d: number, e: number, f: number) => void;
@@ -31,6 +32,7 @@ export const wasmengine_get_many: (a: number, b: number, c: bigint, d: number, e
 export const wasmengine_get_many_packed: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number) => void;
 export const wasmengine_get_schema_version: (a: number, b: number) => void;
 export const wasmengine_has: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number) => void;
+export const wasmengine_has_many: (a: number, b: number, c: bigint, d: number, e: number, f: number) => void;
 export const wasmengine_health: (a: number, b: number) => void;
 export const wasmengine_import_snapshot: (a: number, b: number, c: number, d: number) => void;
 export const wasmengine_list_store_configs: (a: number, b: number) => void;
@@ -50,8 +52,8 @@ export const wasmengine_set_change_feed_policy: (a: number, b: number, c: bigint
 export const wasmengine_set_failpoint: (a: number, b: number, c: number) => void;
 export const wasmengine_set_schema_version: (a: number, b: number, c: bigint, d: bigint) => void;
 export const wasmengine_stats: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_665: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_680: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_721: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_736: (a: number, b: number, c: number, d: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/dist/engine/package.json

@@ -1,7 +1,7 @@
 {
   "name": "moyodb-engine",
   "type": "module",
-  "description": "Experimental Rust/WASM transactional key-value storage engine for browser apps.",
+  "description": "Rust/WASM transactional storage engine for browser and native file runtimes.",
   "version": "1.0.0",
   "license": "SEE LICENSE IN ../../LICENSE",
   "repository": {

package/dist/engine/snippets/moyodb-engine-8ebe6af0cc2e81b7/js/opfs_shim.js

@@ -6,12 +6,16 @@ const CONTROL_VERSION = 1;
 const CONTROL_CHECKSUM_OFFSET = 24;
 const CONTROL_NAME_OFFSET = 32;
 const CONTROL_MAGIC = new Uint8Array([66, 68, 66, 82, 79, 79, 84, 49]);
-const OPFS_WRITE_CHUNK_SIZE = 256 * 1024;
+// Chromium rejects a SyncAccessHandle.write larger than a signed 32-bit count.
+const OPFS_MAX_WRITE_SIZE = 0x7fffffff;
 const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder();
 let rootDir = null;
 let nextSessionId = 1;
 const sessions = new Map();
+// Exclusive session handles keep cached sizes valid across Rust backend clones.
+// Length checks for validation and statistics still query OPFS.
+const appendOffsets = new WeakMap();
 function namedError(name, message) {
     const error = new Error(message);
     error.name = name;
@@ -67,7 +71,7 @@ function writeU64(view, offset, value) {
     view.setBigUint64(offset, BigInt(value), true);
 }
 function readU64(view, offset) {
-    return Number(view.getBigUint64(offset, true));
+    return view.getBigUint64(offset, true);
 }
 function fnv1a32(bytes, zeroOffset = -1, zeroLength = 0) {
     let hash = 0x811c9dc5;
@@ -82,12 +86,14 @@ function fnv1a32(bytes, zeroOffset = -1, zeroLength = 0) {
 function isGenerationNameValid(name) {
     return typeof name === 'string' && /^gen-[a-z0-9]+-[a-z0-9]+$/i.test(name);
 }
-// Every byte must reach the file or the call fails: a short write that returns
-// normally would let callers publish state that is not on disk.
+// Returns only after all bytes are written. The caller must flush for durability.
 export function writeAll(handle, bytes, at) {
     let writtenTotal = 0;
     while (writtenTotal < bytes.length) {
-        const chunk = bytes.subarray(writtenTotal, writtenTotal + OPFS_WRITE_CHUNK_SIZE);
+        // Preserve the engine's batch; split only at the browser size limit or
+        // after a short write. Suffix views borrow the original buffer.
+        const end = Math.min(bytes.length, writtenTotal + OPFS_MAX_WRITE_SIZE);
+        const chunk = writtenTotal === 0 && end === bytes.length ? bytes : bytes.subarray(writtenTotal, end);
         const rawWritten = handle.write(chunk, { at: at + writtenTotal });
         const written = Number(rawWritten);
         if (!Number.isSafeInteger(written) || written < 0 || written > chunk.length) {
@@ -100,7 +106,7 @@ export function writeAll(handle, bytes, at) {
     }
     return writtenTotal;
 }
-// Fills `buffer` from `at`, stopping only at end of file. Bytes past EOF stay zero.
+// Reads until the buffer is full or a read returns zero. The unread suffix is unchanged.
 export function readAll(handle, buffer, at) {
     let readTotal = 0;
     while (readTotal < buffer.length) {
@@ -138,8 +144,8 @@ export function encodeControlSlot(generationCounter, activeGeneration) {
     view.setUint32(CONTROL_CHECKSUM_OFFSET, checksum, true);
     return slot;
 }
-// Returns null for any slot whose bytes do not checksum. Fields are interpreted
-// only after the checksum passes, so a torn slot never masks its valid sibling.
+// Reject incomplete slots and bad magic or checksums. Validate the remaining
+// fields after the checksum passes, so torn fields cannot mask a valid slot.
 export function decodeControlSlot(slotIndex, bytes) {
     if (bytes.length < CONTROL_SLOT_SIZE) {
         return null;
@@ -174,9 +180,9 @@ export function decodeControlSlot(slotIndex, bytes) {
         activeGeneration
     };
 }
-// `absent`  — the file is empty: no generation has ever been published.
-// `invalid` — the file has bytes but no slot checksums.
-// `valid`   — `control` is the newest checksummed slot.
+// `absent`: empty file.
+// `invalid`: nonempty file with no valid slot.
+// `valid`: `control` is the valid slot with the highest generation counter.
 export function readControlStateFromAccessHandle(accessHandle) {
     const size = Number(accessHandle.getSize());
     if (!Number.isSafeInteger(size) || size < 0) {
@@ -207,21 +213,18 @@ async function readControlFile(dbRoot) {
         accessHandle.close();
     }
 }
-async function hasLegacyDataFiles(dbRoot) {
-    for (const fileName of FILE_NAMES) {
-        if (await lookupFileHandle(dbRoot, fileName)) {
-            return true;
-        }
+async function hasLegacyDataFiles(dbRoot, fileKind = 0) {
+    if (fileKind === FILE_NAMES.length) {
+        return false;
+    }
+    if (await lookupFileHandle(dbRoot, FILE_NAMES[fileKind])) {
+        return true;
     }
-    return false;
+    return await hasLegacyDataFiles(dbRoot, fileKind + 1);
 }
-// Resolves which directory holds the live database, failing closed on damage.
-//
-// Legacy root files are removed before the first write into a published
-// generation (see opfsCleanupInactiveEntries and opfsOpenActiveDb). So an
-// unreadable control file next to legacy files can only be a torn first
-// publication, and legacy is still authoritative. Without legacy files it is
-// real corruption of the pointer to live data.
+// Legacy files remain authoritative after a torn first publication. They must
+// be removed before a published generation accepts writes, so later control
+// damage cannot make stale legacy files appear current.
 async function resolveActiveGeneration(dbRoot) {
     const state = await readControlFile(dbRoot);
     if (state.status === 'valid') {
@@ -251,7 +254,11 @@ async function writeControlState(dbRoot, activeGeneration, expectedCurrentGenera
             );
         }
         const nextSlot = current.control ? (current.control.slotIndex === 0 ? 1 : 0) : 0;
-        const nextGenerationCounter = (current.control?.generationCounter ?? 0) + 1;
+        const generationCounter = current.control?.generationCounter ?? 0n;
+        if (generationCounter === 0xffffffffffffffffn) {
+            throw namedError('StorageError', 'control generation counter exhausted');
+        }
+        const nextGenerationCounter = generationCounter + 1n;
         const encoded = encodeControlSlot(nextGenerationCounter, activeGeneration);
         writeAll(accessHandle, encoded, nextSlot * CONTROL_SLOT_SIZE);
         accessHandle.flush();
@@ -274,19 +281,29 @@ function createGenerationName() {
     const randomPart = Array.from(randomBytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
     return `gen-${timePart}-${randomPart}`;
 }
+async function createGenerationDirectory(dbRoot) {
+    const generationName = createGenerationName();
+    if (await lookupDirectoryHandle(dbRoot, generationName)) {
+        return await createGenerationDirectory(dbRoot);
+    }
+    await dbRoot.getDirectoryHandle(generationName, { create: true });
+    return generationName;
+}
 async function getDbRoot(encodedDbName, createIfMissing) {
     const stackdb = await getOrCreateStackdbRoot();
-    let dbRoot = await lookupDirectoryHandle(stackdb, encodedDbName);
+    if (createIfMissing) {
+        // Creation also opens existing directories, avoiding a separate lookup.
+        return await stackdb.getDirectoryHandle(encodedDbName, { create: true });
+    }
+    const dbRoot = await lookupDirectoryHandle(stackdb, encodedDbName);
     if (!dbRoot) {
-        if (!createIfMissing) {
-            throw new Error(`database ${encodedDbName} does not exist`);
-        }
-        dbRoot = await stackdb.getDirectoryHandle(encodedDbName, { create: true });
+        throw new Error(`database ${encodedDbName} does not exist`);
     }
     return dbRoot;
 }
 async function removeLegacyDataFiles(dbRoot) {
-    for (const fileName of FILE_NAMES) {
+    await FILE_NAMES.reduce(async (previous, fileName) => {
+        await previous;
         try {
             await dbRoot.removeEntry(fileName);
         } catch (err) {
@@ -294,7 +311,7 @@ async function removeLegacyDataFiles(dbRoot) {
                 throw err;
             }
         }
-    }
+    }, Promise.resolve());
 }
 async function resolveActiveDataDir(dbRoot) {
     const activeGeneration = await resolveActiveGeneration(dbRoot);
@@ -309,8 +326,7 @@ async function resolveActiveDataDir(dbRoot) {
     if (!activeDir) {
         throw corruptionError(`active generation ${activeGeneration} is missing`);
     }
-    // A crash after publication but before legacy cleanup leaves stale root
-    // files. They must be gone before this generation accepts writes.
+    // Remove stale legacy files before writes can make this generation newer.
     await removeLegacyDataFiles(dbRoot);
     return {
         dirHandle: activeDir,
@@ -324,9 +340,10 @@ function closeSession(sessionId) {
         return;
     }
     for (const handle of session.handles.values()) {
+        appendOffsets.delete(handle);
         try {
             handle.close();
-        } catch (_err) {}
+        } catch {}
     }
     sessions.delete(sessionId);
 }
@@ -339,24 +356,34 @@ function closeSessionsForDb(encodedDbName) {
     }
 }
 async function openSessionForDir(dbPath, dirHandle, generationName) {
-    const handles = new Map();
-    try {
-        for (let fileKind = 0; fileKind < FILE_NAMES.length; fileKind += 1) {
-            const fileName = FILE_NAMES[fileKind];
+    // Acquire independent files concurrently. Publish the session only after
+    // all handles are acquired; failures must release every acquired handle.
+    const opened = await Promise.allSettled(
+        FILE_NAMES.map(async (fileName) => {
             const fileHandle = await dirHandle.getFileHandle(fileName, { create: true });
             if (typeof fileHandle.createSyncAccessHandle !== 'function') {
                 throw new Error('createSyncAccessHandle is unavailable');
             }
-            const accessHandle = await fileHandle.createSyncAccessHandle();
-            handles.set(fileKind, accessHandle);
+            return await fileHandle.createSyncAccessHandle();
+        })
+    );
+    const handles = new Map();
+    for (let fileKind = 0; fileKind < opened.length; fileKind += 1) {
+        const result = opened[fileKind];
+        if (result.status === 'fulfilled') {
+            handles.set(fileKind, result.value);
         }
-    } catch (error) {
+    }
+    const failed = opened.find((result) => result.status === 'rejected');
+    if (failed) {
+        // Waiting for all results also captures late successes for cleanup.
         for (const handle of handles.values()) {
             try {
                 handle.close();
-            } catch (_err) {}
+            } catch {}
         }
-        throw error;
+        // Error precedence follows FILE_NAMES order, regardless of completion order.
+        throw failed.reason;
     }
     const sessionId = nextSessionId;
     nextSessionId += 1;
@@ -381,11 +408,29 @@ function getAccessHandle(sessionId, fileKind) {
     }
     return handle;
 }
+function rememberFileSize(handle, size) {
+    if (typeof size === 'number' && Number.isSafeInteger(size) && size >= 0) {
+        appendOffsets.set(handle, size);
+    } else {
+        appendOffsets.delete(handle);
+    }
+}
+function readFileSize(handle) {
+    try {
+        const size = handle.getSize();
+        rememberFileSize(handle, size);
+        return size;
+    } catch (error) {
+        appendOffsets.delete(handle);
+        throw error;
+    }
+}
 function lookupOpenFileSize(path) {
     for (const session of sessions.values()) {
         for (let fileKind = 0; fileKind < FILE_NAMES.length; fileKind += 1) {
             if (`${session.path}/${FILE_NAMES[fileKind]}` === path) {
-                return Number(session.handles.get(fileKind)?.getSize() ?? 0);
+                const handle = session.handles.get(fileKind);
+                return Number((handle ? readFileSize(handle) : 0) ?? 0);
             }
         }
     }
@@ -426,6 +471,14 @@ export async function opfsReadActiveGeneration(encodedDbName) {
     const dbRoot = await getDbRoot(encodedDbName, false);
     return await resolveActiveGeneration(dbRoot);
 }
+// The WASM view is valid only during this synchronous call. Zero the unread
+// suffix to preserve the backend read contract when the destination is reused.
+export function opfsReadAtInto(sessionId, fileKind, offset, buffer) {
+    const handle = getAccessHandle(sessionId, fileKind);
+    const read = readAll(handle, buffer, Number(offset));
+    buffer.fill(0, read);
+    return read;
+}
 export function opfsReadAt(sessionId, fileKind, offset, len) {
     const handle = getAccessHandle(sessionId, fileKind);
     const buffer = new Uint8Array(len);
@@ -433,32 +486,67 @@ export function opfsReadAt(sessionId, fileKind, offset, len) {
     return buffer;
 }
 export function opfsWriteAt(sessionId, fileKind, offset, bytes) {
-    return writeAll(getAccessHandle(sessionId, fileKind), bytes, Number(offset));
+    const handle = getAccessHandle(sessionId, fileKind);
+    try {
+        const at = Number(offset);
+        const written = writeAll(handle, bytes, at);
+        // Empty writes cannot extend the file. A successful overwrite alone
+        // cannot establish the full file length.
+        if (written > 0) {
+            const previous = appendOffsets.get(handle);
+            const end = at + written;
+            if (previous !== undefined && Number.isSafeInteger(at) && at >= 0 && Number.isSafeInteger(end)) {
+                appendOffsets.set(handle, Math.max(previous, end));
+            } else {
+                appendOffsets.delete(handle);
+            }
+        }
+        return written;
+    } catch (error) {
+        // A failed write may leave a prefix. The next append must read the
+        // actual file length, even when the thrown value is not an Error.
+        appendOffsets.delete(handle);
+        throw error;
+    }
 }
 export function opfsFlush(sessionId, fileKind) {
-    getAccessHandle(sessionId, fileKind).flush();
+    const handle = getAccessHandle(sessionId, fileKind);
+    try {
+        handle.flush();
+    } catch (error) {
+        appendOffsets.delete(handle);
+        throw error;
+    }
 }
 export function opfsLen(sessionId, fileKind) {
-    return BigInt(getAccessHandle(sessionId, fileKind).getSize());
+    return BigInt(readFileSize(getAccessHandle(sessionId, fileKind)));
+}
+export function opfsAppendOffset(sessionId, fileKind) {
+    const handle = getAccessHandle(sessionId, fileKind);
+    const size = appendOffsets.get(handle);
+    return size === undefined ? opfsLen(sessionId, fileKind) : BigInt(size);
 }
 export function opfsTruncate(sessionId, fileKind, size) {
-    getAccessHandle(sessionId, fileKind).truncate(Number(size));
+    const handle = getAccessHandle(sessionId, fileKind);
+    try {
+        const length = Number(size);
+        handle.truncate(length);
+        rememberFileSize(handle, length);
+    } catch (error) {
+        appendOffsets.delete(handle);
+        throw error;
+    }
 }
 export function opfsCloseSession(sessionId) {
     closeSession(sessionId);
 }
 export async function opfsPrepareRebuildTarget(encodedDbName) {
     const dbRoot = await getDbRoot(encodedDbName, true);
-    let generationName = createGenerationName();
-    while (await lookupDirectoryHandle(dbRoot, generationName)) {
-        generationName = createGenerationName();
-    }
-    await dbRoot.getDirectoryHandle(generationName, { create: true });
+    const generationName = await createGenerationDirectory(dbRoot);
     return { generationName };
 }
-// Publishes `generationName` as the live database. Resolves only after the
-// control file has been flushed and read back selecting the new generation;
-// the caller may switch its live engine only after that.
+// Resolves after the control file is flushed and verified to select the new
+// generation. The caller may then switch its live engine.
 export async function opfsSwapActiveGeneration(encodedDbName, generationName, expectedCurrentGeneration) {
     if (!isGenerationNameValid(generationName)) {
         throw new Error(`invalid generation name ${generationName}`);
@@ -470,8 +558,8 @@ export async function opfsSwapActiveGeneration(encodedDbName, generationName, ex
     }
     await writeControlState(dbRoot, generationName, expectedCurrentGeneration ?? null);
 }
-// Legacy root files are removed strictly (see resolveActiveGeneration); stale
-// generation directories are best effort because nothing can select them.
+// Legacy-file removal must succeed to prevent stale fallback after control
+// damage. Inactive generation cleanup is best effort.
 export async function opfsCleanupInactiveEntries(encodedDbName) {
     const dbRoot = await lookupDirectoryHandle(await getOrCreateStackdbRoot(), encodedDbName);
     if (!dbRoot) {
@@ -487,11 +575,12 @@ export async function opfsCleanupInactiveEntries(encodedDbName) {
             staleDirectories.push(name);
         }
     }
-    for (const name of staleDirectories) {
+    await staleDirectories.reduce(async (previous, name) => {
+        await previous;
         try {
             await dbRoot.removeEntry(name, { recursive: true });
-        } catch (_err) {}
-    }
+        } catch {}
+    }, Promise.resolve());
 }
 export async function opfsDbDirectorySize(encodedDbName) {
     const dbRoot = await lookupDirectoryHandle(await getOrCreateStackdbRoot(), encodedDbName);

package/dist/errors.d.ts

@@ -28,6 +28,9 @@ export declare class UniqueIndexConstraintError extends ConstraintError {
 export declare class WriteTransactionAlreadyOpenError extends MoyoDbError {
     constructor(message?: string);
 }
+export declare class TransactionConflictError extends MoyoDbError {
+    constructor(message?: string);
+}
 export declare class ReadonlyTransactionError extends MoyoDbError {
     constructor(message?: string);
 }
@@ -65,9 +68,9 @@ export declare class ChangeFeedCompactedError extends MoyoDbError {
     constructor(message: string);
 }
 /**
- * The outcome of a commit could not be confirmed (storage failed at or after
- * the WAL append) or the engine hit an unrecoverable fault. The database
- * rejects further work until it is reopened, which replays durable state.
+ * The engine state could not be trusted, or automatic recovery failed.
+ * A failed commit may already be durable. The worker attempts recovery before
+ * a new transaction and after a failed commit. Recovery discards all open transactions.
  */
 export declare class RecoveryRequiredError extends MoyoDbError {
     constructor(message: string);