@openparachute/vault 0.6.4 → 0.6.5-rc.10

package/core/src/sql-in.ts

@@ -0,0 +1,76 @@
+/**
+ * SQL `IN`-list helpers sized for the smallest backing SQLite we run on.
+ *
+ * ## The DO 100-bound-parameter cap
+ *
+ * Cloudflare Durable Object SQLite (the cloud vault's backing store) rejects
+ * any statement carrying **more than 100 bound parameters** with
+ * `too many SQL variables`. Standard SQLite — including bun:sqlite (self-host)
+ * — tolerates 999 on old builds and 32766 on new ones, which is why an
+ * `IN (?, ?, …)` list sized for the 999 floor shipped fine on self-host and
+ * only 500'd on cloud vaults: a >100-note export page passed >100 ids in one
+ * statement and DO SQLite rejected it. See vault export-500 diagnosis.
+ *
+ * Two DO-safe shapes, depending on whether the id-list is the *only* thing
+ * in the statement:
+ *
+ * 1. **Standalone id-list** (its own `SELECT … WHERE id IN (…)`, no other
+ *    params, no pagination): chunk at {@link IN_PARAM_CHUNK} and union the
+ *    results in JS. Use {@link chunkForInClause}.
+ *
+ * 2. **Embedded id-set** (an `IN` filter inside a larger statement that also
+ *    carries `ORDER BY` / `LIMIT` / `OFFSET` / other params — chunking would
+ *    break the shared pagination window): bind the whole set as a SINGLE JSON
+ *    array param via {@link IN_VIA_JSON_EACH} + {@link jsonEachParam}. One
+ *    param regardless of set size, so it can never trip the cap. Requires the
+ *    JSON1 extension, which both bun:sqlite and DO SQLite ship (the vault
+ *    already relies on `json_extract` on DO for metadata queries).
+ *
+ * ## Future refinement — `maxBoundParams`
+ *
+ * The clean long-term shape is for the Store / DB shim to advertise a
+ * `maxBoundParams` (DO = 100, bun = 999) and chunk to
+ * `min(IN_PARAM_CHUNK, maxBoundParams - reservedParams)`, so self-host keeps
+ * large-batch efficiency instead of paying the DO tax. Until then a global
+ * 90 is SAFE on bun — it just issues more cheap, fully-indexed IN queries —
+ * and is the conservative floor everywhere.
+ */
+
+/**
+ * Chunk size for standalone `IN (?, ?, …)` id-lists. 90 leaves headroom
+ * under the DO 100-param cap for statements whose only bound params are the
+ * IN-list (the extra 10 covers the rare embedded extra param). Never raise
+ * this above 100 without teaching every embedded callsite the DO cap — see
+ * the module header.
+ */
+export const IN_PARAM_CHUNK = 90;
+
+/**
+ * Split `items` into consecutive chunks of at most `size` (default
+ * {@link IN_PARAM_CHUNK}) for feeding to a chunked `IN (?, …)` query. Empty
+ * input yields no chunks. This is the single place that decides IN-list chunk
+ * boundaries, so a regression that raises the size is caught by one test.
+ */
+export function chunkForInClause<T>(items: readonly T[], size = IN_PARAM_CHUNK): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    chunks.push(items.slice(i, i + size));
+  }
+  return chunks;
+}
+
+/**
+ * SQL fragment for a single-param `IN` filter over an id-set embedded in a
+ * larger statement: `WHERE col IN ${IN_VIA_JSON_EACH}`. Bind the matching
+ * `?` with {@link jsonEachParam}. json_each expands the bound JSON array into
+ * a one-column table, so the whole set costs exactly ONE bound parameter and
+ * can never exceed the DO cap. Callers must guarantee the set is non-empty
+ * (`json_each('[]')` yields no rows — correct for `IN`, but an empty set is
+ * usually short-circuited to a `0 = 1` no-match upstream to skip the query).
+ */
+export const IN_VIA_JSON_EACH = "(SELECT value FROM json_each(?))";
+
+/** Serialize an id-set for the single {@link IN_VIA_JSON_EACH} bound param. */
+export function jsonEachParam(values: readonly (string | number)[]): string {
+  return JSON.stringify(values);
+}

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/transcription/provider.ts

