@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/core/src/mcp.ts

@@ -3,6 +3,7 @@ import type { Store, Note } from "./types.js";
 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, type TagExpandMode } from "./tag-hierarchy.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -14,6 +15,12 @@ import {
   type ExpandContext,
   type ExpandMode,
 } from "./expand.js";
+import {
+  parseContentRange,
+  applyContentRange,
+  contentRangeRequiresContent,
+  MIN_CONTENT_LENGTH,
+} from "./content-range.js";
 
 export interface McpToolDef {
   name: string;
@@ -99,13 +106,41 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // Tool generation
 // ---------------------------------------------------------------------------
 
+/**
+ * Options for {@link generateMcpTools}.
+ *
+ * `expandVisibility` (vault security review) is an OPTIONAL per-note
+ * visibility predicate threaded into the wikilink-expansion context for
+ * `query-notes`. When provided, `expand_links` inlining leaves any wikilink
+ * whose target fails the predicate UNRESOLVED — so a tag-scoped MCP session
+ * can't inline out-of-scope note content during expansion (the filtering
+ * happens DURING expansion, not after). Core stays scope-unaware: it
+ * receives a plain `(note) => boolean` closure and never imports the
+ * server's tag-scope module. Omitted (every internal / unscoped caller) →
+ * expansion behaves exactly as before.
+ */
+export interface GenerateMcpToolsOpts {
+  expandVisibility?: (note: Note) => boolean;
+  /**
+   * `nearTraversable` (vault#439) is an OPTIONAL per-note predicate threaded
+   * into the `near[]` graph BFS. When provided, the traversal refuses to walk
+   * THROUGH any note that fails the predicate — making a tag-scoped `near[]`
+   * query symmetric with `find-path` (scope is a wall, not a sieve). Core
+   * stays scope-unaware: it receives a plain `(noteId) => boolean` closure.
+   * Omitted (unscoped / internal callers) → the full graph is walked.
+   */
+  nearTraversable?: (noteId: string) => boolean;
+}
+
 /**
  * Generate the consolidated MCP tools for a vault. Surface (10):
  * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
  * delete-tag, find-path, vault-info, prune-schema (admin).
  */
-export function generateMcpTools(store: Store): McpToolDef[] {
-  const db: Database = (store as any).db;
+export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
+  const db: Database = store.db;
+  const expandVisibility = opts?.expandVisibility;
+  const nearTraversable = opts?.nearTraversable;
 
   return [
 
@@ -124,6 +159,8 @@ export function generateMcpTools(store: Store): McpToolDef[] {
 
 Defaults: include_content=true for single note, false for lists. include_links=false. tag_match="any".
 
+Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bounded read of note content — the response carries the slice plus \`content_total_length\` and \`content_next_offset\` (null when complete). Loop, feeding \`content_next_offset\` back as \`content_offset\`, to read a note too large for one response.
+
 Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.`,
       inputSchema: {
         type: "object",
@@ -137,6 +174,11 @@ 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)" },
+          expand: {
+            type: "string",
+            enum: ["subtypes", "namespace", "both", "exact"],
+            description: "How each `tag` expands. 'subtypes' (DEFAULT): the tag plus its declared parent_names descendants — the semantic is-a axis (e.g. tag:entity also matches person/work). 'namespace': the tag plus everything filed under it by NAME (tag:entity also matches entity/archived) — the lexical filing axis. 'both': union of the two. 'exact': only the literal tag, no expansion. Omit for 'subtypes' (current behavior).",
+          },
           exclude_tags: {
             oneOf: [
               { type: "string" },
@@ -178,7 +220,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             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.",
           },
-          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." },
+          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. The special value `link_count` sorts by link DEGREE (both-directions raw row count) — no declaration needed — matching the `include_link_count` field for every note. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
           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: {
@@ -209,6 +251,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               "Opaque cursor for 'since last checked' agent loops (vault#313). First call: omit. The response will include `next_cursor` — pass it on the subsequent call to receive only notes created or updated since the prior page. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`. The response shape switches to `{notes, next_cursor}` when this parameter is present.",
           },
           include_content: { type: "boolean", description: "Include note content (default: true for single, false for list)" },
+          content_offset: {
+            type: "number",
+            description:
+              "Byte offset (UTF-8) into note content to start reading from (default 0). For reading a note too large for one response: pass the previous response's `content_next_offset` here to continue. An offset landing mid-codepoint is aligned DOWN to the codepoint's leading byte (chained `content_next_offset` values are always aligned); the effective start is echoed back as `content_offset` on the response. Requires content in the response — errors when combined with include_content=false (or a list query without include_content=true).",
+          },
+          content_length: {
+            type: "number",
+            description:
+              `Maximum bytes (UTF-8) of note content to return (minimum ${MIN_CONTENT_LENGTH}). When this or content_offset is set, the returned \`content\` is the byte slice and the response gains \`content_offset\` (effective start), \`content_total_length\` (full content size in bytes), and \`content_next_offset\` (pass back as content_offset to continue; null when the slice reaches the end). Slices end on a UTF-8 codepoint boundary, so a slice may be up to 3 bytes under the budget — never over. Concatenating the slices from offset 0 through content_next_offset=null reconstructs the content byte-for-byte. On list queries the same window applies to each note's content independently. When expand_links=true the range applies to the returned (expanded) content.`,
+          },
           include_metadata: {
             oneOf: [
               { type: "boolean" },
@@ -217,6 +269,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Control metadata in response: true (all, default), false (none), or array of field names to include",
           },
           include_links: { type: "boolean", description: "Include inbound + outbound links per note (default: false)" },
+          include_link_count: {
+            type: "boolean",
+            description:
+              "Include the note's link DEGREE as a `linkCount` field, without hauling the link objects (default: false). Degree is a raw row count: outbound (source) + inbound (target). A self-loop counts as 2. Cheap COUNT over indexes; batched once per request. For a tag-scoped token, `linkCount` is the raw degree and MAY include edges to notes the token can't see — only the number leaks, not the neighbor.",
+          },
+          link_count_direction: {
+            type: "string",
+            enum: ["both", "outbound", "inbound"],
+            description:
+              "Which edges `include_link_count` counts: both (default), outbound only (source_id), or inbound only (target_id). order_by=link_count always uses the both-directions degree.",
+          },
           include_attachments: { type: "boolean", description: "Include attachment records (default: false)" },
           expand_links: { type: "boolean", description: "Inline [[wikilinks]] in returned content (default: false). Has no effect if content is not included (e.g., default list mode with include_content=false); wikilinks inside fenced or inline code are not expanded." },
           expand_depth: { type: "number", description: "Recursion depth for link expansion (default 1, max 3). Only meaningful in 'full' mode — 'summary' mode does not recurse." },
@@ -235,20 +298,43 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           ),
         );
         const expandCtx: ExpandContext | null = expandLinks
-          ? { db, mode: expandMode, expanded: new Set() }
+          ? {
+              db,
+              mode: expandMode,
+              expanded: new Set(),
+              // Tag-scope confidentiality (security review): when a visibility
+              // predicate was injected, wikilinks to out-of-scope notes are
+              // left unresolved DURING inlining — never embedded. Unscoped
+              // callers pass no predicate and inlining is unchanged.
+              ...(expandVisibility ? { isVisible: expandVisibility } : {}),
+            }
           : null;
 
+        // --- Content range (bounded reads for large notes) ---
+        // Validates loudly: bad values throw QueryError here, before any
+        // query work. Null when neither param is present — response shape
+        // stays byte-identical to the no-pagination behavior.
+        const contentRange = parseContentRange(params.content_offset, params.content_length);
+
         // --- 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 };
           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
+          // `expand`).
+          if (contentRange && !includeContent) throw contentRangeRequiresContent();
           let result: any = includeContent ? { ...note } : noteOps.toNoteIndex(note);
           if (expandCtx && includeContent && typeof result.content === "string") {
             // Mark the top-level note as already expanded so it can't recursively inline itself.
             expandCtx.expanded.add(note.id);
             result.content = expandContent(result.content, expandCtx, expandDepth);
           }
+          // Range applies to the FINAL returned content — after wikilink
+          // expansion — so the window the client pages through is the same
+          // document it would have received unpaged.
+          if (contentRange && includeContent) applyContentRange(result, contentRange);
           result = filterMetadata(result, params.include_metadata as boolean | string[] | undefined);
           if (params.include_links) {
             result.links = linkOps.getLinksHydrated(db, note.id);
@@ -256,10 +342,27 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           if (params.include_attachments) {
             result.attachments = await store.getAttachments(note.id);
           }
+          // linkCount injected after filterMetadata on purpose — same as
+          // links/attachments above; filterMetadata only touches `metadata`.
+          if (params.include_link_count) {
+            const dir = normalizeLinkCountDirection(params.link_count_direction);
+            result.linkCount = linkOps.getLinkCounts(db, [note.id], dir).get(note.id) ?? 0;
+          }
           return result;
         }
 
         // --- Build near-scope (graph-filtered set of allowed IDs) ---
+        //
+        // Tag-scope policy for `near[]` (vault#439 — hop-guard, symmetric with
+        // find-path): when the session is tag-scoped the server injects a
+        // `nearTraversable` predicate (mcp-tools.ts), and the BFS refuses to
+        // walk THROUGH out-of-scope notes — scope is a wall, not a sieve. So a
+        // token scoped to ["work"] can't reach an in-scope note at depth 2 via
+        // a #personal intermediary at depth 1. Core stays scope-unaware: it
+        // only invokes the injected closure. Unscoped sessions pass no
+        // predicate → the FULL graph is walked exactly as before. The
+        // `applyTagScopeWrappers` result-filter still runs afterward (defense
+        // in depth), but the wall makes it redundant for `near[]`.
         let nearScope: Set<string> | null = null;
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
@@ -269,6 +372,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           const traversed = linkOps.traverseLinks(db, anchor.id, {
             max_depth: depth,
             relationship: near.relationship,
+            isTraversable: nearTraversable,
           });
           nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         }
@@ -295,6 +399,18 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             "INVALID_QUERY",
           );
         }
+        // Tag-expansion axis (vault tag `expand` axis). Validate loudly so a
+        // typo'd value doesn't silently fall back to the default.
+        let expand: TagExpandMode | undefined;
+        if (params.expand !== undefined && params.expand !== null) {
+          if (typeof params.expand !== "string" || !(TAG_EXPAND_MODES as readonly string[]).includes(params.expand)) {
+            throw new QueryError(
+              `invalid \`expand\` value ${JSON.stringify(params.expand)} — must be one of ${TAG_EXPAND_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("subtypes").`,
+              "INVALID_QUERY",
+            );
+          }
+          expand = params.expand as TagExpandMode;
+        }
 
         // --- Full-text search ---
         let results: Note[];
@@ -310,6 +426,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           results = await store.searchNotes(params.search as string, {
             tags,
             limit: (params.limit as number) ?? 50,
+            expand,
           });
         } else {
           // --- Structured query ---
@@ -329,6 +446,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           const queryOpts = {
             tags,
             tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+            expand,
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
             hasLinks: params.has_links as boolean | undefined,
@@ -371,6 +489,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // --- Format output ---
         const includeContent = params.include_content === true; // default false for list
+        // Range params require content in the response — on lists that
+        // means an explicit include_content=true (the lean default carries
+        // no content to slice). Error rather than silently ignore.
+        if (contentRange && !includeContent) throw contentRangeRequiresContent();
         const includeMetadata = params.include_metadata as boolean | string[] | undefined;
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(noteOps.toNoteIndex);
 
@@ -385,17 +507,46 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
+        // --- Content range (per-note, post-expansion) ---
+        // The same byte window applies to EACH note's content independently
+        // — the primary use is a single large note, but list mode keeps the
+        // simple per-note semantic (every note reports its own
+        // content_total_length / content_next_offset).
+        if (contentRange && includeContent) {
+          for (const n of output) applyContentRange(n, contentRange);
+        }
+
         // --- Apply metadata filtering ---
         if (includeMetadata !== undefined && includeMetadata !== true) {
           output = output.map((n: any) => filterMetadata(n, includeMetadata));
         }
 
+        // --- Opt-in link degree (vault feedback #4) ---
+        // ONE batch count over all result ids (NOT per-note), so the field
+        // stays O(2 index scans) per request regardless of page size.
+        // Injected on the same objects the enrichment loop copies below.
+        // Ordering: runs AFTER the filterMetadata pass above on purpose —
+        // filterMetadata only touches the `metadata` key, so linkCount
+        // survives. Don't casually swap the order.
+        if (params.include_link_count) {
+          const dir = normalizeLinkCountDirection(params.link_count_direction);
+          const counts = linkOps.getLinkCounts(db, output.map((n: any) => n.id), dir);
+          for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+        }
+
         // --- Hydrate links/attachments per note if requested ---
         if (params.include_links || params.include_attachments) {
+          // Links hydrate for the WHOLE page in a constant number of
+          // queries (see getLinksHydratedForNotes) — the per-note variant
+          // cost (1 link query + 1 summary query + N tag queries) × page
+          // size. 2026-06-10 perf measurements.
+          const linksByNote = params.include_links
+            ? linkOps.getLinksHydratedForNotes(db, (output as any[]).map((n: any) => n.id))
+            : null;
           const enrichedOut: any[] = [];
           for (const n of output as any[]) {
             const enriched: any = { ...n };
-            if (params.include_links) enriched.links = linkOps.getLinksHydrated(db, n.id);
+            if (linksByNote) enriched.links = linksByNote.get(n.id) ?? [];
             if (params.include_attachments) enriched.attachments = await store.getAttachments(n.id);
             enrichedOut.push(enriched);
           }
@@ -512,17 +663,35 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           throw e;
         }
 
-        // Apply tag schema effects
+        // Apply tag schema effects, then re-read the notes whose metadata was
+        // actually default-filled so the response reflects the final on-disk
+        // state (the `created` entries were read before `applySchemaDefaults`
+        // ran, so default-filled metadata isn't on them yet). This mirrors the
+        // update-note path, which already re-reads post-defaults. The re-read
+        // is batched (`getNotes` = one `WHERE id IN (...)`) and skipped
+        // entirely when no defaults were applied, so the common no-defaults
+        // path adds zero extra reads.
+        const mutatedIds = new Set<string>();
         for (const note of created) {
           if (note.tags && note.tags.length > 0) {
-            await applySchemaDefaults(store, db, [note.id], note.tags);
+            for (const id of await applySchemaDefaults(store, db, [note.id], note.tags)) {
+              mutatedIds.add(id);
+            }
           }
         }
-
-        // 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));
+        const refreshed =
+          mutatedIds.size === 0
+            ? created
+            : (() => {
+                const byId = new Map(
+                  noteOps.getNotes(db, [...mutatedIds]).map((n) => [n.id, n]),
+                );
+                return created.map((n) => byId.get(n.id) ?? n);
+              })();
+
+        // Attach `validation_status` from any tag's `fields` declaration that
+        // applies to this note, against the post-defaults state.
+        const final = refreshed.map((n) => attachValidationStatus(store, db, n));
         return batch ? final : final[0];
       },
     },
