@openparachute/vault 0.6.5-rc.9 → 0.6.5

package/src/services-manifest.ts

@@ -15,6 +15,14 @@ export interface ServiceEntry {
   paths: string[];
   health: string;
   version: string;
+  /**
+   * When `true`, the hub's ws-bridge forwards `Upgrade: websocket` requests on
+   * this module's mounts to it (deny-by-default). Carried from the module's
+   * `.parachute/module.json` `websocket` field by self-registration; the hub
+   * honors either source. Optional + free-riding — extra fields survive the
+   * read/merge via the `...e` spread in `validateEntry` / `upsertService`.
+   */
+  websocket?: boolean;
 }
 
 export interface ServicesManifest {

package/src/subscriptions.ts

@@ -1,6 +1,8 @@
 /**
- * Live-query subscription registry (live-query SSE — design
- * `design/2026-06-08-live-query-sse.md`).
+ * Live-query subscription registry — fans out post-commit note events to live
+ * WebSocket subscriptions (originally an SSE fan-out — design
+ * `design/2026-06-08-live-query-sse.md`; the SSE transport was removed in
+ * Phase 5 of the WS-hibernation migration).
  *
  * A second consumer of the post-commit hook dispatcher (`core/src/hooks.ts`),
  * alongside the durable webhook-trigger sink. Where a trigger survives across
@@ -8,6 +10,24 @@
  * connection-scoped, driving a live UI. Same event source, same predicate,
  * different durability.
  *
+ * ## The live transport: WebSocket (WS-hibernation migration)
+ *
+ * The manager is transport-agnostic: it emits abstract `(event, data)` tuples
+ * and a {@link SubscriptionSink} renders them for its wire.
+ *   - {@link WsSink} renders a WebSocket message `{ type: event, ...data }`. The
+ *     inner payload (`note` / `id` / `notes`) is pinned byte-for-byte against the
+ *     shared frame-corpus fixture and is congruent with the cloud door
+ *     (`parachute-cloud/workers/vault/src/live/subscriptions.ts`). See
+ *     `parachute-cloud/workers/vault/docs/live-query-ws.md`.
+ *
+ * WebSocket is the SOLE live transport as of Phase 5 — the earlier SSE binding
+ * was removed once cached notes-ui bundles converged, and polling (client-side)
+ * is the floor beneath live. All subscriptions share ONE process-wide
+ * {@link SubscriptionManager}. Self-host has no hibernation (a self-run Bun box
+ * has no per-connection duration bill) — the WS binding gives bidirectionality +
+ * contract-congruence with cloud, nothing more. The Bun.serve WS integration
+ * lives in `ws-server.ts` + `ws-subscribe.ts`.
+ *
  * ## How fan-out works
  *
  * All vault stores share the process-wide `defaultHookRegistry`
@@ -54,16 +74,19 @@ export const DEFAULT_MAX_SUBSCRIPTIONS_PER_VAULT = 100;
  * Default bound on a single subscription's pending (unflushed) event buffer.
  * If a slow client lets the buffer grow past this, the stream is closed — it
  * reconnects and re-snapshots rather than the server growing memory unbounded.
+ * Only enforced for flush-tracking sinks (SSE); the WS transport delegates
+ * outgoing-buffer bounds to the Bun runtime.
  */
 export const DEFAULT_MAX_BUFFERED_EVENTS = 1000;
 
-/** A serialized SSE frame ready to write to the wire. */
-type SseFrame = string;
-
+/**
+ * The abstract sink an event is rendered to. The manager calls `send(event,
+ * data)`; each transport formats for its wire. Returns `false` when the sink is
+ * gone (the manager then drops the subscription).
+ */
 export interface SubscriptionSink {
-  /** Enqueue a serialized SSE frame. Returns false if the sink is closed. */
-  write(frame: SseFrame): boolean;
-  /** Close the underlying stream (teardown). Idempotent. */
+  send(event: string, data: unknown): boolean;
+  /** Close the underlying stream/socket (teardown). Idempotent. */
   close(): void;
 }
 
@@ -75,14 +98,56 @@ interface Subscription {
   /** Raw root-tag allowlist (null = unscoped) — `noteWithinTagScope` arg. */
   readonly tagScopeRaw: string[] | null;
   readonly sink: SubscriptionSink;
-  /** Pending unflushed frame count (backpressure bound). */
+  /** SSE tracks unflushed frames to bound memory; WS delegates to the runtime. */
+  readonly tracksFlush: boolean;
+  /** Whether this sub counts against the per-vault manager cap (SSE) — the WS
+   *  transport enforces its own cap via the live-socket count at upgrade. */
+  readonly countsTowardCap: boolean;
+  /** Pending unflushed frame count (backpressure bound; SSE only). */
   buffered: number;
   readonly maxBuffered: number;
   closed: boolean;
 }
 
-function sseEvent(event: string, data: unknown): SseFrame {
-  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+/** WebSocket message: `{ type: <event>, ...data }` — the event name becomes the
+ *  `type` discriminator and the inner payload (`note` / `id` / `notes`)
+ *  serializes as-is. The ONE place WS bytes are formatted. */
+export function wsFrame(event: string, data: unknown): string {
+  const body = data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+  return JSON.stringify({ type: event, ...body });
+}
+
+/** Minimal structural shape of a Bun `ServerWebSocket` (or a test double) that
+ *  {@link WsSink} needs — keeps this module free of a hard Bun-server import. */
+export interface WsLike {
+  send(data: string): unknown;
+  close(code?: number, reason?: string): unknown;
+}
+
+/** WebSocket sink: renders `(event, data)` to a `{ type, ...data }` message and
+ *  sends it on the socket. `sendRaw` is for pre-formatted frames (the chunked
+ *  snapshot the WS binding builds directly). A send on a dead socket returns
+ *  false → the manager drops the sub. */
+export class WsSink implements SubscriptionSink {
+  constructor(private readonly ws: WsLike) {}
+  send(event: string, data: unknown): boolean {
+    return this.sendRaw(wsFrame(event, data));
+  }
+  sendRaw(frame: string): boolean {
+    try {
+      this.ws.send(frame);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  close(): void {
+    try {
+      this.ws.close(1011, "subscription closed");
+    } catch {
+      /* already closing/closed */
+    }
+  }
 }
 
 export class SubscriptionManager {
@@ -140,9 +205,15 @@ export class SubscriptionManager {
     tagScopeRaw: string[] | null;
     sink: SubscriptionSink;
     maxBuffered?: number;
+    /** SSE (default true) tracks unflushed frames; WS passes false. */
+    tracksFlush?: boolean;
+    /** SSE (default true) counts against the per-vault manager cap; WS passes
+     *  false — the WS transport caps via the live-socket count at upgrade. */
+    countsTowardCap?: boolean;
   }): SubscriptionHandle | null {
+    const countsTowardCap = args.countsTowardCap ?? true;
     const current = this.countForVault(args.vaultName);
-    if (current >= this.maxPerVault) return null;
+    if (countsTowardCap && current >= this.maxPerVault) return null;
 
     this.ensureHooks();
 
@@ -152,12 +223,14 @@ export class SubscriptionManager {
       tagScopeAllowed: args.tagScopeAllowed,
       tagScopeRaw: args.tagScopeRaw,
       sink: args.sink,
+      tracksFlush: args.tracksFlush ?? true,
+      countsTowardCap,
       buffered: 0,
       maxBuffered: args.maxBuffered ?? DEFAULT_MAX_BUFFERED_EVENTS,
       closed: false,
     };
     this.subs.add(sub);
-    this.perVaultCount.set(args.vaultName, current + 1);
+    if (countsTowardCap) this.perVaultCount.set(args.vaultName, current + 1);
 
     return {
       /** Note that a previously-buffered frame flushed to the wire. */
@@ -172,9 +245,11 @@ export class SubscriptionManager {
     if (sub.closed) return;
     sub.closed = true;
     this.subs.delete(sub);
-    const n = this.perVaultCount.get(sub.vaultName) ?? 0;
-    if (n <= 1) this.perVaultCount.delete(sub.vaultName);
-    else this.perVaultCount.set(sub.vaultName, n - 1);
+    if (sub.countsTowardCap) {
+      const n = this.perVaultCount.get(sub.vaultName) ?? 0;
+      if (n <= 1) this.perVaultCount.delete(sub.vaultName);
+      else this.perVaultCount.set(sub.vaultName, n - 1);
+    }
     try {
       sub.sink.close();
     } catch {
@@ -182,33 +257,21 @@ export class SubscriptionManager {
     }
   }
 
-  /**
-   * Send a keepalive comment to every open subscription (the route's timer
-   * calls this). A `:` comment defeats idle-proxy timeouts; it's not an event
-   * so it never counts against the buffer bound.
-   */
-  keepaliveAll(): void {
-    for (const sub of this.subs) {
-      if (sub.closed) continue;
-      const ok = sub.sink.write(":\n\n");
-      if (!ok) this.remove(sub);
-    }
-  }
-
-  /** Emit a frame to one subscription, enforcing the buffer bound. */
-  private emit(sub: Subscription, frame: SseFrame): void {
+  /** Emit an `(event, data)` tuple to one subscription, enforcing the buffer
+   *  bound for flush-tracking (SSE) sinks. */
+  private emit(sub: Subscription, event: string, data: unknown): void {
     if (sub.closed) return;
-    if (sub.buffered >= sub.maxBuffered) {
+    if (sub.tracksFlush && sub.buffered >= sub.maxBuffered) {
       // Backpressure: client can't keep up. Close → it reconnects + re-snapshots.
       this.remove(sub);
       return;
     }
-    const ok = sub.sink.write(frame);
+    const ok = sub.sink.send(event, data);
     if (!ok) {
       this.remove(sub);
       return;
     }
-    sub.buffered++;
+    if (sub.tracksFlush) sub.buffered++;
   }
 
   /** Lazily register the three broad hooks (once per manager). */
@@ -244,7 +307,7 @@ export class SubscriptionManager {
         // the client ignores ids it never held. Documented low-sensitivity
         // existence leak (see design §scope-intersection).
         const ref = payload as DeletedNoteRef;
-        this.emit(sub, sseEvent("remove", { id: ref.id }));
+        this.emit(sub, "remove", { id: ref.id });
         continue;
       }
 
@@ -257,14 +320,14 @@ export class SubscriptionManager {
       const matches = sub.matcher.match(note) && inScope;
 
       if (matches) {
-        this.emit(sub, sseEvent("upsert", { note }));
+        this.emit(sub, "upsert", { note });
       } else if (event === "updated" && inScope) {
         // Left the set (predicate no longer true) BUT still within this
         // token's scope, so the sub could have held it — idempotent remove
         // (client drops the id if held, no-op otherwise). When the note is
         // OUT of scope the sub never had it; emitting would leak its id, so
         // we stay silent.
-        this.emit(sub, sseEvent("remove", { id: note.id }));
+        this.emit(sub, "remove", { id: note.id });
       }
       // created that doesn't match → nothing (it was never in the set).
     }
@@ -286,10 +349,5 @@ export interface SubscriptionHandle {
   close: () => void;
 }
 
-/** Serialize a snapshot frame (exported for the route + tests). */
-export function snapshotFrame(notes: Note[]): SseFrame {
-  return sseEvent("snapshot", { notes });
-}
-
 /** Process-wide manager — shared like `defaultHookRegistry`. */
 export const subscriptionManager = new SubscriptionManager();

package/src/tag-scope.ts

@@ -1,12 +1,12 @@
 /**
- * Tag-scope enforcement for tag-scoped tokens (patterns/tag-scoped-tokens.md).
+ * Tag-scope enforcement for tag-scoped tokens (docs/contracts/tag-scoped-tokens.md).
  *
  * A token's `scoped_tags` allowlist narrows its effective access to notes
  * carrying one of the allowlisted tags or a sub-tag thereof. The expansion
  * to descendants happens via the per-vault `_tags/<name>` config-note
  * hierarchy (see core/src/tag-hierarchy.ts).
  *
- * Auth check pseudocode (from patterns/tag-scoped-tokens.md):
+ * Auth check pseudocode (from docs/contracts/tag-scoped-tokens.md):
  *
  *   if (!hasScope(token, ...)) return forbidden();
  *   if (token.scoped_tags === null) return ok();   // unscoped
@@ -38,7 +38,7 @@ export async function expandTokenTagScope(
 
 /**
  * Return true iff the note's tag set intersects the expanded allowlist OR
- * — fail-open per patterns/tag-scoped-tokens.md §Storage — any of the
+ * — fail-open per docs/contracts/tag-scoped-tokens.md §Storage — any of the
  * note's tags has a string-form root inside `rawRoots`. The string-form
  * fallback covers the orphan-sub-tag case: a token allowlisted for
  * `health` should still see `#health/food` even when no `_tags/health/food`

package/src/test-support/live-frame-corpus.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared live-query frame corpus — MIRRORED VERBATIM from the cloud door's
+ * `parachute-cloud/workers/vault/test/fixtures/live-frame-corpus.ts` (the SINGLE
+ * source of truth). Kept byte-identical here so the self-host WS/SSE parity test
+ * asserts against the EXACT same fixture the cloud door pins — the load-bearing
+ * cross-door conformance check (WS-hibernation migration, 2026-07-04). If the
+ * canonical corpus changes upstream, re-mirror this file.
+ *
+ * Each case is a transport-neutral `(event, data)` tuple. The invariant under
+ * test: for a given case, the SSE `data:` body and the WS message carry a
+ * byte-IDENTICAL serialization of the inner payload (`notes` / `note` / `id`) —
+ * the ONLY difference is that the WS message folds the SSE `event:` NAME into a
+ * `type` discriminator (`{ type, ...data }`), because a WebSocket message has no
+ * separate event-name framing. The snapshot case additionally chunks with a
+ * `done` flag on the WS side (transport framing under the ~1 MiB message cap);
+ * its note OBJECTS still serialize identically.
+ *
+ * The notes deliberately include the drift-prone bits: unicode, nested metadata,
+ * a null value, an empty array, quotes/newlines in content, and stable key
+ * ordering — anything a careless re-serialization would reorder or mangle.
+ */
+
+/** A note-shaped payload (loosely typed — the parity test cares about bytes, not
+ *  the full Note interface; the wire carries whatever the store returns). */
+export interface CorpusNote {
+  id: string;
+  path: string;
+  content: string;
+  tags: string[];
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+  extension: string;
+}
+
+export const NOTE_A: CorpusNote = {
+  id: "11111111-1111-4111-8111-111111111111",
+  path: "greetings/héllo",
+  content: 'line one\nline "two" with quotes\n#greeting [[world]]',
+  tags: ["greeting", "watch"],
+  metadata: { mood: "warm", priority: 5, pinned: true, note: null, aliases: [] },
+  createdAt: "2026-07-04T00:00:00.000Z",
+  updatedAt: "2026-07-04T00:00:01.000Z",
+  extension: "md",
+};
+
+export const NOTE_B: CorpusNote = {
+  id: "22222222-2222-4222-8222-222222222222",
+  path: "meetings/2026-07-04",
+  content: "standup — ☂️ parachute cloud",
+  tags: ["meeting"],
+  metadata: { attendees: ["aaron", "uni"], count: 2 },
+  createdAt: "2026-07-04T09:00:00.000Z",
+  updatedAt: "2026-07-04T09:30:00.000Z",
+  extension: "md",
+};
+
+export interface FrameCase {
+  name: string;
+  event: "snapshot" | "upsert" | "remove";
+  /** The inner payload — the SSE `data:` body is exactly `JSON.stringify(data)`;
+   *  the WS message is `JSON.stringify({ type: event, ...data })`. */
+  data: Record<string, unknown>;
+}
+
+export const FRAME_CORPUS: FrameCase[] = [
+  { name: "snapshot (two notes)", event: "snapshot", data: { notes: [NOTE_A, NOTE_B] } },
+  { name: "snapshot (empty set)", event: "snapshot", data: { notes: [] } },
+  { name: "upsert (rich note)", event: "upsert", data: { note: NOTE_A } },
+  { name: "upsert (unicode note)", event: "upsert", data: { note: NOTE_B } },
+  { name: "remove (id)", event: "remove", data: { id: NOTE_A.id } },
+];

package/src/token-store.ts

@@ -54,7 +54,7 @@ export interface Token {
    * access is the intersection of `scopes` and notes carrying one of these
    * tags or a sub-tag thereof (hierarchy expansion via getTagDescendants).
    * NULL = unscoped, full vault access per `scopes`. See
-   * patterns/tag-scoped-tokens.md.
+   * docs/contracts/tag-scoped-tokens.md.
    */
   scoped_tags: string[] | null;
   /**
@@ -301,7 +301,7 @@ export function markMcpMintLedgerRevoked(
  * Returns display ID + label pairs (no token-hash exposure) so error
  * envelopes can name the offending tokens for the operator. The match is
  * exact on the root name — `scoped_tags` only ever stores roots per
- * patterns/tag-scoped-tokens.md.
+ * docs/contracts/tag-scoped-tokens.md.
  */
 export function findTokensReferencingTag(
   db: Database,

package/src/transcription/build.test.ts

@@ -6,6 +6,9 @@ import {
   detectCompiler,
   compilerInstallHint,
   cliSourceUrl,
+  patchMainCppBackendInit,
+  BACKEND_INIT_PATCH_ANCHOR,
+  BACKEND_INIT_PATCH_MARKER,
   CLI_SOURCE_FILES,
   CXX_CANDIDATES,
   TRANSCRIBE_CPP_SOURCE_REF,
@@ -17,10 +20,26 @@ import {
  * transcribe-cli build tests (scribe-fold Phase 2b). Pure recipe shape +
  * fully-mocked orchestration — NO network, NO real compiler (the real compile
  * is exercised only by the install-time live verify). Covers the toolchain-
- * absent, fetch-failure, compile-failure, and success branches, and the
- * "never leave a half-built binary" invariant.
+ * absent, fetch-failure, patch-failure, compile-failure, and success branches,
+ * and the "never leave a half-built binary" invariant.
  */
 
+/** A minimal stand-in for the pinned main.cpp: log-sink install + the batch-
+ *  mode comment the vault#534 patch anchors on. */
+const MAIN_CPP_FIXTURE = [
+  "int main(int argc, char ** argv) {",
+  "    if (!args.quiet) {",
+  "        transcribe_log_set(log_cb, nullptr);",
+  "    }",
+  "",
+  BACKEND_INIT_PATCH_ANCHOR,
+  "    // the model ONCE and reuses the context across all files.",
+  "    if (!args.batch_file.empty()) {",
+  "    }",
+  "}",
+  "",
+].join("\n");
+
 describe("detectCompiler", () => {
   test("returns the first candidate found (c++ preferred)", () => {
     const which = (c: string) => (c === "c++" ? "/usr/bin/c++" : null);
@@ -106,15 +125,31 @@ describe("buildCompileCommand — the proven recipe shape", () => {
 
 /** Build a deps object with call-recording mocks; overrides win. */
 function mkDeps(over: Partial<BuildCliDeps> = {}): BuildCliDeps & {
-  calls: { fetch: number; compile: number; removed: string[]; renamed: Array<[string, string]> };
+  calls: {
+    fetch: number;
+    compile: number;
+    removed: string[];
+    renamed: Array<[string, string]>;
+    written: Array<[string, string]>;
+  };
 } {
-  const calls = { fetch: 0, compile: 0, removed: [] as string[], renamed: [] as Array<[string, string]> };
+  const calls = {
+    fetch: 0,
+    compile: 0,
+    removed: [] as string[],
+    renamed: [] as Array<[string, string]>,
+    written: [] as Array<[string, string]>,
+  };
   const deps: BuildCliDeps = {
     platform: "darwin",
     which: (c) => (c === "c++" ? "/usr/bin/c++" : null),
     fetchSource: async () => {
       calls.fetch++;
     },
+    readFile: () => MAIN_CPP_FIXTURE,
+    writeFile: (p, content) => {
+      calls.written.push([p, content]);
+    },
     compile: async (): Promise<CompileResult> => {
       calls.compile++;
       return { exitCode: 0, stderr: "" };
@@ -134,8 +169,36 @@ function mkDeps(over: Partial<BuildCliDeps> = {}): BuildCliDeps & {
 const INPUT = { srcDir: "/t/.src", libsDir: "/t/libs", binPath: "/t/bin/transcribe-cli" };
 const TMP = `${INPUT.binPath}.building`; // the temp output the build compiles to
 
+describe("patchMainCppBackendInit — the vault#534 backend-init source patch", () => {
+  test("injects transcribe_init_backends_default() before the batch-mode anchor", () => {
+    const patched = patchMainCppBackendInit(MAIN_CPP_FIXTURE);
+    expect(patched).toContain("transcribe_init_backends_default();");
+    expect(patched).toContain(BACKEND_INIT_PATCH_MARKER);
+    // The init call lands BEFORE the inference paths (the anchor) and AFTER
+    // the log-sink install, so backend plugin-load logs route through the sink.
+    const initAt = patched.indexOf("transcribe_init_backends_default();");
+    expect(initAt).toBeGreaterThan(patched.indexOf("transcribe_log_set(log_cb, nullptr);"));
+    expect(initAt).toBeLessThan(patched.indexOf(BACKEND_INIT_PATCH_ANCHOR));
+    // Everything else is preserved verbatim: removing the injected block
+    // restores the original source exactly.
+    const [before, after] = patched.split(/    \/\/ \[parachute-vault[\s\S]*?transcribe_init_backends_default\(\);\n\n/);
+    expect(`${before}${after}`).toBe(MAIN_CPP_FIXTURE);
+  });
+
+  test("idempotent: an already-patched source is returned unchanged", () => {
+    const once = patchMainCppBackendInit(MAIN_CPP_FIXTURE);
+    expect(patchMainCppBackendInit(once)).toBe(once);
+  });
+
+  test("anchor missing ⇒ throws a loud, actionable error naming the pin + vault#534", () => {
+    expect(() => patchMainCppBackendInit("int main() { return 0; }\n")).toThrow(
+      /anchor not found[\s\S]*vault#534/,
+    );
+  });
+});
+
 describe("buildTranscribeCli — orchestration branches", () => {
-  test("SUCCESS: fetch → compile ok → temp exists ⇒ promote (rename) + { ok:true }", async () => {
+  test("SUCCESS: fetch → patch → compile ok → temp exists ⇒ promote (rename) + { ok:true }", async () => {
     const deps = mkDeps();
     const r = await buildTranscribeCli(INPUT, deps);
     expect(r.ok).toBe(true);
@@ -149,11 +212,29 @@ describe("buildTranscribeCli — orchestration branches", () => {
     }
     expect(deps.calls.fetch).toBe(1);
     expect(deps.calls.compile).toBe(1);
+    // the vault#534 backend-init patch was written into the fetched main.cpp
+    expect(deps.calls.written).toHaveLength(1);
+    const [patchedPath, patchedContent] = deps.calls.written[0]!;
+    expect(patchedPath).toBe(join(INPUT.srcDir, "examples", "cli", "main.cpp"));
+    expect(patchedContent).toContain("transcribe_init_backends_default();");
     // only the TEMP is cleared pre-compile; the fresh temp is renamed into place
     expect(deps.calls.removed).toEqual([TMP]);
     expect(deps.calls.renamed).toEqual([[TMP, INPUT.binPath]]);
   });
 
+  test("PATCH FAILURE: anchor missing in fetched source ⇒ { ok:false, stage:'patch' }, no write, no compile", async () => {
+    const deps = mkDeps({ readFile: () => "int main() { return 0; }\n" });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("patch");
+      expect(r.message).toContain("anchor not found");
+      expect(r.message).toContain("vault#534");
+    }
+    expect(deps.calls.written).toEqual([]);
+    expect(deps.calls.compile).toBe(0);
+  });
+
   test("TOOLCHAIN ABSENT: no compiler ⇒ { ok:false, stage:'toolchain' }, no fetch/compile", async () => {
     const deps = mkDeps({ which: () => null });
     const r = await buildTranscribeCli(INPUT, deps);

package/src/transcription/build.ts

@@ -6,8 +6,10 @@
  * `install.ts` + the provider-seam design doc. This module closes that gap: it
  * fetches the CLI's source (`examples/cli/main.cpp` + `examples/common/wav.cpp`
  * + the public headers) from the transcribe.cpp repo pinned at the v0.1.1 tag
- * commit, then compiles it with the host C++ compiler against the extracted
- * prebuilt dylibs. The result is a ~127KB driver that links the prebuilt
+ * commit, applies the **vault#534 backend-init patch** (see
+ * `patchMainCppBackendInit` below — temporary until upstream ships the fix),
+ * then compiles it with the host C++ compiler against the extracted prebuilt
+ * dylibs. The result is a ~127KB driver that links the prebuilt
  * `libtranscribe` at runtime — **no ggml / Metal rebuild**.
  *
  * ## The proven recipe (live-verified 2026-07-03, macOS arm64 M4)
@@ -34,10 +36,11 @@
  * ## Testability
  *
  * `buildTranscribeCli` is a pure orchestrator over injected side effects
- * (`which` / `fetchSource` / `compile` / `exists` / `removeBin`), mirroring the
- * provider's `SpawnRunner` seam. Tests exercise every branch — toolchain
- * absent, fetch failure, compile failure, success — with no network and no real
- * compiler. The real compile is exercised only by the install-time live verify.
+ * (`which` / `fetchSource` / `readFile` / `writeFile` / `compile` / `exists` /
+ * `removeBin`), mirroring the provider's `SpawnRunner` seam. Tests exercise
+ * every branch — toolchain absent, fetch failure, patch failure, compile
+ * failure, success — with no network and no real compiler. The real compile is
+ * exercised only by the install-time live verify.
  */
 
 import { join } from "path";
@@ -78,6 +81,63 @@ export function cliSourceUrl(repoPath: string): string {
   return `${RAW_BASE}/${repoPath}`;
 }
 
+// ---------------------------------------------------------------------------
+// Build-time source patch: unconditional backend init (vault#534 blocker 2)
+// ---------------------------------------------------------------------------
+
+/** Marker comment baked into the injected code — makes the patch idempotent
+ *  and greppable in a fetched source tree. */
+export const BACKEND_INIT_PATCH_MARKER = "[parachute-vault vault#534 backend-init patch]";
+
+/**
+ * The anchor line in the pinned `examples/cli/main.cpp` the patch injects
+ * before: the batch-mode comment that opens the inference half of `main()`,
+ * directly AFTER the log-sink install (so backend plugin-load logs route
+ * through the CLI's log callback) and after the `--list-devices` early return.
+ * Unique at the pinned ref (verified); if the pin ever advances and this
+ * anchor drifts, the build fails LOUDLY (stage "patch") so the patch gets
+ * re-evaluated against the new source instead of silently shipping a CLI that
+ * can't transcribe on Linux.
+ */
+export const BACKEND_INIT_PATCH_ANCHOR =
+  "    // Batch mode: --batch reads a file list, one wav path per line. Loads";
+
+const BACKEND_INIT_PATCH_BLOCK = `    // ${BACKEND_INIT_PATCH_MARKER}
+    // Upstream (at the pinned ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)}) only calls
+    // transcribe_init_backends_default() in the --list-devices path. On Linux
+    // the CPU backends are dlopen plugins (libggml-cpu-*.so), so with no init
+    // the ggml device registry is empty and EVERY transcription fails
+    // ("whisper: failed to initialize CPU backend", exit 1). macOS is masked:
+    // its libtranscribe.dylib direct-links libggml-cpu, which self-registers
+    // at library load. Init the default backends unconditionally before any
+    // inference (batch or single-file). Verified fix on real Linux containers,
+    // both arches — see vault#534. DROP THIS PATCH when upstream ships the fix
+    // and the source pin advances past it.
+    transcribe_init_backends_default();
+
+`;
+
+/**
+ * Apply the vault#534 backend-init patch to the fetched `main.cpp` source.
+ * Pure (string → string) so tests pin the behavior without a filesystem.
+ * Idempotent: an already-patched source is returned unchanged. Throws with a
+ * clear operator-facing message when the anchor is missing — the caller
+ * surfaces it as a `stage: "patch"` build failure (fail loudly; never compile
+ * an unpatched CLI on the assumption it'll work).
+ */
+export function patchMainCppBackendInit(source: string): string {
+  if (source.includes(BACKEND_INIT_PATCH_MARKER)) return source;
+  const idx = source.indexOf(BACKEND_INIT_PATCH_ANCHOR);
+  if (idx === -1) {
+    throw new Error(
+      `backend-init patch anchor not found in examples/cli/main.cpp at ${TRANSCRIBE_CPP_SOURCE_REF.slice(0, 12)} — ` +
+        `the pinned source no longer matches the vault#534 patch. If the pin advanced, check whether upstream ` +
+        `now calls transcribe_init_backends_default() unconditionally (then drop the patch); otherwise re-anchor it.`,
+    );
+  }
+  return source.slice(0, idx) + BACKEND_INIT_PATCH_BLOCK + source.slice(idx);
+}
+
 /** C++ compiler binaries we probe for, in preference order. */
 export const CXX_CANDIDATES = ["c++", "clang++", "g++"] as const;
 
@@ -158,6 +218,10 @@ export interface BuildCliDeps {
   which: (cmd: string) => string | null | undefined;
   /** Fetch `files` (repo-relative) into `srcDir`. Throws on network failure. */
   fetchSource: (files: readonly string[], srcDir: string) => Promise<void>;
+  /** Read a fetched source file as UTF-8 (production: `fs.readFileSync`). */
+  readFile: (p: string) => string;
+  /** Write a patched source file (production: `fs.writeFileSync`). */
+  writeFile: (p: string, content: string) => void;
   /** Run the compiler argv. */
   compile: (cmd: string[]) => CompileResult | Promise<CompileResult>;
   /** Existence probe (production: `fs.existsSync`). */
@@ -185,7 +249,7 @@ export type CliBuildResult =
   | {
       ok: false;
       /** Which stage failed — drives the operator guidance. */
-      stage: "toolchain" | "fetch" | "compile";
+      stage: "toolchain" | "fetch" | "patch" | "compile";
       message: string;
       compiler?: string;
       /** The compile argv (as a string) when we got far enough to build one. */
@@ -223,6 +287,22 @@ export async function buildTranscribeCli(
     };
   }
 
+  // Apply the vault#534 backend-init source patch BEFORE compiling — without
+  // it the built CLI exits 1 on every transcription on Linux (dlopen'd CPU
+  // backends are never registered). A missing anchor is a loud, typed failure,
+  // never a silent skip.
+  const mainCppPath = join(input.srcDir, "examples", "cli", "main.cpp");
+  try {
+    deps.writeFile(mainCppPath, patchMainCppBackendInit(deps.readFile(mainCppPath)));
+  } catch (err) {
+    return {
+      ok: false,
+      stage: "patch",
+      compiler,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+
   const common = { platform: deps.platform, compiler, srcDir: input.srcDir, libsDir: input.libsDir };
   // The reported command targets the FINAL binPath (what an operator would run
   // by hand to reproduce). The actual compile writes to a temp sibling and is