@openparachute/vault 0.6.5 → 0.7.0-rc.1

package/core/src/contract-concurrency.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Contract suite — concurrency + write-path strengths (Wave 1 of the
+ * Reliability & Usability Program, umbrella #556). Encodes the 2026-07-09
+ * nine-persona deep test's verdict that "the storage/concurrency core is
+ * trustworthy — zero server errors, zero corruption, zero lost writes across
+ * ~100 hostile operations and a live two-writer session" (#556, #555 work
+ * item "document the strong contracts the deep test verified but that are
+ * currently unwritten selling points"). Every test here is a PASSING lock-in
+ * — there is no known-broken behavior in this file, only undocumented
+ * correctness worth pinning as contract before later waves touch adjacent
+ * code paths.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { ConflictError, PathConflictError } from "./notes.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("contract: concurrency — passing (lock in verified strengths)", () => {
+  it("sequential interleaved appends from two writers preserve call order and lose nothing (25-line pattern)", async () => {
+    const note = await store.createNote("", { id: "log" });
+
+    // Simulate two independent writers interleaving 25 appends each.
+    // Sequential (not truly parallel) — the contract under test is that
+    // SQL-level `content = content || ?` concatenation never drops or
+    // reorders a write relative to the order calls actually landed in,
+    // which is exactly what a real two-writer race also guarantees
+    // (see core.test.ts's "update-note append is atomic under concurrent
+    // calls" for the Promise.all interleaving twin of this test).
+    const expectedLines: string[] = [];
+    for (let i = 1; i <= 25; i++) {
+      const lineA = `writer-A line ${i}\n`;
+      await store.updateNote(note.id, { append: lineA });
+      expectedLines.push(lineA);
+
+      const lineB = `writer-B line ${i}\n`;
+      await store.updateNote(note.id, { append: lineB });
+      expectedLines.push(lineB);
+    }
+
+    const final = await store.getNote(note.id);
+    expect(final!.content).toBe(expectedLines.join(""));
+    // 50 appends, none lost: every planted line is present exactly once.
+    expect(final!.content.match(/writer-A line/g)?.length).toBe(25);
+    expect(final!.content.match(/writer-B line/g)?.length).toBe(25);
+  });
+
+  it("two updates racing on the same if_updated_at token: exactly one succeeds, the other gets a ConflictError", async () => {
+    const note = await store.createNote("v0", { id: "n1" });
+    const token = note.updatedAt!;
+
+    const first = await store.updateNote(note.id, { content: "v1 (writer A)", if_updated_at: token });
+    expect(first.content).toBe("v1 (writer A)");
+
+    let err: any;
+    try {
+      // Writer B read the note before writer A's update landed and is still
+      // holding the stale token — this must conflict, not silently overwrite.
+      await store.updateNote(note.id, { content: "v1 (writer B)", if_updated_at: token });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(ConflictError);
+    expect(err.note_id).toBe(note.id);
+    expect(err.expected_updated_at).toBe(token);
+    expect(err.current_updated_at).toBe(first.updatedAt);
+
+    // Writer A's write is the one that stuck.
+    const final = await store.getNote(note.id);
+    expect(final!.content).toBe("v1 (writer A)");
+  });
+
+  it("creating a note at an already-taken path throws PathConflictError — the prior note is untouched", async () => {
+    const original = await store.createNote("original owner", { path: "shared/path" });
+
+    let err: any;
+    try {
+      await store.createNote("racing creator", { path: "shared/path" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(PathConflictError);
+    expect(err.path).toBe("shared/path");
+
+    const survivor = await store.getNote(original.id);
+    expect(survivor!.content).toBe("original owner");
+  });
+
+  it("a metadata update merges rather than replaces — untouched top-level keys survive a partial patch", async () => {
+    const note = await store.createNote("has metadata", {
+      metadata: { keep: "me", also_keep: 42, drop_me: "bye" },
+    });
+
+    // mergeMetadata is the pure merge primitive the MCP/REST write paths
+    // call before handing the merged object to store.updateNote (the
+    // Store/engine-level updateNote itself replaces `metadata` wholesale —
+    // merge is a caller responsibility, exercised here directly).
+    const { mergeMetadata } = await import("./notes.js");
+    const merged = mergeMetadata(note.metadata as Record<string, unknown>, {
+      also_keep: 43,
+      drop_me: null,
+      new_key: "hello",
+    });
+    await store.updateNote(note.id, { metadata: merged, if_updated_at: note.updatedAt });
+
+    const after = await store.getNote(note.id);
+    expect(after!.metadata).toEqual({ keep: "me", also_keep: 43, new_key: "hello" });
+  });
+});

package/core/src/contract-taxonomy.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Contract suite — taxonomy integrity (Wave 1 of the Reliability & Usability
+ * Program, umbrella #556). Encodes the 2026-07-09 nine-persona deep test's
+ * WS3 findings (#552) as executable tests: PASSING tests lock in behavior
+ * that is correct today (the tag-expand axis, `delete-tag`'s "untag, don't
+ * delete notes" contract, and `renameTag`'s full cascade — note_tags,
+ * `parent_names` references in OTHER tags, and note body content); `test.todo`
+ * entries describe the target behavior for confirmed-broken cases, to be
+ * flipped to real assertions in a later wave. See #552 for the full write-up.
+ */
+
+import { describe, it, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+const idsOf = (notes: { id: string }[]) => new Set(notes.map((n) => n.id));
+
+describe("contract: taxonomy — passing (lock in current behavior)", () => {
+  it("expand axis 4-way discrimination: subtypes/namespace/both/exact each answer a distinct question", async () => {
+    // Two-axis corpus (mirrors tag-expand-axis.test.ts): `person` is a
+    // declared subtype of `entity` (parent_names) but not name-prefixed;
+    // `entity/archived` is name-prefixed under `entity` but NOT a declared
+    // subtype; `entity/person` is both.
+    await store.upsertTagRecord("entity", { description: "an entity" });
+    await store.upsertTagRecord("person", { parent_names: ["entity"] });
+    await store.upsertTagRecord("entity/archived", {});
+    await store.upsertTagRecord("entity/person", { parent_names: ["entity"] });
+
+    const nEntity = await store.createNote("literal entity", { tags: ["entity"] });
+    const nPerson = await store.createNote("a person (subtype)", { tags: ["person"] });
+    const nArchived = await store.createNote("filed under entity/", { tags: ["entity/archived"] });
+    const nBoth = await store.createNote("subtype AND filed", { tags: ["entity/person"] });
+
+    const subtypes = await store.queryNotes({ tags: ["entity"], expand: "subtypes" });
+    expect(idsOf(subtypes)).toEqual(new Set([nEntity.id, nPerson.id, nBoth.id]));
+
+    const namespace = await store.queryNotes({ tags: ["entity"], expand: "namespace" });
+    expect(idsOf(namespace)).toEqual(new Set([nEntity.id, nArchived.id, nBoth.id]));
+
+    const both = await store.queryNotes({ tags: ["entity"], expand: "both" });
+    expect(idsOf(both)).toEqual(new Set([nEntity.id, nPerson.id, nArchived.id, nBoth.id]));
+
+    const exact = await store.queryNotes({ tags: ["entity"], expand: "exact" });
+    expect(idsOf(exact)).toEqual(new Set([nEntity.id]));
+  });
+
+  it("delete-tag untags notes without deleting the notes themselves", async () => {
+    const note = await store.createNote("keep me", { tags: ["temp", "keeper"] });
+    const result = await store.deleteTag("temp");
+    expect(result).toEqual({ deleted: true, notes_untagged: 1 });
+
+    const survivor = await store.getNote(note.id);
+    expect(survivor).not.toBeNull();
+    expect(survivor!.content).toBe("keep me");
+    expect(survivor!.tags).toEqual(["keeper"]);
+    expect(survivor!.tags).not.toContain("temp");
+  });
+
+  it("renameTag cascades note_tags, other tags' parent_names, AND note body content in one atomic call", async () => {
+    // note_tags surface: a note directly tagged `proj`.
+    const tagged = await store.createNote("owns the proj tag", { tags: ["proj"] });
+    // parent_names surface: another tag declares `proj` as a parent.
+    await store.upsertTagRecord("proj", { description: "root project tag" });
+    await store.upsertTagRecord("special", { parent_names: ["proj"] });
+    // note-body surface: a note mentions `#proj` inline (not as a real tag).
+    const mentioning = await store.createNote("kickoff notes, see #proj for context", {});
+
+    const result = await store.renameTag("proj", "initiative");
+    expect("error" in result).toBe(false);
+    if ("error" in result) throw new Error("unreachable");
+    expect(result.renamed).toBeGreaterThanOrEqual(1);
+    expect(result.parent_refs_updated).toBeGreaterThanOrEqual(1);
+    expect(result.notes_rewritten).toBeGreaterThanOrEqual(1);
+
+    // 1. note_tags cascade.
+    const taggedAfter = await store.getNote(tagged.id);
+    expect(taggedAfter!.tags).toContain("initiative");
+    expect(taggedAfter!.tags).not.toContain("proj");
+
+    // 2. OTHER tags' parent_names cascade.
+    const specialAfter = await store.getTagRecord("special");
+    expect(specialAfter?.parent_names).toEqual(["initiative"]);
+
+    // 3. Note body content cascade.
+    const mentioningAfter = await store.getNote(mentioning.id);
+    expect(mentioningAfter!.content).toContain("#initiative");
+    expect(mentioningAfter!.content).not.toContain("#proj");
+
+    // The old tag name is fully retired — no longer a live tag row.
+    const oldRecord = await store.getTagRecord("proj");
+    expect(oldRecord).toBeNull();
+  });
+});
+
+describe("contract: taxonomy — todo (#552)", () => {
+  test.todo(
+    "#552: deleting a tag still referenced in another tag's parent_names errors unless cascade/detach is passed (today: store.deleteTag succeeds unconditionally and leaves the referencing tag's parent_names pointing at a now-nonexistent tag name — verified with a fresh parent/child fixture)",
+  );
+  test.todo(
+    "#552: a parent_names cycle (A declares parent B, then B declares parent A) is rejected at write time (today: store.upsertTagRecord accepts both writes with no cycle check — traversal elsewhere is cycle-safe, but the write itself is not honest about creating one)",
+  );
+  test.todo(
+    "#552: rename-tag is exposed as an MCP tool, not just a REST endpoint (today: POST /api/tags/:name/rename exists and store.renameTag is wired, but generateMcpTools has no rename-tag tool — an MCP-only agent cannot rename a tag)",
+  );
+  test.todo(
+    "#552: merge-tags is exposed as an MCP tool, not just a REST endpoint (today: POST /api/tags/merge exists and store.mergeTags is wired, but generateMcpTools has no merge-tags tool)",
+  );
+  test.todo(
+    "#552: a `vault doctor` integrity scan reports dangling parent_names references (today: no doctor/scan surface inspects parent_names for referential integrity — the delete-tag gap above goes undetected)",
+  );
+});

package/core/src/contract-typed-index.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Contract suite — typed indexes (Wave 1 of the Reliability & Usability
+ * Program, umbrella #556). Encodes the 2026-07-09 nine-persona deep test's
+ * WS4 findings (#553) as executable tests: PASSING tests lock in behavior
+ * that is correct today (well-typed integer-indexed range queries, the
+ * merge-patch metadata contract, and the state_transition compare-and-set
+ * conflict); `test.todo` entries describe the target behavior for
+ * confirmed-broken cases, to be flipped to real assertions in a later wave.
+ * See #553 for the full write-up.
+ *
+ * The TEXT-poisoning todo below was reproduced live before writing: declaring
+ * an indexed integer field and writing `metadata.n = "four"` succeeds with
+ * only an advisory `type_mismatch` warning, and the resulting row's generated
+ * column carries the raw TEXT value under SQLite's INTEGER-affinity
+ * coercion — which then sorts ABOVE every real integer (SQLite type
+ * ordering: NULL < INTEGER/REAL < TEXT < BLOB), so `{n: {gt: 100}}`
+ * incorrectly matches the poisoned row alongside genuine matches.
+ */
+
+import { describe, it, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { TransitionConflictError } from "./notes.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("contract: typed indexes — passing (lock in current behavior)", () => {
+  it("an integer-indexed field with well-typed integer values answers gte/lt correctly", async () => {
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    const low = await store.createNote("n=5", { tags: ["metric"], metadata: { n: 5 } });
+    const mid = await store.createNote("n=50", { tags: ["metric"], metadata: { n: 50 } });
+    const high = await store.createNote("n=200", { tags: ["metric"], metadata: { n: 200 } });
+
+    const gte50 = await store.queryNotes({ tags: ["metric"], metadata: { n: { gte: 50 } } });
+    expect(new Set(gte50.map((n) => n.id))).toEqual(new Set([mid.id, high.id]));
+
+    const lt50 = await store.queryNotes({ tags: ["metric"], metadata: { n: { lt: 50 } } });
+    expect(new Set(lt50.map((n) => n.id))).toEqual(new Set([low.id]));
+  });
+
+  it("merge-patch metadata preserves untouched fields, updates named fields, and RFC-7386-deletes null fields", async () => {
+    const note = await store.createNote("has metadata", {
+      metadata: { a: 1, b: 2, c: 3 },
+    });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result: any = await updateNote.execute({
+      id: note.id,
+      metadata: { b: 20, c: null },
+      force: true,
+    });
+
+    expect(result.metadata).toEqual({ a: 1, b: 20 });
+  });
+
+  it("a state_transition compare-and-set conflicts when the note has already transitioned away from `from`", async () => {
+    const note = await store.createNote("workflow item", { metadata: { status: "draft" } });
+
+    const first = await store.updateNote(note.id, {
+      state_transition: { field: "status", from: "draft", to: "published" },
+    });
+    expect((first.metadata as any).status).toBe("published");
+
+    let err: any;
+    try {
+      // Same `from: "draft"` precondition — but the note is now "published",
+      // so this must conflict rather than silently no-op or overwrite.
+      await store.updateNote(note.id, {
+        state_transition: { field: "status", from: "draft", to: "archived" },
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(TransitionConflictError);
+    expect(err.field).toBe("status");
+    expect(err.expected_from).toBe("draft");
+    expect(err.current).toBe("published");
+
+    // The note's status is untouched by the rejected transition.
+    const after = await store.getNote(note.id);
+    expect((after!.metadata as any).status).toBe("published");
+  });
+});
+
+describe("contract: typed indexes — todo (#553)", () => {
+  test.todo(
+    `#553: a write of a TEXT value to an indexed integer field is REJECTED (today: it is accepted with only an advisory type_mismatch warning, and the poisoned row then silently matches {gt: 100}-style range queries via SQLite's TEXT-sorts-above-INTEGER type-affinity ordering — reproduced live: metadata.n = "four" on an indexed integer field succeeds, and query {n: {gt: 100}} incorrectly returns it)`,
+  );
+  test.todo(
+    `#553: an unset enum field stays ABSENT — no first-value backfill — so exists:false correctly matches a note that never set the field (today: applySchemaDefaults in core/src/mcp.ts backfills the schema's first enum value onto every note that gains the tag, so "never set" is indistinguishable from "explicitly set to the default" and exists:false never matches)`,
+  );
+  test.todo(
+    `#553: update-tag reports ALL invalid fields in one call AND states explicitly that no changes were applied (today: the cross-tag type/indexed-flag validation loop in core/src/mcp.ts throws on the FIRST offending field and never reports the rest, and the thrown Error's message doesn't say whether the tag's other, valid fields were partially applied — reproduced live: declaring two invalid fields in one update-tag call surfaces only the first field's error)`,
+  );
+  test.todo(
+    `#553: the indexed-field type list is honest about what's actually indexable (core/src/mcp.ts's update-tag field-type description advertises "string, boolean, integer, number, array, object" but indexed-fields.ts's TYPE_MAP only supports string/integer/boolean — "number" and the container types are accepted as declared but silently un-indexable)`,
+  );
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.5",
+  "version": "0.7.0-rc.1",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/contract-errors.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Contract suite — error taxonomy at the REST boundary (Wave 1 of the
+ * Reliability & Usability Program, umbrella #556). Encodes the 2026-07-09
+ * nine-persona deep test's WS5 findings (#554) as executable tests: PASSING
+ * tests lock in the structured-error precedents that already exist
+ * (`path_conflict`, `conflict` with current/expected timestamps,
+ * `precondition_required`, `schema_validation`); `test.todo` entries
+ * describe the target behavior for confirmed-broken cases, to be flipped to
+ * real assertions in a later wave. See #554 for the full write-up.
+ */
+
+import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+const BASE = "http://localhost/api";
+
+function post(body: unknown): Promise<Response> {
+  return handleNotes(
+    new Request(`${BASE}/notes`, { method: "POST", body: JSON.stringify(body) }),
+    store,
+    "",
+  );
+}
+
+function patch(id: string, body: unknown): Promise<Response> {
+  return handleNotes(
+    new Request(`${BASE}/notes/${id}`, { method: "PATCH", body: JSON.stringify(body) }),
+    store,
+    `/${id}`,
+  );
+}
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+describe("contract: error taxonomy — passing (lock in existing structured precedents)", () => {
+  it("creating a note at a path that's already taken returns 409 path_conflict", async () => {
+    await store.createNote("first", { path: "taken" });
+    const res = await post({ content: "second", path: "taken" });
+    expect(res.status).toBe(409);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("path_conflict");
+    expect(body.path).toBe("taken");
+  });
+
+  it("updating with a stale if_updated_at returns 409 conflict carrying current_updated_at + your_updated_at", async () => {
+    const note = await store.createNote("original", { id: "n1" });
+    const res = await patch(note.id, { content: "changed", if_updated_at: "2020-01-01T00:00:00.000Z" });
+    expect(res.status).toBe(409);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("conflict");
+    expect(body.current_updated_at).toBe(note.updatedAt);
+    expect(body.your_updated_at).toBe("2020-01-01T00:00:00.000Z");
+  });
+
+  it("a strict schema violation on write returns 422 schema_validation naming every violation", async () => {
+    await store.upsertTagRecord("strict-status", {
+      fields: { status: { type: "string", enum: ["active", "archived"], strict: true } },
+    });
+    const res = await post({ content: "x", tags: ["strict-status"], metadata: { status: "bogus" } });
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("schema_validation");
+    expect(Array.isArray(body.violations)).toBe(true);
+    expect(body.violations.length).toBeGreaterThan(0);
+    expect(body.violations[0].field).toBe("status");
+    expect(body.violations[0].reason).toBe("enum_mismatch");
+  });
+
+  it("updating a note without if_updated_at or force returns 428 precondition_required", async () => {
+    const note = await store.createNote("original", { id: "n1" });
+    const res = await patch(note.id, { content: "changed, no precondition" });
+    expect(res.status).toBe(428);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("precondition_required");
+    expect(body.note_id).toBe(note.id);
+  });
+});
+
+describe("contract: error taxonomy — todo (#554)", () => {
+  test.todo(
+    "#554: every error response carries a structured {error_type, hint} pair — today error_type exists on many paths but no response carries a `hint` field, and some error paths (e.g. bad_request/ambiguous/unprocessable_content in the PATCH content_edit branch) are still bare {error, message} strings with no error_type at all",
+  );
+  test.todo(
+    "#554: batch update-note honors a top-level `force` (or `if_updated_at`) applied per-item — today the batch entry point does `items = batch ?? [params]`, so a top-level force:true on the request never reaches the per-item precondition check (core/src/mcp.ts ~line 1114 reads item.force only) and each item without its OWN force/if_updated_at still throws precondition_required",
+  );
+});

package/src/contract-honest-queries.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Contract suite — honest queries at the REST boundary (Wave 1 of the
+ * Reliability & Usability Program, umbrella #556). Encodes the 2026-07-09
+ * nine-persona deep test's WS1 findings (#550) as executable tests: PASSING
+ * tests lock in behavior that is correct today; `test.todo` entries describe
+ * the target behavior for confirmed-broken cases, to be flipped to real
+ * assertions in a later wave. See #550 for the full write-up — this file
+ * covers the `src/routes.ts` REST surface specifically (the cursor-bootstrap
+ * gap lives at routes.ts:1102/1106, the tags/{name} 404 gap at the GET /tags
+ * handler in `handleTags`).
+ */
+
+import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes, handleTags } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+const BASE = "http://localhost/api";
+
+function getNotes(qs: string): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes?${qs}`, { method: "GET" }), store, "");
+}
+
+function getTags(qs: string): Promise<Response> {
+  return handleTags(new Request(`${BASE}/tags?${qs}`, { method: "GET" }), store, "");
+}
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+describe("contract: honest queries — passing (lock in current behavior)", () => {
+  it("querying a nonexistent tag returns 200 with an empty array, not an error", async () => {
+    const res = await getNotes("tag=zzznonexistenttag");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    // Shape may gain a `warnings` field later (#550) — assert only status +
+    // array shape now so that addition doesn't break this contract test.
+    expect(Array.isArray(body)).toBe(true);
+    expect(body).toEqual([]);
+  });
+
+  it("a metadata operator query on a non-indexed field errors loudly with FIELD_NOT_INDEXED (existing behavior)", async () => {
+    const res = await getNotes("meta[not_a_real_field][gt]=5");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("FIELD_NOT_INDEXED");
+  });
+
+  it("a `near` query against a nonexistent anchor note errors cleanly with 404, not a silent []", async () => {
+    const res = await getNotes("near[note_id]=does-not-exist");
+    expect(res.status).toBe(404);
+    const body: any = await res.json();
+    expect(body.error).toBeDefined();
+    expect(body.note_id).toBe("does-not-exist");
+  });
+
+  // removed in W2 — once #550's cursor-bootstrap fix lands, an omitted
+  // `cursor` param will (per the documented intent) still return a flat
+  // array for callers who never opt into cursor pagination, so this
+  // specific assertion should survive; the paired todo below is the one
+  // that flips when the bootstrap gap closes. Kept both here so the fix
+  // is a conscious, reviewed change rather than an incidental snapshot.
+  it("a cursor-less limit query returns a flat array (today's shape) — removed in W2", async () => {
+    await store.createNote("only note");
+    const res = await getNotes("limit=5");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+  });
+});
+
+describe("contract: honest queries — todo (#550)", () => {
+  test.todo(
+    "#550: limit=-1 returns a structured error instead of silently meaning \"unlimited\" (today: SQLite's negative-LIMIT-means-no-limit semantics leak straight through to the caller)",
+  );
+  test.todo(
+    "#550: query responses carry a warnings: [] channel, populated with a did_you_mean suggestion for an unknown tag name",
+  );
+  test.todo(
+    "#550: an invalid date_filter value (unparseable date string) returns a structured error instead of silently matching nothing or everything",
+  );
+  test.todo(
+    "#550: GET /api/tags/{nonexistent} returns 404 instead of 200 with an all-null synthesized record",
+  );
+  test.todo(
+    "#550: list-tags reports expanded_count (rollup through parent_names descendants) alongside the literal per-tag count — today a parent tag with only child-tagged notes reports count: 0",
+  );
+  test.todo(
+    "#550: cursor bootstrap — a first call that expresses cursor intent (no `cursor` param yet, but pagination is desired) returns a {notes, next_cursor} envelope, and a second call passing that cursor back sees only notes written since the first call (today: routes.ts only wraps the response in {notes, next_cursor} when a cursor param is ALREADY present, so the very first call can never obtain one — core/src/mcp.ts:331 documents a bootstrap flow that is not actually reachable)",
+  );
+});

package/src/contract-search.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Contract suite — search (Wave 1 of the Reliability & Usability Program,
+ * umbrella #556). Encodes the 2026-07-09 nine-persona deep test's search
+ * findings (WS2, #551) as executable tests: PASSING tests lock in behavior
+ * that is correct today; `test.todo` entries describe the target behavior
+ * for confirmed-broken cases, to be flipped to real assertions in a later
+ * wave. See #551 for the full write-up.
+ *
+ * Ground truth for every assertion here was re-verified live against this
+ * repo's FTS5 search path (`core/src/notes.ts` searchNotes → REST `GET
+ * /notes?search=`) before writing — see the PR description for the probe
+ * transcript.
+ */
+
+import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+const BASE = "http://localhost/api";
+
+function search(qs: string): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes?${qs}`, { method: "GET" }), store, "");
+}
+
+/** Planted corpus — each note exists to exercise exactly one FTS5 quirk. */
+const NOTES = {
+  hyphenPhrase: "The rollout had an eleven-day capping delay before it shipped.",
+  contraction: "She said she didn't know about the capping delay.",
+  decimal: "The measurement came out to 18.6 percent this quarter.",
+  bothWords: "A plain keyword note about widgets and gadgets.",
+  widgetsOnly: "Only widgets here, no other word.",
+  gadgetsOnly: "Gadgets alone, nothing else notable.",
+  filler1: "Quarterly report drafted for the finance team.",
+  filler2: "Meeting notes from the Tuesday standup.",
+  filler3: "Grocery list: eggs, bread, oat milk.",
+  filler4: "Project plan for the Q3 roadmap.",
+  filler5: "Weekly retro: wins and blockers for the sprint.",
+  filler6: "Random thoughts on the trip itinerary.",
+};
+
+beforeEach(async () => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+  for (const content of Object.values(NOTES)) {
+    await store.createNote(content);
+  }
+});
+
+afterEach(() => {
+  db.close();
+});
+
+async function bodyOf(res: Response): Promise<any> {
+  return res.json();
+}
+
+describe("contract: search — passing (lock in current behavior)", () => {
+  it("plain keyword search finds the matching notes", async () => {
+    const res = await search("search=widgets&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    const contents = new Set(body.map((n: any) => n.content));
+    expect(contents.has(NOTES.bothWords)).toBe(true);
+    expect(contents.has(NOTES.widgetsOnly)).toBe(true);
+    expect(contents.has(NOTES.gadgetsOnly)).toBe(false);
+  });
+
+  it("two-word unquoted search is implicit AND — only the note containing BOTH terms matches", async () => {
+    const res = await search("search=widgets+gadgets&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.bothWords]);
+  });
+
+  it('quoted phrase finds hyphenated phrase text: "eleven-day capping delay"', async () => {
+    const res = await search(`search=${encodeURIComponent('"eleven-day capping delay"')}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.hyphenPhrase]);
+  });
+
+  it('quoted decimal literal finds it: "18.6"', async () => {
+    const res = await search(`search=${encodeURIComponent('"18.6"')}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.decimal]);
+  });
+
+  it('quoted contraction finds it: "didn\'t"', async () => {
+    const res = await search(`search=${encodeURIComponent(`"didn't"`)}&include_content=true`);
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body.map((n: any) => n.content)).toEqual([NOTES.contraction]);
+  });
+
+  it("unknown-word search returns []", async () => {
+    const res = await search("search=zzzznonexistentword&include_content=true");
+    expect(res.status).toBe(200);
+    const body = await bodyOf(res);
+    expect(body).toEqual([]);
+  });
+});
+
+describe("contract: search — todo (#551, literal-by-default + recall + ranking)", () => {
+  test.todo(
+    `#551: unquoted search: "didn't" finds the contraction content (literal-by-default — today the bare apostrophe splits into two AND'd tokens and returns [])`,
+  );
+  test.todo(
+    `#551: unquoted search: "eleven-day capping delay" finds the hyphenated-phrase note (literal-by-default — today the bare hyphenated word tokenizes into separate AND'd terms and returns [])`,
+  );
+  test.todo(
+    `#551: unquoted search: "18.6" finds the decimal note (literal-by-default — today the bare decimal tokenizes into separate AND'd terms and returns [])`,
+  );
+  test.todo(
+    `#551: search_mode:"advanced" preserves raw FTS5 query syntax (AND/OR/NOT, phrase, prefix) once literal-by-default escaping ships as the new default`,
+  );
+  test.todo(
+    `#551: sort:"asc"/"desc" changes result order under search (today silently ignored — FTS5 rank order wins regardless of the sort param)`,
+  );
+  test.todo(
+    `#551: malformed FTS syntax (e.g. an unbalanced quote) yields a structured warning or error, not a silently swallowed [] (today searchNotes catches every FTS5 syntax error and returns [])`,
+  );
+});