@openparachute/vault 0.4.7-rc.1 → 0.4.8-rc.4

package/core/src/schema.ts

@@ -200,12 +200,108 @@ CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_id);
 -- because migrateToV16 also runs the unconditional CREATE INDEX path.
 `;
 
+/**
+ * Connection-level pragmas applied on every Database open, in the order they
+ * appear here.
+ *
+ * `journal_mode = WAL` is a persistent, DB-level setting (lives in the SQLite
+ * header). Once any writer flips a DB into WAL it stays in WAL across opens
+ * and processes — so daemon + CLI + parachute-runner + any read-side tool
+ * see the same mode. Re-applying on every open is cheap and idempotent;
+ * SQLite returns the current mode either way.
+ *
+ * `synchronous = NORMAL` is the safe, recommended pairing with WAL per the
+ * SQLite docs: fsync only at checkpoint rather than on every commit. Crash
+ * safety is preserved (WAL frames are still ordered + checksummed); the only
+ * cost vs FULL is that an OS-level crash *between* checkpoints might lose
+ * the last transaction. Acceptable for a knowledge graph that's snapshotted
+ * by `VACUUM INTO` for backups.
+ *
+ * `wal_autocheckpoint = 1000` is SQLite's default; we set it explicitly so
+ * the contract is visible in code rather than implicit. 1000 pages ≈ 4MB
+ * before a passive checkpoint is triggered on the next write.
+ *
+ * `foreign_keys = ON` is per-connection (not persistent) — must be re-applied
+ * on every open. Migrations occasionally disable it transiently (see
+ * migrateToV14's BEGIN IMMEDIATE block); the boot path re-enables.
+ *
+ * WAL requires a filesystem that supports memory-mapped shared-memory
+ * (the `-shm` sidecar). NFS, some FUSE mounts, and a few Docker volume
+ * drivers don't qualify and silently fall back to the prior journal mode
+ * (typically `delete`). `applyConnectionPragmas` detects this and returns
+ * `wal: false` so the caller can log a warning — operators on those
+ * filesystems should know they've lost multi-process concurrency.
+ */
+const APPLY_PRAGMAS_LOGGED = new WeakSet<Database>();
+
+export interface ConnectionPragmaResult {
+  /** True when the connection ended up in WAL mode. False means the FS doesn't support WAL. */
+  wal: boolean;
+  /** The actual journal_mode SQLite reports — "wal", "delete", "memory", etc. */
+  journalMode: string;
+}
+
+/**
+ * Apply connection-level pragmas (journal mode, synchronous, FK enforcement)
+ * and verify WAL took effect. Idempotent — safe to call multiple times on
+ * the same connection. Logs a one-time warning per connection when WAL
+ * couldn't be applied.
+ *
+ * Exported for read-side callers (auth-status, mirror-manager, etc.) that
+ * open a Database directly without going through initSchema. Setting
+ * `journal_mode` on a read-only handle is a no-op but harmless; the
+ * useful state is set by whichever writer opens first.
+ */
+export function applyConnectionPragmas(db: Database): ConnectionPragmaResult {
+  // PRAGMA journal_mode returns a row { journal_mode: "wal" } on success.
+  // Use `.get()` (not `.exec()`) so we capture the result. Some bun:sqlite
+  // versions throw on readonly handles attempting to set journal_mode; treat
+  // that as "we couldn't set it, just read the current value" and recover.
+  let journalMode: string;
+  try {
+    const row = db.prepare("PRAGMA journal_mode = WAL").get() as { journal_mode?: string } | null;
+    journalMode = (row?.journal_mode ?? "").toLowerCase();
+  } catch {
+    // Most likely: readonly handle. Read-only opens never write the DB
+    // header, so they can't change journal_mode — but they can still query
+    // the current mode, which is set by the most recent writer.
+    const row = db.prepare("PRAGMA journal_mode").get() as { journal_mode?: string } | null;
+    journalMode = (row?.journal_mode ?? "").toLowerCase();
+  }
+  const wal = journalMode === "wal";
+
+  // synchronous + wal_autocheckpoint only matter when WAL is active. They're
+  // harmless under DELETE mode but the rationale is WAL-specific, so gate
+  // them on the success path. Both are best-effort — wrap in try to keep
+  // readonly handles (which reject writes) from failing the whole open.
+  if (wal) {
+    try { db.exec("PRAGMA synchronous = NORMAL"); } catch {}
+    try { db.exec("PRAGMA wal_autocheckpoint = 1000"); } catch {}
+  } else if (journalMode !== "memory" && !APPLY_PRAGMAS_LOGGED.has(db)) {
+    // `journalMode === "memory"` ⇒ this is a `:memory:` database, an
+    // explicit choice (tests, ephemeral probes) rather than a filesystem
+    // limitation. Suppress the warning so the test suite stays quiet;
+    // real on-disk vaults that can't host WAL (NFS, some FUSE/Docker
+    // volume drivers) still surface the diagnostic.
+    APPLY_PRAGMAS_LOGGED.add(db);
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[vault] WAL mode could not be enabled (journal_mode=${journalMode || "unknown"}). ` +
+      `The underlying filesystem may not support WAL (NFS, some FUSE/Docker volume drivers). ` +
+      `Multi-process concurrent access will be limited to a single writer at a time.`,
+    );
+  }
+
+  try { db.exec("PRAGMA foreign_keys = ON"); } catch {}
+
+  return { wal, journalMode };
+}
+
 /**
  * Initialize database schema. Idempotent — safe to call on every startup.
  */
 export function initSchema(db: Database): void {
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA foreign_keys = ON");
+  applyConnectionPragmas(db);
 
   // Check if we need to migrate from v2
   const hasOldTables = hasTable(db, "things");

package/core/src/store.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { Store, Note, Link, Attachment, QueryOpts } from "./types.js";
+import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage } from "./types.js";
 import { initSchema } from "./schema.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
