@rulvar/store-sqlite 1.45.0 → 1.47.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,6 +18,17 @@ 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
@@ -30,6 +41,7 @@ declare class SqliteStore implements MetaLookupStore, LeasableStore {
   private readonly db;
   private readonly ttlMs;
   private readonly now;
+  private transcriptTwin;
   constructor(options: SqliteStoreOptions);
   close(): void;
   private liveLease;
@@ -62,6 +74,25 @@ declare class SqliteStore implements MetaLookupStore, LeasableStore {
   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
   * this store's expiry instead of trusting two config sources to agree.
@@ -72,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

@@ -27,6 +27,11 @@ import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter }
 *   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.
@@ -48,6 +53,7 @@ var SqliteStore = class {
 	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)}`);
@@ -82,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() {
@@ -205,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.45.0",
+  "version": "1.47.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.45.0"
+    "@rulvar/core": "1.47.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.45.0"
+    "@rulvar/store-conformance": "1.47.0"
   },
   "repository": {
     "type": "git",