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

package/core/src/notes.ts

@@ -22,6 +22,7 @@ import {
 import { getIndexedField, releaseField } from "./indexed-fields.js";
 import { computeExpandedTagCounts, loadTagHierarchy, stripTagHash } from "./tag-hierarchy.js";
 import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
+import { buildLiteralSearchQuery, type SearchMode } from "./search-query.js";
 
 let idCounter = 0;
 
@@ -283,6 +284,11 @@ export class TransitionConflictError extends Error {
  */
 export class PathConflictError extends Error {
   code = "PATH_CONFLICT" as const;
+  // Stable error_type (vault#554) — additive; mirrors the `error_type` REST
+  // has hardcoded in its json response since #126. Lets the generic MCP
+  // domain-error mapping (src/mcp-http.ts) pick this class up without a
+  // bespoke branch, the same way REST's catch already does explicitly.
+  error_type = "path_conflict" as const;
   path: string;
 
   constructor(path: string) {
@@ -305,6 +311,8 @@ export class PathConflictError extends Error {
  */
 export class AmbiguousPathError extends Error {
   code = "AMBIGUOUS_PATH" as const;
+  // Stable error_type (vault#554) — see PathConflictError's comment.
+  error_type = "ambiguous_path" as const;
   path: string;
   candidates: { id: string; extension: string }[];
 
@@ -345,6 +353,8 @@ export const EXTENSION_PATTERN = /^[a-z0-9]{1,16}$/;
 
 export class ExtensionValidationError extends Error {
   code = "INVALID_EXTENSION" as const;
+  // Stable error_type (vault#554) — see PathConflictError's comment.
+  error_type = "invalid_extension" as const;
   extension: string;
   reason: string;
 
@@ -1309,12 +1319,78 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
   return { notes, next_cursor };
 }
 
+/**
+ * Turn a thrown FTS5 MATCH error into the structured `invalid_search_syntax`
+ * shape (vault#551, WS2A item 2). ALWAYS structured, never a raw rethrow —
+ * a raw `SQLiteError` escaping to the transport is an unstructured 500
+ * (REST) / generic `isError` text (MCP), which is exactly the swallowed-
+ * failure class this wave is closing.
+ *
+ * The two modes carry different hints:
+ *   - advanced: the caller passed raw FTS5 syntax that FTS5 rejected — tell
+ *     them to fix it or drop back to literal.
+ *   - literal: escaping + control-char sanitization
+ *     (`buildLiteralSearchQuery`) make every input syntactically valid
+ *     FTS5, so this is unreachable by construction — the belt-and-suspenders
+ *     structured error (rather than a raw rethrow) means that IF the
+ *     invariant is ever broken it still surfaces as an honest error, not a
+ *     500. Signals a vault bug worth reporting.
+ */
+function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): QueryError {
+  const causeMessage = err instanceof Error ? err.message : String(err);
+  const hint =
+    mode === "advanced"
+      ? `FTS5 rejected this as advanced query syntax (${causeMessage}). Fix the syntax, or omit search_mode:"advanced" for literal (punctuation-safe) search.`
+      : `FTS5 rejected the escaped literal query (${causeMessage}) — this should be impossible after literal-mode escaping + control-char sanitization; please report it as a vault bug.`;
+  return new QueryError(`invalid search syntax: ${causeMessage}`, "INVALID_QUERY", {
+    error_type: "invalid_search_syntax",
+    field: "search",
+    got: rawQuery,
+    hint,
+  });
+}
+
 export function searchNotes(
   db: Database,
   query: string,
-  opts?: { tags?: string[]; limit?: number },
+  opts?: { tags?: string[]; limit?: number; mode?: SearchMode; sort?: "asc" | "desc" },
 ): Note[] {
   const limit = typeof opts?.limit === "number" ? opts.limit : 50;
+  // Literal-by-default (vault#551): escape the caller's text so FTS5's own
+  // query syntax (hyphen = NOT, apostrophe/period = tokenizer breakage,
+  // etc.) is treated as ordinary content, not syntax. `search_mode:
+  // "advanced"` opts back into raw FTS5 query syntax — today's pre-#551
+  // behavior, unchanged — for callers who want boolean/phrase/prefix
+  // operators.
+  const mode: SearchMode = opts?.mode ?? "literal";
+  let ftsQuery: string;
+  if (mode === "literal") {
+    const built = buildLiteralSearchQuery(query);
+    // "Only whitespace/quotes" (vault#551 edge case): the caller (store.ts /
+    // the REST + MCP entry points) is expected to short-circuit this case
+    // itself (with an `empty_search` warning) before ever reaching here —
+    // this is a defensive fallback for any direct-core caller that skips
+    // that check.
+    if (built.isEmpty) return [];
+    ftsQuery = built.query;
+  } else {
+    ftsQuery = query;
+  }
+
+  // `sort` honored under search (vault#551 WS2A item 3): default stays FTS5
+  // relevance (`rank`, unchanged); an EXPLICIT `sort: "asc"|"desc"` switches
+  // to `created_at` ordering. Checked against the literal string values (not
+  // truthiness) so an absent `sort` can never accidentally match a branch.
+  // `n.id ${direction}` is appended as a deterministic tiebreaker — same
+  // rationale as `queryNotes` (two notes at the same created_at millisecond
+  // would otherwise return in arbitrary/unstable order). `rank` needs no
+  // tiebreaker (bm25 score is effectively unique per row).
+  const orderBy =
+    opts?.sort === "asc"
+      ? "n.created_at ASC, n.id ASC"
+      : opts?.sort === "desc"
+        ? "n.created_at DESC, n.id DESC"
+        : "rank";
 
   if (opts?.tags && opts.tags.length > 0) {
     // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
@@ -1334,12 +1410,19 @@ export function searchNotes(
         JOIN notes_fts fts ON fts.rowid = n.rowid
         WHERE notes_fts MATCH ?
           AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
-        ORDER BY rank
+        ORDER BY ${orderBy}
         LIMIT ?
-      `).all(query, ...searchTags, limit) as NoteRow[];
+      `).all(ftsQuery, ...searchTags, limit) as NoteRow[];
       return notesWithTags(db, rows);
-    } catch {
-      return [];
+    } catch (err) {
+      // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
+      // advanced mode expects it (the caller passed raw syntax); literal
+      // mode should never reach it (escaping + control-char sanitization
+      // make the query valid) but if the invariant breaks we still want an
+      // honest error, not an unstructured 500. A QueryError we threw
+      // ourselves (empty-limit validation, etc.) is re-raised untouched.
+      if (err instanceof QueryError) throw err;
+      throw searchSyntaxError(query, err, mode);
     }
     }
   }
@@ -1349,12 +1432,13 @@ export function searchNotes(
       SELECT n.* FROM notes n
       JOIN notes_fts fts ON fts.rowid = n.rowid
       WHERE notes_fts MATCH ?
-      ORDER BY rank
+      ORDER BY ${orderBy}
       LIMIT ?
-    `).all(query, limit) as NoteRow[];
+    `).all(ftsQuery, limit) as NoteRow[];
     return notesWithTags(db, rows);
-  } catch {
-    return [];
+  } catch (err) {
+    if (err instanceof QueryError) throw err;
+    throw searchSyntaxError(query, err, mode);
   }
 }
 

package/core/src/query-warnings.ts

@@ -182,3 +182,38 @@ export function collectUnknownTagWarnings(
   }
   return warnings;
 }
+
+/**
+ * `empty_search` warning (vault#551) — the `search` string carried no
+ * literal content: blank/whitespace-only, or (in literal mode, where a
+ * manually-typed `"` is ordinary content rather than syntax) nothing but
+ * quote characters. Rather than let this degenerate into an FTS5 syntax
+ * error or a confusing always-empty-but-syntactically-valid query, the
+ * search path short-circuits BEFORE ever calling FTS5 and reports this
+ * warning alongside an honest `[]`. See `core/src/search-query.ts`
+ * `buildLiteralSearchQuery`, which is the choke point that detects this.
+ */
+export function emptySearchWarning(): QueryWarning {
+  return {
+    code: "empty_search",
+    message:
+      "the search query has no literal content (blank, or only whitespace/quote characters) — returning no results without querying FTS5.",
+  };
+}
+
+/**
+ * `ignored_param` warning (vault#551) — a query-shaping param was passed
+ * but has no effect given the rest of the request. First (and so far only)
+ * case: `search_mode` without `search` — the mode only shapes how `search`
+ * text is turned into an FTS5 query, so passing it alone almost always
+ * means the caller meant to pass `search` too. Generic over `param` /
+ * `reason` so a future ignored-param case can reuse the same shape instead
+ * of inventing a new warning code.
+ */
+export function ignoredParamWarning(param: string, reason: string): QueryWarning {
+  return {
+    code: "ignored_param",
+    message: `\`${param}\` has no effect: ${reason}`,
+    param,
+  };
+}

package/core/src/search-query.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "bun:test";
+import {
+  SEARCH_MODES,
+  escapeFtsToken,
+  buildLiteralSearchQuery,
+  isValidSearchMode,
+} from "./search-query.js";
+
+describe("escapeFtsToken", () => {
+  it("wraps a plain token in quotes", () => {
+    expect(escapeFtsToken("widgets")).toBe(`"widgets"`);
+  });
+
+  it("doubles an embedded quote", () => {
+    expect(escapeFtsToken(`say"hi`)).toBe(`"say""hi"`);
+  });
+
+  it("doubles multiple embedded quotes", () => {
+    expect(escapeFtsToken(`"eleven-day`)).toBe(`"""eleven-day"`);
+    expect(escapeFtsToken(`delay"`)).toBe(`"delay"""`);
+  });
+
+  it("preserves punctuation that isn't a quote (hyphen, period, apostrophe)", () => {
+    expect(escapeFtsToken("eleven-day")).toBe(`"eleven-day"`);
+    expect(escapeFtsToken("18.6")).toBe(`"18.6"`);
+    expect(escapeFtsToken("didn't")).toBe(`"didn't"`);
+  });
+});
+
+describe("buildLiteralSearchQuery", () => {
+  it("wraps a single token", () => {
+    const r = buildLiteralSearchQuery("widgets");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"widgets"`);
+  });
+
+  it("phrase-quotes each whitespace-delimited token and ANDs them (vault#551 root fix)", () => {
+    const r = buildLiteralSearchQuery("eleven-day capping delay");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"eleven-day" "capping" "delay"`);
+  });
+
+  it("escapes an apostrophe as literal content, not syntax", () => {
+    const r = buildLiteralSearchQuery("didn't");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"didn't"`);
+  });
+
+  it("escapes a decimal point as literal content, not syntax", () => {
+    const r = buildLiteralSearchQuery("18.6");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"18.6"`);
+  });
+
+  it("collapses runs of whitespace between tokens", () => {
+    const r = buildLiteralSearchQuery("widgets    gadgets");
+    expect(r.query).toBe(`"widgets" "gadgets"`);
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    const r = buildLiteralSearchQuery("  widgets  ");
+    expect(r.query).toBe(`"widgets"`);
+  });
+
+  it("escapes a manually-quoted phrase's embedded quote characters as content", () => {
+    // The user typed literal quote marks expecting phrase syntax; in
+    // literal mode those quote characters are just more content that gets
+    // escaped like anything else (vault#551 — this is CORRECT, not a bug:
+    // raw phrase/boolean/prefix syntax now requires search_mode:"advanced").
+    const r = buildLiteralSearchQuery(`"eleven-day capping delay"`);
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"""eleven-day" "capping" "delay"""`);
+  });
+
+  it("treats a blank string as empty", () => {
+    expect(buildLiteralSearchQuery("").isEmpty).toBe(true);
+  });
+
+  it("treats a whitespace-only string as empty", () => {
+    expect(buildLiteralSearchQuery("   ").isEmpty).toBe(true);
+  });
+
+  it("treats a lone quote character as empty", () => {
+    expect(buildLiteralSearchQuery(`"`).isEmpty).toBe(true);
+  });
+
+  it("treats a quotes-and-whitespace-only string as empty", () => {
+    expect(buildLiteralSearchQuery(`"  "  "`).isEmpty).toBe(true);
+  });
+
+  it("an empty-flagged result never carries a query string callers should use", () => {
+    const r = buildLiteralSearchQuery("   ");
+    expect(r.isEmpty).toBe(true);
+    expect(r.query).toBe("");
+  });
+
+  // Control-character sanitization (vault#551 review fold) — a NUL byte
+  // (or any C0/DEL control) inside a token would otherwise crash FTS5's
+  // C-string parser with a raw `unterminated string` error, breaking the
+  // "literal mode cannot throw" guarantee.
+  it("splits a token on an embedded NUL byte — both halves stay searchable", () => {
+    const r = buildLiteralSearchQuery("hello\x00world");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"hello" "world"`);
+  });
+
+  it("treats a NUL-only string as empty (short-circuits, never reaches FTS5)", () => {
+    const r = buildLiteralSearchQuery("\x00");
+    expect(r.isEmpty).toBe(true);
+    expect(r.query).toBe("");
+  });
+
+  it("collapses a run of NUL/control bytes between tokens like whitespace", () => {
+    const r = buildLiteralSearchQuery("hello\x00\x00world");
+    expect(r.query).toBe(`"hello" "world"`);
+  });
+
+  it("sanitizes the other C0 controls and DEL (0x01-0x1F, 0x7F) as separators too", () => {
+    expect(buildLiteralSearchQuery("a\x01\x02b").query).toBe(`"a" "b"`);
+    expect(buildLiteralSearchQuery("a\x1fb").query).toBe(`"a" "b"`);
+    expect(buildLiteralSearchQuery("a\x7fb").query).toBe(`"a" "b"`);
+  });
+
+  it("a control byte adjacent to a real token still yields the clean token", () => {
+    expect(buildLiteralSearchQuery("\x00hello\x00").query).toBe(`"hello"`);
+  });
+});
+
+describe("isValidSearchMode / SEARCH_MODES", () => {
+  it("SEARCH_MODES is exactly literal + advanced", () => {
+    expect(SEARCH_MODES).toEqual(["literal", "advanced"]);
+  });
+
+  it("accepts literal and advanced", () => {
+    expect(isValidSearchMode("literal")).toBe(true);
+    expect(isValidSearchMode("advanced")).toBe(true);
+  });
+
+  it("rejects an unknown string", () => {
+    expect(isValidSearchMode("bogus")).toBe(false);
+  });
+
+  it("rejects non-string values", () => {
+    expect(isValidSearchMode(123)).toBe(false);
+    expect(isValidSearchMode(null)).toBe(false);
+    expect(isValidSearchMode(undefined)).toBe(false);
+    expect(isValidSearchMode(["literal"])).toBe(false);
+  });
+});

package/core/src/store.ts

@@ -34,6 +34,7 @@ import {
   countConformanceViolations,
   type ConformanceReport,
 } from "./conformance.js";
+import type { SearchMode } from "./search-query.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -375,7 +376,7 @@ export class BunSqliteStore implements Store {
     return { ...opts, _tagsExpanded: expanded } as QueryOpts;
   }
 
-  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]> {
+  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]> {
     // Canonical-bare-tag guard (vault#XXX): strip leading `#` from search tag
     // filters before expansion, so `#manual` and `manual` resolve identically.
     if (opts?.tags && opts.tags.length > 0) {

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

@@ -2,6 +2,7 @@ import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 import type { TagExpandMode, TagHierarchy } from "./tag-hierarchy.js";
+import type { SearchMode } from "./search-query.js";
 import type { ValidationStatus } from "./schema-defaults.js";
 import type { ConformanceReport } from "./conformance.js";
 import type { FindPathResult } from "./links.js";
@@ -314,7 +315,18 @@ export interface Store {
    * agent loop can persist a single watermark and keep polling.
    */
   queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
-  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]>;
+  /**
+   * `mode` (vault#551 — literal-by-default): "literal" (default) escapes +
+   * phrase-quotes the query so FTS5 punctuation syntax (hyphen = NOT, an
+   * apostrophe/period breaking the parse, ...) is treated as ordinary
+   * content. "advanced" passes `query` through to FTS5 raw (pre-#551
+   * behavior) for callers who want boolean/phrase/prefix operators — a
+   * syntax error in that mode throws (`error_type: "invalid_search_syntax"`)
+   * rather than silently returning `[]`. `sort` (vault#551): omitted stays
+   * FTS5 relevance ranking (default); an explicit "asc"/"desc" switches to
+   * `created_at` ordering. See `core/src/search-query.ts`.
+   */
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]>;
 
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;

package/package.json

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