@oxidezap/baileyrs 0.2.11 → 0.2.12

package/lib/Utils/use-bridge-store.d.ts

@@ -1,13 +1,84 @@
 import type { AuthenticationState } from '../Types/index.js';
+/**
+ * Pure classifier for directory-barrier failures: does this error mean
+ * "this platform cannot sync directory handles" (degrade to process-crash
+ * atomicity) or "the durability barrier did not hold" (propagate)?
+ *
+ * - `ENOSYS` / `ENOTSUP` on any platform: the operation is not
+ *   implemented — genuinely unsupported, safe to degrade.
+ * - `EINVAL` / `EPERM` / `EISDIR` on `win32` only: Windows directory
+ *   handles reject open-for-read and FlushFileBuffers with these codes,
+ *   so they are the documented platform fallback there. On Linux/macOS
+ *   the same codes from a freshly opened directory handle mean something
+ *   is genuinely wrong and they propagate.
+ * - Everything else propagates everywhere: `EIO`, `ENOSPC`, `EROFS`,
+ *   `EACCES`, `ENOENT`, and notably `EBADF` (a bad handle is a real bug,
+ *   never evidence of an unsupported platform).
+ *
+ * `platform` defaults to the running platform; tests pass explicit values
+ * to cover the matrix deterministically on any OS.
+ */
+export declare const isUnsupportedDirSync: (e: unknown, platform?: NodeJS.Platform) => boolean;
+type BridgeStoreFileHandle = {
+    writeFile(value: Uint8Array): Promise<void>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+};
+type BridgeStoreFileIO = {
+    writeTmp?(tmpPath: string, value: Uint8Array): Promise<void>;
+    publishTmp?(tmpPath: string, finalPath: string): Promise<void>;
+    syncDir?(dir: string): Promise<void>;
+    openTmp?(tmpPath: string): Promise<BridgeStoreFileHandle>;
+};
+type BridgeStoreOptions = {
+    io?: BridgeStoreFileIO;
+};
 /**
  * Creates a file-based store for the WASM bridge.
  *
  * Each (store, key) pair maps to a file: `<folder>/<store>-<key>.bin`
  *
- * Uses a write-through in-memory cache to avoid redundant disk reads.
- * Writes go to both cache and disk. Reads hit cache first, disk on miss.
+ * Durability model:
+ * - Caller buffers are copied synchronously at admission (`set`/`setMany`
+ *   copy before queueing), so mutating a buffer after the call — even
+ *   before awaiting it — can never change what gets persisted.
+ * - Critical stores write through `durableWrite` before `set`/`setMany`
+ *   resolve. The in-memory map only records bytes AFTER the full barrier
+ *   (write + fsync + atomic rename + directory sync) succeeds, so an
+ *   identical retry following a failure is never skipped and always
+ *   re-attempts the write.
+ * - If the post-rename barrier fails, the key is marked uncertain: prior
+ *   durable knowledge is discarded, reads serve best-available bytes
+ *   without re-certifying them, and no identical set is skipped until a
+ *   later operation completes the full barrier for that key.
+ * - Non-critical stores are debounced (50ms coalescing) and readable
+ *   immediately (read-your-write), but such reads are NOT durable until
+ *   `flush()` succeeds. A failed flush keeps the pending entry and throws,
+ *   so the next `flush()` retries the same bytes.
+ * - `flush()` first waits for every operation admitted before it
+ *   (barrier), then drains the pending writes those operations produced.
+ *   Failures observed by the barrier propagate — a failed admitted write
+ *   fails the flush — but only operations outstanding during that flush
+ *   are reported, so history never poisons later flushes. A drain pass
+ *   with any failure stops at that pass and leaves the failed entries
+ *   for the next explicit flush. `flush()` never reports quiescence
+ *   while prior admitted work is still running.
+ * - All operations on one key (set, delete, flush, concurrent batches) run
+ *   through a per-key chain, so a stale failure can never erase newer
+ *   state and an in-flight write can never resurrect a deleted key.
+ * - A failed delete restores the preceding pending/durable state, so an
+ *   acknowledged value stays readable and flushable; only a successful
+ *   delete (unlink + directory barrier) clears it. A delete retried while
+ *   the key is uncertain re-runs the directory barrier instead of
+ *   swallowing the uncertainty as idempotent absence — except that a
+ *   directory removed externally surfaces ENOENT rather than success.
+ * - Every byte array handed back to callers is a copy.
  *
  * @param folder Directory to store bridge state files
+ * @param options Optional per-store file-I/O steps. Test/fault-injection
+ *   seam only: the default implementation is the sole provider of the
+ *   durability contract above.
  */
-export declare function useBridgeStore(folder: string): Promise<NonNullable<AuthenticationState['store']>>;
+export declare function useBridgeStore(folder: string, options?: BridgeStoreOptions): Promise<NonNullable<AuthenticationState['store']>>;
+export {};
 //# sourceMappingURL=use-bridge-store.d.ts.map