@@ -543,7 +712,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - \`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. \`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).
 - **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\`, \`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: {
@@ -567,7 +736,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           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 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." },
+          force: { type: "boolean", description: "Waive the *requirement to supply* `if_updated_at` and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe. Note: this does not override an `if_updated_at` you actually pass — if you supply both, the precondition still applies and a mismatch returns a conflict error." },
           if_missing: { type: "string", enum: ["fail", "create"], description: "What to do when the note (by `id`/path) doesn't exist. `\"fail\"` (default) — error, current behavior. `\"create\"` — create the note from this same payload (content/path/tags/metadata become the create fields; the response carries `created: true`). Skips the `if_updated_at` precondition on the create branch (nothing to conflict with). Idempotent for sync loops that don't know ahead of time whether the note exists. See vault#309." },
           tags: {
             type: "object",
@@ -609,6 +778,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             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.",
           },
+          include_links: {
+            type: "boolean",
+            description: "Echo the note's hydrated inbound + outbound links on the response (vault feedback #8). Links are *also* echoed automatically whenever the update itself mutated links (`links.add`/`links.remove`), so you rarely need to set this — its purpose is to fetch the current link set on an update that didn't touch links. Default: `false` (and absent from the response unless mutated or requested). Mirrors `query-notes`'s `include_links`. This top-level flag applies to the single-note form only; for a batch, set `include_links` on each note object in `notes` (a top-level `include_links` is ignored when `notes` is present).",
+          },
           // Batch
           notes: {
             type: "array",
@@ -632,10 +805,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 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 or the item is `append`/`prepend`-only." },
-                force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
+                force: { type: "boolean", description: "Waive the *requirement to supply* `if_updated_at` for this item. Does not override an `if_updated_at` you actually pass — a supplied precondition still applies and a mismatch conflicts." },
                 if_missing: { type: "string", enum: ["fail", "create"], description: "Per-item: see top-level `if_missing` docs. Each batch item carries its own setting." },
                 tags: { type: "object" },
                 links: { type: "object" },
+                include_links: { type: "boolean", description: "Per-item: echo hydrated links on this item's response (vault feedback #8). Also implied when this item mutates links." },
               },
               required: ["id"],
             },