@@ -227,6 +227,16 @@ export class BunSqliteStore implements Store {
     return noteOps.queryNotes(this.db, this.expandQueryTags(opts));
   }
 
+  async queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage> {
+    // Hierarchy expansion happens internally — but importantly the cursor's
+    // query_hash is computed from the CALLER'S opts (pre-expansion), so a
+    // tag hierarchy edit between calls invalidates the cursor (different
+    // descendant set → different rows match → caller should restart). The
+    // alternative — hash the expanded set — would silently keep returning
+    // stale results from a hierarchy snapshot the caller never saw.
+    return noteOps.queryNotesPaged(this.db, this.expandQueryTags(opts));
+  }
+
   /**
    * If `tags` are present, attach a parallel `_tagsExpanded` array where
    * each input tag is replaced with `{tag} ∪ descendants(tag)`. The SQL

package/core/src/types.ts

@@ -116,6 +116,30 @@ export interface QueryOpts {
   orderBy?: string;
   limit?: number;
   offset?: number;
+  /**
+   * Opaque cursor for "since last checked" agent loops (vault#313).
+   * When passed, the engine decodes it, verifies its `query_hash` matches
+   * the current query (mismatch → CursorError `cursor_query_mismatch`),
+   * and adds a keyset predicate that returns only rows newer than the
+   * cursor's `updated_at`/`id` watermark. Forces `orderBy = updated_at`
+   * (with `id` as a stable tiebreaker) so the watermark math is sound.
+   *
+   * Cursors are minted by `queryNotesPaged` (engine) and surfaced via
+   * the `query-notes` MCP tool's `next_cursor` field; callers should
+   * treat the string as opaque.
+   */
+  cursor?: string;
+}
+
+/**
+ * Cursor-paginated query result (vault#313). Returned by
+ * `queryNotesPaged`/`storeQueryNotesPaged`. `next_cursor` always advances —
+ * even on an empty result page — so an agent loop can persist a single
+ * watermark and keep polling.
+ */
+export interface QueryNotesPage {
+  notes: Note[];
+  next_cursor: string;
 }
 
 /** Note summary — everything except content. Used in link results. */
