@openparachute/vault 0.7.0-rc.3 → 0.7.0-rc.4

package/core/src/tag-schemas.ts

@@ -16,6 +16,7 @@
  */
 
 import { Database } from "bun:sqlite";
+import { mapFieldType, validateFieldName } from "./indexed-fields.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -280,17 +281,23 @@ export function deleteTagSchema(db: Database, tag: string): boolean {
  * time"); dropping the inner-shape gate is consistent with that intent.
  */
 export function validateRelationships(raw: unknown): Record<string, unknown> {
+  // `error_type` (vault#554) is attached directly on the thrown Error
+  // (duck-typed extra property, same pattern as QueryError's optional
+  // fields) rather than via a dedicated class — this is a validation
+  // leaf with one caller-facing shape, not a reusable domain error. Both
+  // REST (src/routes.ts, which already hardcodes this same string) and the
+  // generic MCP domain-error mapping (src/mcp-http.ts) key off it.
   if (raw === null || raw === undefined) {
-    throw new Error("relationships: expected an object, got null/undefined");
+    throw relationshipsError("relationships: expected an object, got null/undefined");
   }
   if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error(
+    throw relationshipsError(
       "relationships: expected an object mapping relationship name → value (got an array or primitive)",
     );
   }
   for (const rel of Object.keys(raw as Record<string, unknown>)) {
     if (!rel) {
-      throw new Error("relationships: keys must be non-empty strings");
+      throw relationshipsError("relationships: keys must be non-empty strings");
     }
   }
   // Round-trip through JSON to (a) confirm the payload is serializable —
@@ -300,11 +307,15 @@ export function validateRelationships(raw: unknown): Record<string, unknown> {
   try {
     serialized = JSON.stringify(raw);
   } catch (err) {
-    throw new Error(`relationships: value must be JSON-serializable (${(err as Error).message})`);
+    throw relationshipsError(`relationships: value must be JSON-serializable (${(err as Error).message})`);
   }
   return JSON.parse(serialized) as Record<string, unknown>;
 }
 
+function relationshipsError(message: string): Error {
+  return Object.assign(new Error(message), { error_type: "invalid_relationships" as const });
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -334,3 +345,174 @@ function jsonOrNull(value: unknown): string | null {
   }
   return JSON.stringify(value);
 }
+
+// ---------------------------------------------------------------------------
+// Cross-tag field validation (vault#553 / #554) — update-tag messaging
+// ---------------------------------------------------------------------------
+
+/**
+ * A single field-declaration violation surfaced by {@link collectTagFieldViolations}.
+ * `reason` is a stable machine-checkable slug; `message` is the existing
+ * human-readable prose (unchanged wording, just no longer thrown on the
+ * first hit).
+ */
+export interface TagFieldViolation {
+  field: string;
+  reason: "type_conflict" | "indexed_flag_conflict" | "unsupported_indexed_type" | "invalid_field_name";
+  message: string;
+  /**
+   * The conflicting declarer tag — present on the cross-tag reasons
+   * (`type_conflict` / `indexed_flag_conflict`) only; the solo own-field
+   * reasons have no other party. Core populates it unconditionally
+   * (scope-unaware by architecture); the SERVER layers scrub it — and
+   * generalize `message` — when the declarer is outside a tag-scoped
+   * caller's allowlist (`scrubTagFieldViolationsByScope` in
+   * src/tag-scope.ts), so a scoped session learns THAT a conflict exists
+   * (the write is still rejected — integrity is scope-independent) but not
+   * WHICH out-of-scope tag it conflicts with or what that tag declares.
+   */
+  other_tag?: string;
+}
+
+/**
+ * Thrown by `update-tag` (MCP tool + REST `PUT /api/tags/:name`) when one or
+ * more fields in the incoming `fields` payload conflict with another tag's
+ * declaration, or declare an unindexable/invalid indexed field. Carries
+ * EVERY violation found in the call (vault#553 settled complaint: the prior
+ * behavior threw on the FIRST offending field and silently never reported
+ * the rest — two testers independently assumed the other fields had landed).
+ * The message states explicitly that no changes were applied — the whole
+ * `upsertTagRecord` call is validated BEFORE any write, so a rejection here
+ * always leaves the tag record untouched (atomicity unchanged from before;
+ * this only improves what the caller is told).
+ */
+export class TagFieldConflictError extends Error {
+  code = "TAG_FIELD_CONFLICT" as const;
+  error_type = "tag_field_conflict" as const;
+  tag: string;
+  violations: TagFieldViolation[];
+
+  constructor(tag: string, violations: TagFieldViolation[]) {
+    const summary = violations.map((v) => `${v.field} (${v.reason}): ${v.message}`).join("; ");
+    super(
+      `tag_field_conflict: ${violations.length} field violation(s) for tag "${tag}" — no changes were applied. ${summary}`,
+    );
+    this.name = "TagFieldConflictError";
+    this.tag = tag;
+    this.violations = violations;
+  }
+}
+
+/**
+ * Validate the fields a caller is declaring/redeclaring for `tag` against
+ * every OTHER tag's schema — `type` and `indexed` must agree across all
+ * declarers (both are global per field). Returns every violation found —
+ * never throws — so the caller can report the complete set in one
+ * structured error (or none, when the array is empty).
+ *
+ * `incomingFields` is the set of fields THIS call is declaring (MCP:
+ * `params.fields`; REST: `body.fields`) — not the full merged field map.
+ * Fields the call doesn't touch were already valid (or already accepted)
+ * and are not re-validated here, matching the pre-#553 scope of the check.
+ *
+ * Two deliberate exclusions preserve pre-existing wire contracts
+ * (vault#554 — statuses/error_types on previously-working calls must not
+ * change):
+ *
+ * 1. The SEPARATE own-field checks (unsupported type for indexing,
+ *    invalid identifier) are NOT included — REST's `PUT /api/tags/:name`
+ *    has an established, tested single-violation `IndexedFieldError` →
+ *    400 `invalid_indexed_field` contract for those (vault#478). Use
+ *    {@link collectTagFieldViolations} (own-field checks included) for a
+ *    caller — MCP's `update-tag` tool — with no such prior contract.
+ * 2. The type-conflict check is SKIPPED for any field whose INCOMING spec
+ *    is `indexed: true` (wire review, vault#554): a both-indexed cross-tag
+ *    type conflict already errors on main via `store.upsertTagRecord` →
+ *    `declareField`'s cross-declarer sqlite-type check (`IndexedFieldError`
+ *    → 400 `invalid_indexed_field`), and reporting it here would flip that
+ *    established 400 to a 422. Letting it fall through preserves the 400.
+ *    No case is silently re-accepted by the skip: an incoming-indexed type
+ *    conflict against an INDEXED declarer hits declareField's 400; against
+ *    a NON-indexed declarer the indexed-FLAG conflict below still fires
+ *    (the flags necessarily differ). What this function newly reports —
+ *    both silent 200s on main — is (a) type conflicts on NON-indexed
+ *    incoming fields and (b) indexed-flag conflicts.
+ */
+export function collectCrossTagFieldViolations(
+  db: Database,
+  tag: string,
+  incomingFields: Record<string, TagFieldSchema>,
+): TagFieldViolation[] {
+  const violations: TagFieldViolation[] = [];
+  const otherSchemas = listTagSchemas(db).filter((s) => s.tag !== tag);
+
+  for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    const incomingIndexed = spec.indexed === true;
+    for (const other of otherSchemas) {
+      const otherSpec = other.fields?.[fieldName];
+      if (!otherSpec) continue;
+      // See doc comment exclusion 2: incoming-indexed type conflicts keep
+      // their pre-existing declareField → 400 invalid_indexed_field path.
+      if (!incomingIndexed && otherSpec.type !== spec.type) {
+        violations.push({
+          field: fieldName,
+          reason: "type_conflict",
+          message: `field "${fieldName}" type conflict: tag "${tag}" declares "${spec.type}"; tag "${other.tag}" declares "${otherSpec.type}". Types must agree across all declarers.`,
+          other_tag: other.tag,
+        });
+      }
+      if ((otherSpec.indexed === true) !== incomingIndexed) {
+        violations.push({
+          field: fieldName,
+          reason: "indexed_flag_conflict",
+          message: `field "${fieldName}" indexed-flag conflict: tag "${tag}" sets indexed=${incomingIndexed}; tag "${other.tag}" sets indexed=${otherSpec.indexed === true}. Must match across all declarers — change them atomically or not at all.`,
+          other_tag: other.tag,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Full field-violation collection: {@link collectCrossTagFieldViolations}
+ * PLUS the own-field checks (unsupported type for indexing, invalid
+ * identifier). Used by the MCP `update-tag` tool, which — unlike REST — had
+ * no prior single-violation status-code contract to preserve for those two
+ * checks (its old inline loop threw an unstructured `Error` for them, same
+ * as everything else pre-#554); collecting everything here is a strict
+ * improvement. See {@link collectCrossTagFieldViolations}'s doc comment for
+ * why REST calls that narrower function directly instead of this one.
+ */
+export function collectTagFieldViolations(
+  db: Database,
+  tag: string,
+  incomingFields: Record<string, TagFieldSchema>,
+): TagFieldViolation[] {
+  const violations = collectCrossTagFieldViolations(db, tag, incomingFields);
+
+  for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    if (spec.indexed === true) {
+      const mapped = mapFieldType(spec.type);
+      if (!mapped) {
+        violations.push({
+          field: fieldName,
+          reason: "unsupported_indexed_type",
+          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+        });
+      } else {
+        try {
+          validateFieldName(fieldName);
+        } catch (err) {
+          violations.push({
+            field: fieldName,
+            reason: "invalid_field_name",
+            message: (err as Error).message,
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}

package/package.json

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

package/src/contract-errors.test.ts

@@ -4,15 +4,16 @@
  * 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.
+ * `precondition_required`, `schema_validation`). The Wave 4 (#554) error
+ * taxonomy sweep flipped the original `test.todo` entries into real
+ * assertions below — see that describe block.
  */
 
-import { describe, it, test, expect, beforeEach, afterEach } from "bun:test";
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { BunStore } from "./vault-store.ts";
-import { handleNotes } from "./routes.ts";
+import { handleNotes, handleTags } from "./routes.ts";
+import { generateMcpTools, PreconditionRequiredError } from "../core/src/mcp.ts";
 
 let db: Database;
 let store: BunStore;
@@ -52,6 +53,7 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     const body: any = await res.json();
     expect(body.error_type).toBe("path_conflict");
     expect(body.path).toBe("taken");
+    expect(typeof body.hint).toBe("string");
   });
 
   it("updating with a stale if_updated_at returns 409 conflict carrying current_updated_at + your_updated_at", async () => {
@@ -62,6 +64,7 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     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");
+    expect(typeof body.hint).toBe("string");
   });
 
   it("a strict schema violation on write returns 422 schema_validation naming every violation", async () => {
@@ -76,6 +79,7 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     expect(body.violations.length).toBeGreaterThan(0);
     expect(body.violations[0].field).toBe("status");
     expect(body.violations[0].reason).toBe("enum_mismatch");
+    expect(typeof body.hint).toBe("string");
   });
 
   it("updating a note without if_updated_at or force returns 428 precondition_required", async () => {
@@ -85,14 +89,176 @@ describe("contract: error taxonomy — passing (lock in existing structured prec
     const body: any = await res.json();
     expect(body.error_type).toBe("precondition_required");
     expect(body.note_id).toBe(note.id);
+    expect(typeof body.hint).toBe("string");
   });
 });
 
-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",
-  );
+describe("contract: error taxonomy — #554 (flipped from todo)", () => {
+  it("every error response on the PATCH content_edit branch carries a structured {error_type, hint} pair — previously bare {error, message} strings with no error_type at all", async () => {
+    const note = await store.createNote("the quick brown fox jumps over the fox", { id: "n1" });
+
+    // mutually_exclusive — content + append in the same call.
+    const mutEx = await patch(note.id, { content: "x", append: "y", force: true });
+    expect(mutEx.status).toBe(400);
+    const mutExBody: any = await mutEx.json();
+    expect(mutExBody.error_type).toBe("mutually_exclusive");
+    expect(typeof mutExBody.hint).toBe("string");
+
+    // invalid_content_edit — content_edit missing new_text.
+    const badShape = await patch(note.id, { content_edit: { old_text: "fox" }, force: true });
+    expect(badShape.status).toBe(400);
+    const badShapeBody: any = await badShape.json();
+    expect(badShapeBody.error_type).toBe("invalid_content_edit");
+    expect(badShapeBody.field).toBe("content_edit");
+    expect(typeof badShapeBody.hint).toBe("string");
+
+    // content_edit_not_found — old_text absent from the note's content.
+    const notFound = await patch(note.id, {
+      content_edit: { old_text: "giraffe", new_text: "zebra" },
+      force: true,
+    });
+    expect(notFound.status).toBe(422);
+    const notFoundBody: any = await notFound.json();
+    expect(notFoundBody.error_type).toBe("content_edit_not_found");
+    expect(notFoundBody.field).toBe("content_edit.old_text");
+    expect(typeof notFoundBody.hint).toBe("string");
+
+    // content_edit_ambiguous — old_text ("fox") matches twice in the seed content.
+    const ambiguous = await patch(note.id, {
+      content_edit: { old_text: "fox", new_text: "wolf" },
+      force: true,
+    });
+    expect(ambiguous.status).toBe(409);
+    const ambiguousBody: any = await ambiguous.json();
+    expect(ambiguousBody.error_type).toBe("content_edit_ambiguous");
+    expect(ambiguousBody.field).toBe("content_edit.old_text");
+    expect(typeof ambiguousBody.hint).toBe("string");
+
+    // invalid_state_transition — state_transition.field is an empty string.
+    const badTransition = await patch(note.id, { state_transition: { field: "", from: "a", to: "b" } });
+    expect(badTransition.status).toBe(400);
+    const badTransitionBody: any = await badTransition.json();
+    expect(badTransitionBody.error_type).toBe("invalid_state_transition");
+    expect(badTransitionBody.field).toBe("state_transition.field");
+    expect(typeof badTransitionBody.hint).toBe("string");
+  });
+
+  it("batch update-note honors a top-level `force` applied per-item as a DEFAULT, and an item's own value still wins", async () => {
+    const a = await store.createNote("a", { id: "a1" });
+    const b = await store.createNote("b", { id: "b1" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    // Top-level force:true, item omits its own force/if_updated_at — the
+    // default applies and the write succeeds instead of throwing
+    // precondition_required. Before the fix, `items = batch ?? [params]`
+    // never merged the top-level field in, so this ALWAYS threw.
+    const result: any = await updateNote.execute({
+      force: true,
+      notes: [{ id: a.id, content: "a-updated" }],
+    });
+    expect(result[0].content).toBe("a-updated");
+
+    // Item-level values still win over the top-level default: this item
+    // explicitly sets `force: false` (overriding the batch default) and
+    // supplies no `if_updated_at` of its own, so the precondition gate
+    // still fires for it.
+    let caught: unknown;
+    try {
+      await updateNote.execute({
+        force: true,
+        notes: [{ id: b.id, content: "b-updated", force: false }],
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PreconditionRequiredError);
+  });
+
+  it("REST PUT /api/tags/:name reports ALL cross-tag field violations in one call and states no changes were applied (#553 messaging, mirrors the MCP tool)", async () => {
+    // Tag "a" declares two fields; tag "b" redeclares BOTH with conflicting
+    // specs in the SAME PUT — a NON-indexed type conflict on "x" and an
+    // indexed-flag conflict on "y" (both were silent 200s on main; the
+    // both-indexed type-conflict case deliberately keeps its pre-existing
+    // 400 path — see the regression test below). Before this fix REST had
+    // no cross-tag pre-check at all here (a gap distinct from the MCP
+    // tool's old first-field-only throw); now both surfaces report
+    // identically.
+    await store.upsertTagRecord("a", {
+      fields: {
+        x: { type: "string" },
+        y: { type: "boolean", indexed: true },
+      },
+    });
+
+    const req = new Request("http://localhost/api/tags/b", {
+      method: "PUT",
+      body: JSON.stringify({
+        fields: {
+          x: { type: "integer" },
+          y: { type: "boolean", indexed: false },
+        },
+      }),
+    });
+    const res = await handleTags(req, store, "/b");
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("tag_field_conflict");
+    expect(body.violations).toHaveLength(2);
+    const byField = new Map(body.violations.map((v: any) => [v.field, v.reason]));
+    expect(byField.get("x")).toBe("type_conflict");
+    expect(byField.get("y")).toBe("indexed_flag_conflict");
+    expect(body.message).toContain("no changes were applied");
+    // Full detail for an unscoped caller — the conflicting declarer is named.
+    expect(body.violations[0].other_tag).toBe("a");
+
+    // Nothing partially landed.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+
+  it("REST PUT /api/tags/:name still returns 400 invalid_indexed_field for a solo bad field name (vault#478 contract unchanged)", async () => {
+    // No cross-tag conflict here — "meeting-type" is invalid on its OWN
+    // (kebab-case). This must stay on the pre-existing 400/invalid_indexed_field
+    // path, NOT the new 422/tag_field_conflict path — the cross-tag pre-check
+    // is deliberately scoped to type/indexed-flag agreement only (see
+    // `collectCrossTagFieldViolations`'s doc comment in core/src/tag-schemas.ts).
+    const req = new Request("http://localhost/api/tags/meeting", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { "meeting-type": { type: "string", indexed: true } } }),
+    });
+    const res = await handleTags(req, store, "/meeting");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_indexed_field");
+  });
+
+  it("REST PUT /api/tags/:name: a BOTH-INDEXED cross-tag type conflict stays 400 invalid_indexed_field, NOT 422 (wire-contract floor — pre-existing declareField behavior)", async () => {
+    // Exact regression from the wire review: tag "a" declares x
+    // string+indexed; tag "b" PUTs x integer+indexed. On main this
+    // returned 400 invalid_indexed_field (declareField's cross-declarer
+    // sqlite-type check inside store.upsertTagRecord); the vault#554
+    // pre-check must NOT intercept it as a 422 — statuses/error_types on
+    // previously-working calls are wire contract. See
+    // `collectCrossTagFieldViolations`'s doc-comment exclusion 2.
+    await store.upsertTagRecord("a", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+
+    const req = new Request("http://localhost/api/tags/b", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer", indexed: true } } }),
+    });
+    const res = await handleTags(req, store, "/b");
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_indexed_field");
+    // Unscoped caller: declareField's full message (naming the declarer)
+    // is preserved verbatim.
+    expect(body.error).toContain("tag(s) [a]");
+
+    // Nothing persisted — the store's transaction rolled back.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
 });

package/src/mcp-http.ts

@@ -139,13 +139,18 @@ async function handleMcp(
         content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
       };
     } catch (err) {
-      // Domain errors from the core tools (conflict, missing precondition) get
-      // surfaced as JSON-RPC errors with a structured `data` field so an
-      // agent can key off `data.error_type` and the concurrency tokens.
-      // Everything else falls through to an in-band tool error with
-      // `isError: true` — legible but unstructured.
+      // Domain errors from the core tools (conflict, missing precondition,
+      // path collisions, batch caps, cursor/query validation, tag-field
+      // conflicts, ...) get surfaced as JSON-RPC errors with a structured
+      // `data` field so an agent can key off `data.error_type` and any
+      // error-specific fields (concurrency tokens, violations, candidates,
+      // ...). vault#554: every domain error class is mapped below, either by
+      // a dedicated branch (full field fidelity) or the generic `error_type`
+      // catch-all near the end. Only a TRULY unknown error (no `error_type`
+      // anywhere on it) falls through to the in-band `isError: true` text.
       const message = err instanceof Error ? err.message : "Unknown error";
       const e = err as {
+        name?: string;
         code?: string;
         note_id?: string;
         note_path?: string | null;
@@ -159,6 +164,12 @@ async function handleMcp(
         error_type?: string;
         got?: unknown;
         hint?: string;
+        path?: string;
+        candidates?: unknown;
+        extension?: string;
+        reason?: string;
+        limit?: number;
+        tag?: string;
       };
       // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
       // values that are structurally invalid rather than merely "no
@@ -196,6 +207,7 @@ async function handleMcp(
           your_updated_at: e.expected_updated_at,
           path: e.note_path ?? null,
           note_id: e.note_id,
+          hint: "re-read the note (query-notes) and re-apply your change against its current updated_at, or pass force: true to overwrite",
         });
       }
       // State-transition compare-and-set conflict (vault#299 Part B) — a
@@ -210,6 +222,7 @@ async function handleMcp(
           expected_from: e.expected_from,
           to: e.to,
           current: e.current ?? null,
+          hint: "re-read the note's current value for this field and retry the transition from its actual current state",
         });
       }
       // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
@@ -218,6 +231,7 @@ async function handleMcp(
         throw new McpError(ErrorCode.InvalidParams, message, {
           error_type: "schema_validation",
           violations: e.violations ?? [],
+          hint: "fix every field listed in violations and retry — none of this write was applied",
         });
       }
       if (e?.code === "PRECONDITION_REQUIRED") {
@@ -225,6 +239,96 @@ async function handleMcp(
           error_type: "precondition_required",
           note_id: e.note_id,
           path: e.note_path ?? null,
+          hint: "re-read the note, pass its updated_at as if_updated_at, or pass force: true to skip the check",
+        });
+      }
+      // Any other QueryError (vault#554) — FIELD_NOT_INDEXED, UNKNOWN_OPERATOR,
+      // INVALID_OPERATOR_VALUE, and the various cursor/near/search
+      // incompatibility throws that predate the vault#550/#551 `error_type`
+      // convention (which is why they weren't caught by the two branches
+      // above). Falls back to `error_type: "invalid_query"` — the umbrella
+      // REST already uses for this whole error class — so these no longer
+      // fall through to the unstructured `isError: true` text.
+      if (e?.name === "QueryError") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: e.error_type ?? "invalid_query",
+          code: e.code,
+          field: e.field,
+          got: e.got,
+          hint: e.hint,
+        });
+      }
+      // Malformed / stale opaque cursor (vault#313, vault#554) — was
+      // entirely unmapped here before (REST already returns `{error, code}`
+      // — no `error_type` either; both surfaces get one now). `code` is
+      // already the exact `error_type` vocabulary: "cursor_invalid" or
+      // "cursor_query_mismatch".
+      if (e?.name === "CursorError" && typeof e.code === "string") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: e.code,
+        });
+      }
+      // Path-rename/create collision (vault#126, vault#554) — schema's
+      // UNIQUE(path) tripped. Mirrors REST's 409 `path_conflict` shape.
+      if (e?.code === "PATH_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "path_conflict",
+          path: e.path,
+        });
+      }
+      // A path lookup matched more than one note (vault#330 S1, vault#554) —
+      // mirrors REST's 409 `ambiguous_path` shape (candidates = the
+      // disambiguating extensions).
+      if (e?.code === "AMBIGUOUS_PATH") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "ambiguous_path",
+          path: e.path,
+          candidates: e.candidates,
+        });
+      }
+      // Bad `extension` value (vault#328, vault#554) — mirrors REST's 400
+      // `invalid_extension` shape.
+      if (e?.code === "INVALID_EXTENSION") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "invalid_extension",
+          extension: e.extension,
+          reason: e.reason,
+        });
+      }
+      // Batch cap exceeded (#213, vault#554) — mirrors REST's 413
+      // `batch_too_large` shape.
+      if (e?.code === "BATCH_TOO_LARGE") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "batch_too_large",
+          limit: e.limit,
+          got: e.got,
+        });
+      }
+      // update-tag cross-tag field conflicts (vault#553/#554) — carries
+      // EVERY violation in one response (see `TagFieldConflictError`).
+      if (e?.code === "TAG_FIELD_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "tag_field_conflict",
+          tag: e.tag,
+          violations: e.violations ?? [],
+        });
+      }
+      // Generic catch-all (vault#554): any remaining error that carries a
+      // stable `error_type` — either a domain error class that stamps it as
+      // an instance property (IndexedFieldError, and the classes handled by
+      // dedicated branches above as defense-in-depth) or a validation leaf
+      // built with `structuredError()` in core/src/mcp.ts (mutually_exclusive,
+      // invalid_content_edit, content_edit_not_found, content_edit_ambiguous,
+      // invalid_state_transition, invalid_parent_names, invalid_relationships,
+      // not_found, ...). This is the backstop that makes "nothing falls
+      // through to the unstructured isError text except a TRULY unknown
+      // error" true by construction: only errors nobody tagged with
+      // `error_type` still hit the fallback below.
+      if (typeof e?.error_type === "string") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: e.error_type,
+          field: e.field,
+          hint: e.hint,
         });
       }
       return {

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

@@ -151,4 +151,40 @@ describe("MCP list-tags single-tag path — tag-scope enforcement (vault#550 fol
     expect(names).toContain("health");
     expect(names).not.toContain("work");
   });