@@ -657,6 +831,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // sync-loop caller (Gitcoin Brain et al) reads this to know which
         // path fired without doing a separate query. vault#309.
         const createdIds = new Set<string>();
+        // Track which note IDs should echo hydrated links on the response.
+        // A note qualifies when this request mutated its links
+        // (`links.add`/`links.remove`) OR the caller set `include_links`.
+        // vault feedback #8 — previously the update response omitted links
+        // entirely, forcing a re-query just to confirm a link the caller had
+        // just added/removed. Per-item on batch. Note IDs (not item indices)
+        // key this so the create-on-missing branch, which assigns the id
+        // late, can register correctly.
+        const echoLinkIds = new Set<string>();
         // 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.
@@ -745,6 +928,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               const fresh = noteOps.getNote(db, created.id) ?? created;
               updated.push(fresh);
               createdIds.add(fresh.id);
+              // Echo links if this create-on-missing declared `links.add`
+              // (the only link op honored on create) or asked explicitly.
+              if (linksAdd !== undefined || item.include_links === true) {
+                echoLinkIds.add(fresh.id);
+              }
               continue;
             }
             // Fallthrough: not-found + no if_missing → existing error
@@ -907,6 +1095,13 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             }
           }
 
+          // Echo links if this update mutated them (`links.add`/`links.remove`)
+          // or the caller asked explicitly. vault feedback #8.
+          const linkMutated = (item.links as any)?.add !== undefined || (item.links as any)?.remove !== undefined;
+          if (linkMutated || item.include_links === true) {
+            echoLinkIds.add(note.id);
+          }
+
           // Re-read for final state
           updated.push(noteOps.getNote(db, note.id) ?? result);
         }
