@openparachute/vault 0.7.6 → 0.7.7

package/README.md

@@ -949,26 +949,26 @@ Set `PARACHUTE_VAULT_NAME` to auto-create a first vault on startup (name: lowerc
 
 ### Cloud platforms
 
-#### Render — recommended (hub-managed, v0.6)
+#### A VPS — the tested path
 
-Most users deploy vault via parachute-hub's `/admin/modules` after the
-hub itself is on Render. See <https://parachute.computer/deploy/render/>
-for the primary v0.6 self-host story: one Render Blueprint provisions
-hub on a persistent disk, then you install vault (and the other
-Parachute modules) from the hub's admin UI. The hub container
-supervises vault's process, the shared persistent disk holds vault
-state, and module upgrades flow through the admin UI rather than
-separate Render redeploys.
+The current self-host story is a **bun-native install on a plain
+Ubuntu/Debian box**: create the box, open a root shell, paste one line.
+See <https://parachute.computer/start/>, which walks it click by click
+for DigitalOcean and works the same on Hetzner, EC2, or a machine in
+your closet. That's the path the project tests and supports.
 
-#### Render — standalone vault (advanced)
+The PaaS Blueprints below still work and stay in tree for operators who
+want them, but they're a **legacy** shape — reach for them only if you
+specifically want that platform's ergonomics.
+
+#### Render — standalone vault (legacy)
 
 The `render.yaml` Blueprint at the repo root deploys vault as its own
-Render web service, separate from hub. This is the **advanced path** —
-useful when you want vault on its own container (separate scaling,
-isolated logs, vault-only deploy without a hub) but not what the
-typical v0.6 self-host wants. If you're not sure, use the hub-managed
-path above. The standalone Blueprint stays in tree because some
-operators specifically want this shape (vault#341).
+Render web service, separate from hub — useful when you want vault on
+its own container (separate scaling, isolated logs, vault-only deploy
+without a hub). If you're not sure, use the VPS path above. The
+Blueprint stays in tree because some operators specifically want this
+shape (vault#341).
 
 Set `PARACHUTE_VAULT_NAME` to auto-create a first vault on startup (name:
 lowercase alphanumeric + hyphens or underscores, 2–32 chars). Without it

package/core/src/attachment/policy.test.ts

@@ -4,6 +4,7 @@ import {
   ATTACHMENT_MIME_TYPES,
   sanitizeAttachmentExtension,
   mimeForAttachmentExtension,
+  contentTypeForAttachmentPath,
 } from "./policy.ts";
 
 describe("sanitizeAttachmentExtension", () => {
@@ -49,6 +50,12 @@ describe("mimeForAttachmentExtension", () => {
     expect(mimeForAttachmentExtension(".azw3")).toBe("application/octet-stream");
   });
 
+  test("contentTypeForAttachmentPath ignores a caller-asserted active mime (vault#617)", () => {
+    expect(contentTypeForAttachmentPath("2026-07-17/photo.png")).toBe("image/png");
+    expect(contentTypeForAttachmentPath("notes/evil.png")).toBe("image/png");
+    expect(contentTypeForAttachmentPath("notes/unknown.azw3")).toBe("application/octet-stream");
+  });
+
   test("no MIME entry maps to a browser-active type (INVARIANT)", () => {
     const activeTypes = new Set([
       "text/html",

package/core/src/attachment/policy.ts

@@ -129,3 +129,12 @@ export function sanitizeAttachmentExtension(filename: string): string {
 export function mimeForAttachmentExtension(ext: string): string {
   return ATTACHMENT_MIME_TYPES[ext] ?? "application/octet-stream";
 }
+
+/**
+ * Download Content-Type for an attachment path (vault#617).
+ * Extension wins; the row's caller-asserted `mime_type` is never consulted.
+ * Matches REST `GET /storage/<path>` (`src/routes.ts`).
+ */
+export function contentTypeForAttachmentPath(path: string): string {
+  return mimeForAttachmentExtension(sanitizeAttachmentExtension(path));
+}

package/core/src/attachment-tickets-tool.test.ts

@@ -245,6 +245,21 @@ describe("request-attachment-download — mint", () => {
     expect(stored.attachmentId).toBe(attachment.id);
   });
 
+  test("mime_type is derived from the path, not the caller-asserted row mime (vault#617)", async () => {
+    const note = await store.createNote("# T\n", { path: "t7-mime" });
+    const attachment = await store.addAttachment(note.id, "2026-07-17/photo.png", "text/html", { size: 42 });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const result = await callTool(findTool(tools, "request-attachment-download"), {
+      attachment_id: attachment.id,
+    });
+    expect(result.mime_type).toBe("image/png");
+    const ticketId = result.url.split("/tickets/")[1] as string;
+    expect(provider.tickets.get(ticketId)!.mimeType).toBe("image/png");
+  });
+
   test("missing attachment_id → missing_required_field", async () => {
     const provider = new FakeTicketProvider();
     const tools = generateMcpTools(store, {

package/core/src/conformance.test.ts

@@ -99,6 +99,84 @@ describe("countConformanceViolations", () => {
     expect(r.violating_notes).toBe(5);
     expect(r.sample.length).toBe(2);
   });
+  describe("past the queryNotes default LIMIT 100 (vault#592)", () => {
+    it("counts every note on a >100-note tag, not just the first page", async () => {
+      for (let i = 0; i < 137; i++) {
+        await store.createNote(`n${i}`, { tags: ["task"], metadata: {} });
+      }
+      const r = countConformanceViolations(db, "task", {
+        req: { type: "string", required: true },
+      });
+      expect(r.total_notes).toBe(137);
+      expect(r.violating_notes).toBe(137);
+    });
+
+    it("reports total_notes honestly past the cap with no fields proposed", async () => {
+      for (let i = 0; i < 137; i++) {
+        await store.createNote(`n${i}`, { tags: ["task"], metadata: {} });
+      }
+      const r = countConformanceViolations(db, "task", {});
+      expect(r.total_notes).toBe(137);
+      expect(r.violating_notes).toBe(0);
+    });
+
+    it("finds violations that live only past the first 100 notes", async () => {
+      // 120 conforming notes first, then 5 violators — under the old LIMIT 100
+      // walk the violators were never even looked at.
+      for (let i = 0; i < 120; i++) {
+        await store.createNote(`ok${i}`, { tags: ["task"], metadata: { req: "here" } });
+      }
+      for (let i = 0; i < 5; i++) {
+        await store.createNote(`bad${i}`, { tags: ["task"], metadata: {} });
+      }
+      const r = countConformanceViolations(db, "task", {
+        req: { type: "string", required: true },
+      });
+      expect(r.total_notes).toBe(125);
+      expect(r.violating_notes).toBe(5);
+    });
+
+    it("counts across a tag hierarchy past the cap (descendants included)", async () => {
+      await store.upsertTagRecord("dev/log", { parent_names: ["dev"] });
+      for (let i = 0; i < 60; i++) {
+        await store.createNote(`p${i}`, { tags: ["dev"], metadata: {} });
+      }
+      for (let i = 0; i < 60; i++) {
+        await store.createNote(`c${i}`, { tags: ["dev/log"], metadata: {} });
+      }
+      const r = countConformanceViolations(db, "dev", {
+        req: { type: "string", required: true },
+      });
+      expect(r.total_notes).toBe(120);
+      expect(r.violating_notes).toBe(120);
+    });
+
+    it("counts a note carrying BOTH the tag and a descendant exactly once", async () => {
+      await store.upsertTagRecord("dev/log", { parent_names: ["dev"] });
+      for (let i = 0; i < 105; i++) {
+        await store.createNote(`both${i}`, { tags: ["dev", "dev/log"], metadata: {} });
+      }
+      const r = countConformanceViolations(db, "dev", {
+        req: { type: "string", required: true },
+      });
+      expect(r.total_notes).toBe(105);
+      expect(r.violating_notes).toBe(105);
+    });
+
+    it("still caps the sample at sampleLimit while counting the full set", async () => {
+      for (let i = 0; i < 137; i++) {
+        await store.createNote(`n${i}`, { tags: ["task"], metadata: {} });
+      }
+      const r = countConformanceViolations(
+        db,
+        "task",
+        { req: { type: "string", required: true } },
+        { sampleLimit: 3 },
+      );
+      expect(r.violating_notes).toBe(137);
+      expect(r.sample.length).toBe(3);
+    });
+  });
 });
 
 describe("store.countTagConformance", () => {

package/core/src/conformance.ts

@@ -36,7 +36,8 @@ import {
 } from "./schema-defaults.ts";
 import type { TagFieldSchema } from "./tag-schemas.ts";
 import { getTagDescendants, loadTagHierarchy } from "./tag-hierarchy.ts";
-import { queryNotes, getNoteTagsForNotes } from "./notes.ts";
+import { getNotes, getNoteTagsForNotes } from "./notes.ts";
+import { chunkForInClause } from "./sql-in.ts";
 
 export interface ConformanceViolation {
   /** Note id of a non-conforming note. */
@@ -131,6 +132,9 @@ function overlayProposedSchema(
  *
  * Pure read; no mutation. Returns 0 violating notes when `proposedFields` is
  * empty (nothing to enforce).
+ *
+ * The walk is UNBOUNDED — every note carrying the tag or a descendant, not a
+ * `queryNotes` page (vault#592). `total_notes` is a real total.
  */
 export function countConformanceViolations(
   db: Database,
@@ -155,10 +159,35 @@ export function countConformanceViolations(
   const tagSet = Array.from(getTagDescendants(hierarchy, tag));
   if (tagSet.length === 0) return empty;
 
-  // All notes carrying the tag (or a descendant). `tagMatch: "any"` over the
-  // expanded set — a note on ANY of these tags is in scope. We hydrate tags
-  // ourselves (batched) so the resolver sees the full ancestor set per note.
-  const notes = queryNotes(db, { tags: tagSet, tagMatch: "any" });
+  // All notes carrying the tag (or a descendant) — a note on ANY of these
+  // tags is in scope.
+  //
+  // UNBOUNDED id sweep (vault#592). This used to call
+  // `queryNotes(db, { tags: tagSet, tagMatch: "any" })` with no `limit`,
+  // which silently inherits that function's default `LIMIT 100`
+  // (`notes.ts`) — so on a tag with more than 100 notes both `total_notes`
+  // and the violation scan reported the first page only. The operator was
+  // told "3 of 100 notes violate this" for a 1,200-note tag, and violations
+  // living past note 100 were never even looked at. A conformance count that
+  // undercounts is worse than no count: it is the number the operator
+  // decides on.
+  //
+  // Same shape as `SqliteStore.backfillReferenceFieldLinks` (store.ts),
+  // which fixed the identical inherited-cap bug on the reference backfill: a
+  // direct `note_tags` scan chunked under the IN-param cap, deduped across
+  // tags (a note carrying both `dev` and `dev/log` is ONE note), then
+  // hydrated in a batch. Still a pure read.
+  const idSet = new Set<string>();
+  for (const chunk of chunkForInClause(tagSet)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db
+      .prepare(`SELECT DISTINCT note_id FROM note_tags WHERE tag_name IN (${placeholders})`)
+      .all(...chunk) as { note_id: string }[];
+    for (const r of rows) idSet.add(r.note_id);
+  }
+  if (idSet.size === 0) return empty;
+
+  const notes = getNotes(db, Array.from(idSet));
   if (notes.length === 0) return empty;
 
   if (checkedFields.length === 0) {

package/core/src/connection-pragmas.test.ts

@@ -13,7 +13,7 @@ import { Database } from "bun:sqlite";
 import { mkdtempSync, rmSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import { applyConnectionPragmas, initSchema } from "./schema.ts";
+import { applyConnectionPragmas, BUSY_TIMEOUT_MS, initSchema } from "./schema.ts";
 
 let dir: string;
 
@@ -133,6 +133,32 @@ describe("applyConnectionPragmas — :memory: DB", () => {
     expect(pragma(db, "foreign_keys")).toBe(1);
     db.close();
   });
+
+  it("sets busy_timeout on the non-WAL branch too (vault#527)", () => {
+    // SQLITE_BUSY is not WAL-specific — a rollback-journal DB serializes even
+    // harder. The timeout must not be gated on the WAL success path.
+    const db = new Database(":memory:");
+    applyConnectionPragmas(db);
+    expect(pragma(db, "busy_timeout")).toBe(BUSY_TIMEOUT_MS);
+    db.close();
+  });
+});
+
+describe("applyConnectionPragmas — busy_timeout (vault#527)", () => {
+  it("sets a non-zero busy_timeout so SQLITE_BUSY retries instead of failing instantly", () => {
+    const db = new Database(join(dir, "busy.db"));
+    applyConnectionPragmas(db);
+    expect(pragma(db, "busy_timeout")).toBe(BUSY_TIMEOUT_MS);
+    expect(BUSY_TIMEOUT_MS).toBeGreaterThan(0);
+    db.close();
+  });
+
+  it("initSchema's open path carries the busy_timeout", () => {
+    const db = new Database(join(dir, "busy-init.db"));
+    initSchema(db);
+    expect(pragma(db, "busy_timeout")).toBe(BUSY_TIMEOUT_MS);
+    db.close();
+  });
 });
 
 describe("applyConnectionPragmas — WAL-unsupported on-disk filesystem (simulated)", () => {

package/core/src/core.test.ts

@@ -2334,6 +2334,25 @@ describe("searchNotes", async () => {
     expect(results[0].tags).toContain("daily");
   });
 
+  it("filters search by excludeTags (vault#647)", async () => {
+    await store.createNote("Flagstaff keep", { tags: ["daily"] });
+    await store.createNote("Flagstaff drop", { tags: ["daily", "archived"] });
+
+    const results = await store.searchNotes("Flagstaff", { tags: ["daily"], excludeTags: ["archived"] });
+    expect(results).toHaveLength(1);
+    expect(results[0].content).toContain("keep");
+    expect(results[0].tags).not.toContain("archived");
+  });
+
+  it("filters search by dateFrom (vault#647)", async () => {
+    await store.createNote("Flagstaff recent", { tags: ["daily"], created_at: "2026-07-01T00:00:00.000Z" });
+    await store.createNote("Flagstaff old", { tags: ["daily"], created_at: "2023-06-01T00:00:00.000Z" });
+
+    const results = await store.searchNotes("Flagstaff", { tags: ["daily"], dateFrom: "2026-06-01" });
+    expect(results).toHaveLength(1);
+    expect(results[0].content).toContain("recent");
+  });
+
   it("returns empty for no match", async () => {
     await store.createNote("Hello world");
     const results = await store.searchNotes("nonexistent");
@@ -4339,7 +4358,38 @@ describe("MCP tools", async () => {
     }) as any;
     const page = Array.isArray(pageResult) ? pageResult : pageResult.notes;
     expect(page).toHaveLength(2);
-    expect(pageResult.warnings?.some((w: any) => w.code === "truncated" && w.limit === 2)).toBe(true);
+    // vault#601: explicit offset is deliberate paging — no truncated warning.
+    expect(pageResult.warnings?.some((w: any) => w.code === "truncated") ?? false).toBe(false);
+  });
+
+  it("query-notes exclude_path_prefix drops matching paths and keeps pathless notes (vault#628)", async () => {
+    await store.createNote("user", { path: "Projects/a" });
+    await store.createNote("sys", { path: ".parachute/notes/settings" });
+    await store.createNote("bare"); // no path
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const r = await query.execute({ exclude_path_prefix: ".parachute/", include_content: true }) as any[];
+    const contents = r.map((n: any) => n.content).sort();
+    expect(contents).toEqual(["bare", "user"]);
+  });
+
+  it("query-notes search composes with exclude_path_prefix (vault#628)", async () => {
+    // The MCP search branch enumerates QueryOpts fields rather than
+    // spreading them. After #656, REST search picks up exclude_path_prefix
+    // via ...parsed.queryOpts; omitting the field here is the silent-drop
+    // class this lane kills.
+    await store.createNote("unique-628-search-term keep", { path: "Projects/a" });
+    await store.createNote("unique-628-search-term drop", { path: ".parachute/notes/settings" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const r = await query.execute({
+      search: "unique-628-search-term",
+      exclude_path_prefix: ".parachute/",
+      include_content: true,
+    }) as any[];
+    const contents = r.map((n: any) => n.content);
+    expect(contents).toContain("unique-628-search-term keep");
+    expect(contents).not.toContain("unique-628-search-term drop");
   });
 
   it("query-notes full-text search works", async () => {
@@ -4411,13 +4461,17 @@ describe("MCP tools", async () => {
     expect(b.metadata).toEqual({ summary: "b" }); // status absent → omitted
   });
 
-  it("query-notes include_metadata: string[] with no matching fields returns undefined metadata", async () => {
+  it("query-notes include_metadata: string[] with no matching fields keeps metadata: {} (vault#600)", async () => {
+    // V1.1 invariant: rowToNote always emits `metadata: {}`. The projection
+    // branch used to set `metadata: undefined` when no requested keys
+    // matched, so the key vanished from the wire again.
     await store.createNote("A", { tags: ["no-match-meta"], metadata: { summary: "a" } });
     const tools = generateMcpTools(store);
     const query = tools.find((t) => t.name === "query-notes")!;
     const result = await query.execute({ tag: "no-match-meta", include_metadata: ["nonexistent"] }) as any[];
     expect(result).toHaveLength(1);
-    expect(result[0].metadata).toBeUndefined();
+    expect(result[0]).toHaveProperty("metadata", {});
+    expect(JSON.parse(JSON.stringify(result[0]))).toHaveProperty("metadata", {});
   });
 
   it("query-notes near param scopes results to graph neighborhood", async () => {
@@ -5386,6 +5440,37 @@ describe("MCP tools", async () => {
     expect(r[0].content).toBe("a");
   });
 
+  it("query-notes search composes with exclude_tags (vault#647)", async () => {
+    // Pre-fix the FTS branch forwarded only `{tags, limit, expand, mode, sort}`
+    // so exclude_tags was silently dropped: the response looked like a real
+    // result set that simply answered a different question.
+    await store.createNote("widget keep", { tags: ["email"] });
+    await store.createNote("widget drop", { tags: ["email", "urgent"] });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({
+      search: "widget",
+      tag: "email",
+      exclude_tags: "urgent",
+      include_content: true,
+    }) as any[];
+    expect(r.map((n: any) => n.content)).toEqual(["widget keep"]);
+  });
+
+  it("query-notes search composes with date_from (vault#647)", async () => {
+    await store.createNote("widget recent", { tags: ["email"], created_at: "2026-07-01T00:00:00.000Z" });
+    await store.createNote("widget old", { tags: ["email"], created_at: "2023-06-01T00:00:00.000Z" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const r = await queryNotes.execute({
+      search: "widget",
+      tag: "email",
+      date_from: "2026-06-01",
+      include_content: true,
+    }) as any[];
+    expect(r.map((n: any) => n.content)).toEqual(["widget recent"]);
+  });
+
   it("query-notes routes through store.queryNotes so tag-hierarchy expansion fires", async () => {
     // `voice` and `text` declare "manual" as their parent via the v14
     // tags.parent_names column. A query for `tag: "manual"` should match

package/core/src/cursor.ts

@@ -176,6 +176,7 @@ export interface QueryHashInputs {
   hasBrokenLinks?: boolean;
   path?: string;
   pathPrefix?: string;
+  excludePathPrefix?: string[];
   extension?: string | string[];
   ids?: string[];
   metadata?: Record<string, unknown>;
@@ -249,6 +250,7 @@ function canonicalize(value: unknown): unknown {
   const ORDER_IRRELEVANT_STRING_ARRAYS = new Set([
     "tags",
     "excludeTags",
+    "excludePathPrefix",
     "ids",
     "extension",
   ]);

package/core/src/do-param-cap.test.ts

@@ -133,6 +133,173 @@ describe("id-list query paths stay under the DO 100-bound-param cap", () => {
     expect(notes.length).toBe(0);
   });
 
+  describe("metadata in / not_in operators (vault#536)", () => {
+    /**
+     * `in` / `not_in` used to build `meta_<field> IN (?, ?, …)` — one bound
+     * param per user-supplied value, with no chunking and no json_each. It's
+     * an embedded filter inside a paginated statement, so chunking isn't
+     * available (it would break the shared LIMIT/OFFSET window); the fix is
+     * the single-json_each-param shape #535 introduced for `near`.
+     */
+    beforeEach(async () => {
+      await store.upsertTagRecord("doc", {
+        fields: { rank: { type: "integer", indexed: true } },
+      });
+      for (let i = 0; i < 250; i++) {
+        await store.updateNote(`n${pad(i)}`, { tags: ["doc"], metadata: { rank: i } });
+      }
+    });
+
+    it("a >100-value `in` binds one json_each param, not one per value", async () => {
+      const wanted = Array.from({ length: 150 }, (_, i) => i);
+      const spy = installBindSpy(db);
+      let notes;
+      try {
+        notes = await store.queryNotes({
+          metadata: { rank: { in: wanted } },
+          limit: 1000,
+          sort: "asc",
+        });
+      } finally {
+        spy.restore();
+      }
+      expect(notes.length).toBe(150);
+      expect(spy.usedJsonEach()).toBe(true);
+      expect(spy.maxPlaceholderInBinds()).toBeLessThanOrEqual(IN_PARAM_CHUNK);
+      expect(spy.maxAnyBinds()).toBeLessThanOrEqual(DO_PARAM_CAP);
+    });
+
+    it("a >100-value `not_in` binds one json_each param too", async () => {
+      const excluded = Array.from({ length: 150 }, (_, i) => i);
+      const spy = installBindSpy(db);
+      let notes;
+      try {
+        notes = await store.queryNotes({
+          metadata: { rank: { not_in: excluded } },
+          limit: 1000,
+          sort: "asc",
+        });
+      } finally {
+        spy.restore();
+      }
+      // 250 notes, 150 excluded → the 100 with rank >= 150.
+      expect(notes.length).toBe(100);
+      expect(spy.usedJsonEach()).toBe(true);
+      expect(spy.maxAnyBinds()).toBeLessThanOrEqual(DO_PARAM_CAP);
+    });
+
+    it("stays under the cap alongside LIMIT/OFFSET pagination params", async () => {
+      const wanted = Array.from({ length: 200 }, (_, i) => i);
+      const spy = installBindSpy(db);
+      let notes;
+      try {
+        notes = await store.queryNotes({
+          metadata: { rank: { in: wanted } },
+          limit: 25,
+          offset: 10,
+          sort: "asc",
+        });
+      } finally {
+        spy.restore();
+      }
+      expect(notes.length).toBe(25);
+      expect(spy.maxAnyBinds()).toBeLessThanOrEqual(DO_PARAM_CAP);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Cross-type affinity: `in`/`not_in` route the value-set through a
+  // `json_each` subquery, which — unlike a placeholder `IN (?, …)` list — does
+  // NOT apply the left column's type affinity to each candidate. The fix CASTs
+  // the set to the column's declared storage type so numeric-vs-TEXT (and the
+  // reverse) matches stay identical to the pre-#536 placeholder-list path
+  // (vault#676). These probes send the exact shapes the reviewer flagged and
+  // pin the row-sets that a naive json_each would silently narrow.
+  // -------------------------------------------------------------------------
+  describe("in / not_in preserve cross-type affinity (vault#676)", () => {
+    it("string-typed indexed column matches BARE NUMERIC in/not_in values", async () => {
+      // `version` is a TEXT-affinity column; the stored values are strings.
+      await store.upsertTagRecord("release", {
+        fields: { version: { type: "string", indexed: true } },
+      });
+      await store.updateNote("n00000", { tags: ["release"], metadata: { version: "5" } });
+      await store.updateNote("n00001", { tags: ["release"], metadata: { version: "6" } });
+      await store.updateNote("n00002", { tags: ["release"], metadata: { version: "7" } });
+
+      // The reviewer's probe: bare JSON numbers against a string column.
+      const inHit = await store.queryNotes({
+        metadata: { version: { in: [5, 6] } },
+        limit: 100,
+        sort: "asc",
+      });
+      expect(inHit.map((n) => n.id)).toEqual(["n00000", "n00001"]);
+
+      // Same set as JSON strings must return the SAME rows (the control the
+      // placeholder-list path always satisfied).
+      const inHitStr = await store.queryNotes({
+        metadata: { version: { in: ["5", "6"] } },
+        limit: 100,
+        sort: "asc",
+      });
+      expect(inHitStr.map((n) => n.id)).toEqual(inHit.map((n) => n.id));
+
+      // not_in with bare numbers must exclude the string rows `"5"`/`"6"` and
+      // keep `"7"` — the affinity-reconciled mirror of the `in` probe. (Rows
+      // with no `version` at all have a NULL column and legitimately match
+      // not_in, so assert membership rather than an exact set.)
+      const notInHit = await store.queryNotes({
+        metadata: { version: { not_in: [5, 6] } },
+        limit: 1000,
+        sort: "asc",
+      });
+      const notInIds = new Set(notInHit.map((n) => n.id));
+      expect(notInIds.has("n00000")).toBe(false); // version "5" — excluded
+      expect(notInIds.has("n00001")).toBe(false); // version "6" — excluded
+      expect(notInIds.has("n00002")).toBe(true); // version "7" — kept
+
+      // The bare-number not_in must exclude exactly the same rows a
+      // string-valued not_in does (the placeholder-list contract).
+      const notInHitStr = await store.queryNotes({
+        metadata: { version: { not_in: ["5", "6"] } },
+        limit: 1000,
+        sort: "asc",
+      });
+      expect(notInHitStr.map((n) => n.id)).toEqual(notInHit.map((n) => n.id));
+    });
+
+    it("integer-typed indexed column matches STRING in/not_in values (reverse direction)", async () => {
+      // `rank` is an INTEGER-affinity column populated 0..249; string-form
+      // membership (e.g. `"5"`) must still match under both shapes.
+      await store.upsertTagRecord("doc", {
+        fields: { rank: { type: "integer", indexed: true } },
+      });
+      for (let i = 0; i < 250; i++) {
+        await store.updateNote(`n${pad(i)}`, { tags: ["doc"], metadata: { rank: i } });
+      }
+      const inHit = await store.queryNotes({
+        metadata: { rank: { in: ["5", "6"] } },
+        limit: 100,
+        sort: "asc",
+      });
+      const inHitNum = await store.queryNotes({
+        metadata: { rank: { in: [5, 6] } },
+        limit: 100,
+        sort: "asc",
+      });
+      expect(inHit.map((n) => n.id)).toEqual(["n00005", "n00006"]);
+      expect(inHit.map((n) => n.id)).toEqual(inHitNum.map((n) => n.id));
+
+      const notInHit = await store.queryNotes({
+        metadata: { rank: { not_in: ["5"] } },
+        limit: 1000,
+        sort: "asc",
+      });
+      // 250 rows, only rank 5 excluded.
+      expect(notInHit.length).toBe(249);
+      expect(notInHit.some((n) => n.id === "n00005")).toBe(false);
+    });
+  });
+
   describe("export a >100-note vault", () => {
     let outDir: string;
     beforeEach(() => { outDir = mkdtempSync(join(tmpdir(), "do-cap-export-")); });