@@ -0,0 +1,141 @@
+/**
+ * Transcription provider seam (scribe-fold Phase 1).
+ *
+ * A `TranscriptionProvider` is the single, runtime-agnostic contract for
+ * turning an audio blob into text. It exists so vault's transcription worker
+ * doesn't hard-code "POST to scribe" — the worker resolves a provider and
+ * calls `transcribe()`, and the provider owns HOW the bytes become text.
+ *
+ * ## Why this lives in core (not src)
+ *
+ * The interface must be importable from BOTH runtimes without dragging in
+ * Bun- or Node-only APIs:
+ *
+ *   - the Bun vault (`src/transcription/providers/scribe-http.ts` — the
+ *     whisper-compatible remote provider that reproduces today's scribe call);
+ *   - the cloud vault (a future Cloudflare Workers-AI provider implemented
+ *     against THIS interface for the metered voice build).
+ *
+ * So it is pure types + one dependency-free error class — no `fs`, no
+ * `FormData` serialization, no `fetch`. `audio` arrives as a `Uint8Array`
+ * (both runtimes have it); a provider decides how to ship it. Core has no
+ * package `exports` map, so consumers import the src subpath directly
+ * (`../core/src/transcription/provider.ts`), the same convention as
+ * `core/src/seed-packs.ts`.
+ *
+ * ## The fold (context)
+ *
+ * Ratified 2026-07-03 (Aaron): scribe folds into vault as a built-in
+ * transcription feature. Phase 1 (this seam) is behavior-preserving — the
+ * default `scribe-http` provider does EXACTLY what today's `callScribe` did,
+ * so existing scribe installs keep working unchanged. Phase 2 moves local-ASR
+ * backends behind the same interface. See
+ * `design/2026-07-03-transcription-provider-seam.md`.
+ */
+
+/**
+ * A single context entry attached alongside the audio (person/project notes,
+ * etc.). Structurally identical to `src/context.ts`'s `ContextEntry` — the
+ * same shape scribe already consumes over the `context` multipart part — so a
+ * `ContextPayload` produced there is assignable here without conversion. The
+ * interface stays runtime-agnostic: a provider decides whether/how to
+ * serialize it.
+ */
+export interface TranscriptionContextEntry {
+  /** Note path basename, or note id if no path. */
+  name: string;
+  /** Whitelisted metadata fields carried through from the vault query. */
+  [key: string]: unknown;
+}
+
+/** The `{ entries: [...] }` context blob a provider may forward with the audio. */
+export interface TranscriptionContext {
+  entries: TranscriptionContextEntry[];
+}
+
+/** The audio + descriptors handed to a provider for one transcription. */
+export interface TranscribeInput {
+  /** Raw audio bytes. Both runtimes expose `Uint8Array`; a `Buffer` is one. */
+  audio: Uint8Array;
+  /** Original filename (used for the multipart `file` part / provider hints). */
+  filename: string;
+  /** MIME type of the audio (e.g. `audio/webm`). */
+  mimeType: string;
+  /**
+   * Optional vault-provided context (person/project notes) to forward with the
+   * audio so the provider/model can use it. `null`/`undefined` means none.
+   */
+  context?: TranscriptionContext | null;
+}
+
+/** What a provider returns on a successful transcription. */
+export interface TranscribeResult {
+  /** The transcript text. */
+  text: string;
+  /**
+   * Duration of the transcribed AUDIO in seconds, when the provider reports it.
+   * This is a metered/plan concern (the cloud voice build will decrement a
+   * minutes balance by it); self-host providers that don't measure it leave it
+   * unset. NOT the wall-clock request time — the worker measures that itself.
+   */
+  audioSeconds?: number;
+}
+
+/** Provider readiness probe result. */
+export interface ProviderAvailability {
+  /** True when the provider can service `transcribe()` calls right now. */
+  ok: boolean;
+  /** Human-readable cause when `ok` is false (e.g. "no scribe URL configured"). */
+  reason?: string;
+}
+
+/**
+ * The transcription contract. Implementations own the audio→text step; the
+ * worker owns queueing, backoff/retry, transcript-note materialization, and
+ * retention — none of which belong here.
+ */
+export interface TranscriptionProvider {
+  /** Stable provider identifier, surfaced on the capability flag (e.g. "scribe-http"). */
+  readonly name: string;
+  /** Turn audio into text (or throw — see `TranscriptionError` for the retry contract). */
+  transcribe(input: TranscribeInput): Promise<TranscribeResult>;
+  /**
+   * Cheap, side-effect-free readiness check. MUST NOT perform the actual
+   * transcription or a network round-trip unless that is genuinely cheap —
+   * it gates the capability flag on the vault landing, called on config reads.
+   */
+  available(): Promise<ProviderAvailability>;
+}
+
+/**
+ * Structured, provider-agnostic transcription failure.
+ *
+ * The worker's terminal-vs-retry decision keys off `retriable`: a
+ * non-retriable error (a 4xx the operator must fix — no provider configured,
+ * bad auth) fails immediately with no backoff; a retriable one (5xx, transient
+ * upstream) is retried with exponential backoff. `code` is a stable machine
+ * string (e.g. `missing_provider`) surfaced on the transcript note's
+ * frontmatter and the attachment's `transcribe_error_code` so callers branch
+ * on it instead of regex-matching message text.
+ *
+ * Providers throw this for structured failures; a plain `Error` (network drop,
+ * timeout, malformed response) is treated as retriable by the worker.
+ */
+export class TranscriptionError extends Error {
+  /** Stable machine code (e.g. "missing_provider"), when the provider supplied one. */
+  readonly code?: string;
+  /** Upstream HTTP status, when the failure came from an HTTP provider. */
+  readonly httpStatus?: number;
+  /** Whether retrying the same audio could plausibly succeed. */
+  readonly retriable: boolean;
+  constructor(
+    message: string,
+    opts: { code?: string; httpStatus?: number; retriable: boolean },
+  ) {
+    super(message);
+    this.name = "TranscriptionError";
+    this.code = opts.code;
+    this.httpStatus = opts.httpStatus;
+    this.retriable = opts.retriable;
+  }
+}

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/core/src/vault-projection.ts

