@rulvar/store-sqlite 1.44.0 → 1.45.0

package/dist/index.d.ts

@@ -19,20 +19,48 @@ interface SqliteStoreOptions {
   now?: () => number;
 }
 declare class SqliteStore implements MetaLookupStore, LeasableStore {
+  /**
+  * The fenced writes promise (fenced run state RFC, phase 2): every
+  * lease-carrying mutation of this store (append, putMeta, delete)
+  * verifies the lease is the current holder FOR THE MUTATED RUN,
+  * atomically with the mutation, and rejects stale or mismatched
+  * holders with the typed LeaseHeldError leaving nothing changed.
+  */
+  readonly fencedWrites = true;
   private readonly db;
   private readonly ttlMs;
   private readonly now;
   constructor(options: SqliteStoreOptions);
   close(): void;
   private liveLease;
+  /**
+  * A lease fences exactly the run it names: guarding a mutation of a
+  * DIFFERENT run with it would pass the holder check while touching
+  * state the lease never protected, so the mismatch rejects typed
+  * before any check runs.
+  */
+  private requireRunMatch;
   /** Rejects unless `lease` is the CURRENT live lease for its run. */
   private assertFencing;
+  /**
+  * Runs the fence check and the guarded mutation as ONE immediate
+  * transaction, the same shape acquire already uses: BEGIN IMMEDIATE
+  * takes the write lock BEFORE the check reads the lease row, so a
+  * competing takeover cannot land between the check and the mutation
+  * (it serializes behind the commit and the loser sees the final rows).
+  * As two autocommit statements, a takeover in that window let a
+  * superseded holder mutate live state (fenced-run-state RFC, F3).
+  */
+  private fenced;
+  private insertEntry;
   append(runId: string, e: JournalEntry, lease?: Lease): Promise<void>;
   load(runId: string): Promise<JournalEntry[]>;
-  putMeta(m: RunMeta): Promise<void>;
+  private upsertMeta;
+  putMeta(m: RunMeta, lease?: Lease): Promise<void>;
   getMeta(runId: string): Promise<RunMeta | undefined>;
   listRuns(f?: RunFilter): Promise<RunMeta[]>;
-  delete(runId: string): Promise<void>;
+  private deleteRows;
+  delete(runId: string, lease?: Lease): Promise<void>;
   /**
   * TTL introspection (the LeasableStore optional capability): lets
   * createWorker verify at construction that its renew cadence matches

package/dist/index.js

@@ -14,7 +14,19 @@ import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter }
 *   through untouched.
 * - Fencing: the epoch is monotonic per run for the store's lifetime;
 *   an append carrying a stale or released lease rejects with the typed
-*   LeaseHeldError and the entry never becomes visible.
+*   LeaseHeldError and the entry never becomes visible. The fence check
+*   and the guarded mutation (append's insert, renew's extension,
+*   release's deletion) commit as ONE immediate transaction: checking in
+*   one autocommit statement and mutating in the next left a
+*   cross-process window where a takeover landing between them let the
+*   superseded holder append a visible entry, extend the successor's
+*   lease, or delete it outright (the fenced-run-state RFC, finding F3).
+* - Fenced writes (`fencedWrites: true`, the RFC's phase 2): putMeta
+*   and delete accept the same optional lease under the same atomic
+*   rule, and every lease-guarded mutation additionally requires the
+*   lease's runId to BE the mutated run, so a superseded worker can
+*   neither strand a run through a stale terminal meta write (F1) nor
+*   delete live run state (F4).
 * - 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.
@@ -25,6 +37,14 @@ import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter }
 const DEFAULT_LEASE_TTL_MS = 6e4;
 const wallClock = Date.now.bind(globalThis);
 var SqliteStore = class {
+	/**
+	* The fenced writes promise (fenced run state RFC, phase 2): every
+	* lease-carrying mutation of this store (append, putMeta, delete)
+	* verifies the lease is the current holder FOR THE MUTATED RUN,
+	* atomically with the mutation, and rejects stale or mismatched
+	* holders with the typed LeaseHeldError leaving nothing changed.
+	*/
+	fencedWrites = true;
 	db;
 	ttlMs;
 	now;
@@ -72,25 +92,73 @@ var SqliteStore = class {
 		if (row === void 0 || row.expires_at <= this.now()) return;
 		return row;
 	}
+	/**
+	* A lease fences exactly the run it names: guarding a mutation of a
+	* DIFFERENT run with it would pass the holder check while touching
+	* state the lease never protected, so the mismatch rejects typed
+	* before any check runs.
+	*/
+	requireRunMatch(lease, runId, mutation) {
+		if (lease.runId !== runId) throw new LeaseHeldError(`lease for run '${lease.runId}' (owner ${lease.owner}, epoch ${lease.epoch}) cannot guard a ${mutation} of run '${runId}'; the mutation is rejected and nothing changed`);
+	}
 	/** Rejects unless `lease` is the CURRENT live lease for its run. */
 	assertFencing(lease) {
 		const live = this.liveLease(lease.runId);
 		if (live === void 0 || live.owner !== lease.owner || live.epoch !== lease.epoch) throw new LeaseHeldError(`stale fencing epoch for run '${lease.runId}': lease (owner ${lease.owner}, epoch ${lease.epoch}) is not the current holder; the append or renew is rejected and nothing became visible`);
 	}
-	async append(runId, e, lease) {
-		if (lease !== void 0) this.assertFencing(lease);
+	/**
+	* Runs the fence check and the guarded mutation as ONE immediate
+	* transaction, the same shape acquire already uses: BEGIN IMMEDIATE
+	* takes the write lock BEFORE the check reads the lease row, so a
+	* competing takeover cannot land between the check and the mutation
+	* (it serializes behind the commit and the loser sees the final rows).
+	* As two autocommit statements, a takeover in that window let a
+	* superseded holder mutate live state (fenced-run-state RFC, F3).
+	*/
+	fenced(lease, mutate) {
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			this.assertFencing(lease);
+			mutate();
+			this.db.exec("COMMIT");
+		} catch (thrown) {
+			this.db.exec("ROLLBACK");
+			throw thrown;
+		}
+	}
+	insertEntry(runId, e) {
 		if (!Number.isFinite(e.seq)) {
 			this.db.prepare("INSERT INTO entries (run_id, payload) VALUES (?, ?)").run(runId, JSON.stringify(e));
 			return;
 		}
 		if (this.db.prepare("INSERT INTO entries (run_id, payload) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM entries WHERE run_id = ? AND CAST(json_extract(payload, '$.seq') AS INTEGER) >= ?)").run(runId, JSON.stringify(e), runId, e.seq).changes === 0) throw new JournalOrderViolation(`SqliteStore: append of seq ${e.seq} to run '${runId}' is not after the stored tail seq; a concurrent writer raced this journal from a stale tail`);
 	}
+	async append(runId, e, lease) {
+		if (lease !== void 0) {
+			this.requireRunMatch(lease, runId, "journal append");
+			this.fenced(lease, () => {
+				this.insertEntry(runId, e);
+			});
+			return;
+		}
+		this.insertEntry(runId, e);
+	}
 	async load(runId) {
 		return this.db.prepare("SELECT payload FROM entries WHERE run_id = ? ORDER BY id").all(runId).map((row) => JSON.parse(row.payload));
 	}
-	async putMeta(m) {
+	upsertMeta(m) {
 		this.db.prepare("INSERT INTO meta (run_id, payload) VALUES (?, ?) ON CONFLICT(run_id) DO UPDATE SET payload = excluded.payload").run(m.runId, JSON.stringify(m));
 	}
+	async putMeta(m, lease) {
+		if (lease !== void 0) {
+			this.requireRunMatch(lease, m.runId, "meta write");
+			this.fenced(lease, () => {
+				this.upsertMeta(m);
+			});
+			return;
+		}
+		this.upsertMeta(m);
+	}
 	async getMeta(runId) {
 		const row = this.db.prepare("SELECT payload FROM meta WHERE run_id = ?").get(runId);
 		return row === void 0 ? void 0 : JSON.parse(row.payload);
@@ -113,13 +181,23 @@ var SqliteStore = class {
 		const sql = "SELECT payload FROM meta" + (where.length === 0 ? "" : ` WHERE ${where.join(" AND ")}`) + " ORDER BY run_id";
 		return this.db.prepare(sql).all(...params).map((row) => JSON.parse(row.payload)).filter((meta) => metaMatchesFilter(meta, f));
 	}
-	async delete(runId) {
+	deleteRows(runId) {
+		this.db.prepare("DELETE FROM entries WHERE run_id = ?").run(runId);
+		this.db.prepare("DELETE FROM meta WHERE run_id = ?").run(runId);
+		this.db.prepare("DELETE FROM leases WHERE run_id = ?").run(runId);
+		this.db.prepare("DELETE FROM epochs WHERE run_id = ?").run(runId);
+	}
+	async delete(runId, lease) {
+		if (lease !== void 0) {
+			this.requireRunMatch(lease, runId, "run deletion");
+			this.fenced(lease, () => {
+				this.deleteRows(runId);
+			});
+			return;
+		}
 		this.db.exec("BEGIN IMMEDIATE");
 		try {
-			this.db.prepare("DELETE FROM entries WHERE run_id = ?").run(runId);
-			this.db.prepare("DELETE FROM meta WHERE run_id = ?").run(runId);
-			this.db.prepare("DELETE FROM leases WHERE run_id = ?").run(runId);
-			this.db.prepare("DELETE FROM epochs WHERE run_id = ?").run(runId);
+			this.deleteRows(runId);
 			this.db.exec("COMMIT");
 		} catch (thrown) {
 			this.db.exec("ROLLBACK");
@@ -154,12 +232,14 @@ var SqliteStore = class {
 		}
 	}
 	async renew(l) {
-		this.assertFencing(l);
-		this.db.prepare("UPDATE leases SET expires_at = ? WHERE run_id = ?").run(this.now() + this.ttlMs, l.runId);
+		this.fenced(l, () => {
+			this.db.prepare("UPDATE leases SET expires_at = ? WHERE run_id = ? AND owner = ? AND epoch = ?").run(this.now() + this.ttlMs, l.runId, l.owner, l.epoch);
+		});
 	}
 	async release(l) {
-		this.assertFencing(l);
-		this.db.prepare("DELETE FROM leases WHERE run_id = ?").run(l.runId);
+		this.fenced(l, () => {
+			this.db.prepare("DELETE FROM leases WHERE run_id = ? AND owner = ? AND epoch = ?").run(l.runId, l.owner, l.epoch);
+		});
 	}
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-sqlite",
-  "version": "1.44.0",
+  "version": "1.45.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.44.0"
+    "@rulvar/core": "1.45.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.44.0"
+    "@rulvar/store-conformance": "1.45.0"
   },
   "repository": {
     "type": "git",