@rulvar/store-sqlite 1.47.0 → 1.48.0

package/dist/index.d.ts

@@ -3,6 +3,16 @@ import { JournalEntry, LeasableStore, Lease, MetaLookupStore, RunFilter, RunMeta
 //#region src/store.d.ts
 /** Appendix A interim reference for the sqlite store. */
 declare const DEFAULT_LEASE_TTL_MS = 6e4;
+/**
+* Total time the constructor keeps retrying its schema bootstrap
+* through SQLITE_BUSY before giving up, so concurrent multi-process
+* construction over one fresh file serializes instead of dying raw.
+* The bound applies ONLY to boot; every runtime contention path keeps
+* the documented fail-fast semantics (busy surfaces immediately). A
+* boot still busy past the bound throws the driver's error: something
+* is wedged, not merely concurrent.
+*/
+declare const BOOT_BUSY_TIMEOUT_MS = 5e3;
 interface SqliteStoreOptions {
   /** Database file path, or ':memory:' for an in-process store. */
   path: string;
@@ -103,4 +113,4 @@ declare class SqliteStore implements MetaLookupStore, LeasableStore {
   release(l: Lease): Promise<void>;
 }
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, SqliteStore, type SqliteStoreOptions, type SqliteTranscriptStore };
+export { BOOT_BUSY_TIMEOUT_MS, DEFAULT_LEASE_TTL_MS, SqliteStore, type SqliteStoreOptions, type SqliteTranscriptStore };

package/dist/index.js

@@ -35,11 +35,43 @@ import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter }
 * - acquire on a held, unexpired lease rejects with LeaseHeldError; the
 *   holder MUST renew at an interval of at most ttl/3; an unrenewed
 *   lease is reclaimable after ttl and reclaiming advances the epoch.
+* - Concurrent boot: constructing over one shared file from several
+*   processes at once serializes on a boot-scoped busy timeout
+*   (BOOT_BUSY_TIMEOUT_MS) instead of dying raw in the schema
+*   bootstrap; runtime contention stays fail fast (busy 0).
 * - The lease ttl default is the Appendix A interim reference for this
 *   store (60000 ms; the committed value is decided before M8).
 */
 /** Appendix A interim reference for the sqlite store. */
 const DEFAULT_LEASE_TTL_MS = 6e4;
+/**
+* Total time the constructor keeps retrying its schema bootstrap
+* through SQLITE_BUSY before giving up, so concurrent multi-process
+* construction over one fresh file serializes instead of dying raw.
+* The bound applies ONLY to boot; every runtime contention path keeps
+* the documented fail-fast semantics (busy surfaces immediately). A
+* boot still busy past the bound throws the driver's error: something
+* is wedged, not merely concurrent.
+*/
+const BOOT_BUSY_TIMEOUT_MS = 5e3;
+/**
+* The SQLITE_BUSY family, the one boot error class worth a bounded
+* retry. The driver reports EXTENDED result codes (a concurrent boot
+* also yields SQLITE_BUSY_RECOVERY 261 while a sibling process is
+* recovering the fresh WAL), so the primary code is the low byte.
+*/
+function isSqliteBusy(thrown) {
+	const errcode = thrown?.errcode;
+	return errcode !== void 0 && (errcode & 255) === 5;
+}
+/**
+* Synchronous bounded sleep for the boot retry loop (the constructor is
+* synchronous by SPI shape): Atomics.wait blocks the thread for the few
+* milliseconds another process needs to finish the shared bootstrap.
+*/
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 const wallClock = Date.now.bind(globalThis);
 var SqliteStore = class {
 	/**
@@ -60,7 +92,7 @@ var SqliteStore = class {
 		this.db = new DatabaseSync(options.path);
 		this.ttlMs = ttlMs;
 		this.now = options.now ?? wallClock;
-		this.db.exec(`
+		const schema = `
       PRAGMA journal_mode = WAL;
       CREATE TABLE IF NOT EXISTS entries (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -94,7 +126,15 @@ var SqliteStore = class {
         data BLOB NOT NULL
       );
       CREATE INDEX IF NOT EXISTS blobs_by_run ON blobs (run_id);
-    `);
+    `;
+		const bootDeadline = wallClock() + BOOT_BUSY_TIMEOUT_MS;
+		for (let attempt = 0;; attempt += 1) try {
+			this.db.exec(schema);
+			break;
+		} catch (thrown) {
+			if (!isSqliteBusy(thrown) || wallClock() > bootDeadline) throw thrown;
+			sleepSync(2 + attempt % 7);
+		}
 	}
 	close() {
 		this.db.close();
@@ -314,4 +354,4 @@ var SqliteStore = class {
 	}
 };
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, SqliteStore };
+export { BOOT_BUSY_TIMEOUT_MS, DEFAULT_LEASE_TTL_MS, SqliteStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-sqlite",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "description": "Rulvar SQLite store implementing JournalStore and LeasableStore with a fencing epoch.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.47.0"
+    "@rulvar/core": "1.48.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.47.0"
+    "@rulvar/store-conformance": "1.48.0"
   },
   "repository": {
     "type": "git",