@@ -33,7 +33,7 @@ import {
 import { DEFAULT_TAG_NAME } from "./tag-hierarchy.ts";
 import * as noteOps from "./notes.ts";
 import type { VaultStats } from "./types.ts";
-import { GETTING_STARTED_PATH } from "./onboarding.ts";
+import { GETTING_STARTED_PATH } from "./seed-packs.ts";
 
 /**
  * Does a note live at the seeded onboarding path? Used to gate the "Start here"

package/core/src/wikilinks.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import * as linkOps from "./links.js";
+import { chunkForInClause } from "./sql-in.js";
 
 // ---------------------------------------------------------------------------
 // Parser — extract [[wikilinks]] from markdown content
@@ -272,10 +273,15 @@ export function listUnresolvedWikilinks(db: Database, limit = 50): { unresolved:
   if (rows.length === 0) return { unresolved: [], count: total };
 
   const sourceIds = [...new Set(rows.map((r) => r.source_id))];
-  const placeholders = sourceIds.map(() => "?").join(", ");
-  const pathRows = db.prepare(
-    `SELECT id, path FROM notes WHERE id IN (${placeholders})`,
-  ).all(...sourceIds) as { id: string; path: string | null }[];
+  // Chunk under the DO 100-bound-param cap (see sql-in.ts) — with a large
+  // `limit` this hydrates >100 source ids in one IN-list otherwise.
+  const pathRows: { id: string; path: string | null }[] = [];
+  for (const chunk of chunkForInClause(sourceIds)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    pathRows.push(...db.prepare(
+      `SELECT id, path FROM notes WHERE id IN (${placeholders})`,
+    ).all(...chunk) as { id: string; path: string | null }[]);
+  }
   const pathMap = new Map(pathRows.map((r) => [r.id, r.path]));
 
   const unresolved: UnresolvedWikilink[] = rows.map((r) => ({

package/package.json

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