@openparachute/vault 0.3.3 → 0.4.3

package/core/src/mcp.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
-import { filterMetadata } from "./notes.js";
+import { filterMetadata, MAX_BATCH_SIZE } from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -68,7 +68,9 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Generate the 9 consolidated MCP tools for a vault.
+ * Generate the consolidated MCP tools for a vault. Post-v17 surface (9):
+ * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
+ * delete-tag, find-path, vault-info.
  */
 export function generateMcpTools(store: Store): McpToolDef[] {
   const db: Database = (store as any).db;
@@ -102,7 +104,31 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Filter by tag(s)",
           },
           tag_match: { type: "string", enum: ["any", "all"], description: "How to match multiple tags: 'any' (OR, default) or 'all' (AND)" },
-          exclude_tags: { type: "array", items: { type: "string" }, description: "Exclude notes with these tags" },
+          exclude_tags: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Exclude notes with these tag(s). Accepts a single tag or an array. Aliases `excludeTags` and `exclude_tag` are also accepted. If multiple alias forms are provided, `exclude_tags` takes precedence (then `excludeTags`, then `exclude_tag`).",
+          },
+          // The runtime alias-fallback chain accepts these too. Declared
+          // here so schema-introspecting clients (Claude, MCP clients
+          // that surface tool schemas) see them as valid inputs rather
+          // than thinking the canonical is the only option.
+          excludeTags: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Alias for `exclude_tags` (camelCase). Same shape and semantics — pick whichever is more natural for your client.",
+          },
+          exclude_tag: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Alias for `exclude_tags` (singular). Same shape and semantics — accepts a single tag or an array.",
+          },
           has_tags: { type: "boolean", description: "Presence filter: true = only notes with at least one tag; false = only untagged notes. Ignored when `tag` is set." },
           has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
@@ -113,8 +139,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             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.",
           },
           order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