@@ -184,6 +208,14 @@ export interface Store {
   syncAllWikilinks(): Promise<{ synced: number; totalAdded: number; totalRemoved: number }>;
   deleteNote(id: string): Promise<void>;
   queryNotes(opts: QueryOpts): Promise<Note[]>;
+  /**
+   * Cursor-paginated `queryNotes` (vault#313). Returns the same notes plus
+   * an opaque `next_cursor` string the caller can pass on the next call
+   * to resume from the watermark of the LAST returned row. The cursor is
+   * always present in the response — even on an empty page — so an
+   * agent loop can persist a single watermark and keep polling.
+   */
+  queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
   searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Promise<Note[]>;
 
   // Tags

package/package.json

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

package/src/auth-status.ts

@@ -40,6 +40,10 @@ export interface AuthStatusResponse {
  * caller's signal to degrade `hasTokens` to `null`.
  */
 function vaultHasTokens(dbPath: string): boolean {
+  // Readonly handle — no pragma application here. Journal mode is a
+  // persistent DB-header setting written by the first writer (the daemon's
+  // BunSqliteStore via openVaultDb), so this probe sees WAL automatically
+  // and is safe under concurrent writes.
   const db = new Database(dbPath, { readonly: true });
   try {
     const row = db.prepare("SELECT 1 FROM tokens LIMIT 1").get();

package/src/auto-transcribe.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Auto-transcribe gating decisions (vault#353).
+ *
+ * Three independent guards: mime-type prefix, enabled toggle, scribe URL
+ * present. Pure function — exercise the truth table.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+
+function readGlobalConfig(enabled: boolean | undefined) {
+  return () => ({
+    port: 1940,
+    ...(enabled !== undefined ? { auto_transcribe: { enabled } } : {}),
+  }) as any;
+}
+
+describe("shouldAutoTranscribe", () => {
+  const scribePresent = () => "http://127.0.0.1:1943";
+  const scribeAbsent = () => undefined;
+
+  test("triggers on audio/* mime-type when enabled + scribe reachable", () => {
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(true);
+  });
+
+  test("triggers on audio/mp4 (m4a)", () => {
+    expect(shouldAutoTranscribe("audio/mp4", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(true);
+  });
+
+  test("triggers on audio/webm", () => {
+    expect(shouldAutoTranscribe("audio/webm", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(true);
+  });
+
+  test("triggers case-insensitively (AUDIO/WAV)", () => {
+    expect(shouldAutoTranscribe("AUDIO/WAV", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(true);
+  });
+
+  test("skips non-audio mime-types (image/png, application/pdf, video/mp4)", () => {
+    expect(shouldAutoTranscribe("image/png", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+    expect(shouldAutoTranscribe("application/pdf", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+    expect(shouldAutoTranscribe("video/mp4", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+  });
+
+  test("skips when enabled is false (default off)", () => {
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(false),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+  });
+
+  test("skips when enabled is unset (no auto_transcribe block in config)", () => {
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(undefined),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+  });
+
+  test("skips when scribe URL is undefined (no services.json entry, no env)", () => {
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribeAbsent,
+    })).toBe(false);
+  });
+
+  test("skips when scribe URL is empty string", () => {
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: () => "",
+    })).toBe(false);
+  });
+
+  test("skips on garbage mime-type input", () => {
+    expect(shouldAutoTranscribe("", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+    expect(shouldAutoTranscribe("not-a-mime", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+    })).toBe(false);
+  });
+
+  test("respects enabledOverride when present", () => {
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(false),
+      getCachedScribeUrlImpl: scribePresent,
+      enabledOverride: true,
+    })).toBe(true);
+    expect(shouldAutoTranscribe("audio/wav", {
+      readGlobalConfigImpl: readGlobalConfig(true),
+      getCachedScribeUrlImpl: scribePresent,
+      enabledOverride: false,
+    })).toBe(false);
+  });
+});

package/src/auto-transcribe.ts

@@ -0,0 +1,48 @@
+/**
+ * Auto-transcribe trigger decision (vault#353, design 2026-05-21 Part 2).
+ *
+ * One pure function: given an attachment's mime-type + the operator's
+ * settings + whether scribe is reachable, decide whether to enqueue the
+ * attachment for the transcription worker. Lives in its own module so the
+ * attachment-write code path (`routes.ts`) and the retry endpoint share the
+ * same gate without duplicating logic.
+ */
+
+import { readGlobalConfig } from "./config.ts";
+import { getCachedScribeUrl } from "./scribe-discovery.ts";
+
+/**
+ * Pre-vault#353 callers passed `transcribe: true` explicitly on the
+ * attachment POST. The auto-transcribe path inlines the decision: if the
+ * upload is an audio mime-type AND the toggle is on AND scribe is reachable,
+ * the worker is enqueued. This function is the single decision site.
+ *
+ * Returns `true` only when ALL three conditions hold:
+ *   1. mime-type starts with `audio/` (case-insensitive).
+ *   2. `globalConfig.auto_transcribe?.enabled === true`.
+ *   3. Scribe is discoverable (services.json entry OR SCRIBE_URL env).
+ *
+ * The three conditions are independent guards: a single `false` is sufficient
+ * to skip enqueuing. The audio stays as a regular attachment in that case.
+ */
+export function shouldAutoTranscribe(
+  mimeType: string,
+  opts: {
+    /** Injection seam for tests — defaults to live globals. */
+    readGlobalConfigImpl?: typeof readGlobalConfig;
+    getCachedScribeUrlImpl?: () => string | undefined;
+    /** Allow per-call enabled override — used by the explicit-opt-in path. */
+    enabledOverride?: boolean;
+  } = {},
+): boolean {
+  if (typeof mimeType !== "string" || !mimeType.toLowerCase().startsWith("audio/")) {
+    return false;
+  }
+  const enabled = opts.enabledOverride
+    ?? (opts.readGlobalConfigImpl ?? readGlobalConfig)().auto_transcribe?.enabled
+    ?? false;
+  if (!enabled) return false;
+  const url = (opts.getCachedScribeUrlImpl ?? getCachedScribeUrl)();
+  if (!url || !url.trim()) return false;
+  return true;
+}