@@ -929,11 +1124,23 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const final = updated.map((n) => {
           const validated = attachValidationStatus(store, db, n);
           const created = createdIds.has(n.id);
-          if (includeContent) return { ...validated, created } as Note & { created: boolean };
+          // Echo hydrated links when this note was flagged for it (mutated
+          // its links or `include_links` was set). Additive key, present only
+          // when triggered — mirrors the GET / query-notes shape exactly via
+          // the shared `linkOps.getLinksHydrated` call. vault feedback #8.
+          const echoLinks = echoLinkIds.has(n.id);
+          if (includeContent) {
+            const full: any = { ...validated, created };
+            if (echoLinks) full.links = linkOps.getLinksHydrated(db, n.id);
+            return full as Note & { created: boolean };
+          }
           const lean: any = noteOps.toNoteIndex(validated);
           const vs = (validated as any).validation_status;
           if (vs !== undefined) lean.validation_status = vs;
           lean.created = created;
+          // Carry the link echo across the lean conversion — `toNoteIndex`
+          // drops unknown fields.
+          if (echoLinks) lean.links = linkOps.getLinksHydrated(db, n.id);
           return lean;
         });
         return batch ? final : final[0];
@@ -1029,7 +1236,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     {
       name: "update-tag",
       requiredVerb: "write",
-      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.",
+      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, 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: {
@@ -1051,16 +1258,8 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           },
           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"],
-            },
+            description: 'Opaque relationship-vocabulary map: keys are relationship names, values are arbitrary JSON the declaring app interprets. Vault stores and returns the values verbatim and does NOT enforce any inner shape — only that this is a JSON object (a map), not an array or primitive. Replaces any prior map wholesale when provided; pass null to clear. The historical typed shape { "lives_in": { "target_tag": "place", "cardinality": "one" } } is still a valid value, as is any app-defined shape e.g. { "works-on": { "from": "person", "to": "project" } }.',
+            additionalProperties: true,
           },
           parent_names: {
             type: "array",
@@ -1124,10 +1323,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
-        // ---- 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;
+        // ---- relationships: replace wholesale when provided. `relationships`
+        // is an opaque vocabulary map (relationship-name → arbitrary JSON the
+        // app interprets). Validate only that it's a JSON object (a map), then
+        // persist verbatim — no inner-shape enforcement.
+        let relationshipsPatch: tagSchemaOps.TagRelationshipMap | null | undefined;
         if (params.relationships === null) {
           relationshipsPatch = null;
         } else if (params.relationships !== undefined) {
@@ -1296,9 +1496,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 // Tag schema effects — auto-populate defaults when tags are applied
 // ---------------------------------------------------------------------------
 
-async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<void> {
+/**
+ * Fill schema-declared default values into the metadata of the given notes
+ * for any field they omitted. Returns the IDs of the notes whose metadata was
+ * actually written — callers use this to re-read ONLY the mutated notes (and
+ * to skip the re-read entirely when nothing changed). The common no-schema /
+ * no-defaults path returns an empty array.
+ */
+async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
   const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return;
+  if (Object.keys(schemas).length === 0) return [];
 
   const defaults: Record<string, unknown> = {};
   for (const tag of tags) {
@@ -1310,8 +1517,9 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
       }
     }
   }
-  if (Object.keys(defaults).length === 0) return;
+  if (Object.keys(defaults).length === 0) return [];
 
+  const mutated: string[] = [];
   for (const noteId of noteIds) {
     const note = noteOps.getNote(db, noteId);
     if (!note) continue;
@@ -1327,7 +1535,9 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
       metadata: { ...existing, ...missing },
       skipUpdatedAt: true,
     });
+    mutated.push(noteId);
   }
+  return mutated;
 }
 
 function defaultForField(field: { type: string; enum?: string[] }): unknown {
@@ -1382,6 +1592,16 @@ function normalizeTags(tag: unknown): string[] | undefined {
   return [tag as string];
 }
 
+/**
+ * Coerce the `link_count_direction` MCP param to a known value, defaulting
+ * to "both" (matches the REST `parseLinkCountDirection` fallback). A typo
+ * silently degrades to the documented default rather than erroring.
+ */
+function normalizeLinkCountDirection(v: unknown): "both" | "outbound" | "inbound" {
+  if (v === "outbound" || v === "inbound") return v;
+  return "both";
+}
+
 // Re-exported for backward compat; defined in notes.ts alongside the
 // conditional-UPDATE implementation that raises it. AmbiguousPathError
 // joins the set (vault#331 N2) so external callers can `instanceof`