-          date_from: { type: "string", description: "Start date (ISO, inclusive)" },
-          date_to: { type: "string", description: "End date (ISO, exclusive)" },
+          date_from: { type: "string", description: "Start date (ISO, inclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', from }`." },
+          date_to: { type: "string", description: "End date (ISO, exclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', to }`." },
+          date_filter: {
+            type: "object",
+            properties: {
+              field: { type: "string", description: "Field to filter on. Defaults to `created_at` (vault ingestion time). `updated_at` is also recognized as a real column — use it for incremental rebuilds (\"what changed since X\"). Any other field must be declared `indexed: true` in a tag schema — same contract as metadata operator queries and `order_by`." },
+              from: { type: "string", description: "Inclusive lower bound (ISO date)." },
+              to: { type: "string", description: "Exclusive upper bound (ISO date)." },
+            },
+            description: "Generalized date-range filter. Use this when the date that matters is the *content* date (e.g. an email's received date, a meeting's scheduled date) rather than the vault ingestion time, or when paging by `updated_at` for incremental rebuilds. Mutually exclusive with the top-level `date_from` / `date_to` shorthand.",
+          },
           near: {
             type: "object",
             properties: {
@@ -198,24 +233,49 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
-          results = noteOps.searchNotes(db, params.search as string, {
+          // 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,
           });
         } else {
           // --- Structured query ---
           const tags = normalizeTags(params.tag);
-          results = noteOps.queryNotes(db, {
+          // Accept canonical `exclude_tags` plus camelCase / singular aliases.
+          // LLM callers frequently pick the wrong name (training-data drift
+          // toward camelCase across MCP tools) and the JSON-RPC layer drops
+          // unknown keys silently; aliasing here closes the silent-no-op gap.
+          const excludeTagsRaw = params.exclude_tags ?? params.excludeTags ?? params.exclude_tag;
+          const excludeTags = normalizeTags(excludeTagsRaw);
+          // Route through `store.queryNotes` (not `noteOps.queryNotes`) so
+          // tag-hierarchy expansion fires for MCP callers the same as for
+          // HTTP REST callers — `tag: "manual"` matches descendants declared
+          // via `_tags/*` config notes. The previous direct-noteOps call
+          // bypassed the wrapper and silently dropped hierarchy expansion.
+          results = await store.queryNotes({
             tags,
             tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
-            excludeTags: params.exclude_tags as string[] | undefined,
+            excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            // Push the near-scope into the SQL WHERE so that LIMIT and ORDER
+            // BY apply to the neighborhood. Without this, queryNotes would
+            // fetch the first `limit` notes by created_at and then post-
+            // filter to the few in-scope ones — which silently empties the
+            // result whenever the neighborhood lies outside that prefix.
+            ids: nearScope ? [...nearScope] : undefined,
             metadata: params.metadata as Record<string, unknown> | undefined,
             dateFrom: params.date_from as string | undefined,
             dateTo: params.date_to as string | undefined,
+            dateFilter: params.date_filter as
+              | { field?: string; from?: string; to?: string }
+              | undefined,
             sort: params.sort as "asc" | "desc" | undefined,
             orderBy: params.order_by as string | undefined,
             limit: (params.limit as number) ?? 50,
@@ -223,8 +283,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           });
         }
 
-        // --- Apply near-scope filter ---
-        if (nearScope) {
+        // For full-text search the post-filter is still the right shape — FTS
+        // owns its own ranked LIMIT and we just narrow to the neighborhood
+        // afterwards. Structured queries already pushed `ids` into SQL above.
+        if (nearScope && params.search) {
           results = results.filter((n) => nearScope!.has(n.id));
         }
 
@@ -315,26 +377,65 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const batch = params.notes as any[] | undefined;
         const items = batch ?? [params];
 
+        if (items.length > MAX_BATCH_SIZE) {
+          throw new BatchTooLargeError(items.length);
+        }
+
+        // Empty-note pre-validation (#213): make mixed batches atomic for
+        // the empty-note case. The Store will throw EmptyNoteError on the
+        // empty entry, but in a sequential batch loop the prefix would have
+        // already committed before we hit it. Pre-walk so the whole call
+        // either creates everything or nothing. The error carries
+        // `item_index` so MCP callers with multi-item batches can pinpoint
+        // the bad entry — parity with the HTTP route's response shape.
+        // TODO: tighten batch input type — `items[i] as any` mirrors the
+        // top-of-call cast at `params.notes as any[]`. A typed McpCreateNoteInput
+        // would let us drop both casts.
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i] as any;
+          const content = ((item?.content as string | undefined) ?? "").toString();
+          const rawPath = item?.path;
+          const pathEmpty = rawPath === undefined || rawPath === null
+            || (typeof rawPath === "string" && rawPath.trim() === "");
+          if (!content.trim() && pathEmpty) {
+            throw new noteOps.EmptyNoteError(null, batch ? i : null);
+          }
+        }
+
         const created: Note[] = [];
-        for (const item of items) {
-          const note = await store.createNote(item.content as string ?? "", {
-            path: item.path as string | undefined,
-            tags: item.tags as string[] | undefined,
-            metadata: item.metadata as Record<string, unknown> | undefined,
-            created_at: item.created_at as string | undefined,
-          });
+        // Wrap multi-item batches in a SQLite transaction so a mid-batch
+        // failure rolls back every prior insert — see #236. The pre-walk
+        // above catches empty-note cases; this guards anything thrown from
+        // store.createNote / createLink (path conflict, etc.). Single-item
+        // calls skip the wrap to avoid colliding with concurrent callers
+        // on the shared bun:sqlite connection.
+        const batched = items.length > 1;
+        if (batched) db.exec("BEGIN");
+        try {
+          for (const item of items) {
+            const note = await store.createNote(item.content as string ?? "", {
+              path: item.path as string | undefined,
+              tags: item.tags as string[] | undefined,
+              metadata: item.metadata as Record<string, unknown> | undefined,
+              created_at: item.created_at as string | undefined,
+            });
 
-          // Create explicit links (not wikilinks — those are automatic)
-          if (item.links) {
-            for (const link of item.links as { target: string; relationship: string }[]) {
-              const target = resolveNote(db, link.target);
-              if (target) {
-                await store.createLink(note.id, target.id, link.relationship);
+            // Create explicit links (not wikilinks — those are automatic)
+            if (item.links) {
+              for (const link of item.links as { target: string; relationship: string }[]) {
+                const target = resolveNote(db, link.target);
+                if (target) {
+                  await store.createLink(note.id, target.id, link.relationship);
+                }
               }
             }
-          }
 
-          created.push(noteOps.getNote(db, note.id) ?? note);
+            created.push(noteOps.getNote(db, note.id) ?? note);
+          }
+          if (batched) db.exec("COMMIT");
+        } catch (e) {
+          if (batched) db.exec("ROLLBACK");
+          throw e;
         }
 
         // Apply tag schema effects
@@ -344,7 +445,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
-        return batch ? created : created[0];
+        // Re-read after schema-default population so the response reflects the
+        // final on-disk state, then attach `validation_status` from any
+        // tag's `fields` declaration that applies to this note.
+        const final = created.map((n) => attachValidationStatus(store, db, n));
+        return batch ? final : final[0];
       },
     },
 
@@ -355,20 +460,36 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       name: "update-note",
       description: `Update one or more notes. Accepts ID or path. Supports content, path, metadata updates plus tag and link mutations.
 
+- Three content-modification modes (mutually exclusive):
+  - \`content\` — full replace.
+  - \`append\` / \`prepend\` — atomic concatenation at the SQL layer. Multiple agents appending to the same note never overwrite each other. No separator is added; include trailing/leading whitespace yourself if needed. May be combined with each other.
+  - \`content_edit: { old_text, new_text }\` — surgical find-and-replace. \`old_text\` must occur exactly once; zero or multiple matches return an error. Add surrounding context to disambiguate.
 - \`tags: { add: ["x"], remove: ["y"] }\` — add/remove tags
 - \`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.`,
+- **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. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`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.`,
       inputSchema: {
         type: "object",
         properties: {
           id: { type: "string", description: "Note ID or path" },
-          content: { type: "string", description: "New content" },
+          content: { type: "string", description: "New content (full replace). Mutually exclusive with `append`/`prepend` and `content_edit`." },
+          append: { type: "string", description: "Text to append to the end of the note. Atomic at the SQL layer — concurrent appends are safe. Mutually exclusive with `content` and `content_edit`. No precondition required." },
+          prepend: { type: "string", description: "Text to prepend to the start of the note. Atomic at the SQL layer. Mutually exclusive with `content` and `content_edit`. May combine with `append`. No precondition required." },
+          content_edit: {
+            type: "object",
+            properties: {
+              old_text: { type: "string", description: "Exact text to find. Must match exactly once in the note's current content." },
+              new_text: { type: "string", description: "Replacement text." },
+            },
+            required: ["old_text", "new_text"],
+            description: "Find-and-replace one occurrence. Errors if `old_text` is not found or matches multiple locations. Mutually exclusive with `content` and `append`/`prepend`.",
+          },
           path: { type: "string", description: "New path" },
           metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
           created_at: { type: "string", description: "New created_at timestamp" },
-          if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set." },
+          if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
           force: { type: "boolean", description: "Override the required `if_updated_at` check and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe." },
           tags: {
             type: "object",
@@ -406,6 +527,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             },
             description: "Links to add/remove",
           },
+          include_content: {
+            type: "boolean",
+            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
+          },
           // Batch
           notes: {
             type: "array",
@@ -414,10 +539,20 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               properties: {
                 id: { type: "string" },
                 content: { type: "string" },
+                append: { type: "string" },
+                prepend: { type: "string" },
+                content_edit: {
+                  type: "object",
+                  properties: {
+                    old_text: { type: "string" },
+                    new_text: { type: "string" },
+                  },
+                  required: ["old_text", "new_text"],
+                },
                 path: { type: "string" },
                 metadata: { type: "object" },
                 created_at: { type: "string" },
-                if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item." },
+                if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item or the item is `append`/`prepend`-only." },
                 force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
                 tags: { type: "object" },
                 links: { type: "object" },
@@ -432,24 +567,91 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const batch = params.notes as any[] | undefined;
         const items = batch ?? [params];
 
+        if (items.length > MAX_BATCH_SIZE) {
+          throw new BatchTooLargeError(items.length);
+        }
+
         const updated: Note[] = [];
+        // Wrap multi-item batches in a SQLite transaction so any mid-batch
+        // failure (precondition error, content_edit miss, ConflictError, …)
+        // rolls back every prior mutation in the batch — see #236.
+        // Single-item calls skip the wrap so concurrent callers don't
+        // collide on the shared bun:sqlite connection.
+        const batched = items.length > 1;
+        if (batched) db.exec("BEGIN");
+        try {
         for (const item of items) {
           const note = requireNote(db, item.id as string);
 
+          // --- Validate mutual exclusion of content modes ---
+          const hasContent = item.content !== undefined;
+          const hasAppendPrepend = item.append !== undefined || item.prepend !== undefined;
+          const hasContentEdit = item.content_edit !== undefined;
+          const contentModes = (hasContent ? 1 : 0) + (hasAppendPrepend ? 1 : 0) + (hasContentEdit ? 1 : 0);
+          if (contentModes > 1) {
+            throw new Error(
+              `update-note: \`content\`, \`append\`/\`prepend\`, and \`content_edit\` are mutually exclusive — pick one mode of content update for note "${note.id}".`,
+            );
+          }
+
           // --- Safety-by-default: refuse mutations without a precondition ---
           // The caller must either echo the note's last-seen `updated_at`
           // (`if_updated_at`) so the conditional UPDATE can catch lost
           // writes, or explicitly opt out with `force: true`. This runs
           // *before* any DB writes so a rejection leaves the note untouched.
-          if (item.if_updated_at === undefined && item.force !== true) {
+          //
+          // Append/prepend-only updates are exempt: they're SQL-atomic
+          // concatenations that can't lose data on a stale read, so the
+          // precondition would be ceremony for no benefit. Tag and link
+          // mutations are *not* exempt — they're idempotent set-ops at
+          // the SQL layer but still represent a non-content change the
+          // caller should have observed before re-asserting (#201).
+          const isAppendOnly = hasAppendPrepend
+            && !hasContent
+            && !hasContentEdit
+            && item.path === undefined
+            && item.metadata === undefined
+            && item.created_at === undefined
+            && item.tags === undefined
+            && item.links === undefined;
+          if (!isAppendOnly && item.if_updated_at === undefined && item.force !== true) {
             throw new PreconditionRequiredError(note.id, note.path ?? null);
           }
 
+          // --- Resolve content_edit into a full content string ---
+          // We do the find-and-replace at the JS level (read note.content,
+          // validate occurrence count, replace). The race window between
+          // this read and the UPDATE is closed by `if_updated_at` for
+          // strict callers; without it, content_edit is fail-closed —
+          // a stale read where someone else removed `old_text` produces
+          // a "not found" error instead of silently overwriting.
+          let contentOverride = item.content as string | undefined;
+          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(
+                "update-note: `content_edit` requires { old_text: string, new_text: string }.",
+              );
+            }
+            const idx = note.content.indexOf(ce.old_text);
+            if (idx < 0) {
+              throw new Error(
+                `update-note content_edit: \`old_text\` not found in note "${note.id}". The note may have been edited — re-read and retry.`,
+              );
+            }
+            const second = note.content.indexOf(ce.old_text, idx + 1);
+            if (second >= 0) {
+              throw new Error(
+                `update-note content_edit: \`old_text\` matches multiple times in note "${note.id}" — must match exactly once. Add surrounding context to disambiguate.`,
+              );
+            }
+            contentOverride = note.content.slice(0, idx) + ce.new_text + note.content.slice(idx + ce.old_text.length);
+          }
+
           // --- Plan bracket cleanup for wikilink removals (no DB writes yet) ---
           // We compute the cleaned content so we can do the core UPDATE first
           // (with if_updated_at atomically) before any link deletions. If the
           // UPDATE fails on a conflict, nothing has been mutated.
-          let contentOverride = item.content as string | undefined;
           const linksRemove = (item.links as any)?.remove as { target: string; relationship: string }[] | undefined;
           const resolvedLinksToRemove: { targetId: string; relationship: string }[] = [];
           if (linksRemove) {
@@ -458,7 +660,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               if (!target) continue;
               resolvedLinksToRemove.push({ targetId: target.id, relationship: link.relationship });
               if (link.relationship === "wikilink" && target.path) {
-                const currentContent = contentOverride ?? note.content;
+                // Wikilink-removal bracket cleanup operates on the prospective
+                // *full* content. Coexists with content_edit; would fight
+                // append/prepend (which leave existing content untouched at
+                // the JS layer), so we pre-materialize the would-be content
+                // for those callers and switch to a `content`-style update.
+                const currentContent = contentOverride
+                  ?? (hasAppendPrepend
+                    ? (item.prepend as string ?? "") + note.content + (item.append as string ?? "")
+                    : note.content);
                 const cleaned = removeWikilinkBrackets(currentContent, target.path);
                 if (cleaned !== currentContent) {
                   contentOverride = cleaned;
@@ -469,7 +679,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
           // --- Core update (content, path, metadata, created_at + concurrency check) ---
           const updates: any = {};
-          if (contentOverride !== undefined) updates.content = contentOverride;
+          if (contentOverride !== undefined) {
+            updates.content = contentOverride;
+          } else if (hasAppendPrepend) {
+            // No content_edit and no wikilink-removal pre-materialization —
+            // route the append/prepend down to the SQL-atomic path.
+            if (item.append !== undefined) updates.append = item.append;
+            if (item.prepend !== undefined) updates.prepend = item.prepend;
+          }
           if (item.path !== undefined) updates.path = item.path;
           if (item.metadata !== undefined) {
             // Merge metadata (don't replace wholesale)
@@ -519,8 +736,26 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           // Re-read for final state
           updated.push(noteOps.getNote(db, note.id) ?? result);
         }
+          if (batched) db.exec("COMMIT");
+        } catch (e) {
+          if (batched) db.exec("ROLLBACK");
+          throw e;
+        }
 
-        return batch ? updated : updated[0];
+        // Response shape: full Note (back-compat default) or lean NoteIndex
+        // (#285 friction point 2.response — opt-out for callers making
+        // frequent small edits to large notes). `validation_status` from
+        // `tags.fields` is preserved across either shape.
+        const includeContent = params.include_content !== false;
+        const final = updated.map((n) => {
+          const validated = attachValidationStatus(store, db, n);
+          if (includeContent) return validated;
+          const lean: any = noteOps.toNoteIndex(validated);
+          const vs = (validated as any).validation_status;
+          if (vs !== undefined) lean.validation_status = vs;
+          return lean;
+        });
+        return batch ? final : final[0];
       },
     },
 
@@ -549,39 +784,50 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "list-tags",
-      description: `List tags with usage counts. Pass \`tag\` to get a single tag's details including its schema (description + fields). Pass \`include_schema: true\` to include schemas for all tags.`,
+      description: `List tags with usage counts. Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps). Pass \`include_schema: true\` to include the full record for every tag.`,
       inputSchema: {
         type: "object",
         properties: {
           tag: { type: "string", description: "Get details for a single tag" },
-          include_schema: { type: "boolean", description: "Include schema (description + fields) for each tag (default: false)" },
+          include_schema: { type: "boolean", description: "Include full tag record (description, fields, relationships, parent_names, timestamps) for each tag (default: false)" },
         },
       },
       execute: (params) => {
         const singleTag = params.tag as string | undefined;
 
         if (singleTag) {
-          // Single tag detail
           const allTags = noteOps.listTags(db);
           const found = allTags.find((t) => t.name === singleTag);
-          const schema = tagSchemaOps.getTagSchema(db, singleTag);
+          const record = tagSchemaOps.getTagRecord(db, singleTag);
           return {
             name: singleTag,
             count: found?.count ?? 0,
-            description: schema?.description ?? null,
-            fields: schema?.fields ?? null,
+            description: record?.description ?? null,
+            fields: record?.fields ?? null,
+            relationships: record?.relationships ?? null,
+            parent_names: record?.parent_names ?? null,
+            created_at: record?.created_at ?? null,
+            updated_at: record?.updated_at ?? null,
           };
         }
 
-        // All tags
         const tags = noteOps.listTags(db);
         if (params.include_schema) {
-          const schemas = tagSchemaOps.getTagSchemaMap(db);
-          return tags.map((t) => ({
-            ...t,
-            description: schemas[t.name]?.description ?? null,
-            fields: schemas[t.name]?.fields ?? null,
-          }));
+          const records = new Map(
+            tagSchemaOps.listTagRecords(db).map((r) => [r.tag, r] as const),
+          );
+          return tags.map((t) => {
+            const r = records.get(t.name);
+            return {
+              ...t,
+              description: r?.description ?? null,
+              fields: r?.fields ?? null,
+              relationships: r?.relationships ?? null,
+              parent_names: r?.parent_names ?? null,
+              created_at: r?.created_at ?? null,
+              updated_at: r?.updated_at ?? null,
+            };
+          });
         }
         return tags;
       },
@@ -592,7 +838,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "update-tag",
-      description: "Create or update a tag's description and schema fields. If the tag doesn't exist, it's created. Fields are merged — new keys are added, existing keys are replaced.",
+      description: "Create or update a tag's identity row: description, indexed-field schemas, typed-link relationships, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
       inputSchema: {
         type: "object",
         properties: {
@@ -612,12 +858,32 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               required: ["type"],
             },
           },
+          relationships: {
+            type: "object",
+            description: 'Typed-link declarations. Each value declares { target_tag, cardinality, description? }. Cardinality is one of: one | optional | many | many-required. Phase 1: informational, not enforced at write time. E.g., { "lives_in": { "target_tag": "place", "cardinality": "one" } }',
+            additionalProperties: {
+              type: "object",
+              properties: {
+                target_tag: { type: "string", description: "Tag the relationship points at" },
+                cardinality: { type: "string", enum: ["one", "optional", "many", "many-required"], description: "How many targets this relationship may have" },
+                description: { type: "string", description: "Why this relationship exists; surfaced to AI clients" },
+              },
+              required: ["target_tag", "cardinality"],
+            },
+          },
+          parent_names: {
+            type: "array",
+            items: { type: "string" },
+            description: "Tag names this tag is a child of, for the query-time hierarchy. Replaces any prior parent list. Pass [] (empty array) or null to clear. E.g., parent_names: [\"manual\", \"note\"] makes this tag a descendant of both.",
+          },
         },
         required: ["tag"],
       },
-      execute: (params) => {
+      execute: async (params) => {
         const tag = params.tag as string;
-        const existing = tagSchemaOps.getTagSchema(db, tag);
+        const existing = tagSchemaOps.getTagRecord(db, tag);
+
+        // ---- fields: shallow-merge into existing (preserves prior keys).
         const incomingFields = (params.fields as Record<string, TagFieldSchema> | undefined) ?? {};
         const mergedFields: Record<string, TagFieldSchema> = {
           ...(existing?.fields ?? {}),
@@ -626,7 +892,6 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
-        // `description` and `enum` are per-tag, so we don't compare them.
         const otherSchemas = tagSchemaOps
           .listTagSchemas(db)
           .filter((s) => s.tag !== tag);
@@ -657,15 +922,47 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
-        // Persist the schema first, then reconcile indexing lifecycle. An
-        // error here would leave the on-disk schema untouched, matching
-        // prior behavior.
-        const result = tagSchemaOps.upsertTagSchema(db, tag, {
-          description: (params.description as string | undefined) ?? existing?.description,
-          fields: Object.keys(mergedFields).length > 0 ? mergedFields : undefined,
+        // ---- relationships: replace wholesale when provided. Validate
+        // shape + cardinality vocabulary before persisting so a malformed
+        // payload can't leave the row in an inconsistent state.
+        let relationshipsPatch: Record<string, tagSchemaOps.TagRelationship> | null | undefined;
+        if (params.relationships === null) {
+          relationshipsPatch = null;
+        } else if (params.relationships !== undefined) {
+          relationshipsPatch = tagSchemaOps.validateRelationships(params.relationships);
+        }
+
+        // ---- parent_names: replace wholesale when provided. Empty array
+        // collapses to null (clear) — a tag with `parent_names = []` and
+        // a tag with `parent_names = null` are indistinguishable at the
+        // hierarchy layer.
+        let parentNamesPatch: string[] | null | undefined;
+        if (params.parent_names === null) {
+          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");
+          }
+          const cleaned = (params.parent_names as unknown[])
+            .filter((p): p is string => typeof p === "string" && p.length > 0);
+          parentNamesPatch = cleaned.length > 0 ? cleaned : null;
+        }
+
+        // ---- Persist via the store wrapper so the hierarchy cache is
+        // invalidated when parent_names is touched.
+        const fieldsPatch = Object.keys(mergedFields).length > 0
+          ? mergedFields
+          : (params.fields !== undefined ? null : undefined);
+        const descriptionPatch =
+          params.description === undefined ? undefined : (params.description as string);
+        const result = await store.upsertTagRecord(tag, {
+          ...(descriptionPatch !== undefined ? { description: descriptionPatch } : {}),
+          ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
+          ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),
+          ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
         });
 
-        // Diff indexed state for this tag: what it indexed before vs. now.
+        // ---- Reconcile indexed-field lifecycle for this tag.
         const priorIndexed = new Set(
           Object.entries(existing?.fields ?? {})
             .filter(([, v]) => v.indexed === true)
@@ -706,9 +1003,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
       execute: async (params) => {
         const tag = params.tag as string;
-        // Release any indexed fields this tag declared before the schema
-        // row disappears. releaseField drops the generated column + index
-        // when the declarer set empties.
+        // Release any indexed fields this tag declared before the row
+        // drops. releaseField drops the generated column + index when the
+        // declarer set empties.
         const schema = tagSchemaOps.getTagSchema(db, tag);
         if (schema?.fields) {
           for (const [fieldName, spec] of Object.entries(schema.fields)) {
@@ -717,8 +1014,8 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             }
           }
         }
-        // Delete schema first (FK cascade would handle it, but be explicit)
-        tagSchemaOps.deleteTagSchema(db, tag);
+        // Drop the row outright — description/fields/relationships/parents
+        // travel with it. (No more sidecar table to clear separately.)
         return await store.deleteTag(tag);
       },
     },
@@ -752,11 +1049,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "vault-info",
-      description: "Get vault description and optionally stats (note/tag/link counts, distribution). Pass `description` to update the vault description (changes how AI agents behave in future sessions).",
+      description: "Get a comprehensive vault projection: name, description, tags-with-schemas (own + effective parents/fields per #270 inheritance), indexed metadata fields catalog, and query hints. Pass `include_stats: true` to add note/tag/link counts and the monthly distribution. Pass `description` to update the vault description (changes how AI agents behave in future sessions). Call this anytime mid-session to refresh schema context.",
       inputSchema: {
         type: "object",
         properties: {
-          include_stats: { type: "boolean", description: "Include note count, tag count, distribution by month (default: false)" },
+          include_stats: { type: "boolean", description: "Include note count, tag count, attachment/link counts, and the monthly note distribution (default: false)" },
           description: { type: "string", description: "If provided, updates the vault description" },
         },
       },
@@ -818,19 +1115,47 @@ function defaultForField(field: { type: string; enum?: string[] }): unknown {
   }
 }
 
+// ---------------------------------------------------------------------------
+// `tags.fields` validation — surface validation_status on create/update
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a `validation_status` field to the response when at least one tag
+ * on the note declares `fields` on its `tags` row. Validation is advisory
+ * only — writes are never blocked. The agent receives warnings (type
+ * mismatch, enum mismatch) so it can self-correct on the next turn.
+ *
+ * Returns the note unchanged when no tag declares fields, so callers
+ * without any tag schemas see no behavior change.
+ */
+function attachValidationStatus(store: Store, _db: Database, note: Note): Note {
+  // Short-circuit cheaply: when no tag declares fields, the resolver
+  // returns null without us paying a re-read of the note.
+  const status = store.validateNoteAgainstSchemas({
+    path: note.path,
+    tags: note.tags,
+    metadata: note.metadata as Record<string, unknown> | undefined,
+  });
+  if (!status) return note;
+  return { ...note, validation_status: status } as Note & { validation_status: typeof status };
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 function normalizeTags(tag: unknown): string[] | undefined {
   if (!tag) return undefined;
-  if (Array.isArray(tag)) return tag;
+  // Defensive copy: callers downstream sometimes mutate the array (sort,
+  // splice, push for hierarchy expansion). Returning a fresh array keeps
+  // the original `params` object untouched.
+  if (Array.isArray(tag)) return [...tag];
   return [tag as string];
 }
 
 // Re-exported for backward compat; defined in notes.ts alongside the
 // conditional-UPDATE implementation that raises it.
-export { ConflictError } from "./notes.js";
+export { ConflictError, PathConflictError, EmptyNoteError, MAX_BATCH_SIZE } from "./notes.js";
 
 /**
  * Thrown by the `update-note` MCP tool (and the REST PATCH handler) when a
@@ -854,3 +1179,23 @@ export class PreconditionRequiredError extends Error {
   }
 }
 
+/**
+ * Thrown by `create-note` / `update-note` when a batch exceeds
+ * `MAX_BATCH_SIZE` (re-exported from `./notes.js` — single source of truth).
+ * Bounds the blast radius of a runaway client — see #213, where one MCP
+ * burst created 7,453 empty notes in minutes. Surfaces as 413 at the HTTP
+ * layer.
+ */
+export class BatchTooLargeError extends Error {
+  code = "BATCH_TOO_LARGE" as const;
+  limit: number;
+  got: number;
+
+  constructor(got: number) {
+    super(`batch_too_large: max ${MAX_BATCH_SIZE} notes per call, got ${got}`);
+    this.name = "BatchTooLargeError";
+    this.limit = MAX_BATCH_SIZE;
+    this.got = got;
+  }
+}
+