+
+  // vault#554 carry-forward: the wrapper's SECOND scrub branch (the one
+  // AFTER the early out-of-scope short-circuit above) fires when the queried
+  // tag itself IS in the allowlist but core still reports tag_not_found —
+  // the hollow-tag case (vault#550: no identity row, no notes directly
+  // carrying it) reached ONLY via a child's `parent_names`. Core computes
+  // `did_you_mean` vault-wide (scope-unaware by architecture), so it can
+  // name an out-of-scope tag; the wrapper must strip that suggestion even
+  // though the queried tag itself passed the allowlist gate. This branch was
+  // execution-verified in a prior review; this test commits it.
+  test("scoped token + in-scope HOLLOW tag (reachable only via a child's parent_names) scrubs an out-of-scope did_you_mean", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+
+    // "health" itself has NO identity row and NO note directly carrying it —
+    // it's in the allowlist expansion ONLY because "kale" declares it as a
+    // parent. "kale" is deliberately NOT lexically close to "health" (the
+    // mission's "non-close child") so it can't win did_you_mean and mask
+    // the bug this test targets.
+    await store.upsertTagRecord("kale", { parent_names: ["health"] });
+    await store.createNote("k", { tags: ["kale"] });
+
+    // Out-of-scope decoy, lexically close to "health" (prefix match) — this
+    // is what core's vault-wide suggestSimilarTag would pick if nothing
+    // scrubbed it.
+    await store.createNote("hy", { tags: ["healthy"] });
+
+    const tool = await listTagsTool("journal", ["health"]);
+    const result = (await tool.execute({ tag: "health" })) as any;
+
+    expect(result.error_type).toBe("tag_not_found");
+    expect(result.tag).toBe("health");
+    // The scrub: did_you_mean must NOT leak the out-of-scope "healthy",
+    // even though "health" (the query) itself passed the allowlist gate.
+    expect(result.did_you_mean).toBeUndefined();
+  });
 });