@openparachute/vault 0.6.5 → 0.7.0-rc.2

package/src/mcp-http.ts

@@ -156,7 +156,26 @@ async function handleMcp(
         to?: unknown;
         current?: unknown;
         violations?: unknown;
+        error_type?: string;
+        got?: unknown;
+        hint?: string;
       };
+      // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
+      // values that are structurally invalid rather than merely "no
+      // results." Gated on `error_type === "invalid_query"` specifically
+      // (not `code === "INVALID_QUERY"` broadly) so long-standing QueryError
+      // throws WITHOUT this field (FIELD_NOT_INDEXED, UNKNOWN_OPERATOR, the
+      // various cursor/near/search incompatibility errors, ...) keep their
+      // existing unstructured `isError: true` fallback — only the NEW #550
+      // call sites that explicitly set `error_type` opt into this shape.
+      if (e?.error_type === "invalid_query") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "invalid_query",
+          field: e.field,
+          got: e.got,
+          hint: e.hint,
+        });
+      }
       if (e?.code === "CONFLICT") {
         throw new McpError(ErrorCode.InvalidRequest, message, {
           error_type: "conflict",

package/src/mcp-list-tags-scope.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Tag-scope enforcement on the MCP `list-tags` single-tag path (vault#550
+ * fold; also closes vault#560). Core's list-tags is scope-unaware by
+ * architecture — `applyTagScopeWrappers` in src/mcp-tools.ts is the
+ * enforcement layer. Before this fix the wrapper only filtered ARRAY
+ * results, so the single-tag (`{tag}` param) shape passed through
+ * unwrapped, leaking (a) the FULL record of an existing out-of-scope tag
+ * (#560), and (b) post-#550, a vault-wide `did_you_mean` suggestion that
+ * could name an out-of-scope tag.
+ *
+ * Fixture: PARACHUTE_HOME temp home + a hand-built AuthResult (no JWT
+ * infra needed — `generateScopedMcpTools` takes the resolved auth
+ * directly), same pattern as attribution-threading.test.ts's MCP section.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import type { AuthResult } from "./auth.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-listtags-scope-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null): AuthResult {
+  return {
+    permission: "full",
+    scopes: [`vault:${vaultName}:read`, `vault:${vaultName}:write`],
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function listTagsTool(vaultName: string, scopedTags: string[] | null) {
+  const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+  return tools.find((t) => t.name === "list-tags")!;
+}
+
+describe("MCP list-tags single-tag path — tag-scope enforcement (vault#550 fold, closes #560)", () => {
+  test("scoped token + EXISTING out-of-scope tag → tag_not_found with no record fields, no did_you_mean (#560's full-record leak)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("work", { description: "top secret reorg planning" });
+    await store.createNote("w", { tags: ["work"] });
+    await store.createNote("h", { tags: ["health"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "work" })) as any;
+
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("work");
+    // No leak: none of the record's fields, no counts, no suggestion.
+    expect(result.description).toBeUndefined();
+    expect(result.count).toBeUndefined();
+    expect(result.expanded_count).toBeUndefined();
+    expect(result.fields).toBeUndefined();
+    expect(result.parent_names).toBeUndefined();
+    expect(result.did_you_mean).toBeUndefined();
+  });
+
+  test("scoped token + NONEXISTENT tag → tag_not_found without an out-of-scope did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // "project" exists but is OUT of scope — it must not surface as a
+    // suggestion for the near-miss "projet".
+    await store.upsertTagRecord("project", {});
+    await store.createNote("h", { tags: ["health"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    // "projet" is not in the allowlist → short-circuits to tag_not_found
+    // before core even computes a suggestion.
+    const result = (await tool.execute({ tag: "projet" })) as any;
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("projet");
+    expect(result.did_you_mean).toBeUndefined();
+  });
+
+  test("scoped token + in-scope miss keeps did_you_mean only when the suggestion is also in-scope", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // Declared hierarchy: health/food is a child of health, so the
+    // allowlist expansion covers both. A near-miss on the CHILD name is in
+    // the allowlist's expansion? No — "health/fod" itself isn't a known
+    // tag, but it IS within scope only if the allowlist contains it.
+    // expandTokenTagScope(["health"]) = {health, health/food}; the literal
+    // input "health/fod" is NOT in that set → short-circuit tag_not_found
+    // (no suggestion) — pinning that the wrapper gates on the allowlist,
+    // not on string prefixes.
+    await store.upsertTagRecord("health/food", { parent_names: ["health"] });
+    await store.createNote("hf", { tags: ["health/food"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "health/fod" })) as any;
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.did_you_mean).toBeUndefined();
+  });
+
+  test("unscoped token unchanged — full record for existing tags, did_you_mean on misses", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("project", { description: "projects" });
+    await store.createNote("p", { tags: ["project"] });
+
+    const tool = await listTagsTool("journal", null);
+
+    const hit = (await tool.execute({ tag: "project" })) as any;
+    expect(hit.name).toBe("project");
+    expect(hit.count).toBe(1);
+    expect(hit.description).toBe("projects");
+
+    const miss = (await tool.execute({ tag: "projet" })) as any;
+    expect(miss.error_type).toBe("tag_not_found");
+    expect(miss.did_you_mean).toBe("project");
+  });
+
+  test("scoped token + array list still filters to the allowlist (regression: pre-existing behavior)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("h", { tags: ["health"] });
+    await store.createNote("w", { tags: ["work"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({})) as any[];
+    const names = result.map((t) => t.name);
+    expect(names).toContain("health");
+    expect(names).not.toContain("work");
+  });
+});

package/src/mcp-tools.ts

@@ -308,9 +308,11 @@ function applyTagScopeWrappers(
     const allowed = await getAllowed();
     const result = await orig(params);
     if (!allowed) return result;
-    // Three possible response shapes:
-    //   - Array (legacy list, no cursor)
+    // Possible response shapes (vault#550 added the `warnings` variants):
+    //   - Array (legacy list, no cursor, no warnings)
     //   - `{notes, next_cursor}` (cursor mode, vault#313)
+    //   - `{notes, warnings}` (warnings present, not in cursor mode)
+    //   - `{notes, next_cursor, warnings}` (both)
     //   - `{...note}` with `id`+`tags` (single-note by id)
     if (Array.isArray(result)) {
       return result
@@ -321,15 +323,22 @@ function applyTagScopeWrappers(
       result &&
       typeof result === "object" &&
       "notes" in result &&
-      Array.isArray((result as any).notes) &&
-      "next_cursor" in result
+      Array.isArray((result as any).notes)
     ) {
-      const r = result as { notes: any[]; next_cursor: string | null };
+      const r = result as { notes: any[]; next_cursor?: string | null; warnings?: unknown };
       return {
         notes: r.notes
           .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
           .map(scrubNoteLinks),
-        next_cursor: r.next_cursor,
+        ...("next_cursor" in r ? { next_cursor: r.next_cursor } : {}),
+        // `warnings` intentionally DROPPED for a tag-scoped session: core's
+        // `collectUnknownTagWarnings` (core/src/query-warnings.ts) resolves
+        // `did_you_mean` against the FULL vault-wide tag catalog, which
+        // would leak an out-of-scope tag's existence/name to a token that
+        // can't otherwise see it — the same "no leak across the scope
+        // boundary" stance this file takes everywhere else (see
+        // docs/contracts/tag-scoped-tokens.md). Unscoped sessions keep
+        // `warnings` untouched via the `!allowed` early return above.
       };
     }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
@@ -342,9 +351,41 @@ function applyTagScopeWrappers(
 
   wrapReadTool(tools, "list-tags", async (orig, params) => {
     const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    // Single-tag detail (`{tag}` param) — the non-array shape the old
+    // wrapper silently passed through, which leaked BOTH the full record of
+    // an existing out-of-scope tag (vault#560) AND, post-#550, a vault-wide
+    // `did_you_mean` suggestion for a nonexistent one. This wrapper is the
+    // enforcement layer for tag scope on this tool; core's list-tags stays
+    // scope-unaware by architecture (same division as every other wrapper
+    // in this file).
+    const singleTag = typeof (params as any).tag === "string" ? ((params as any).tag as string) : null;
+    if (singleTag !== null && !allowed.has(singleTag)) {
+      // Out-of-scope name — whether the tag exists or not. Same
+      // "tag_not_found, no leak" shape as the REST handlers' early-return,
+      // and deliberately NO did_you_mean (any suggestion would be computed
+      // vault-wide). Short-circuits BEFORE core runs, so the full record /
+      // suggestion is never even computed.
+      return { error: "Tag not found", error_type: "tag_not_found", tag: singleTag };
+    }
     const result = await orig(params);
-    if (!allowed || !Array.isArray(result)) return result;
-    return result.filter((t: any) => allowed.has(t.name));
+    if (Array.isArray(result)) {
+      return result.filter((t: any) => allowed.has(t.name));
+    }
+    // In-scope single-tag miss (nonexistent but allowlisted name): core's
+    // tag_not_found may carry a vault-wide `did_you_mean` — keep it only
+    // when the suggestion itself is inside the allowlist.
+    if (
+      result &&
+      typeof result === "object" &&
+      (result as any).error_type === "tag_not_found" &&
+      typeof (result as any).did_you_mean === "string" &&
+      !allowed.has((result as any).did_you_mean)
+    ) {
+      const { did_you_mean: _dropped, ...scrubbed } = result as Record<string, unknown>;
+      return scrubbed;
+    }
+    return result;
   });
 
   wrapReadTool(tools, "find-path", async (orig, params) => {

package/src/routes.ts

@@ -12,7 +12,8 @@
  */
 
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
-import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
+import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
+import { collectUnknownTagWarnings, type QueryWarning } from "../core/src/query-warnings.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { transactionAsync } from "../core/src/txn.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
@@ -128,6 +129,56 @@ function json(data: unknown, status = 200): Response {
   return Response.json(data, { status });
 }
 
+/**
+ * `json(...)` plus the `X-Parachute-Warnings` response header (vault#550) —
+ * `encodeURIComponent(JSON.stringify(warnings))`, set only when `warnings`
+ * is non-empty. Percent-encoded because HTTP header VALUES are
+ * Latin1/ASCII-only (the Fetch spec's ByteString requirement) while warning
+ * `message` text uses this codebase's normal house style (em dashes,
+ * curly-free but occasionally non-ASCII punctuation) — a raw
+ * `JSON.stringify` throws `TypeError: invalid header value` the first time
+ * a message isn't 7-bit-clean. Decode with `decodeURIComponent` then
+ * `JSON.parse`. Exists so bare-array responses (`GET /notes` without a
+ * cursor) can carry warnings WITHOUT changing their wire shape — a code
+ * consumer doing `for (const note of await res.json())` keeps working
+ * unmodified, while a consumer that cares can read the header. Envelope
+ * shapes (`{notes, next_cursor}`, `{nodes, edges}`) get the header too for
+ * uniform discoverability; callers that want warnings INLINE in an
+ * envelope should also spread them into the response body before calling
+ * this (see the cursor-envelope call sites in `handleNotesInner`).
+ */
+function jsonWithWarnings(data: unknown, warnings: QueryWarning[], status = 200): Response {
+  const res = json(data, status);
+  if (warnings.length > 0) {
+    res.headers.set("X-Parachute-Warnings", encodeURIComponent(JSON.stringify(warnings)));
+  }
+  return res;
+}
+
+/**
+ * REST-only `removed_param` warning (vault#550) — the flat `date_field` /
+ * `date_from` / `date_to` query-string params were removed at 0.6.4
+ * (vault#288) and have been silently ignored ever since (routes.ts:633-ish
+ * comment). A request that passes any of them now gets a warning naming
+ * the ignored param and the bracket-style replacement, instead of quietly
+ * coming back unfiltered. One warning per param present (a caller passing
+ * all three gets three entries — precise, not lossy-summarized).
+ */
+function collectRemovedParamWarnings(url: URL): QueryWarning[] {
+  const REMOVED_DATE_PARAMS = ["date_field", "date_from", "date_to"] as const;
+  const warnings: QueryWarning[] = [];
+  for (const param of REMOVED_DATE_PARAMS) {
+    if (url.searchParams.has(param)) {
+      warnings.push({
+        code: "removed_param",
+        message: `\`${param}\` was removed in 0.6.4 (vault#288) and is silently ignored — use bracket-style date filters instead: \`meta[created_at][gte]=…\` / \`meta[created_at][lt]=…\` (or \`meta[updated_at][...]\`).`,
+        param,
+      });
+    }
+  }
+  return warnings;
+}
+
 function parseBool(val: string | null, defaultVal: boolean): boolean {
   if (val === null) return defaultVal;
   return val === "true" || val === "1";
@@ -221,6 +272,59 @@ function parseInt10(val: string | null): number | undefined {
   return isNaN(n) ? undefined : n;
 }
 
+/**
+ * Parse + validate `?limit=` / `?offset=` for the structured-query path
+ * (vault#550). Before this, `parseInt10(...) ?? 50` silently swallowed a
+ * non-numeric value into the default (a caller's typo `?limit=fifty` just
+ * became `limit=50` with no signal), and any negative value that DID parse
+ * flowed straight through to SQLite, whose `LIMIT -1` means "no limit" —
+ * silently returning EVERYTHING instead of erroring. Returns `{value}`
+ * (undefined when the param is absent — the caller applies its own
+ * default) or `{error}` (400 `invalid_query`) when present-but-malformed.
+ * `got` echoes the ORIGINAL raw string so the error is legible even though
+ * the coerced value (e.g. `NaN`) wouldn't be.
+ */
+function parseNonNegativeIntParam(
+  url: URL,
+  key: "limit" | "offset",
+): { value?: number; error?: Response } {
+  const raw = parseQuery(url, key);
+  if (raw === null || raw === "") return {};
+  const trimmed = raw.trim();
+  if (!/^-?\d+$/.test(trimmed)) {
+    return {
+      error: json(
+        {
+          error: `\`${key}\` must be an integer, got ${JSON.stringify(raw)}`,
+          error_type: "invalid_query",
+          code: "INVALID_QUERY",
+          field: key,
+          got: raw,
+          hint: `pass a non-negative integer (e.g. ?${key}=${key === "limit" ? "50" : "0"}), or omit for the default`,
+        },
+        400,
+      ),
+    };
+  }
+  const n = parseInt(trimmed, 10);
+  if (n < 0) {
+    return {
+      error: json(
+        {
+          error: `\`${key}\` must be zero or greater, got ${n}${key === "limit" ? " — a negative limit used to silently mean \"unlimited\" (SQLite semantics leaking through)" : ""}`,
+          error_type: "invalid_query",
+          code: "INVALID_QUERY",
+          field: key,
+          got: raw,
+          hint: "pass a non-negative integer, or omit for the default",
+        },
+        400,
+      ),
+    };
+  }
+  return { value: n };
+}
+
 /**
  * Parse bracket-style metadata filters (vault#285 friction point 1.3).
  *
@@ -612,6 +716,12 @@ export function parseNotesQueryOpts(url: URL): {
   if (expandParsed.error) return { hasSearch, hasNear, hasCursor, error: expandParsed.error };
   const expand = expandParsed.expand;
 
+  // limit/offset validation (vault#550) — see parseNonNegativeIntParam.
+  const limitParsed = parseNonNegativeIntParam(url, "limit");
+  if (limitParsed.error) return { hasSearch, hasNear, hasCursor, error: limitParsed.error };
+  const offsetParsed = parseNonNegativeIntParam(url, "offset");
+  if (offsetParsed.error) return { hasSearch, hasNear, hasCursor, error: offsetParsed.error };
+
   const queryOpts: QueryOpts = {
     tags,
     tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
@@ -639,8 +749,8 @@ export function parseNotesQueryOpts(url: URL): {
     ...(bracket.dateFilter ? { dateFilter: bracket.dateFilter } : {}),
     sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
     orderBy: parseQuery(url, "order_by") ?? undefined,
-    limit: parseInt10(parseQuery(url, "limit")) ?? 50,
-    offset: parseInt10(parseQuery(url, "offset")),
+    limit: limitParsed.value ?? 50,
+    offset: offsetParsed.value,
     cursor: cursorParam ?? undefined,
   };
 
@@ -839,8 +949,11 @@ async function handleNotesInner(
       // FTS owns its own ordering (relevance, not updated_at), so a cursor
       // would skip rows. MCP rejects this combo at `core/src/mcp.ts`; REST
       // would otherwise route into the `if (search)` branch below and
-      // silently drop the cursor. Reject here for surface parity.
-      if (search && parseQuery(url, "cursor")) {
+      // silently drop the cursor. Reject here for surface parity. Presence
+      // check (`!== null`), not truthiness (vault#550) — a bootstrap
+      // `?cursor=` attempt against a search query is still cursor intent
+      // and must still be rejected, not silently treated as "no cursor."
+      if (search && parseQuery(url, "cursor") !== null) {
         return json(
           {
             error: "cursor is incompatible with full-text search — FTS has its own ordering. Use date_filter on updated_at for since-last-checked search.",
@@ -934,11 +1047,22 @@ async function handleNotesInner(
       if (parsed.error) return parsed.error;
       const queryOpts = parsed.queryOpts!;
       const cursorParam = parseQuery(url, "cursor");
+      // Cursor mode is keyed on PRESENCE (`!== null`), not truthiness
+      // (vault#550 bootstrap fix). `?cursor=` (present, empty) is the
+      // bootstrap call — "I want to paginate, no watermark yet" — and must
+      // still engage the `{notes, next_cursor}` envelope. Before this fix
+      // `if (cursorParam)` treated an empty string exactly like an absent
+      // param, so the FIRST call could never obtain a cursor even though
+      // `core/src/mcp.ts` documented that flow — the cursor bootstrap gap
+      // this wave closes. Omitting `cursor` entirely (`cursorParam ===
+      // null`) is the only way to opt OUT — that keeps today's bare-array
+      // compat shape.
+      const cursorMode = cursorParam !== null;
       // Opaque cursor for "since last checked" agent loops (vault#313) is
       // mutually exclusive with the `near` graph-neighborhood scope (rebuilding
       // the neighborhood per page isn't stable).
       const nearNoteIdEarly = parseQuery(url, "near[note_id]");
-      if (cursorParam && nearNoteIdEarly) {
+      if (cursorMode && nearNoteIdEarly) {
         return json(
           {
             error: "cursor is incompatible with near (graph neighborhood). Resolve the neighborhood first, then iterate with cursor over the resulting note set.",
@@ -947,10 +1071,25 @@ async function handleNotesInner(
           400,
         );
       }
+      // Warnings channel (vault#550) — structured-query only for this wave
+      // (search= is out of scope, see #551). Skipped entirely for a
+      // tag-scoped session: `collectUnknownTagWarnings` resolves
+      // `did_you_mean` against the FULL vault-wide tag catalog, which would
+      // leak an out-of-scope tag's existence/name across the scope boundary
+      // — the same "no leak" stance this codebase takes everywhere else
+      // (docs/contracts/tag-scoped-tokens.md). `removed_param` warnings
+      // (below, at the response-shaping stage) carry no tag information and
+      // fire regardless of scope.
+      const queryWarnings: QueryWarning[] = [
+        ...collectRemovedParamWarnings(url),
+        ...(tagScope.allowed === null
+          ? collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy())
+          : []),
+      ];
       let results: Note[];
       let nextCursor: string | null = null;
       try {
-        if (cursorParam) {
+        if (cursorMode) {
           const page = await store.queryNotesPaged(queryOpts);
           results = page.notes;
           nextCursor = page.next_cursor;
@@ -960,9 +1099,23 @@ async function handleNotesInner(
       } catch (e: any) {
         // QueryError (non-indexed order_by, unknown operator, ...) surfaces
         // here. Duck-type on `name` + `code` — core is a separate module, so
-        // `instanceof` is fragile across bundling boundaries.
+        // `instanceof` is fragile across bundling boundaries. The newer
+        // vault#550 call sites (limit/offset/date validation in
+        // core/src/notes.ts) additionally set `error_type`/`field`/`got`/
+        // `hint` — merged in when present; long-standing QueryError throws
+        // that don't set them keep their existing `{error, code}` shape.
         if (e && e.name === "QueryError") {
-          return json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400);
+          return json(
+            {
+              error: e.message,
+              code: e.code ?? "INVALID_QUERY",
+              ...(e.error_type !== undefined ? { error_type: e.error_type } : {}),
+              ...(e.field !== undefined ? { field: e.field } : {}),
+              ...(e.got !== undefined ? { got: e.got } : {}),
+              ...(e.hint !== undefined ? { hint: e.hint } : {}),
+            },
+            400,
+          );
         }
         // CursorError carries a structured code (cursor_invalid /
         // cursor_query_mismatch) so the agent loop can distinguish a
@@ -1072,7 +1225,12 @@ async function handleNotesInner(
             }
           }
         }
-        return json({ nodes, edges });
+        // Envelope shape → warnings inline (same policy as the cursor
+        // envelope below), plus the header via jsonWithWarnings.
+        return jsonWithWarnings(
+          { nodes, edges, ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}) },
+          queryWarnings,
+        );
       }
 
       if (includeLinks || includeAttachments) {
@@ -1099,12 +1257,24 @@ async function handleNotesInner(
         // Cursor mode wraps the list in {notes, next_cursor} so an agent
         // loop can chain calls without tracking a watermark client-side.
         // Legacy callers (no `cursor` param) still get the flat array.
-        if (cursorParam) return json({ notes: enrichedOut, next_cursor: nextCursor });
-        return json(enrichedOut);
+        // Warnings (vault#550): inline on the envelope, header either way
+        // (see jsonWithWarnings).
+        if (cursorMode) {
+          return jsonWithWarnings(
+            { notes: enrichedOut, next_cursor: nextCursor, ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}) },
+            queryWarnings,
+          );
+        }
+        return jsonWithWarnings(enrichedOut, queryWarnings);
       }
 
-      if (cursorParam) return json({ notes: output, next_cursor: nextCursor });
-      return json(output);
+      if (cursorMode) {
+        return jsonWithWarnings(
+          { notes: output, next_cursor: nextCursor, ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}) },
+          queryWarnings,
+        );
+      }
+      return jsonWithWarnings(output, queryWarnings);
     }
 
     // POST /notes — create (single or batch)
@@ -1874,16 +2044,42 @@ export async function handleTags(
     if (singleTag) {
       // Tag-scope: a tag-scoped token can only see tags reachable from its
       // allowlist (root + descendants per the parent_names hierarchy).
-      // Anything else 404s — same "no leak" stance as note reads.
+      // Anything else 404s — same "no leak" stance as note reads. This
+      // early-return means the vault#550 unknown-tag 404 below never even
+      // runs for a scope-excluded name — `did_you_mean` (which searches
+      // vault-wide) can't fire and leak an out-of-scope tag's existence.
       if (tagScope.allowed && !tagScope.allowed.has(singleTag)) {
-        return json({ error: "Tag not found", tag: singleTag }, 404);
+        return json({ error: "Tag not found", error_type: "tag_not_found", tag: singleTag }, 404);
       }
       const allTags = await store.listTags();
       const found = allTags.find((t) => t.name === singleTag);
       const record = await store.getTagRecord(singleTag);
+      // vault#550 — a tag with no identity row AND no notes carrying it
+      // isn't a legitimate (if empty) tag; it's a typo or a tag from a
+      // different vault. Return a structured 404 instead of synthesizing
+      // an all-null 200. `did_you_mean` candidates are restricted to the
+      // caller's allowlist when scoped (defense in depth — this branch is
+      // normally unreachable for a scoped session per the early-return
+      // above, but stays scope-safe if that ever changes).
+      if (!found && !record) {
+        const candidates = tagScope.allowed
+          ? allTags.filter((t) => tagScope.allowed!.has(t.name)).map((t) => t.name)
+          : allTags.map((t) => t.name);
+        const suggestion = suggestSimilarTag(candidates, singleTag);
+        return json(
+          {
+            error: "Tag not found",
+            error_type: "tag_not_found",
+            tag: singleTag,
+            ...(suggestion ? { did_you_mean: suggestion } : {}),
+          },
+          404,
+        );
+      }
       return json({
         name: singleTag,
         count: found?.count ?? 0,
+        expanded_count: found?.expanded_count ?? 0,
         description: record?.description ?? null,
         fields: record?.fields ?? null,
         relationships: record?.relationships ?? null,
@@ -2069,15 +2265,36 @@ export async function handleTags(
 
   // GET /tags/:name — single tag detail (full record)
   if (req.method === "GET") {
+    // Same "no leak" early-return as the `?tag=` form above — a
+    // scope-excluded name 404s before `did_you_mean` (vault-wide) can run.
     if (tagScope.allowed && !tagScope.allowed.has(tagName)) {
-      return json({ error: "Tag not found", tag: tagName }, 404);
+      return json({ error: "Tag not found", error_type: "tag_not_found", tag: tagName }, 404);
     }
     const allTags = await store.listTags();
     const found = allTags.find((t) => t.name === tagName);
     const record = await store.getTagRecord(tagName);
+    // vault#550 — see the `?tag=` form above for the rationale (no
+    // identity row + no memberships = not a real tag, not a legitimate
+    // empty one).
+    if (!found && !record) {
+      const candidates = tagScope.allowed
+        ? allTags.filter((t) => tagScope.allowed!.has(t.name)).map((t) => t.name)
+        : allTags.map((t) => t.name);
+      const suggestion = suggestSimilarTag(candidates, tagName);
+      return json(
+        {
+          error: "Tag not found",
+          error_type: "tag_not_found",
+          tag: tagName,
+          ...(suggestion ? { did_you_mean: suggestion } : {}),
+        },
+        404,
+      );
+    }
     return json({
       name: tagName,
       count: found?.count ?? 0,
+      expanded_count: found?.expanded_count ?? 0,
       description: record?.description ?? null,
       fields: record?.fields ?? null,
       relationships: record?.relationships ?? null,