@openparachute/vault 0.1.0

package/core/src/hooks.test.ts

@@ -0,0 +1,361 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { HookRegistry } from "./hooks.js";
+import type { Note } from "./types.js";
+
+let db: Database;
+let hooks: HookRegistry;
+let store: SqliteStore;
+
+/** Silent logger so expected-error tests don't spam output. */
+const silentLogger = { error: () => {} };
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  hooks = new HookRegistry({ concurrency: 4, logger: silentLogger });
+  store = new SqliteStore(db, { hooks });
+});
+
+/** Wait for all hook dispatches queued on the microtask loop and any
+ *  currently in-flight handlers to settle. */
+async function settle(): Promise<void> {
+  // Let queueMicrotask-scheduled dispatches enqueue their tasks.
+  await Promise.resolve();
+  await Promise.resolve();
+  await hooks.drain();
+}
+
+describe("HookRegistry", () => {
+  it("fires registered hook on createNote", async () => {
+    const fired: string[] = [];
+    hooks.onNote({
+      event: "created",
+      handler: (note) => {
+        fired.push(note.id);
+      },
+    });
+
+    const note = store.createNote("hello");
+    expect(fired).toEqual([]); // async — not yet
+    await settle();
+    expect(fired).toEqual([note.id]);
+  });
+
+  it("fires registered hook on updateNote", async () => {
+    const fired: Array<{ event: string; id: string }> = [];
+    hooks.onNote({
+      event: "updated",
+      handler: (note) => {
+        fired.push({ event: "updated", id: note.id });
+      },
+    });
+
+    const note = store.createNote("hello");
+    await settle();
+    expect(fired).toEqual([]); // we only subscribed to updated
+
+    store.updateNote(note.id, { content: "world" });
+    await settle();
+    expect(fired).toEqual([{ event: "updated", id: note.id }]);
+  });
+
+  it("fires for bulk createNotes after transaction commits", async () => {
+    const fired: string[] = [];
+    hooks.onNote({
+      handler: (note) => {
+        fired.push(note.id);
+      },
+    });
+
+    const notes = store.createNotes([
+      { content: "a", id: "a1" },
+      { content: "b", id: "b1" },
+      { content: "c", id: "c1" },
+    ]);
+    await settle();
+    expect(fired.sort()).toEqual(["a1", "b1", "c1"]);
+    expect(notes.length).toBe(3);
+  });
+
+  it("respects predicate — does not fire for non-matching notes", async () => {
+    const fired: string[] = [];
+    hooks.onNote({
+      when: (note) => (note.tags ?? []).includes("reader"),
+      handler: (note) => {
+        fired.push(note.id);
+      },
+    });
+
+    const skipped = store.createNote("plain", { tags: ["journal"] });
+    const matched = store.createNote("reader-note", { tags: ["reader"] });
+    await settle();
+
+    expect(fired).toEqual([matched.id]);
+    expect(fired).not.toContain(skipped.id);
+  });
+
+  it("does not fire on read paths (getNote, getNotes, queryNotes)", async () => {
+    const fired: string[] = [];
+    hooks.onNote({
+      handler: (note) => {
+        fired.push(note.id);
+      },
+    });
+
+    const note = store.createNote("one");
+    await settle();
+    expect(fired).toEqual([note.id]);
+
+    fired.length = 0;
+    store.getNote(note.id);
+    store.getNotes([note.id]);
+    store.queryNotes({});
+    await settle();
+    expect(fired).toEqual([]);
+  });
+
+  it("idempotency: handler writing a marker does not re-fire itself", async () => {
+    let handlerCalls = 0;
+    hooks.onNote({
+      event: ["created", "updated"],
+      when: (note) => !note.metadata?.processed_at,
+      handler: async (note, s) => {
+        handlerCalls++;
+        s.updateNote(note.id, {
+          metadata: { ...(note.metadata ?? {}), processed_at: new Date().toISOString() },
+        });
+      },
+    });
+
+    const note = store.createNote("work me");
+    await settle();
+    // The handler ran once for "created"; its updateNote triggered an
+    // "updated" dispatch, but the predicate excluded it because the
+    // marker is now set. So exactly one call.
+    expect(handlerCalls).toBe(1);
+
+    const refreshed = store.getNote(note.id)!;
+    expect(refreshed.metadata?.processed_at).toBeTruthy();
+  });
+
+  it("handler failure is logged but does not crash or affect the mutation", async () => {
+    const errors: unknown[] = [];
+    const localHooks = new HookRegistry({
+      concurrency: 2,
+      logger: { error: (...args) => errors.push(args) },
+    });
+    const localDb = new Database(":memory:");
+    const localStore = new SqliteStore(localDb, { hooks: localHooks });
+
+    localHooks.onNote({
+      name: "boom",
+      handler: async () => {
+        throw new Error("kaboom");
+      },
+    });
+
+    const note = localStore.createNote("survive");
+    expect(note.id).toBeTruthy();
+    // Original mutation still persisted
+    expect(localStore.getNote(note.id)?.content).toBe("survive");
+
+    await Promise.resolve();
+    await Promise.resolve();
+    await localHooks.drain();
+    expect(errors.length).toBe(1);
+  });
+
+  it("concurrency cap: HOOK_CONCURRENCY=1 serializes handler execution", async () => {
+    const localHooks = new HookRegistry({ concurrency: 1, logger: silentLogger });
+    const localDb = new Database(":memory:");
+    const localStore = new SqliteStore(localDb, { hooks: localHooks });
+
+    let running = 0;
+    let maxConcurrent = 0;
+    const releasers: Array<() => void> = [];
+
+    localHooks.onNote({
+      handler: async () => {
+        running++;
+        if (running > maxConcurrent) maxConcurrent = running;
+        await new Promise<void>((resolve) => releasers.push(resolve));
+        running--;
+      },
+    });
+
+    localStore.createNote("a");
+    localStore.createNote("b");
+    localStore.createNote("c");
+
+    // Let dispatch microtasks enqueue tasks and the semaphore start one.
+    await Promise.resolve();
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(maxConcurrent).toBe(1);
+    expect(running).toBe(1);
+    expect(releasers.length).toBe(1);
+
+    // Release them one at a time and verify only one runs at once.
+    while (releasers.length > 0) {
+      const next = releasers.shift()!;
+      next();
+      await new Promise((r) => setTimeout(r, 10));
+    }
+
+    await localHooks.drain();
+    expect(maxConcurrent).toBe(1);
+  });
+
+  it("unregister stops hook from firing", async () => {
+    const fired: string[] = [];
+    const off = hooks.onNote({
+      handler: (note) => {
+        fired.push(note.id);
+      },
+    });
+
+    store.createNote("first");
+    await settle();
+    expect(fired.length).toBe(1);
+
+    off();
+    store.createNote("second");
+    await settle();
+    expect(fired.length).toBe(1);
+  });
+
+  it("multiple hooks all fire for a matching note", async () => {
+    const order: string[] = [];
+    hooks.onNote({ name: "one", handler: () => void order.push("one") });
+    hooks.onNote({ name: "two", handler: () => void order.push("two") });
+
+    store.createNote("both");
+    await settle();
+    expect(order.sort()).toEqual(["one", "two"]);
+  });
+
+  it("drain waits for in-flight handlers", async () => {
+    let done = false;
+    hooks.onNote({
+      handler: async () => {
+        await new Promise((r) => setTimeout(r, 20));
+        done = true;
+      },
+    });
+    store.createNote("slow");
+    // Let dispatch schedule
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(done).toBe(false);
+    await hooks.drain();
+    expect(done).toBe(true);
+  });
+
+  it("logs and skips a hook whose predicate throws; other hooks still run", async () => {
+    const errors: unknown[] = [];
+    const loggingHooks = new HookRegistry({
+      concurrency: 4,
+      logger: { error: (...args) => errors.push(args) },
+    });
+    const loggingStore = new SqliteStore(new Database(":memory:"), { hooks: loggingHooks });
+    let goodFired = 0;
+
+    loggingHooks.onNote({
+      name: "throwing-predicate",
+      when: () => {
+        throw new Error("predicate boom");
+      },
+      handler: () => {
+        throw new Error("should not reach here");
+      },
+    });
+    loggingHooks.onNote({
+      name: "good",
+      handler: () => {
+        goodFired++;
+      },
+    });
+
+    loggingStore.createNote("hi");
+    await Promise.resolve();
+    await Promise.resolve();
+    await loggingHooks.drain();
+
+    // The good hook ran.
+    expect(goodFired).toBe(1);
+    // The throwing predicate was logged.
+    expect(errors.length).toBeGreaterThanOrEqual(1);
+    const joined = errors.map((a) => JSON.stringify(a)).join(" ");
+    expect(joined).toContain("predicate");
+  });
+});
+
+describe("HookRegistry — HOOK_CONCURRENCY env var parsing", () => {
+  const original = process.env.HOOK_CONCURRENCY;
+  const restore = () => {
+    if (original === undefined) delete process.env.HOOK_CONCURRENCY;
+    else process.env.HOOK_CONCURRENCY = original;
+  };
+
+  it("defaults to 2 when HOOK_CONCURRENCY is unset", () => {
+    delete process.env.HOOK_CONCURRENCY;
+    const r = new HookRegistry();
+    // Acquire 3 in sequence — first 2 should resolve immediately, third should wait.
+    let resolvedCount = 0;
+    const pending: Array<Promise<() => void>> = [];
+    for (let i = 0; i < 3; i++) {
+      const p = (r as unknown as { semaphore: { acquire: () => Promise<() => void> } }).semaphore.acquire();
+      p.then(() => resolvedCount++);
+      pending.push(p);
+    }
+    return Promise.resolve().then(() => {
+      expect(resolvedCount).toBe(2);
+      restore();
+    });
+  });
+
+  it("falls back to default when HOOK_CONCURRENCY is NaN / empty / negative", () => {
+    for (const bad of ["", "abc", "0", "-5", "NaN"]) {
+      process.env.HOOK_CONCURRENCY = bad;
+      const r = new HookRegistry();
+      // Should not throw; registry is usable.
+      r.onNote({ handler: () => {} });
+      expect(r.size).toBe(1);
+    }
+    restore();
+  });
+
+  it("honors HOOK_CONCURRENCY=1 from env", async () => {
+    process.env.HOOK_CONCURRENCY = "1";
+    const r = new HookRegistry({ logger: silentLogger });
+    const s = new SqliteStore(new Database(":memory:"), { hooks: r });
+
+    let concurrent = 0;
+    let maxConcurrent = 0;
+    const releasers: Array<() => void> = [];
+    r.onNote({
+      handler: async () => {
+        concurrent++;
+        maxConcurrent = Math.max(maxConcurrent, concurrent);
+        await new Promise<void>((resolve) => releasers.push(resolve));
+        concurrent--;
+      },
+    });
+
+    s.createNote("a");
+    s.createNote("b");
+    s.createNote("c");
+    await Promise.resolve();
+    await Promise.resolve();
+    // Release them one at a time and let each drain through the semaphore.
+    while (releasers.length > 0) {
+      releasers.shift()!();
+      await new Promise((r) => setTimeout(r, 1));
+    }
+    await r.drain();
+    expect(maxConcurrent).toBe(1);
+    restore();
+  });
+});

