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

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

@@ -22,6 +22,7 @@ import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { TransitionConflictError } from "./notes.js";
+import { TagFieldConflictError } from "./tag-schemas.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -97,10 +98,98 @@ describe("contract: typed indexes — todo (#553)", () => {
   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)`,
   );
 });
+
+describe("contract: update-tag messaging — #553/#554 (flipped from todo)", () => {
+  it("update-tag reports ALL invalid fields in one call (not just the first) and states explicitly that no changes were applied", async () => {
+    // Tag "a" declares two fields. Tag "b" then redeclares BOTH with
+    // conflicting specs — a NON-indexed type conflict on "x" AND an
+    // indexed-flag conflict on "y" — in the SAME update-tag call. Pre-#553
+    // the cross-tag validation loop threw on the first offending field
+    // ("x") and never even evaluated "y"; two testers independently assumed
+    // the whole call (including "y") had partially landed. (The
+    // BOTH-indexed type-conflict case is deliberately absent here — it
+    // keeps its pre-existing declareField → IndexedFieldError path; see
+    // `collectCrossTagFieldViolations`'s doc-comment exclusion 2 and the
+    // both-indexed test below.)
+    await store.upsertTagRecord("a", {
+      fields: {
+        x: { type: "string" },
+        y: { type: "boolean", indexed: true },
+      },
+    });
+
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    let caught: unknown;
+    try {
+      await updateTag.execute({
+        tag: "b",
+        fields: {
+          x: { type: "integer" }, // non-indexed type_conflict vs tag "a"
+          y: { type: "boolean", indexed: false }, // indexed_flag_conflict vs tag "a"
+        },
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(2);
+    const byField = new Map(err.violations.map((v) => [v.field, v.reason]));
+    expect(byField.get("x")).toBe("type_conflict");
+    expect(byField.get("y")).toBe("indexed_flag_conflict");
+    // States explicitly that no changes were applied.
+    expect(err.message).toContain("no changes were applied");
+    // Structured conflicting-declarer field (scrubbed by the server layer
+    // for tag-scoped sessions; full detail here — core is scope-unaware).
+    expect(err.violations[0]!.other_tag).toBe("a");
+
+    // Nothing partially landed — tag "b" has no field declarations at all.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+
+  it("a BOTH-indexed cross-tag type conflict keeps its pre-existing IndexedFieldError path (not TagFieldConflictError)", async () => {
+    // Wire-contract floor (vault#554): this exact case already errored on
+    // main via store.upsertTagRecord → declareField's cross-declarer
+    // sqlite-type check → IndexedFieldError (REST maps it to 400
+    // invalid_indexed_field). The new pre-check must not intercept it.
+    await store.upsertTagRecord("a", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    let caught: any;
+    try {
+      await updateTag.execute({
+        tag: "b",
+        fields: { x: { type: "integer", indexed: true } },
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught).not.toBeInstanceOf(TagFieldConflictError);
+    expect(caught.name).toBe("IndexedFieldError");
+    expect(caught.error_type).toBe("invalid_indexed_field");
+    // The structured declarer context the server's tag-scope scrub keys on.
+    expect(caught.field).toBe("x");
+    expect(caught.declarer_tags).toEqual(["a"]);
+
+    // The store's transaction rolled back — nothing persisted for "b".
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+  // REST `PUT /api/tags/:name` coverage for the same behavior lives in
+  // src/contract-errors.test.ts (core/ shouldn't import from src/ — that
+  // boundary runs one direction only).
+});

package/core/src/indexed-fields.test.ts

@@ -14,6 +14,7 @@ import {
   validateFieldName,
 } from "./indexed-fields.js";
 import { buildVaultProjection } from "./vault-projection.js";
+import { TagFieldConflictError } from "./tag-schemas.js";
 
 let db: Database;
 let store: SqliteStore;
@@ -186,9 +187,17 @@ describe("update-tag: indexed flag", () => {
   it("type conflict across declarers throws and names the other tag", async () => {
     const t = findTool("update-tag");
     await t.execute({ tag: "project", fields: { status: { type: "string", indexed: true } } });
+    // vault#554 wire review: a BOTH-indexed cross-tag type conflict is
+    // deliberately excluded from the update-tag pre-check (see
+    // `collectCrossTagFieldViolations` doc-comment exclusion 2) so it keeps
+    // its pre-existing declareField → IndexedFieldError path — REST maps
+    // that to the established 400 invalid_indexed_field. The declarer is
+    // still named (declareField's message shape), which is this test's
+    // intent; the pre-#554 inline-loop wording (`tag "project" declares
+    // "string"`) is gone along with the loop.
     expect(() =>
       t.execute({ tag: "ticket", fields: { status: { type: "integer", indexed: true } } }),
-    ).toThrow(/tag "project".*"string"/);
+    ).toThrow(/declared by tag\(s\) \[project\]/);
   });
 
   it("indexed-flag conflict across declarers throws", async () => {
@@ -209,12 +218,28 @@ describe("update-tag: indexed flag", () => {
   });
 
   it("invalid field name for indexing throws", async () => {
-    expect(() =>
-      findTool("update-tag").execute({
+    // vault#553/#554: update-tag's cross-tag field validation now collects
+    // EVERY violation into one `TagFieldConflictError` (carrying a
+    // `violations` array) instead of throwing the first `IndexedFieldError`
+    // it hits — see core/src/tag-schemas.ts `collectTagFieldViolations`.
+    // The underlying reason ("invalid_field_name") and message text are
+    // unchanged; only the thrown class + the "collect everything" framing
+    // are new.
+    let caught: unknown;
+    try {
+      await findTool("update-tag").execute({
         tag: "project",
         fields: { "bad-name": { type: "string", indexed: true } },
-      }),
-    ).toThrow(IndexedFieldError);
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(1);
+    expect(err.violations[0]!.field).toBe("bad-name");
+    expect(err.violations[0]!.reason).toBe("invalid_field_name");
+    expect(err.message).toContain("no changes were applied");
   });
 
   it("rejects non-atomic indexed-flag change while other declarers hold it true", async () => {

package/core/src/indexed-fields.ts

@@ -45,6 +45,22 @@ interface IndexedFieldRow {
 
 export class IndexedFieldError extends Error {
   override name = "IndexedFieldError";
+  // Stable error_type (vault#554) — additive; matches the string REST has
+  // hardcoded in its json response since vault#478. Lets the generic MCP
+  // domain-error mapping (src/mcp-http.ts) pick this class up.
+  error_type = "invalid_indexed_field" as const;
+  /**
+   * Structured context for the CROSS-DECLARER sqlite-type conflict thrown
+   * by `declareField` (vault#554 auth-and-scope fold): the message names
+   * the other declarer tag(s), which a tag-scoped caller must not learn
+   * when they're outside its allowlist. `declarer_tags` lets the server
+   * layer (`scrubIndexedFieldConflictError` in src/tag-scope.ts) detect
+   * that case and generalize the message. Absent on the solo own-field
+   * throws (invalid name, unsupported type), whose messages name no other
+   * tag.
+   */
+  field?: string;
+  declarer_tags?: string[];
 }
 
 // Restrict field names to safe SQL identifiers. This also bounds the
@@ -172,8 +188,14 @@ export function declareField(
   if (existing.sqliteType !== sqliteType) {
     const others = existing.declarerTags.filter((t) => t !== tag);
     if (others.length > 0) {
-      throw new IndexedFieldError(
-        `field "${field}" is declared by tag(s) [${others.join(", ")}] with sqlite type ${existing.sqliteType}; tag "${tag}" requested ${sqliteType}`,
+      // `field` + `declarer_tags` stamped so the server's tag-scope layer
+      // can generalize this message when a declarer is outside a scoped
+      // caller's allowlist (see IndexedFieldError's doc comment).
+      throw Object.assign(
+        new IndexedFieldError(
+          `field "${field}" is declared by tag(s) [${others.join(", ")}] with sqlite type ${existing.sqliteType}; tag "${tag}" requested ${sqliteType}`,
+        ),
+        { field, declarer_tags: others },
       );
     }
     dropColumnAndIndex(db, field);

package/core/src/mcp.ts

@@ -5,11 +5,11 @@ 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, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
-import { collectUnknownTagWarnings, type QueryWarning } from "./query-warnings.js";
+import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "./query-warnings.js";
+import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
-import * as indexedFieldOps from "./indexed-fields.js";
 import {
   SchemaValidationError,
   strictViolations,
@@ -52,6 +52,22 @@ export interface McpToolDef {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a plain `Error` carrying a stable `error_type` (+ optional `field`/
+ * `hint`) as duck-typed extra properties — the same pattern `QueryError`
+ * uses for its optional structured fields. For validation leaves that don't
+ * warrant a dedicated exported class (one caller-facing shape, not a reusable
+ * domain error), this is what lets the generic domain-error mapping in
+ * `src/mcp-http.ts` surface `data.error_type` instead of falling through to
+ * the unstructured `isError: true` text fallback (vault#554).
+ */
+function structuredError(
+  message: string,
+  fields: { error_type: string; field?: string; hint?: string },
+): Error {
+  return Object.assign(new Error(message), fields);
+}
+
 /**
  * Resolve a note identifier — tries ID first, then case-insensitive
  * path match. Works everywhere a note reference is accepted.
@@ -85,7 +101,9 @@ function resolveNote(db: Database, idOrPath: string): Note | null {
 
 function requireNote(db: Database, idOrPath: string): Note {
   const note = resolveNote(db, idOrPath);
-  if (!note) throw new Error(`Note not found: "${idOrPath}"`);
+  if (!note) {
+    throw structuredError(`Note not found: "${idOrPath}"`, { error_type: "not_found", field: "id" });
+  }
   return note;
 }
 
@@ -243,7 +261,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 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.`,
+- 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.
+
+\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -297,7 +317,17 @@ Response shape (vault#550 — three variants, pick by what you passed):
             ],
             description: "Filter by file extension (vault#328). Pass a single extension (e.g. \"csv\") or an array (e.g. [\"csv\", \"yaml\", \"json\"]). Notes default to \"md\"; case-insensitive match.",
           },
-          search: { type: "string", description: "Full-text search query" },
+          search: {
+            type: "string",
+            description:
+              'Full-text search query. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking.',
+          },
+          search_mode: {
+            type: "string",
+            enum: [...SEARCH_MODES],
+            description:
+              'How `search` text is turned into an FTS5 query (vault#551). "literal" (DEFAULT): escape + phrase-quote the text so punctuation is literal content, not FTS5 syntax — the fix for `search: "didn\'t"` / "eleven-day" / "18.6" silently returning `[]`. "advanced": pass the text through to FTS5 raw, for callers who want boolean (AND/OR/NOT), manual phrase quoting, or prefix (`*`) syntax — a malformed advanced query throws a structured error (`error_type: "invalid_search_syntax"`) instead of silently returning `[]`. Has no effect without `search` (an `ignored_param` warning fires if you pass it without `search`). Omit for the default ("literal").',
+          },
           metadata: {
             type: "object",
             description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
@@ -328,7 +358,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
             required: ["note_id"],
             description: "Scope results to notes within N hops of an anchor note",
           },
-          sort: { type: "string", enum: ["asc", "desc"], description: "Sort by created_at" },
+          sort: {
+            type: "string",
+            enum: ["asc", "desc"],
+            description:
+              'Sort by created_at. Under a structured query this is the only ordering (default "asc"). Under `search` (vault#551): omit for FTS5 relevance ranking (default, unchanged) — pass "asc"/"desc" to EXPLICITLY switch to created_at ordering instead of relevance.',
+          },
           limit: { type: "number", description: "Max results (default 50)" },
           offset: { type: "number", description: "Pagination offset (default 0)" },
           cursor: {
@@ -405,7 +440,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // --- Single note by ID/path ---
         if (params.id) {
           const note = resolveNote(db, params.id as string);
-          if (!note) return { error: "Note not found", id: params.id };
+          if (!note) return { error: "Note not found", error_type: "not_found", id: params.id };
           const includeContent = params.include_content !== false; // default true for single
           // Range params are meaningless on a content-less shape — error
           // rather than silently ignore (same loud-validation policy as
@@ -453,7 +488,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
           const anchor = resolveNote(db, near.note_id);
-          if (!anchor) return { error: "Anchor note not found", note_id: near.note_id };
+          if (!anchor) return { error: "Anchor note not found", error_type: "not_found", note_id: near.note_id };
           const depth = Math.min(near.depth ?? 2, 5);
           const traversed = linkOps.traverseLinks(db, anchor.id, {
             max_depth: depth,
@@ -502,13 +537,37 @@ Response shape (vault#550 — three variants, pick by what you passed):
           expand = params.expand as TagExpandMode;
         }
 
+        // `search_mode` (vault#551) — validate loudly (same policy as
+        // `expand` above) so a typo'd value doesn't silently fall back to
+        // the default. Resolved here (before the search/structured branch)
+        // because BOTH branches need to know whether it was passed: the
+        // search branch to select escaping behavior, the structured branch
+        // to warn that it's being ignored.
+        let searchMode: SearchMode | undefined;
+        if (params.search_mode !== undefined && params.search_mode !== null) {
+          if (typeof params.search_mode !== "string" || !isValidSearchMode(params.search_mode)) {
+            throw new QueryError(
+              `invalid \`search_mode\` value ${JSON.stringify(params.search_mode)} — must be one of ${SEARCH_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("literal").`,
+              "INVALID_QUERY",
+              {
+                error_type: "invalid_query",
+                field: "search_mode",
+                got: params.search_mode,
+                hint: `pass "literal" or "advanced", or omit for the default ("literal")`,
+              },
+            );
+          }
+          searchMode = params.search_mode;
+        }
+
         // --- 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
+        // Warnings channel (vault#550). `search=` warnings (`empty_search`,
+        // `ignored_param` for a stray `search_mode`) joined the channel at
+        // #551 — the rest (`unknown_tag`) stays structured-query only.
+        // 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`.
@@ -516,18 +575,47 @@ Response shape (vault#550 — three variants, pick by what you passed):
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
-          // Route through `store.searchNotes` (not `noteOps.searchNotes`) so
-          // tag-hierarchy expansion fires for MCP callers the same as for
-          // HTTP REST callers — `tag: "manual"` matches descendants declared
-          // via `_tags/*` config notes. Mirrors the structured-query fix
-          // from #214; same class of bypass bug (tracked as #227).
-          results = await store.searchNotes(params.search as string, {
-            tags,
-            limit: (params.limit as number) ?? 50,
-            expand,
-          });
+          const mode: SearchMode = searchMode ?? "literal";
+          // "Only whitespace/quotes" (vault#551 edge case): short-circuit
+          // BEFORE ever calling FTS5 — an empty/all-punctuation phrase can
+          // be a syntax error (or a meaningless always-empty query)
+          // depending on exactly how it degenerates, so this is checked
+          // here rather than left to the DB layer to (maybe) reject.
+          if (mode === "literal" && buildLiteralSearchQuery(params.search as string).isEmpty) {
+            results = [];
+            queryWarnings.push(emptySearchWarning());
+          } else {
+            // Route through `store.searchNotes` (not `noteOps.searchNotes`) so
+            // tag-hierarchy expansion fires for MCP callers the same as for
+            // HTTP REST callers — `tag: "manual"` matches descendants declared
+            // via `_tags/*` config notes. Mirrors the structured-query fix
+            // from #214; same class of bypass bug (tracked as #227). A
+            // malformed advanced-mode query throws here (structured
+            // `invalid_search_syntax`, vault#551) — uncaught on purpose, it
+            // propagates to `src/mcp-http.ts`, which maps it to a JSON-RPC
+            // error the same way it maps `invalid_query`.
+            results = await store.searchNotes(params.search as string, {
+              tags,
+              limit: (params.limit as number) ?? 50,
+              expand,
+              mode,
+              sort: params.sort as "asc" | "desc" | undefined,
+            });
+          }
         } else {
           // --- Structured query ---
+          // `search_mode` only shapes how `search` text becomes an FTS5
+          // query — passing it without `search` is almost always a mistake
+          // (meant to pass `search` too), so flag it rather than silently
+          // doing nothing with it.
+          if (searchMode !== undefined) {
+            queryWarnings.push(
+              ignoredParamWarning(
+                "search_mode",
+                "no `search` was provided — search_mode only affects full-text search query parsing",
+              ),
+            );
+          }
           const tags = normalizeTags(params.tag);
           // Accept canonical `exclude_tags` plus camelCase / singular aliases.
           // LLM callers frequently pick the wrong name (training-data drift
@@ -574,7 +662,12 @@ Response shape (vault#550 — three variants, pick by what you passed):
             offset: params.offset as number | undefined,
             cursor: cursorMode ? (params.cursor as string) : undefined,
           };
-          queryWarnings = collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy());
+          // Concatenate (not overwrite) — `queryWarnings` may already carry
+          // the `ignored_param` warning for a stray `search_mode` pushed
+          // above (vault#551).
+          queryWarnings = queryWarnings.concat(
+            collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy()),
+          );
           if (cursorMode) {
             const page = await store.queryNotesPaged(queryOpts);
             results = page.notes;
@@ -838,7 +931,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - \`links: { add: [{ target, relationship }], remove: [{ target, relationship }] }\` — add/remove links
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - For batch: pass a \`notes\` array, each with an \`id\` field.
-- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
+- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
 - \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
 
@@ -967,7 +1060,23 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       },
       execute: async (params) => {
         const batch = params.notes as any[] | undefined;
-        const items = batch ?? [params];
+        // vault#554: top-level `force` / `if_updated_at` apply as per-item
+        // DEFAULTS in a batch call — item-level values win when both are
+        // present. Before this fix `items = batch ?? [params]` never merged
+        // the top-level fields into batch items at all, so a caller passing
+        // `{force: true, notes: [...]}` had it silently ignored: every item
+        // without its OWN `force`/`if_updated_at` still threw
+        // `PreconditionRequiredError` (a gardener-reported round-trip cost).
+        // The single-item form (`items = [params]`) already behaved this
+        // way implicitly (params IS the item), so only the batch branch
+        // needs the merge.
+        const items = batch
+          ? batch.map((item: any) => ({
+              ...(params.force !== undefined ? { force: params.force } : {}),
+              ...(params.if_updated_at !== undefined ? { if_updated_at: params.if_updated_at } : {}),
+              ...item,
+            }))
+          : [params];
 
         if (items.length > MAX_BATCH_SIZE) {
           throw new BatchTooLargeError(items.length);
@@ -1099,7 +1208,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               // Fallthrough: not-found + no if_missing → existing error
               // contract. Match `requireNote`'s message shape so existing
               // callers see no behavior change.
-              throw new Error(`Note not found: "${item.id}"`);
+              throw structuredError(`Note not found: "${item.id}"`, { error_type: "not_found", field: "id" });
             }
             const note = resolved;
 
@@ -1109,8 +1218,9 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const hasContentEdit = item.content_edit !== undefined;
             const contentModes = (hasContent ? 1 : 0) + (hasAppendPrepend ? 1 : 0) + (hasContentEdit ? 1 : 0);
             if (contentModes > 1) {
-              throw new Error(
+              throw structuredError(
                 `update-note: \`content\`, \`append\`/\`prepend\`, and \`content_edit\` are mutually exclusive — pick one mode of content update for note "${note.id}".`,
+                { error_type: "mutually_exclusive", hint: "pass exactly one of `content`, `append`/`prepend`, or `content_edit`" },
               );
             }
 
@@ -1161,20 +1271,23 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             if (hasContentEdit) {
               const ce = item.content_edit as { old_text: string; new_text: string };
               if (typeof ce?.old_text !== "string" || typeof ce?.new_text !== "string") {
-                throw new Error(
+                throw structuredError(
                   "update-note: `content_edit` requires { old_text: string, new_text: string }.",
+                  { error_type: "invalid_content_edit", field: "content_edit", hint: "pass { old_text: string, new_text: string }" },
                 );
               }
               const idx = note.content.indexOf(ce.old_text);
               if (idx < 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note content_edit: \`old_text\` not found in note "${note.id}". The note may have been edited — re-read and retry.`,
+                  { error_type: "content_edit_not_found", field: "content_edit.old_text", hint: "re-read the note's current content and retry with an old_text that occurs exactly once" },
                 );
               }
               const second = note.content.indexOf(ce.old_text, idx + 1);
               if (second >= 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note content_edit: \`old_text\` matches multiple times in note "${note.id}" — must match exactly once. Add surrounding context to disambiguate.`,
+                  { error_type: "content_edit_ambiguous", field: "content_edit.old_text", hint: "add surrounding context to old_text so it matches exactly once" },
                 );
               }
               contentOverride = note.content.slice(0, idx) + ce.new_text + note.content.slice(idx + ce.old_text.length);
@@ -1239,8 +1352,9 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const stItem = item.state_transition as { field?: unknown; from?: unknown; to?: unknown } | undefined;
             if (stItem !== undefined) {
               if (typeof stItem.field !== "string" || stItem.field.length === 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note: \`state_transition.field\` must be a non-empty string (note "${note.id}").`,
+                  { error_type: "invalid_state_transition", field: "state_transition.field", hint: "pass a non-empty string naming the metadata field to transition" },
                 );
               }
               updates.state_transition = { field: stItem.field, from: stItem.from, to: stItem.to };
@@ -1529,34 +1643,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
-        const otherSchemas = tagSchemaOps
-          .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;
-            if (otherSpec.type !== spec.type) {
-              throw new Error(
-                `field "${fieldName}" type conflict: tag "${tag}" declares "${spec.type}"; tag "${other.tag}" declares "${otherSpec.type}". Types must agree across all declarers.`,
-              );
-            }
-            if ((otherSpec.indexed === true) !== incomingIndexed) {
-              throw new Error(
-                `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.`,
-              );
-            }
-          }
-          if (incomingIndexed) {
-            const mapped = indexedFieldOps.mapFieldType(spec.type);
-            if (!mapped) {
-              throw new Error(
-                `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
-              );
-            }
-            indexedFieldOps.validateFieldName(fieldName);
-          }
+        // vault#553/#554: collects EVERY violation instead of throwing on the
+        // first — a caller declaring two bad fields sees both in one
+        // response, and the thrown error states explicitly that no changes
+        // were applied (nothing is persisted before this check runs).
+        const fieldViolations = tagSchemaOps.collectTagFieldViolations(db, tag, incomingFields);
+        if (fieldViolations.length > 0) {
+          throw new tagSchemaOps.TagFieldConflictError(tag, fieldViolations);
         }
 
         // ---- relationships: replace wholesale when provided. `relationships`
@@ -1579,7 +1672,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           parentNamesPatch = null;
         } else if (params.parent_names !== undefined) {
           if (!Array.isArray(params.parent_names)) {
-            throw new Error("parent_names must be an array of tag names");
+            throw structuredError("parent_names must be an array of tag names", {
+              error_type: "invalid_parent_names",
+              field: "parent_names",
+              hint: "pass an array of tag name strings, or null to clear",
+            });
           }
           const cleaned = (params.parent_names as unknown[])
             .filter((p): p is string => typeof p === "string" && p.length > 0);
@@ -1686,7 +1783,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       execute: () => {
         // This is a placeholder — vault-info needs access to vault config,
         // which is only available in the server layer (mcp-tools.ts).
-        return { error: "vault-info must be configured by the server layer" };
+        return { error: "vault-info must be configured by the server layer", error_type: "not_configured" };
       },
     },
 
@@ -1918,6 +2015,9 @@ export class PreconditionRequiredError extends Error {
  */
 export class BatchTooLargeError extends Error {
   code = "BATCH_TOO_LARGE" as const;
+  // Stable error_type (vault#554) — additive; matches the string REST has
+  // hardcoded in its json response since #213.
+  error_type = "batch_too_large" as const;
   limit: number;
   got: number;