@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/src/hub-jwt.test.ts

@@ -14,7 +14,14 @@
  */
 import { describe, test, expect, beforeAll, afterAll, beforeEach } from "bun:test";
 import { generateKeyPair, exportJWK, SignJWT } from "jose";
-import { resetJwksCache, resetRevocationCache, validateHubJwt, looksLikeJwt } from "./hub-jwt.ts";
+import {
+  resetJwksCache,
+  resetRevocationCache,
+  validateHubJwt,
+  looksLikeJwt,
+  getHubOrigin,
+  getJwksOrigin,
+} from "./hub-jwt.ts";
 
 interface Keypair {
   privateKey: CryptoKey;
@@ -113,6 +120,7 @@ async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
 let fixture: JwksFixture;
 let kp: Keypair;
 let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
 
 beforeAll(async () => {
   fixture = startJwksFixture();
@@ -124,12 +132,19 @@ afterAll(() => {
   fixture.stop();
   if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
   else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  if (prevJwksOrigin === undefined) delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  else process.env.PARACHUTE_HUB_JWKS_ORIGIN = prevJwksOrigin;
 });
 
 beforeEach(() => {
-  // Each test sets its own origin for clarity.
+  // Each test sets its own origin for clarity. Post-vault#464 the JWKS *fetch*
+  // origin is resolved separately from the iss-validation origin, so point the
+  // JWKS fetch at the fixture too — otherwise the guard would read keys from
+  // the loopback default (no JWKS server there) and every case would fail.
   prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
   fixture.setUnreachable(false);
   fixture.setKeys([kp]);
   resetJwksCache();
@@ -153,6 +168,64 @@ describe("looksLikeJwt", () => {
   });
 });
 
+describe("origin resolvers — iss/jwks split (vault#464)", () => {
+  test("getHubOrigin honors PARACHUTE_HUB_ORIGIN (iss-validation origin)", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "https://vault.example.com/";
+    expect(getHubOrigin()).toBe("https://vault.example.com");
+  });
+
+  test("getHubOrigin falls back to loopback when unset", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("getJwksOrigin defaults to loopback (no env override)", () => {
+    delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+    expect(getJwksOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("getJwksOrigin honors PARACHUTE_HUB_JWKS_ORIGIN and strips trailing slash", () => {
+    process.env.PARACHUTE_HUB_JWKS_ORIGIN = "http://10.0.0.5:1939/";
+    expect(getJwksOrigin()).toBe("http://10.0.0.5:1939");
+  });
+
+  test("jwks fetch is decoupled from the iss origin: keys served ONLY at the jwks origin still validate a token whose iss is the (separate) public origin", async () => {
+    // Mirrors the vault#464 deploy shape: iss + revocation live at the public
+    // origin (the default `fixture` here), while the JWKS is reachable only at
+    // a SEPARATE jwks origin (a second fixture standing in for loopback). The
+    // guard must fetch keys from the jwks origin, not the iss origin.
+    const jwksOnly = startJwksFixture();
+    jwksOnly.setKeys([kp]);
+    // The public iss origin (default fixture) serves revocation but NOT keys —
+    // if the guard fetched JWKS from here, verification would fail "no key".
+    fixture.setKeys([]);
+    try {
+      process.env.PARACHUTE_HUB_ORIGIN = fixture.origin; // iss + revocation
+      process.env.PARACHUTE_HUB_JWKS_ORIGIN = jwksOnly.origin; // keys only
+      resetJwksCache();
+      const token = await signJwt(kp, { iss: fixture.origin });
+      const claims = await validateHubJwt(token);
+      expect(claims.sub).toBe("user-1");
+    } finally {
+      jwksOnly.stop();
+    }
+  });
+
+  test("token whose iss does NOT match the iss origin is rejected even when keys resolve at the jwks origin", async () => {
+    const jwksOnly = startJwksFixture();
+    jwksOnly.setKeys([kp]);
+    try {
+      process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+      process.env.PARACHUTE_HUB_JWKS_ORIGIN = jwksOnly.origin;
+      resetJwksCache();
+      const token = await signJwt(kp, { iss: "https://attacker.example" });
+      await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+    } finally {
+      jwksOnly.stop();
+    }
+  });
+});
+
 describe("validateHubJwt — happy path", () => {
   test("valid JWT with correct iss → claims surface", async () => {
     const token = await signJwt(kp, { iss: fixture.origin, scope: "vault:work:read vault:work:write" });

package/src/hub-jwt.ts

@@ -23,13 +23,18 @@ import {
 const DEFAULT_HUB_LOOPBACK = "http://127.0.0.1:1939";
 
 /**
- * Resolve the hub origin used to fetch JWKS and validate `iss`. Strips a
+ * Resolve the hub origin used to validate the token's `iss` claim. Strips a
  * trailing slash so we get a single canonical form.
  *
  * Order: env var → loopback fallback. We deliberately don't read
  * `~/.parachute/services.json` — the hub is the dispatcher, not a registered
  * service in that file. If a deployment exposes the hub on a non-default
  * origin, the env var is the contract.
+ *
+ * `parachute expose` pins `PARACHUTE_HUB_ORIGIN` to the PUBLIC FQDN so the
+ * `iss` we validate against matches what the hub stamps on the tokens it
+ * mints — keep using this origin for iss-validation. The JWKS *fetch* origin
+ * is resolved separately by `getJwksOrigin()`; see vault#464.
  */
 export function getHubOrigin(): string {
   const env = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
@@ -37,12 +42,44 @@ export function getHubOrigin(): string {
   return DEFAULT_HUB_LOOPBACK;
 }
 
+/**
+ * Resolve the origin used to FETCH the hub's JWKS — kept distinct from
+ * `getHubOrigin()` (the iss-validation origin) per vault#464.
+ *
+ * Vault is co-located with its hub (the hub supervises vault on the same box,
+ * the common deploy). After `parachute expose --cloudflare`, `getHubOrigin()`
+ * is the public Cloudflare FQDN. If we fetched JWKS from that public origin we
+ * would hairpin out through the tunnel and back to the same box — a round-trip
+ * that times out (hard fail under Docker NAT-loopback, slow/flaky on a real
+ * VPS) and 401s the first MCP connect after expose. So we always read keys
+ * from the LOCAL hub on loopback instead.
+ *
+ * Order: `PARACHUTE_HUB_JWKS_ORIGIN` override → loopback default. The override
+ * exists for the rare non-co-located case — a vault running on a DIFFERENT box
+ * than its hub sets `PARACHUTE_HUB_JWKS_ORIGIN` to the hub's reachable
+ * internal address. Trailing-slash-stripped, matching `getHubOrigin()`.
+ */
+export function getJwksOrigin(): string {
+  const env = process.env.PARACHUTE_HUB_JWKS_ORIGIN?.replace(/\/$/, "");
+  if (env && env.length > 0) return env;
+  return DEFAULT_HUB_LOOPBACK;
+}
+
 // Process-wide guard. The resolver form lets tests flip
-// `PARACHUTE_HUB_ORIGIN` between cases — the lib re-resolves on every
-// `validateHubJwt` and `resetJwksCache` call so the env-var change picks up
-// without a server restart. JWKS cache (5min/30s defaults) lives inside the
-// guard, shared across requests.
-const guard = createScopeGuard({ hubOrigin: () => getHubOrigin() });
+// `PARACHUTE_HUB_ORIGIN` / `PARACHUTE_HUB_JWKS_ORIGIN` between cases — the lib
+// re-resolves on every `validateHubJwt` and `resetJwksCache` call so the
+// env-var change picks up without a server restart. JWKS cache (5min/30s
+// defaults) lives inside the guard, shared across requests.
+//
+// The iss/jwks split (vault#464): `hubOrigin` validates the token's `iss`
+// (public FQDN post-expose, via PARACHUTE_HUB_ORIGIN); `jwksOrigin` fetches
+// the keys from the local hub (loopback by default, via
+// PARACHUTE_HUB_JWKS_ORIGIN). Co-located vault never egresses to read its own
+// hub's keys, so no tunnel hairpin.
+const guard = createScopeGuard({
+  hubOrigin: () => getHubOrigin(),
+  jwksOrigin: () => getJwksOrigin(),
+});
 
 /**
  * Verify a presented JWT against the hub's JWKS. Throws `HubJwtError` on any

package/src/init-summary.test.ts

@@ -13,6 +13,7 @@ const baseInput = {
   bindHost: "127.0.0.1",
   port: 1940,
   mcpUrl: "http://127.0.0.1:1940/vault/default/mcp",
+  vaultName: "default",
 };
 
 function lines(addMcp: boolean, addToken: boolean, apiKey: string | undefined) {
@@ -96,16 +97,70 @@ describe("buildInitSummaryLines", () => {
     });
   });
 
-  describe("MCP=N + token=N (unreachable)", () => {
+  // vault#442: the DEFAULT init path — MCP wired, NO token minted (per-user
+  // OAuth). The summary must LEAD with the OAuth connect path, never mint, and
+  // never surface the old "no token issued" failure copy.
+  describe("MCP=Y + no token (vault#442 OAuth default)", () => {
+    const out = lines(true, false, undefined).join("\n");
+
+    test("leads with the OAuth connect message — no token needed", () => {
+      expect(out).toContain("no token needed, you'll sign in on first use");
+    });
+
+    test("tells the user Claude Code is already wired in", () => {
+      expect(out).toContain("Claude Code is already wired in");
+    });
+
+    test("shows the OAuth `claude mcp add` command for other clients", () => {
+      expect(out).toContain(
+        "claude mcp add --transport http parachute-vault http://127.0.0.1:1940/vault/default/mcp",
+      );
+    });
+
+    test("offers the scope-narrow opt-in mint for scripts (full vault:<name>:read, never admin)", () => {
+      // Must be the three-segment named-resource form the hub mint-token model
+      // requires — a bare `vault:read` would mint a malformed scope (vault#443).
+      expect(out).toContain("parachute auth mint-token --scope vault:default:read");
+      expect(out).not.toContain("--scope vault:read ");
+      expect(out).not.toMatch(/--scope vault:read$/m);
+      expect(out).not.toContain("vault:admin");
+    });
+
+    test("does NOT print or imply any minted token", () => {
+      expect(out).not.toContain("Your API token:");
+      expect(out).not.toContain("Baked into ~/.claude.json");
+      expect(out).not.toContain("Authorization: Bearer");
+    });
+
+    test("does NOT surface the old no-token-issued failure copy", () => {
+      expect(out).not.toContain("No token issued");
+    });
+
+    test("threads a non-default vault name into the mint-token scope", () => {
+      const out2 = buildInitSummaryLines({
+        ...baseInput,
+        vaultName: "journal",
+        mcpUrl: "http://127.0.0.1:1940/vault/journal/mcp",
+        addMcp: true,
+        addToken: false,
+        apiKey: undefined,
+      }).join("\n");
+      expect(out2).toContain("parachute auth mint-token --scope vault:journal:read");
+      expect(out2).not.toContain("vault:default:read");
+    });
+  });
+
+  describe("MCP=N + token=N (OAuth default, Claude Code not wired)", () => {
     const out = lines(false, false, undefined).join("\n");
 
-    test("warns the vault is unreachable", () => {
-      expect(out).toContain("your vault isn't reachable by any client");
+    test("frames skipping the MCP entry as OAuth-first, not 'unreachable'", () => {
+      expect(out).toContain("uses per-user OAuth, no token needed");
+      expect(out).not.toContain("your vault isn't reachable by any client");
     });
 
-    test("points to the mcp-install recovery path (hub JWT)", () => {
+    test("points to mcp-install (no token-minting framing)", () => {
       expect(out).toContain("parachute-vault mcp-install");
-      expect(out).toContain("mints a hub JWT");
+      expect(out).not.toContain("mints a hub JWT");
     });
 
     test("does not print any token", () => {
@@ -118,6 +173,66 @@ describe("buildInitSummaryLines", () => {
     });
   });
 
+  // Explicit opt-in but no hub reachable to mint (vault#282 Stage 2 path,
+  // reached only when the operator passes --token without a hub).
+  describe("MCP=N + token=Y but no hub (opt-in mint failed, standalone)", () => {
+    const out = buildInitSummaryLines({
+      ...baseInput,
+      addMcp: false,
+      addToken: true,
+      apiKey: undefined,
+      noTokenGuidance: "No token issued — hub unreachable.",
+      hubPresent: false,
+    }).join("\n");
+
+    test("surfaces the no-token-issued guidance + recovery", () => {
+      expect(out).toContain("No token issued");
+      expect(out).toContain("parachute-vault mcp-install");
+    });
+
+    test("standalone framing — points at bringing a hub up / VAULT_AUTH_TOKEN", () => {
+      expect(out).toContain("Once a hub is running");
+      expect(out).toContain("VAULT_AUTH_TOKEN");
+    });
+
+    test("does NOT claim the vault is reachable (no hub present)", () => {
+      expect(out).not.toContain("Your vault is still reachable");
+    });
+  });
+
+  // #445: opted into a token, none minted, but a HUB IS PRESENT. The vault is
+  // reachable via the hub's browser OAuth flow even with no header-auth token,
+  // so the standalone "isn't reachable" framing would be false here.
+  describe("MCP=N + token=Y, no token minted, but hub present (#445)", () => {
+    const out = buildInitSummaryLines({
+      ...baseInput,
+      addMcp: false,
+      addToken: true,
+      apiKey: undefined,
+      noTokenGuidance: "No token yet — the hub's admin wizard mints it.",
+      hubPresent: true,
+    }).join("\n");
+
+    test("affirms the vault is still reachable via the hub's OAuth flow", () => {
+      expect(out).toContain("Your vault is still reachable");
+      expect(out).toContain("sign-in (OAuth)");
+    });
+
+    test("frames a header-auth token as optional (scripts / non-OAuth clients)", () => {
+      expect(out).toContain("only needed for scripts");
+      expect(out).toContain("parachute-vault mcp-install");
+    });
+
+    test("does NOT print the standalone 'Once a hub is running' / VAULT_AUTH_TOKEN copy", () => {
+      expect(out).not.toContain("Once a hub is running");
+      expect(out).not.toContain("VAULT_AUTH_TOKEN");
+    });
+
+    test("never claims the vault isn't reachable by any client", () => {
+      expect(out).not.toContain("isn't reachable by any client");
+    });
+  });
+
   test("always prints Config: and Server: lines", () => {
     for (const [addMcp, addToken] of [
       [true, true],

package/src/init-summary.ts

@@ -12,6 +12,13 @@ export type InitSummaryInput = {
   bindHost: string;
   port: number;
   mcpUrl: string;
+  /**
+   * The default vault's name — used to emit the three-segment
+   * `vault:<vaultName>:read` scope in the OAuth-first mint-token suggestion
+   * (the hub mint-token model requires the named-resource form;
+   * a bare `vault:read` would mint a malformed scope). vault#442/#443.
+   */
+  vaultName: string;
   /**
    * Guidance from the bootstrap-credential step when no token could be issued
    * (standalone install, no hub reachable — vault#282 Stage 2). Surfaced when
@@ -19,66 +26,101 @@ export type InitSummaryInput = {
    * undefined, so they know why and how to make the vault reachable.
    */
   noTokenGuidance?: string | undefined;
+  /**
+   * Whether a hub is present on this host (live `/health` probe or a
+   * configured hub origin — see `detectHubPresence`). Branches the
+   * opted-into-a-token-but-none-minted copy: under a hub the vault is reachable
+   * via the hub's browser OAuth flow even with no header-auth token, so the
+   * old "your vault isn't reachable by any client" framing is false. #445.
+   * Undefined → treat as the conservative standalone case.
+   */
+  hubPresent?: boolean | undefined;
 };
 
 /**
  * Build the post-install summary lines for `vault init`, branched on the
- * (addMcp, addToken, apiKey) decision matrix. Post-0.6.0 the token is a
- * hub-issued JWT minted via operator.token; when no hub is reachable `apiKey`
- * is undefined even though the operator opted in (`addToken`/`addMcp`):
+ * (addMcp, addToken, apiKey) decision matrix.
+ *
+ * vault#442: the DEFAULT is per-user OAuth — no token is minted, and the
+ * Claude Code MCP entry is written without a baked bearer (browser sign-in on
+ * first connect). A token is minted only on explicit opt-in (`addToken`), and
+ * then scope-narrow. Branches:
  *
- *   addMcp,  addToken,  apiKey → token baked into claude.json + printed
- *   addMcp,  !addToken, apiKey → token baked into claude.json, hint
- *   !addMcp, addToken,  apiKey → token printed prominently
- *   wanted-token-but-no-hub    → guidance: no token issued, recovery paths
- *   !addMcp, !addToken         → warning: vault unreachable; recovery paths
+ *   addMcp,  !apiKey            → OAuth-first: connect, sign in on first use
+ *   addMcp,  addToken,  apiKey  → token baked into claude.json + printed
+ *   addMcp,  !addToken, apiKey  → token baked into claude.json, hint
+ *   !addMcp, addToken,  apiKey  → token printed prominently
+ *   !addMcp, addToken,  !apiKey → opted into a token but no hub reachable
+ *   !addMcp, !addToken          → OAuth-first: add Claude Code later
  */
 export function buildInitSummaryLines(input: InitSummaryInput): string[] {
-  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, noTokenGuidance } = input;
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance, hubPresent } = input;
   const lines: string[] = [];
   lines.push("");
   lines.push("---");
 
-  const wantedToken = addMcp || addToken;
-
-  if (addMcp && addToken && apiKey) {
+  if (addMcp && apiKey && addToken) {
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
     lines.push(`  - Baked into ~/.claude.json for Claude Code ✓`);
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
-  } else if (addMcp && !addToken && apiKey) {
+  } else if (addMcp && apiKey && !addToken) {
     lines.push("");
     lines.push(
       "Token in ~/.claude.json; run `parachute-vault mcp-install` later if you need one for other clients.",
     );
+  } else if (addMcp && !apiKey) {
+    // vault#442 default: OAuth-first. The MCP entry is wired without a bearer —
+    // Claude Code signs in via browser OAuth on first connect. No token needed.
+    lines.push("");
+    lines.push("Connect your AI — no token needed, you'll sign in on first use:");
+    lines.push(`  Claude Code is already wired in (~/.claude.json) — just start a session.`);
+    lines.push(`  Other clients: claude mcp add --transport http parachute-vault ${mcpUrl}`);
+    lines.push(`  Need a header-auth token for a script? parachute auth mint-token --scope vault:${vaultName}:read`);
   } else if (!addMcp && addToken && apiKey) {
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
-  } else if (wantedToken && !apiKey) {
-    // Opted into a token but no hub was reachable to mint one (vault#282
-    // Stage 2 — vault no longer mints local pvt_* tokens). Surface why and
-    // the recovery paths.
+  } else if (!addMcp && addToken && !apiKey) {
+    // Explicitly opted into a token but none was minted (vault#282 Stage 2 —
+    // vault no longer mints local pvt_* tokens). Surface why + recovery.
     lines.push("");
     lines.push(
       noTokenGuidance ??
         "No token issued — no hub was reachable to mint a hub JWT.",
     );
-    lines.push(
-      "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
-    );
-    lines.push(
-      "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
-    );
+    if (hubPresent) {
+      // A hub IS present — the vault is already reachable via the hub's
+      // browser OAuth flow / web UI. A header-auth token is optional, only for
+      // non-OAuth clients + scripts. The "isn't reachable" framing is false
+      // here (#445).
+      lines.push(
+        "  Your vault is still reachable — clients connect through the hub's browser",
+      );
+      lines.push(
+        "  sign-in (OAuth); a header-auth token is only needed for scripts / non-OAuth",
+      );
+      lines.push(
+        "  clients. Run `parachute-vault mcp-install` to mint + wire one when you want it.",
+      );
+    } else {
+      lines.push(
+        "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
+      );
+      lines.push(
+        "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+      );
+    }
   } else if (!addMcp && !addToken) {
+    // OAuth-first, but the operator skipped wiring Claude Code too.
     lines.push("");
     lines.push(
-      "You've skipped both MCP install and token generation — your vault isn't reachable by any client.",
+      "Skipped the Claude Code MCP entry. Add it anytime — it uses per-user OAuth, no token needed:",
     );
     lines.push(
-      "  Add Claude Code later with `parachute-vault mcp-install`, which mints a hub JWT (needs a hub running).",
+      "  parachute-vault mcp-install",
     );
   }
 

package/src/live-match.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Predicate-parity tests for the live matcher (live-query SSE).
+ *
+ * The load-bearing invariant: for any supported query, the set of notes the
+ * snapshot SQL (`store.queryNotes`) returns MUST equal the set the in-process
+ * `buildLiveMatcher` accepts over the same corpus. Each `it` seeds a corpus,
+ * runs both evaluators for a query shape, and asserts the id-sets are equal.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "../core/src/store.ts";
+import { generateMcpTools } from "../core/src/mcp.ts";
+import type { QueryOpts } from "../core/src/types.ts";
+import { buildLiveMatcher } from "./live-match.ts";
+
+/**
+ * Declare metadata fields as `indexed: true` via the update-tag MCP tool —
+ * the only path that populates the `indexed_fields` table + reconciles the
+ * generated `meta_<field>` columns the snapshot operator queries need.
+ * `store.upsertTagSchema` alone records the schema but NOT the index.
+ */
+async function declareIndexed(tag: string, fields: Record<string, { type: string; indexed: boolean }>) {
+  const tools = generateMcpTools(store);
+  const updateTag = tools.find((t) => t.name === "update-tag")!;
+  await updateTag.execute({ tag, fields });
+}
+
+let db: Database;
+let store: SqliteStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+/** Build the parity assertion: snapshot id-set === live-matcher id-set. */
+async function assertParity(opts: QueryOpts): Promise<Set<string>> {
+  const snapshot = await store.queryNotes(opts);
+  const snapshotIds = new Set(snapshot.map((n) => n.id));
+
+  const all = await store.queryNotes({ limit: 100000 });
+  const matcher = await buildLiveMatcher(store, opts);
+  const liveIds = new Set(all.filter((n) => matcher.match(n)).map((n) => n.id));
+
+  expect([...liveIds].sort()).toEqual([...snapshotIds].sort());
+  return snapshotIds;
+}
+
+describe("live-match — predicate parity with the query engine", () => {
+  it("tags (single, no hierarchy)", async () => {
+    await store.createNote("a", { tags: ["chat"] });
+    await store.createNote("b", { tags: ["chat", "x"] });
+    await store.createNote("c", { tags: ["other"] });
+    await store.createNote("d", {});
+    const ids = await assertParity({ tags: ["chat"] });
+    expect(ids.size).toBe(2);
+  });
+
+  it("tags 'all' (AND) across multiple tags", async () => {
+    await store.createNote("a", { tags: ["chat", "x"] });
+    await store.createNote("b", { tags: ["chat"] });
+    await store.createNote("c", { tags: ["x"] });
+    const ids = await assertParity({ tags: ["chat", "x"], tagMatch: "all" });
+    expect(ids.size).toBe(1);
+  });
+
+  it("tags 'any' (OR) across multiple tags", async () => {
+    await store.createNote("a", { tags: ["chat"] });
+    await store.createNote("b", { tags: ["x"] });
+    await store.createNote("c", { tags: ["other"] });
+    const ids = await assertParity({ tags: ["chat", "x"], tagMatch: "any" });
+    expect(ids.size).toBe(2);
+  });
+
+  it("tags with descendant/hierarchy expansion", async () => {
+    // Declare voice as a child of manual via parent_names.
+    await store.upsertTagRecord("manual", { description: "manual root" });
+    await store.upsertTagRecord("voice", { parent_names: ["manual"] });
+    await store.createNote("root", { tags: ["manual"] });
+    await store.createNote("child", { tags: ["voice"] });
+    await store.createNote("unrelated", { tags: ["other"] });
+    // Query for #manual should match notes tagged #voice (a descendant).
+    const ids = await assertParity({ tags: ["manual"] });
+    expect(ids.has("nonexistent")).toBe(false);
+    // Both root + child match.
+    const notes = await store.queryNotes({ tags: ["manual"] });
+    expect(notes.length).toBe(2);
+  });
+
+  it("excludeTags (raw, no expansion — mirrors engine)", async () => {
+    await store.createNote("a", { tags: ["chat"] });
+    await store.createNote("b", { tags: ["chat", "muted"] });
+    await assertParity({ tags: ["chat"], excludeTags: ["muted"] });
+  });
+
+  it("path (case-insensitive exact)", async () => {
+    await store.createNote("a", { path: "Channels/general" });
+    await store.createNote("b", { path: "Channels/random" });
+    await assertParity({ path: "channels/general" });
+  });
+
+  it("pathPrefix", async () => {
+    await store.createNote("a", { path: "Channels/general" });
+    await store.createNote("b", { path: "Channels/random" });
+    await store.createNote("c", { path: "Other/thing" });
+    const ids = await assertParity({ pathPrefix: "Channels/" });
+    expect(ids.size).toBe(2);
+  });
+
+  it("pathPrefix (mixed-case — parity with the engine's CI LIKE) (N1)", async () => {
+    await store.createNote("a", { path: "Channels/general" });
+    await store.createNote("b", { path: "Channels/random" });
+    await store.createNote("c", { path: "Other/thing" });
+    // Lower-case prefix must still match the title-case paths, same as the
+    // engine's `LIKE 'channels/%'` (ASCII case-insensitive).
+    const ids = await assertParity({ pathPrefix: "channels/" });
+    expect(ids.size).toBe(2);
+  });
+
+  it("hasTags true/false (M1 — presence parity)", async () => {
+    await store.createNote("tagged", { tags: ["x"] });
+    await store.createNote("bare", {});
+    const has = await assertParity({ hasTags: true });
+    expect(has.size).toBe(1);
+    const none = await assertParity({ hasTags: false });
+    expect(none.size).toBe(1);
+  });
+
+  it("hasTags is ignored when a tag filter is also present (engine parity)", async () => {
+    // queryNotes drops hasTags when `tags` is set (the tag filter already
+    // constrains to tagged notes); the matcher must mirror that exactly.
+    await store.createNote("a", { tags: ["chat"] });
+    await store.createNote("b", { tags: ["other"] });
+    await assertParity({ tags: ["chat"], hasTags: false });
+  });
+
+  it("extension (default md + explicit)", async () => {
+    await store.createNote("md1", { path: "n1" });
+    await store.createNote("csv1", { path: "n2", extension: "csv" });
+    await assertParity({ extension: "csv" });
+    await assertParity({ extension: "md" });
+    await assertParity({ extension: ["csv", "yaml"] });
+  });
+
+  describe("metadata operators (indexed field)", () => {
+    beforeEach(async () => {
+      // Declare `channel` + `count` indexed so the snapshot operator path works.
+      await declareIndexed("msg", {
+        channel: { type: "string", indexed: true },
+        count: { type: "integer", indexed: true },
+      });
+      await store.createNote("g1", { tags: ["msg"], metadata: { channel: "general", count: 5 } });
+      await store.createNote("g2", { tags: ["msg"], metadata: { channel: "general", count: 10 } });
+      await store.createNote("r1", { tags: ["msg"], metadata: { channel: "random", count: 1 } });
+      await store.createNote("n1", { tags: ["msg"] }); // no channel/count
+    });
+
+    it("eq", async () => {
+      const ids = await assertParity({ tags: ["msg"], metadata: { channel: { eq: "general" } } });
+      expect(ids.size).toBe(2);
+    });
+    it("ne (absent field passes)", async () => {
+      await assertParity({ tags: ["msg"], metadata: { channel: { ne: "general" } } });
+    });
+    it("gt / gte / lt / lte", async () => {
+      await assertParity({ tags: ["msg"], metadata: { count: { gt: 5 } } });
+      await assertParity({ tags: ["msg"], metadata: { count: { gte: 5 } } });
+      await assertParity({ tags: ["msg"], metadata: { count: { lt: 5 } } });
+      await assertParity({ tags: ["msg"], metadata: { count: { lte: 5 } } });
+    });
+    it("in / not_in", async () => {
+      await assertParity({ tags: ["msg"], metadata: { channel: { in: ["general", "random"] } } });
+      await assertParity({ tags: ["msg"], metadata: { channel: { not_in: ["random"] } } });
+    });
+    it("exists true/false", async () => {
+      await assertParity({ tags: ["msg"], metadata: { channel: { exists: true } } });
+      await assertParity({ tags: ["msg"], metadata: { channel: { exists: false } } });
+    });
+    it("combined: tag + metadata operator (the channel case)", async () => {
+      const ids = await assertParity({
+        tags: ["msg"],
+        metadata: { channel: { eq: "general" }, count: { gte: 10 } },
+      });
+      expect(ids.size).toBe(1);
+    });
+  });
+
+  it("metadata primitive exact-match (shorthand)", async () => {
+    await store.createNote("a", { tags: ["t"], metadata: { kind: "note" } });
+    await store.createNote("b", { tags: ["t"], metadata: { kind: "task" } });
+    await assertParity({ tags: ["t"], metadata: { kind: "note" } });
+  });
+});