package/core/src/hooks.ts

@@ -0,0 +1,234 @@
+/**
+ * Async note-mutation hook infrastructure (#37).
+ *
+ * Lightweight in-process pub/sub over note mutations. Features register
+ * handlers via `HookRegistry.onNote` at startup; the store fires them
+ * after each mutation commits, out-of-band, capped by HOOK_CONCURRENCY.
+ *
+ * Design notes:
+ * - In-process only. No external queue, no DB table. If the process
+ *   crashes mid-handler, the work is dropped — reconciliation is the
+ *   responsibility of the predicate (idempotency markers in metadata).
+ * - Dispatch is strictly post-commit. The store calls `dispatch()` only
+ *   after the SQLite write has returned, so handlers can safely read
+ *   and update the same note without deadlocking the transaction.
+ * - Concurrency cap is global across all hooks (a bulk import should
+ *   not be able to spawn 1000 parallel TTS jobs). Configured via
+ *   HOOK_CONCURRENCY env var (default 2).
+ * - Failures are logged, not retried. Retries happen naturally on the
+ *   next mutation when the predicate still matches (i.e. the marker
+ *   wasn't written because the handler failed).
+ * - The API matches the proposal in the issue. Predicates are sync
+ *   functions on the note; handlers are async and receive the note
+ *   plus a `Store`-like interface so they can read/update/attach.
+ *
+ * ## Sharp edges for handler authors
+ *
+ * **1. Write your idempotency marker BEFORE any slow async work.**
+ * The predicate is re-evaluated on every dispatch. If your handler
+ * awaits a 30-second TTS call before writing the marker, a concurrent
+ * update to the same note during those 30 seconds will re-match the
+ * predicate and start a second handler run. The semaphore is global,
+ * not per-note, so it won't save you. Write the marker synchronously
+ * at the top of the handler, or — if the marker has to wait until
+ * the work actually succeeds — accept that duplicate runs are possible
+ * and make the handler idempotent in some other way.
+ *
+ * **2. No per-note serialization.** Two different hooks whose
+ * predicates match the same note run concurrently (up to the global
+ * cap). Last write wins if both touch the same fields.
+ *
+ * **3. Shutdown drain is a hard cut.** `drain()` on SIGINT/SIGTERM
+ * waits for in-flight handlers, but the server wraps it in a 5-second
+ * Promise.race. Long-running handlers (webhook triggers) may
+ * get killed mid-run. Handlers must not write the marker before the
+ * work is durably committed, so restart reconciliation works.
+ */
+
+import type { Note, Store } from "./types.js";
+
+export type HookEvent = "created" | "updated";
+
+export interface NoteHook {
+  /** Events this hook listens for. Defaults to ["created", "updated"]. */
+  event?: HookEvent | HookEvent[];
+  /**
+   * Predicate — return true to run the handler for this note.
+   * Should be cheap and synchronous. Idempotency lives here: check
+   * whether a marker (e.g. `metadata.audio_rendered_at`) is already set
+   * and return false if so.
+   */
+  when?: (note: Note) => boolean;
+  /** Handler — runs async, off the request path. Third arg is the event type. */
+  handler: (note: Note, store: Store, event?: HookEvent) => Promise<void> | void;
+  /** Optional label for logs. */
+  name?: string;
+}
+
+interface RegisteredHook extends NoteHook {
+  events: Set<HookEvent>;
+}
+
+/**
+ * Tiny async semaphore — FIFO waiters, no dependencies.
+ * Used to cap concurrent handler execution across all hooks.
+ */
+class Semaphore {
+  private available: number;
+  private waiters: Array<() => void> = [];
+
+  constructor(capacity: number) {
+    this.available = Math.max(1, capacity);
+  }
+
+  async acquire(): Promise<() => void> {
+    if (this.available > 0) {
+      this.available--;
+      return () => this.release();
+    }
+    return new Promise<() => void>((resolve) => {
+      this.waiters.push(() => {
+        this.available--;
+        resolve(() => this.release());
+      });
+    });
+  }
+
+  private release(): void {
+    this.available++;
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+}
+
+export interface HookRegistryOptions {
+  /** Concurrency cap for handler execution. Defaults to HOOK_CONCURRENCY env var, then 2. */
+  concurrency?: number;
+  /** Logger. Defaults to console. */
+  logger?: { error: (...args: unknown[]) => void };
+}
+
+export class HookRegistry {
+  private hooks: RegisteredHook[] = [];
+  private semaphore: Semaphore;
+  private inFlight = new Set<Promise<void>>();
+  private logger: { error: (...args: unknown[]) => void };
+
+  constructor(opts: HookRegistryOptions = {}) {
+    const envCap = Number.parseInt(process.env.HOOK_CONCURRENCY ?? "", 10);
+    const capacity = opts.concurrency ?? (Number.isFinite(envCap) && envCap > 0 ? envCap : 2);
+    this.semaphore = new Semaphore(capacity);
+    this.logger = opts.logger ?? console;
+  }
+
+  /** Register a hook. Returns an unregister function. */
+  onNote(hook: NoteHook): () => void {
+    const events = new Set<HookEvent>(
+      Array.isArray(hook.event)
+        ? hook.event
+        : hook.event
+          ? [hook.event]
+          : (["created", "updated"] as HookEvent[]),
+    );
+    const entry: RegisteredHook = { ...hook, events };
+    this.hooks.push(entry);
+    return () => {
+      const idx = this.hooks.indexOf(entry);
+      if (idx >= 0) this.hooks.splice(idx, 1);
+    };
+  }
+
+  /** Remove all registered hooks. Mostly for tests. */
+  clear(): void {
+    this.hooks = [];
+  }
+
+  /** Count of currently registered hooks. */
+  get size(): number {
+    return this.hooks.length;
+  }
+
+  /** Count of currently in-flight handler executions. */
+  get inFlightCount(): number {
+    return this.inFlight.size;
+  }
+
+  /**
+   * Dispatch a mutation event. Matches hooks, schedules their handlers
+   * onto a microtask, and returns immediately. The caller is never
+   * blocked on handler execution.
+   *
+   * Must only be called after the triggering SQLite write has committed.
+   */
+  dispatch(event: HookEvent, note: Note, store: Store): void {
+    if (this.hooks.length === 0) return;
+
+    // Snapshot matches synchronously so subsequent hook registration
+    // changes don't affect this dispatch.
+    const matches: RegisteredHook[] = [];
+    for (const hook of this.hooks) {
+      if (!hook.events.has(event)) continue;
+      try {
+        if (hook.when && !hook.when(note)) continue;
+      } catch (err) {
+        this.logger.error(
+          `[hooks] predicate threw for ${hook.name ?? "anonymous"} on note ${note.id}:`,
+          err,
+        );
+        continue;
+      }
+      matches.push(hook);
+    }
+    if (matches.length === 0) return;
+
+    // Defer to a microtask so we unwind the caller's stack (and its
+    // SQLite transaction, if any) before handlers run.
+    queueMicrotask(() => {
+      for (const hook of matches) {
+        const task = this.runHandler(hook, event, note, store);
+        this.inFlight.add(task);
+        task.finally(() => this.inFlight.delete(task));
+      }
+    });
+  }
+
+  private async runHandler(
+    hook: RegisteredHook,
+    event: HookEvent,
+    note: Note,
+    store: Store,
+  ): Promise<void> {
+    const release = await this.semaphore.acquire();
+    try {
+      // Re-read the note so the handler sees the latest state (another
+      // handler may have written back in between). If the note was
+      // deleted, silently drop.
+      const fresh = store.getNote(note.id) ?? note;
+      await hook.handler(fresh, store, event);
+    } catch (err) {
+      this.logger.error(
+        `[hooks] handler ${hook.name ?? "anonymous"} threw on ${event} ${note.id}:`,
+        err,
+      );
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Wait for all currently in-flight handlers to settle. Best-effort
+   * drain for graceful shutdown. New hooks dispatched during the drain
+   * are also awaited.
+   */
+  async drain(): Promise<void> {
+    while (this.inFlight.size > 0) {
+      await Promise.allSettled(Array.from(this.inFlight));
+    }
+  }
+}
+
+/**
+ * Module-level default registry. Most consumers (server, CLI) share
+ * this one instance; tests can construct their own for isolation.
+ */
+export const defaultHookRegistry = new HookRegistry();