@rulvar/store-sqlite 1.44.1 → 1.46.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JournalEntry, LeasableStore, Lease, MetaLookupStore, RunFilter, RunMeta } from "@rulvar/core";
+import { JournalEntry, LeasableStore, Lease, MetaLookupStore, RunFilter, RunMeta, TranscriptStore } from "@rulvar/core";
 
 //#region src/store.d.ts
 /** Appendix A interim reference for the sqlite store. */
@@ -18,13 +18,40 @@ interface SqliteStoreOptions {
   /** Injectable clock for lease-expiry tests. */
   now?: () => number;
 }
+/**
+* The fenced transcript twin over a SqliteStore database (the fenced
+* run state RFC, F2): a TranscriptStore that declares `fencedWrites`
+* because its blobs live in the SAME database as the lease rows, giving
+* the fence check and the blob mutation one transactional domain.
+* Obtain it from {@link SqliteStore.transcripts}; its lifetime is the
+* owning store's (one shared connection, one `close()`).
+*/
+interface SqliteTranscriptStore extends TranscriptStore {
+  readonly fencedWrites: true;
+}
 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;
+  private transcriptTwin;
   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;
   /**
@@ -40,10 +67,31 @@ declare class SqliteStore implements MetaLookupStore, LeasableStore {
   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>;
+  /**
+  * The fenced transcript twin (fenced run state RFC, F2): a
+  * TranscriptStore whose blobs live in THIS store's database, beside
+  * the lease rows, so a lease-carrying put or delete verifies the
+  * current holder of the run the ref's leading path segment names
+  * atomically with the blob mutation, in the same one-immediate-
+  * transaction shape as the journal side. Sharing the connection is
+  * what makes the capability implementable at all (a blob write and a
+  * lease check in different domains cannot commit as one unit; with
+  * ':memory:' a separate connection would not even see the leases) and
+  * keeps one close() lifecycle. Wire it as the engine's transcript
+  * store next to this store as the journal: over the pair every
+  * durable run mutation is fenced, which is what
+  * `assertFencedWrites({ journal, transcripts })` verifies. The blob
+  * cascade of `deleteRun`/`pruneRun` stays ENGINE-side, exactly as the
+  * TranscriptStore contract says; the journal-side `delete(runId)`
+  * never touches blob rows.
+  */
+  transcripts(): SqliteTranscriptStore;
   /**
   * TTL introspection (the LeasableStore optional capability): lets
   * createWorker verify at construction that its renew cadence matches
@@ -55,4 +103,4 @@ declare class SqliteStore implements MetaLookupStore, LeasableStore {
   release(l: Lease): Promise<void>;
 }
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, SqliteStore, type SqliteStoreOptions };
+export { DEFAULT_LEASE_TTL_MS, SqliteStore, type SqliteStoreOptions, type SqliteTranscriptStore };

package/dist/index.js

@@ -21,6 +21,17 @@ import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter }
 *   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).
+* - Fenced transcripts (the RFC's F2): transcripts() returns the
+*   TranscriptStore twin over this same database, so checkpoint,
+*   compaction, worktree patch, and workflow source blobs are fenced
+*   under the identical atomic rule, and a superseded segment's late
+*   checkpoint save cannot regress the blob a later boot decodes.
 * - 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.
@@ -31,9 +42,18 @@ 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;
+	transcriptTwin;
 	constructor(options) {
 		const ttlMs = options.ttlMs ?? 6e4;
 		if (!Number.isInteger(ttlMs) || ttlMs < 1 || ttlMs > 2147483647) throw new ConfigError(`SqliteStoreOptions.ttlMs must be an integer between 1 and 2147483647 ms (workers renew on Node timers at ttl/3); got ${String(ttlMs)}`);
@@ -68,6 +88,12 @@ var SqliteStore = class {
         run_id TEXT PRIMARY KEY,
         epoch INTEGER NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS blobs (
+        ref TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL,
+        data BLOB NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS blobs_by_run ON blobs (run_id);
     `);
 	}
 	close() {
@@ -78,6 +104,15 @@ 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);
@@ -112,6 +147,7 @@ var SqliteStore = class {
 	}
 	async append(runId, e, lease) {
 		if (lease !== void 0) {
+			this.requireRunMatch(lease, runId, "journal append");
 			this.fenced(lease, () => {
 				this.insertEntry(runId, e);
 			});
@@ -122,9 +158,19 @@ var SqliteStore = class {
 	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);
@@ -147,13 +193,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");
@@ -161,6 +217,65 @@ var SqliteStore = class {
 		}
 	}
 	/**
+	* The fenced transcript twin (fenced run state RFC, F2): a
+	* TranscriptStore whose blobs live in THIS store's database, beside
+	* the lease rows, so a lease-carrying put or delete verifies the
+	* current holder of the run the ref's leading path segment names
+	* atomically with the blob mutation, in the same one-immediate-
+	* transaction shape as the journal side. Sharing the connection is
+	* what makes the capability implementable at all (a blob write and a
+	* lease check in different domains cannot commit as one unit; with
+	* ':memory:' a separate connection would not even see the leases) and
+	* keeps one close() lifecycle. Wire it as the engine's transcript
+	* store next to this store as the journal: over the pair every
+	* durable run mutation is fenced, which is what
+	* `assertFencedWrites({ journal, transcripts })` verifies. The blob
+	* cascade of `deleteRun`/`pruneRun` stays ENGINE-side, exactly as the
+	* TranscriptStore contract says; the journal-side `delete(runId)`
+	* never touches blob rows.
+	*/
+	transcripts() {
+		if (this.transcriptTwin !== void 0) return this.transcriptTwin;
+		const runOf = (ref) => ref.split("/", 1)[0] ?? ref;
+		const upsertBlob = (ref, blob) => {
+			this.db.prepare("INSERT INTO blobs (ref, run_id, data) VALUES (?, ?, ?) ON CONFLICT(ref) DO UPDATE SET run_id = excluded.run_id, data = excluded.data").run(ref, runOf(ref), blob);
+		};
+		const deleteBlob = (ref) => {
+			this.db.prepare("DELETE FROM blobs WHERE ref = ?").run(ref);
+		};
+		this.transcriptTwin = {
+			fencedWrites: true,
+			put: async (ref, blob, lease) => {
+				if (lease !== void 0) {
+					this.requireRunMatch(lease, runOf(ref), "transcript write");
+					this.fenced(lease, () => {
+						upsertBlob(ref, blob);
+					});
+					return;
+				}
+				upsertBlob(ref, blob);
+			},
+			get: async (ref) => {
+				const row = this.db.prepare("SELECT data FROM blobs WHERE ref = ?").get(ref);
+				return row === void 0 ? null : new Uint8Array(row.data);
+			},
+			list: async (runId) => {
+				return this.db.prepare("SELECT ref FROM blobs WHERE run_id = ? AND ref <> run_id ORDER BY ref").all(runId).map((row) => row.ref);
+			},
+			delete: async (ref, lease) => {
+				if (lease !== void 0) {
+					this.requireRunMatch(lease, runOf(ref), "transcript deletion");
+					this.fenced(lease, () => {
+						deleteBlob(ref);
+					});
+					return;
+				}
+				deleteBlob(ref);
+			}
+		};
+		return this.transcriptTwin;
+	}
+	/**
 	* TTL introspection (the LeasableStore optional capability): lets
 	* createWorker verify at construction that its renew cadence matches
 	* this store's expiry instead of trusting two config sources to agree.

package/package.json

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