@openparachute/vault 0.6.5-rc.1 → 0.6.5-rc.2

package/core/src/txn.test.ts

@@ -103,6 +103,74 @@ describe("transaction (sync)", () => {
   });
 });
 
+describe("transaction — native transactionSync preference (DO backend)", () => {
+  /** A db that exposes a native `transactionSync` (standing in for a Durable
+   *  Object shim delegating to `ctx.storage.transactionSync`). Here it's backed
+   *  by bun's own `.transaction()` so rollback-on-throw is real, while the raw
+   *  BEGIN/COMMIT it issues internally never flow through our `exec` — letting
+   *  us assert the seam issued no explicit transaction SQL. */
+  function nativeDb(): { db: TxnCapableDb; execs: string[]; bun: Database } {
+    const bun = freshDb();
+    const execs: string[] = [];
+    const db: TxnCapableDb = {
+      exec(sql: string): void {
+        execs.push(sql);
+        bun.exec(sql);
+      },
+      transactionSync<T>(fn: () => T): T {
+        return bun.transaction(fn)();
+      },
+    };
+    return { db, execs, bun };
+  }
+
+  it("prefers transactionSync over BEGIN IMMEDIATE — delegates once, issues no raw txn SQL", () => {
+    const calls: string[] = [];
+    const state = { txnCalls: 0 };
+    const db: TxnCapableDb = {
+      exec(sql: string): void { calls.push(sql); },
+      transactionSync<T>(fn: () => T): T { state.txnCalls++; return fn(); },
+    };
+    const result = transaction(db, () => { db.exec("WORK"); return "ok"; });
+    expect(result).toBe("ok");
+    expect(state.txnCalls).toBe(1);
+    // Only the inner write — never BEGIN IMMEDIATE / COMMIT / ROLLBACK.
+    expect(calls).toEqual(["WORK"]);
+  });
+
+  it("commits via native transactionSync and returns the callback's value", () => {
+    const { db, bun } = nativeDb();
+    const result = transaction(db, () => {
+      db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+      return 42;
+    });
+    expect(result).toBe(42);
+    expect((bun.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(1);
+  });
+
+  it("rolls back through the native transactionSync on a throw, re-throwing the ORIGINAL error", () => {
+    const { db, execs, bun } = nativeDb();
+    const sentinel = new Error("native boom");
+    expect(() =>
+      transaction(db, () => {
+        db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+        throw sentinel;
+      }),
+    ).toThrow(sentinel);
+    // Real rollback — the write did not persist.
+    expect((bun.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(0);
+    // The seam issued NO raw transaction SQL of its own (the native primitive
+    // owns BEGIN/COMMIT/ROLLBACK internally); only the inner INSERT flowed through.
+    expect(execs).toEqual(["INSERT INTO t (id, v) VALUES (1, 'a')"]);
+  });
+
+  it("bun path unchanged when the db has no transactionSync (BEGIN IMMEDIATE … COMMIT)", () => {
+    const { db, calls } = fakeDb(); // no transactionSync
+    transaction(db, () => "ok");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT"]);
+  });
+});
+
 describe("transactionAsync", () => {
   it("commits and returns the callback's resolved value", async () => {
     const db = freshDb();

package/core/src/txn.ts

@@ -23,18 +23,38 @@
  */
 
 /** The minimal DB surface the transaction seam needs — kept structural (no
- *  `bun:sqlite` import) so a non-bun backend satisfies it too. */
+ *  `bun:sqlite` import) so a non-bun backend satisfies it too.
+ *
+ *  `transactionSync` is OPTIONAL: a backend whose engine blocks explicit
+ *  `BEGIN`/`COMMIT` (Cloudflare Durable Objects — `sql.exec` throws on them)
+ *  exposes a native synchronous transaction primitive instead, and
+ *  {@link transaction} delegates to it. bun's `Database` has no such method, so
+ *  it takes the `BEGIN IMMEDIATE` path — the check is a duck-type, never a
+ *  behavior change for the bun backend. */
 export interface TxnCapableDb {
   exec(sql: string): void;
+  /** Native commit-on-return / rollback-on-throw transaction, when the backend
+   *  provides one (e.g. a DO shim delegating to `ctx.storage.transactionSync`). */
+  transactionSync?<T>(fn: () => T): T;
 }
 
 /**
  * Run `fn` inside a single write transaction, committing its result or
- * rolling back on throw. Synchronous — the callback must not await (DO's
- * `transactionSync` is sync-only; see `transactionAsync` for the batch paths
- * that legitimately await the async Store facade).
+ * rolling back on throw. Synchronous — the callback must not await (see
+ * `transactionAsync` for the batch paths that legitimately await the async
+ * Store facade).
+ *
+ * When the backing db exposes a native `transactionSync` (a backend whose
+ * engine blocks raw `BEGIN`/`COMMIT` — Durable Objects), we delegate to it: a
+ * real transaction with the same commit-on-return / rollback-on-throw contract,
+ * without ever issuing the explicit transaction SQL that backend rejects. bun's
+ * `Database` has no `transactionSync`, so it takes the `BEGIN IMMEDIATE` path
+ * below unchanged.
  */
 export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
+  if (typeof db.transactionSync === "function") {
+    return db.transactionSync(fn);
+  }
   db.exec("BEGIN IMMEDIATE");
   try {
     const result = fn();
@@ -60,6 +80,13 @@ export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
  * same shape as the pre-seam `if (batched) db.exec("BEGIN")` blocks in
  * mcp.ts / routes.ts. A DO backend can't map this onto `transactionSync`
  * (which forbids awaiting); porting the batch path is a Phase-2 concern.
+ *
+ * Deliberately NOT given the `db.transactionSync` fast-path that {@link transaction}
+ * has: `transactionSync` runs its callback synchronously and forbids awaiting,
+ * so it cannot wrap an `async` body that awaits the Store facade between writes.
+ * A DO backend that needs an atomic async batch has to reshape the batch as a
+ * synchronous unit (or use an async DO transaction primitive) — out of scope
+ * for this seam; the raw `BEGIN IMMEDIATE` path stays the single implementation.
  */
 export async function transactionAsync<T>(db: TxnCapableDb, fn: () => Promise<T>): Promise<T> {
   db.exec("BEGIN IMMEDIATE");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.5-rc.1",
+  "version": "0.6.5-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",