@openparachute/vault 0.6.4 → 0.6.5-rc.2

package/core/src/schema.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
+import { transaction } from "./txn.js";
 
 export const SCHEMA_VERSION = 23;
 
@@ -680,8 +681,7 @@ function migrateToV13(db: Database): void {
 function migrateToV14(db: Database): void {
   if (!hasTable(db, "tags")) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const { copiedSchemas, copiedHierarchy } = transaction(db, () => {
     // 1. ALTER TABLE — additive, idempotent.
     const cols: [string, string][] = [
       ["description", "TEXT"],
@@ -762,16 +762,13 @@ function migrateToV14(db: Database): void {
       db.exec("DROP TABLE tag_schemas");
     }
 
-    db.exec("COMMIT");
+    return { copiedSchemas, copiedHierarchy };
+  });
 
-    if (copiedSchemas > 0 || copiedHierarchy > 0) {
-      console.log(
-        `[vault] migrated to schema v14: copied ${copiedSchemas} tag_schemas + ${copiedHierarchy} _tags/* hierarchies onto tags rows`,
-      );
-    }
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
+  if (copiedSchemas > 0 || copiedHierarchy > 0) {
+    console.log(
+      `[vault] migrated to schema v14: copied ${copiedSchemas} tag_schemas + ${copiedHierarchy} _tags/* hierarchies onto tags rows`,
+    );
   }
 }
 
@@ -806,8 +803,7 @@ function migrateToV15(db: Database): void {
   ).get()) !== null;
   if (hasSchemas || hasMappings) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const { copiedSchemas, copiedMappings } = transaction(db, () => {
     const now = new Date().toISOString();
     let copiedSchemas = 0;
     let copiedMappings = 0;
@@ -884,16 +880,13 @@ function migrateToV15(db: Database): void {
       }
     }
 
-    db.exec("COMMIT");
+    return { copiedSchemas, copiedMappings };
+  });
 
-    if (copiedSchemas > 0 || copiedMappings > 0) {
-      console.log(
-        `[vault] migrated to schema v15: copied ${copiedSchemas} _schemas/* + ${copiedMappings} _schema_defaults mappings into note_schemas/schema_mappings`,
-      );
-    }
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
+  if (copiedSchemas > 0 || copiedMappings > 0) {
+    console.log(
+      `[vault] migrated to schema v15: copied ${copiedSchemas} _schemas/* + ${copiedMappings} _schema_defaults mappings into note_schemas/schema_mappings`,
+    );
   }
 }
 
