@openparachute/vault 0.6.5 → 0.7.0-rc.2

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/core/src/cursor.ts

@@ -94,41 +94,59 @@ export function encodeCursor(payload: CursorPayload): string {
   return Buffer.from(json, "utf8").toString("base64url");
 }
 
-/** Decode a cursor string. Throws `CursorError` on any structural problem. */
+/**
+ * Trailing hint appended to every `cursor_invalid` message (vault#550) so a
+ * caller who passed a garbage cursor — or never understood the bootstrap
+ * shape in the first place — gets the actual recovery flow, not just "this
+ * string is broken." The bootstrap flow: an EMPTY string (`cursor: ""` /
+ * `?cursor=`) opts into cursor mode without a watermark yet; the response's
+ * `next_cursor` is what you pass on every call after that.
+ */
+const CURSOR_BOOTSTRAP_HINT =
+  'first call: pass cursor:"" (or omit `cursor` entirely for a plain, non-paginated list); the response carries `next_cursor` — pass that back on each subsequent call to resume from the watermark.';
+
+/**
+ * Decode a cursor string. Throws `CursorError` on any structural problem.
+ * An EMPTY string is deliberately NOT accepted here — callers (queryNotes /
+ * queryNotesPaged) must special-case `opts.cursor === ""` as "cursor mode,
+ * no watermark yet" and skip calling this at all (vault#550 bootstrap fix).
+ * Any caller that reaches this function with an empty string gets the same
+ * loud `cursor_invalid` as any other malformed cursor.
+ */
 export function decodeCursor(cursor: string): CursorPayload {
   if (typeof cursor !== "string" || cursor.length === 0) {
-    throw new CursorError("cursor must be a non-empty string", "cursor_invalid");
+    throw new CursorError(`cursor must be a non-empty string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   let json: string;
   try {
     json = Buffer.from(cursor, "base64url").toString("utf8");
   } catch {
-    throw new CursorError("cursor is not valid base64url", "cursor_invalid");
+    throw new CursorError(`cursor is not valid base64url — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   let parsed: unknown;
   try {
     parsed = JSON.parse(json);
   } catch {
-    throw new CursorError("cursor payload is not valid JSON", "cursor_invalid");
+    throw new CursorError(`cursor payload is not valid JSON — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (!parsed || typeof parsed !== "object") {
-    throw new CursorError("cursor payload must be an object", "cursor_invalid");
+    throw new CursorError(`cursor payload must be an object — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   const p = parsed as Record<string, unknown>;
   if (typeof p.v !== "number" || p.v !== CURSOR_VERSION) {
     throw new CursorError(
-      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)})`,
+      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)}) — ${CURSOR_BOOTSTRAP_HINT}`,
       "cursor_invalid",
     );
   }
   if (typeof p.last_updated_at !== "number" || !Number.isFinite(p.last_updated_at)) {
-    throw new CursorError("cursor.last_updated_at must be a finite number", "cursor_invalid");
+    throw new CursorError(`cursor.last_updated_at must be a finite number — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (typeof p.last_id !== "string") {
-    throw new CursorError("cursor.last_id must be a string", "cursor_invalid");
+    throw new CursorError(`cursor.last_id must be a string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (typeof p.query_hash !== "string" || p.query_hash.length === 0) {
-    throw new CursorError("cursor.query_hash must be a non-empty string", "cursor_invalid");
+    throw new CursorError(`cursor.query_hash must be a non-empty string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   return {
     v: p.v,

package/core/src/links.ts

@@ -404,6 +404,66 @@ export function traverseLinks(
   return results;
 }
 
+/** Hydrated find-path result — see `hydratePathResult` for field semantics. */
+export interface FindPathResult {
+  /** Note IDs, source → target (unchanged shape — back-compat). */
+  path: string[];
+  /** relationships[i] is the edge connecting path[i] to path[i+1] (unchanged shape). */
+  relationships: string[];
+  /**
+   * Hydrated companion to `path[]` (vault#550, additive): one entry per
+   * node, in the same order, carrying the note's `path` field alongside
+   * its `id` — so a caller doesn't have to round-trip each id through a
+   * separate note fetch just to render a human-legible chain.
+   */
+  nodes: { id: string; path: string | null }[];
+  /**
+   * Hydrated companion to `relationships[]` (vault#550, additive): each
+   * hop as a self-contained `{source, target, relationship}` edge plus
+   * both endpoints' note `path`, so a graph-rendering client can draw the
+   * chain without cross-referencing `nodes`.
+   */
+  edges: {
+    source: string;
+    target: string;
+    relationship: string;
+    sourcePath: string | null;
+    targetPath: string | null;
+  }[];
+}
+
+/**
+ * Hydrate a raw BFS result (`path` ids + `relationships`) with each node's
+ * note `path` field, in ONE batched query (not one fetch per hop). `path`
+ * and `relationships` pass through byte-identical to before this existed —
+ * `nodes`/`edges` are pure additions.
+ */
+function hydratePathResult(db: Database, path: string[], relationships: string[]): FindPathResult {
+  const pathById = new Map<string, string | null>();
+  for (const chunk of chunkForInClause(path)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db.prepare(`SELECT id, path FROM notes WHERE id IN (${placeholders})`).all(...chunk) as
+      { id: string; path: string | null }[];
+    for (const row of rows) pathById.set(row.id, row.path);
+  }
+
+  const nodes = path.map((id) => ({ id, path: pathById.get(id) ?? null }));
+  const edges: FindPathResult["edges"] = [];
+  for (let i = 0; i < path.length - 1; i++) {
+    const source = path[i]!;
+    const target = path[i + 1]!;
+    edges.push({
+      source,
+      target,
+      relationship: relationships[i] ?? "",
+      sourcePath: pathById.get(source) ?? null,
+      targetPath: pathById.get(target) ?? null,
+    });
+  }
+
+  return { path, relationships, nodes, edges };
+}
+
 /**
  * Find a path between two notes in the link graph.
  * Returns the sequence of note IDs from source to target, or null if no path exists.
@@ -413,11 +473,11 @@ export function findPath(
   sourceId: string,
   targetId: string,
   opts?: { max_depth?: number },
-): { path: string[]; relationships: string[] } | null {
+): FindPathResult | null {
   const maxDepth = opts?.max_depth ?? 5;
 
   if (sourceId === targetId) {
-    return { path: [sourceId], relationships: [] };
+    return hydratePathResult(db, [sourceId], []);
   }
 
   // BFS from source
@@ -460,7 +520,7 @@ export function findPath(
             current = entry.parent;
           }
           path.unshift(sourceId);
-          return { path, relationships };
+          return hydratePathResult(db, path, relationships);
         }
       }
     }

package/core/src/mcp.ts

@@ -4,7 +4,8 @@ import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
-import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "./tag-hierarchy.js";
+import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
+import { collectUnknownTagWarnings, type QueryWarning } from "./query-warnings.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -237,7 +238,12 @@ Defaults: include_content=true for single note, false for lists. include_links=f
 
 Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bounded read of note content — the response carries the slice plus \`content_total_length\` and \`content_next_offset\` (null when complete). Loop, feeding \`content_next_offset\` back as \`content_offset\`, to read a note too large for one response.
 
-Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.`,
+Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.
+
+Response shape (vault#550 — three variants, pick by what you passed):
+- Default (no \`cursor\`, no warnings): a bare array of notes.
+- Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
+- Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -328,7 +334,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           cursor: {
             type: "string",
             description:
-              "Opaque cursor for 'since last checked' agent loops (vault#313). First call: omit. The response will include `next_cursor` — pass it on the subsequent call to receive only notes created or updated since the prior page. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`. The response shape switches to `{notes, next_cursor}` when this parameter is present.",
+              "Opaque cursor for 'since last checked' agent loops (vault#313). Bootstrap flow (vault#550): FIRST call passes `cursor: \"\"` (empty string) — this opts into cursor mode with no watermark yet and the response comes back as `{notes, next_cursor}`. Persist `next_cursor` and pass it back verbatim as `cursor` on every SUBSEQUENT call to receive only notes created or updated since the prior page. Omitting `cursor` entirely (not passing the key at all) is a DIFFERENT thing — a plain one-shot list with no cursor envelope and no way to resume; use that when you don't want pagination at all. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error, and a malformed/expired cursor returns `cursor_invalid` naming the bootstrap flow again. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`.",
           },
           include_content: { type: "boolean", description: "Include note content (default: true for single, false for list)" },
           content_offset: {
@@ -466,7 +472,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // neighborhood every call to be cursor-stable; we punt for now).
         // Both surface as INVALID_QUERY rather than silently returning
         // wrong rows.
-        const cursorMode = typeof params.cursor === "string" && params.cursor.length > 0;
+        // Presence, not truthiness (vault#550 bootstrap fix) — `cursor: ""`
+        // is the bootstrap call ("I want to paginate, no watermark yet") and
+        // must still engage cursor mode. Before this fix `"".length > 0` was
+        // false, so the very first call could never obtain a `next_cursor`.
+        const cursorMode = typeof params.cursor === "string";
         if (cursorMode && params.search) {
           throw new QueryError(
             `cursor is incompatible with full-text search — FTS has its own ordering. Use date_filter on updated_at for since-last-checked search.`,
@@ -495,6 +505,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // --- Full-text search ---
         let results: Note[];
         let nextCursor: string | null = null;
+        // Warnings channel (vault#550) — structured-query only for this
+        // wave; `search=` is out of scope (see #551). Scope-unaware by
+        // design (see `core/src/query-warnings.ts` doc comment) — a
+        // tag-scoped MCP session gets these stripped by the
+        // `applyTagScopeWrappers` query-notes wrapper in `src/mcp-tools.ts`
+        // before the result reaches the caller, so an out-of-scope tag name
+        // never leaks via `did_you_mean`.
+        let queryWarnings: QueryWarning[] = [];
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
@@ -556,6 +574,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             offset: params.offset as number | undefined,
             cursor: cursorMode ? (params.cursor as string) : undefined,
           };
+          queryWarnings = collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy());
           if (cursorMode) {
             const page = await store.queryNotesPaged(queryOpts);
             results = page.notes;
@@ -637,13 +656,29 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
           // Cursor mode wraps the list in `{notes, next_cursor}` so callers can
           // chain calls without tracking a watermark client-side. Legacy
-          // callers (no `cursor` param) still get the flat array.
-          if (cursorMode) return { notes: enrichedOut, next_cursor: nextCursor };
-          return enrichedOut;
+          // callers (no `cursor` param, no warnings) still get the flat
+          // array (vault#550 — warnings channel is additive, never forces
+          // the envelope on its own outside cursor mode... except when
+          // there ARE warnings, in which case the envelope is the only way
+          // to attach them).
+          if (cursorMode) {
+            return {
+              notes: enrichedOut,
+              next_cursor: nextCursor,
+              ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}),
+            };
+          }
+          return queryWarnings.length > 0 ? { notes: enrichedOut, warnings: queryWarnings } : enrichedOut;
         }
 
-        if (cursorMode) return { notes: output, next_cursor: nextCursor };
-        return output;
+        if (cursorMode) {
+          return {
+            notes: output,
+            next_cursor: nextCursor,
+            ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}),
+          };
+        }
+        return queryWarnings.length > 0 ? { notes: output, warnings: queryWarnings } : output;
       },
     },
 
@@ -1353,7 +1388,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "list-tags",
       requiredVerb: "read",
-      description: `List tags with usage counts. Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps). Pass \`include_schema: true\` to include the full record for every tag.`,
+      description: `List tags with usage counts. Each row carries \`count\` (notes carrying the EXACT tag) and \`expanded_count\` (vault#550 — distinct notes matching the tag OR any transitive descendant under the default subtypes expansion; use this to see a parent tag's true rollup when its notes are actually tagged with a more specific child). Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps) — errors with \`error_type: "tag_not_found"\` (plus a \`did_you_mean\` hint when a close match exists) if the tag has no identity row and no notes. Pass \`include_schema: true\` to include the full record for every tag.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -1368,9 +1403,30 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           const allTags = noteOps.listTags(db);
           const found = allTags.find((t) => t.name === singleTag);
           const record = tagSchemaOps.getTagRecord(db, singleTag);
+          // vault#550 — a tag with no identity row AND no note carrying it
+          // isn't a legitimate (if empty) tag, it's a typo or a tag from a
+          // different vault. Return a structured miss instead of a
+          // synthesized all-null 200. `did_you_mean` searches the full
+          // vault-wide tag catalog — core is scope-unaware by architecture.
+          // Tag-scope enforcement lives in the server layer's list-tags
+          // wrapper (src/mcp-tools.ts:applyTagScopeWrappers): a scoped
+          // session's out-of-scope `tag` param short-circuits to
+          // tag_not_found BEFORE this executes, and an in-scope miss gets
+          // its `did_you_mean` dropped unless the suggestion is also
+          // in-scope.
+          if (!found && !record) {
+            const suggestion = suggestSimilarTag(allTags.map((t) => t.name), singleTag);
+            return {
+              error: "Tag not found",
+              error_type: "tag_not_found",
+              tag: singleTag,
+              ...(suggestion ? { did_you_mean: suggestion } : {}),
+            };
+          }
           return {
             name: singleTag,
             count: found?.count ?? 0,
+            expanded_count: found?.expanded_count ?? 0,
             description: record?.description ?? null,
             fields: record?.fields ?? null,
             relationships: record?.relationships ?? null,
@@ -1589,7 +1645,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "find-path",
       requiredVerb: "read",
-      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns the chain of note IDs and relationships, or null if no path exists.",
+      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns null if no path exists, else `{path, relationships, nodes, edges}`: `path` (note IDs, source→target) and `relationships` (relationships[i] connects path[i] to path[i+1]) are the original id-only shape; `nodes` (vault#550, additive) hydrates each id in `path` with the note's own `path` field — `[{id, path}]` in the same order; `edges` (additive) is the self-contained hop list — `[{source, target, relationship, sourcePath, targetPath}]` — for rendering the chain without cross-referencing `nodes`.",
       inputSchema: {
         type: "object",
         properties: {