@openparachute/vault 0.6.5-rc.2 → 0.6.5

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

@@ -0,0 +1,305 @@
+import { describe, test, expect } from "bun:test";
+import { join } from "path";
+import {
+  buildTranscribeCli,
+  buildCompileCommand,
+  detectCompiler,
+  compilerInstallHint,
+  cliSourceUrl,
+  patchMainCppBackendInit,
+  BACKEND_INIT_PATCH_ANCHOR,
+  BACKEND_INIT_PATCH_MARKER,
+  CLI_SOURCE_FILES,
+  CXX_CANDIDATES,
+  TRANSCRIBE_CPP_SOURCE_REF,
+  type BuildCliDeps,
+  type CompileResult,
+} from "./build.ts";
+
+/**
+ * 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, 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);
+    expect(detectCompiler(which)).toBe("/usr/bin/c++");
+  });
+  test("falls through to a later candidate when earlier ones are absent", () => {
+    const which = (c: string) => (c === "g++" ? "/usr/bin/g++" : null);
+    expect(detectCompiler(which)).toBe("/usr/bin/g++");
+  });
+  test("returns null when NO compiler is on PATH", () => {
+    expect(detectCompiler(() => null)).toBeNull();
+    expect(detectCompiler(() => undefined)).toBeNull();
+  });
+  test("probes the documented candidate order", () => {
+    expect([...CXX_CANDIDATES]).toEqual(["c++", "clang++", "g++"]);
+  });
+});
+
+describe("compilerInstallHint", () => {
+  test("macOS → xcode-select", () => {
+    expect(compilerInstallHint("darwin")).toContain("xcode-select --install");
+  });
+  test("linux → build-essential / gcc-c++", () => {
+    const h = compilerInstallHint("linux");
+    expect(h).toContain("build-essential");
+    expect(h).toContain("gcc-c++");
+  });
+  test("other → generic compiler hint", () => {
+    expect(compilerInstallHint("win32")).toContain("c++/clang++/g++");
+  });
+});
+
+describe("cliSourceUrl + CLI_SOURCE_FILES", () => {
+  test("URL pins the exact v0.1.1 source ref", () => {
+    const url = cliSourceUrl("examples/cli/main.cpp");
+    expect(url).toContain("raw.githubusercontent.com/handy-computer/transcribe.cpp");
+    expect(url).toContain(TRANSCRIBE_CPP_SOURCE_REF);
+    expect(url.endsWith("/examples/cli/main.cpp")).toBe(true);
+  });
+  test("source set covers the CLI + WAV loader + public header", () => {
+    expect(CLI_SOURCE_FILES).toContain("examples/cli/main.cpp");
+    expect(CLI_SOURCE_FILES).toContain("examples/common/wav.cpp");
+    expect(CLI_SOURCE_FILES).toContain("examples/common/wav.h");
+    expect(CLI_SOURCE_FILES).toContain("examples/common/dr_wav.h");
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe.h");
+    // headers main.cpp includes directly
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe/parakeet.h");
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe/whisper.h");
+    expect(CLI_SOURCE_FILES).toContain("include/transcribe/voxtral_realtime.h");
+  });
+});
+
+describe("buildCompileCommand — the proven recipe shape", () => {
+  const base = {
+    compiler: "/usr/bin/c++",
+    srcDir: "/root/.parachute/transcription/.src",
+    libsDir: "/root/.parachute/transcription/libs",
+    outPath: "/root/.parachute/transcription/bin/transcribe-cli",
+  };
+
+  test("macOS → @loader_path/../libs rpath", () => {
+    const cmd = buildCompileCommand({ ...base, platform: "darwin" });
+    expect(cmd[0]).toBe("/usr/bin/c++");
+    expect(cmd).toContain("-std=c++17");
+    expect(cmd).toContain(`-I${join(base.srcDir, "include")}`);
+    expect(cmd).toContain(`-I${join(base.srcDir, "examples", "common")}`);
+    expect(cmd).toContain(join(base.srcDir, "examples", "cli", "main.cpp"));
+    expect(cmd).toContain(join(base.srcDir, "examples", "common", "wav.cpp"));
+    expect(cmd).toContain(`-L${base.libsDir}`);
+    expect(cmd).toContain("-ltranscribe");
+    expect(cmd).toContain("-Wl,-rpath,@loader_path/../libs");
+    // output is the final -o <path>
+    expect(cmd[cmd.length - 2]).toBe("-o");
+    expect(cmd[cmd.length - 1]).toBe(base.outPath);
+  });
+
+  test("Linux → $ORIGIN/../libs rpath (literal — passed to argv, not a shell)", () => {
+    const cmd = buildCompileCommand({ ...base, platform: "linux" });
+    expect(cmd).toContain("-Wl,-rpath,$ORIGIN/../libs");
+    expect(cmd).not.toContain("-Wl,-rpath,@loader_path/../libs");
+  });
+});
+
+/** 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]>;
+    written: 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: "" };
+    },
+    exists: () => true,
+    removeBin: (p) => {
+      calls.removed.push(p);
+    },
+    rename: (from, to) => {
+      calls.renamed.push([from, to]);
+    },
+    ...over,
+  };
+  return Object.assign(deps, { calls });
+}
+
+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 → patch → compile ok → temp exists ⇒ promote (rename) + { ok:true }", async () => {
+    const deps = mkDeps();
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.binPath).toBe(INPUT.binPath);
+      expect(r.compiler).toBe("/usr/bin/c++");
+      // reported command targets the FINAL binPath (reproducible by hand), not the temp
+      expect(r.command).toContain("-ltranscribe");
+      expect(r.command).toContain(`-o ${INPUT.binPath}`);
+      expect(r.command).not.toContain(TMP);
+    }
+    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);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("toolchain");
+      expect(r.message).toContain("no C++ compiler");
+      expect(r.message).toContain("xcode-select"); // darwin hint embedded
+    }
+    expect(deps.calls.fetch).toBe(0);
+    expect(deps.calls.compile).toBe(0);
+  });
+
+  test("FETCH FAILURE: fetchSource throws ⇒ { ok:false, stage:'fetch' }, no compile", async () => {
+    const deps = mkDeps({
+      fetchSource: async () => {
+        throw new Error("network down");
+      },
+    });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("fetch");
+      expect(r.message).toContain("network down");
+      expect(r.message).toContain(TRANSCRIBE_CPP_SOURCE_REF);
+    }
+    expect(deps.calls.compile).toBe(0);
+  });
+
+  test("COMPILE FAILURE (nonzero exit): keeps provider + surfaces stderr + command; only the temp is cleaned", async () => {
+    const deps = mkDeps({
+      compile: async () => ({ exitCode: 1, stderr: "main.cpp:9: fatal error: transcribe.h not found" }),
+    });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.stage).toBe("compile");
+      expect(r.message).toContain("transcribe.h not found");
+      expect(r.command).toContain("-ltranscribe");
+    }
+    // ONLY the temp is touched (pre-clear + post-cleanup) — the real binPath is never removed
+    expect(deps.calls.removed).toEqual([TMP, TMP]);
+    expect(deps.calls.removed).not.toContain(INPUT.binPath);
+    expect(deps.calls.renamed).toEqual([]);
+  });
+
+  test("COMPILE 'succeeds' but output missing ⇒ { ok:false, stage:'compile' } + only temp cleaned", async () => {
+    const deps = mkDeps({ exists: () => false });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.stage).toBe("compile");
+    expect(deps.calls.removed).toEqual([TMP, TMP]);
+    expect(deps.calls.renamed).toEqual([]);
+  });
+
+  test("ATOMIC: a failed rebuild NEVER removes/renames the existing binary (--force safety)", async () => {
+    // Simulate an existing working binary present at binPath; the rebuild fails.
+    const deps = mkDeps({
+      exists: (p) => p === INPUT.binPath, // real binary exists; the temp never appears
+      compile: async () => ({ exitCode: 1, stderr: "boom" }),
+    });
+    const r = await buildTranscribeCli(INPUT, deps);
+    expect(r.ok).toBe(false);
+    // The existing binary is untouched: no removeBin/rename ever names binPath.
+    expect(deps.calls.removed).not.toContain(INPUT.binPath);
+    expect(deps.calls.renamed).toEqual([]);
+  });
+});