@@ -922,15 +915,10 @@ function migrateToV16(db: Database): void {
   // ALTER block so a fresh vault — where the column exists but the index
   // doesn't — still gets it.
   if (!hasColumn(db, "tokens", "vault_name")) {
-    db.exec("BEGIN IMMEDIATE");
-    try {
+    transaction(db, () => {
       db.exec("ALTER TABLE tokens ADD COLUMN vault_name TEXT");
       db.exec("CREATE INDEX IF NOT EXISTS idx_tokens_vault_name ON tokens(vault_name)");
-      db.exec("COMMIT");
-    } catch (err) {
-      db.exec("ROLLBACK");
-      throw err;
-    }
+    });
     return;
   }
 
@@ -980,8 +968,7 @@ function migrateToV17(db: Database): void {
     ).all() as { schema_name: string; match_kind: string; match_value: string }[];
   }
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  transaction(db, () => {
     // Drop the index first — the index references the table; SQLite would
     // tear it down on DROP TABLE but the explicit DROP keeps the order
     // obvious if a future migration reads from sqlite_master mid-flight.
@@ -993,11 +980,7 @@ function migrateToV17(db: Database): void {
     if (hasNoteSchemas) {
       db.exec("DROP TABLE note_schemas");
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   if (droppedSchemas.length > 0 || droppedMappings.length > 0) {
     const schemaNames = droppedSchemas.map((s) => s.name).join(", ");
@@ -1052,8 +1035,7 @@ function migrateToV18(db: Database): void {
   const hasNewUnique = indexes.some((r) => r.name === "idx_notes_path_ext_unique");
   if (!needsColumn && hasNewUnique && !hasOldUnique) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  transaction(db, () => {
     if (needsColumn) {
       db.exec("ALTER TABLE notes ADD COLUMN extension TEXT NOT NULL DEFAULT 'md'");
     }
@@ -1065,11 +1047,7 @@ function migrateToV18(db: Database): void {
         "CREATE UNIQUE INDEX idx_notes_path_ext_unique ON notes(path, extension) WHERE path IS NOT NULL",
       );
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 }
 
 /**

package/core/src/store.ts

@@ -12,6 +12,7 @@ import {
 } from "./indexed-fields.js";
 import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
+import { transaction } from "./txn.js";
 import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
@@ -55,6 +56,15 @@ export class BunSqliteStore implements Store {
     this.hooks = opts?.hooks ?? new HookRegistry();
   }
 
+  /**
+   * The transaction seam (see core/src/txn.ts). bun backs it with
+   * `BEGIN IMMEDIATE … COMMIT`; a DO-backed Store overrides this with
+   * `ctx.storage.transactionSync`. Synchronous — `fn` must not await.
+   */
+  transaction<T>(fn: () => T): T {
+    return transaction(this.db, fn);
+  }
+
   /**
    * Lazy accessor for the `_tags/*` config-note hierarchy. First call after
    * boot or after an invalidation does the scan; subsequent calls hit the
@@ -716,10 +726,8 @@ export class BunSqliteStore implements Store {
     // mismatch only detectable once the existing declarer set is consulted),
     // the whole write rolls back — the schema never ends up claiming an index
     // that doesn't exist. vault#478 transactional fix.
-    let result: tagSchemaOps.TagRecord;
-    this.db.exec("BEGIN IMMEDIATE");
-    try {
-      result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+    const result = this.transaction(() => {
+      const record = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
 
       if (patch.fields !== undefined) {
         for (const fieldName of nextIndexed) {
@@ -734,11 +742,8 @@ export class BunSqliteStore implements Store {
           }
         }
       }
-      this.db.exec("COMMIT");
-    } catch (err) {
-      this.db.exec("ROLLBACK");
-      throw err;
-    }
+      return record;
+    });
 
     if (patch.parent_names !== undefined) {
       // parent_names drives both query expansion (tag hierarchy) AND, post

package/core/src/txn.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Contract tests for the transaction seam (core/src/txn.ts).
+ *
+ * Pins the behavior every migrated call site now depends on: commit returns
+ * the callback's value, a throw rolls back and re-throws the ORIGINAL error,
+ * and a ROLLBACK that itself fails (the "COMMIT already resolved the txn"
+ * case) is swallowed so the original error still propagates. The swallow /
+ * ordering cases use a structural fake `TxnCapableDb` so we can force a
+ * COMMIT/ROLLBACK failure deterministically; the happy + real-rollback cases
+ * run against a live bun:sqlite connection.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { transaction, transactionAsync, type TxnCapableDb } from "./txn.js";
+
+/** A fake `TxnCapableDb` that records exec calls and can be told to throw on
+ *  COMMIT and/or ROLLBACK — lets us drive the failure branches exactly. */
+function fakeDb(opts: { commitThrows?: Error; rollbackThrows?: Error } = {}): {
+  db: TxnCapableDb;
+  calls: string[];
+} {
+  const calls: string[] = [];
+  const db: TxnCapableDb = {
+    exec(sql: string): void {
+      calls.push(sql);
+      if (sql === "COMMIT" && opts.commitThrows) throw opts.commitThrows;
+      if (sql === "ROLLBACK" && opts.rollbackThrows) throw opts.rollbackThrows;
+    },
+  };
+  return { db, calls };
+}
+
+function freshDb(): Database {
+  const db = new Database(":memory:");
+  db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)");
+  return db;
+}
+
+describe("transaction (sync)", () => {
+  it("commits and returns the callback's value", () => {
+    const db = freshDb();
+    const result = transaction(db, () => {
+      db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+      return { count: 1 };
+    });
+    expect(result).toEqual({ count: 1 });
+    // Write is durable after commit.
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(1);
+  });
+
+  it("wraps in BEGIN IMMEDIATE … COMMIT", () => {
+    const { db, calls } = fakeDb();
+    transaction(db, () => "ok");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT"]);
+  });
+
+  it("rolls back and re-throws the ORIGINAL error when the callback throws", () => {
+    const db = freshDb();
+    const sentinel = new Error("boom");
+    expect(() =>
+      transaction(db, () => {
+        db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+        throw sentinel;
+      }),
+    ).toThrow(sentinel);
+    // The inner INSERT was rolled back.
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(0);
+  });
+
+  it("issues ROLLBACK (not COMMIT) on a callback throw", () => {
+    const { db, calls } = fakeDb();
+    expect(() => transaction(db, () => { throw new Error("x"); })).toThrow("x");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "ROLLBACK"]);
+  });
+
+  it("swallows a ROLLBACK failure after a COMMIT throw and propagates the ORIGINAL (commit) error", () => {
+    const commitErr = new Error("commit failed");
+    const rollbackErr = new Error("no transaction is active");
+    const { db, calls } = fakeDb({ commitThrows: commitErr, rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      transaction(db, () => "value");
+    } catch (e) {
+      thrown = e;
+    }
+    // The COMMIT error is the original that propagates; the ROLLBACK error is swallowed.
+    expect(thrown).toBe(commitErr);
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"]);
+  });
+
+  it("preserves the callback error even when ROLLBACK also fails", () => {
+    const callbackErr = new Error("callback boom");
+    const rollbackErr = new Error("rollback boom");
+    const { db } = fakeDb({ rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      transaction(db, () => { throw callbackErr; });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(callbackErr);
+  });
+});
+
+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();
+    const result = await transactionAsync(db, async () => {
+      db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+      return 7;
+    });
+    expect(result).toBe(7);
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(1);
+  });
+
+  it("wraps in BEGIN IMMEDIATE … COMMIT", async () => {
+    const { db, calls } = fakeDb();
+    await transactionAsync(db, async () => "ok");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT"]);
+  });
+
+  it("rolls back and re-throws the ORIGINAL error when the callback rejects", async () => {
+    const db = freshDb();
+    const sentinel = new Error("async boom");
+    await expect(
+      transactionAsync(db, async () => {
+        db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+        throw sentinel;
+      }),
+    ).rejects.toBe(sentinel);
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(0);
+  });
+
+  it("swallows a ROLLBACK failure after a COMMIT throw and propagates the ORIGINAL (commit) error", async () => {
+    const commitErr = new Error("commit failed");
+    const rollbackErr = new Error("no transaction is active");
+    const { db, calls } = fakeDb({ commitThrows: commitErr, rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      await transactionAsync(db, async () => "value");
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(commitErr);
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"]);
+  });
+
+  it("preserves the callback error even when ROLLBACK also fails", async () => {
+    const callbackErr = new Error("callback boom");
+    const rollbackErr = new Error("rollback boom");
+    const { db } = fakeDb({ rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      await transactionAsync(db, async () => { throw callbackErr; });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(callbackErr);
+  });
+});

package/core/src/txn.ts

@@ -0,0 +1,105 @@
+/**
+ * The transaction seam (Phase-1 shared-core refactor, vault cloud design §4).
+ *
+ * Core code must never emit raw `BEGIN`/`COMMIT`/`ROLLBACK` — that's the one
+ * SQLite construct DO's `sql.exec` blocks, so it can't be shimmed like the
+ * rest of the `Database` surface. Instead every atomic block routes through
+ * `transaction` / `transactionAsync` here. The bun backend implements them
+ * as `BEGIN IMMEDIATE … COMMIT` with rollback-on-throw; a future Durable-
+ * Object backend implements the same contract with `ctx.storage.transactionSync`
+ * (and `Store.transaction`, see types.ts, is the object-level entry point).
+ *
+ * `BEGIN IMMEDIATE` (write lock up front) matches the pre-seam behavior of
+ * the 13 core blocks this replaced — several used a bare `BEGIN`, but every
+ * one of them only ever wrote, so acquiring the write lock eagerly is a
+ * strict improvement (no lazy busy-upgrade) and never a semantic change.
+ *
+ * **Nesting is unsupported**, matching the pre-seam code exactly: SQLite
+ * throws "cannot start a transaction within a transaction" on a nested
+ * `BEGIN`, and none of the migrated call sites nest (a batch wraps individual
+ * `createNote`s, none of which open their own transaction). If a nested
+ * caller ever appears, the fix is SAVEPOINT-based re-entrancy *in the bun
+ * implementation here* — the call sites stay untouched.
+ */
+
+/** The minimal DB surface the transaction seam needs — kept structural (no
+ *  `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 (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();
+    db.exec("COMMIT");
+    return result;
+  } catch (err) {
+    // Best-effort rollback — if the COMMIT itself threw the transaction is
+    // already resolved and ROLLBACK would throw "no transaction is active";
+    // swallow that so the original error is the one that propagates.
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // no active transaction to roll back
+    }
+    throw err;
+  }
+}
+
+/**
+ * Async sibling of {@link transaction} for the batch executors, which run
+ * their body through the async `Store` facade (`await store.createNote(...)`
+ * etc.). The transaction spans the awaits on the shared connection — the
+ * 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");
+  try {
+    const result = await fn();
+    db.exec("COMMIT");
+    return result;
+  } catch (err) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // no active transaction to roll back
+    }
+    throw err;
+  }
+}

package/core/src/types.ts

@@ -263,6 +263,15 @@ export interface Store {
    */
   readonly db: Database;
 
+  /**
+   * Run `fn` inside a single atomic write transaction (commit on return,
+   * rollback on throw). The transaction seam (see core/src/txn.ts): the
+   * bun backend implements it as `BEGIN IMMEDIATE … COMMIT`, a future
+   * Durable-Object backend as `ctx.storage.transactionSync`. Synchronous —
+   * `fn` must not await. Nesting is unsupported (matches raw-SQLite BEGIN).
+   */
+  transaction<T>(fn: () => T): T;
+
   // Notes. `actor` / `via` carry write-attribution (vault#298) — the
   // principal + interface stamped onto created_by/created_via (and mirrored
   // into the last_updated_* pair on create). Omitted → attribution NULL.

package/package.json

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

package/src/routes.ts

@@ -14,6 +14,7 @@
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
+import { transactionAsync } from "../core/src/txn.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import {
   parseContentRange,
@@ -1143,17 +1144,16 @@ async function handleNotesInner(
       // don't collide with concurrent single-item callers on the shared
       // bun:sqlite connection.
       const batched = items.length > 1;
-      if (batched) db.exec("BEGIN");
-      try {
+      const runBatch = async (): Promise<void> => {
         for (const item of items) {
           // Validate extension before reaching the Store (vault#328).
-          // Thrown inside the BEGIN block — outer catch rolls the batch
-          // back, same shape as the path-conflict path.
+          // Thrown inside the batch transaction — rolls the batch back,
+          // same shape as the path-conflict path.
           const extension = item.extension !== undefined
             ? validateExtension(item.extension)
             : undefined;
           // Strict-schema gate (vault#299) — reject before any write so a
-          // mid-batch violation rolls back via the outer BEGIN/ROLLBACK.
+          // mid-batch violation rolls back the batch transaction.
           gateStrictWrite(store, writeCtx, {
             path: item.path,
             tags: item.tags,
@@ -1181,9 +1181,10 @@ async function handleNotesInner(
 
           created.push((await store.getNote(note.id)) ?? note);
         }
-        if (batched) db.exec("COMMIT");
+      };
+      try {
+        await (batched ? transactionAsync(db, runBatch) : runBatch());
       } catch (e: any) {
-        if (batched) db.exec("ROLLBACK");
         // Duck-type for module-boundary robustness (matches the PATCH branch).
         if (e && e.code === "PATH_CONFLICT") {
           return json(