@openparachute/vault 0.6.0-rc.1 → 0.6.0

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";
@@ -99,13 +100,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 [
 
@@ -137,6 +166,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 +212,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: {
@@ -217,6 +251,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,7 +280,16 @@ 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;
 
         // --- Single note by ID/path ---
@@ -256,10 +310,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 +340,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 +367,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 +394,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 +414,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,
@@ -390,6 +476,19 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           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) {
           const enrichedOut: any[] = [];
@@ -512,17 +611,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 +660,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 +684,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 +726,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 +753,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 +779,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 +876,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 +1043,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 +1072,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 +1184,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 +1206,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 +1271,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 +1444,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 +1465,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 +1483,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 +1540,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`

package/core/src/notes.ts

@@ -83,7 +83,7 @@ export function createNote(
 }
 
 export function getNote(db: Database, id: string): Note | null {
-  const row = db.prepare("SELECT * FROM notes WHERE id = ?").get(id) as NoteRow | undefined;
+  const row = db.prepare("SELECT * FROM notes WHERE id = ?").get(id) as NoteRow | null;
   if (!row) return null;
 
   const note = rowToNote(row);
@@ -111,7 +111,7 @@ export function getNoteByPath(db: Database, path: string, extension?: string): N
   if (extension !== undefined) {
     const row = db.prepare(
       "SELECT * FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
-    ).get(path, extension.toLowerCase()) as NoteRow | undefined;
+    ).get(path, extension.toLowerCase()) as NoteRow | null;
     if (!row) return null;
     const note = rowToNote(row);
     note.tags = getNoteTags(db, note.id);
@@ -459,7 +459,7 @@ export function updateNote(
     if (isPathUniqueError(err)) {
       const conflictPath = updates.path !== undefined
         ? (normalizePath(updates.path) ?? updates.path)
-        : ((db.prepare("SELECT path FROM notes WHERE id = ?").get(id) as { path: string | null } | undefined)?.path ?? "<unknown>");
+        : ((db.prepare("SELECT path FROM notes WHERE id = ?").get(id) as { path: string | null } | null)?.path ?? "<unknown>");
       throw new PathConflictError(conflictPath);
     }
     throw err;
@@ -475,7 +475,7 @@ export function updateNote(
 function throwConflictOrMissing(db: Database, id: string, expected: string): never {
   const row = db.prepare("SELECT updated_at, path FROM notes WHERE id = ?").get(id) as
     | { updated_at: string | null; path: string | null }
-    | undefined;
+    | null;
   if (!row) {
     throw new Error(`Note not found: "${id}"`);
   }
@@ -736,6 +736,32 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     // be at the mercy of SQLite's row order and the next page could
     // miss or duplicate one.
     orderBy = "n.updated_at ASC, n.id ASC";
+  } else if (opts.orderBy === "link_count") {
+    // `link_count` is a pseudo-field — like `created_at`/`updated_at` in the
+    // dateFilter block above, it bypasses `requireIndexedField` (it's not a
+    // metadata column). Sort by link DEGREE using the SAME directional-sum
+    // definition as the `linkCount` response field (see `getLinkCounts` in
+    // links.ts): two correlated COUNT subqueries summed. This MUST stay a
+    // sum of two directional counts — a single
+    // `COUNT(*) ... WHERE source_id=n.id OR target_id=n.id` would count a
+    // self-loop ONCE (degree 1) and DIVERGE from the field's degree-2. Both
+    // subqueries ride the existing `idx_links_source` / `idx_links_target`
+    // B-trees. `created_at` stays the stable tiebreaker.
+    //
+    // Always the both-directions degree — inbound-only ordering is a future
+    // extension and is not built here.
+    //
+    // Perf caveat: these are correlated subqueries, evaluated once per
+    // candidate row. At small-to-moderate vault sizes (tens of thousands of
+    // notes) that's fine — each subquery is an O(log n) index probe. At very
+    // large vault sizes the per-row scan cost grows; the upgrade path is a
+    // maintained `link_count` counter column on `notes`, incremented in
+    // `createLink` and decremented in `deleteLink`, then ordered directly.
+    // NOT built now — flagged so a future contributor sees the lever.
+    orderBy =
+      `((SELECT COUNT(*) FROM links WHERE source_id = n.id) ` +
+      `+ (SELECT COUNT(*) FROM links WHERE target_id = n.id)) ${direction}, ` +
+      `n.created_at ${direction}`;
   } else if (opts.orderBy) {
     requireIndexedField(db, opts.orderBy);
     // `orderBy` came from indexed_fields (validated on declaration), so
@@ -946,7 +972,7 @@ export function listTags(db: Database): { name: string; count: number }[] {
 export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {
   const row = db.prepare("SELECT fields FROM tags WHERE name = ?").get(name) as
     | { fields: string | null }
-    | undefined;
+    | null;
   if (!row) return { deleted: false, notes_untagged: 0 };
 
   const countRow = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?").get(name) as { c: number };
@@ -1107,7 +1133,7 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
     for (const { from, to } of renames) {
       const old = readStmt.get(from) as
         | { description: string | null; fields: string | null; relationships: string | null; parent_names: string | null; created_at: string | null }
-        | undefined;
+        | null;
       insertStmt.run(
         to,
         old?.description ?? null,
@@ -1522,11 +1548,11 @@ export function getVaultStats(
 
   const earliestRow = db.prepare(
     "SELECT id, created_at FROM notes ORDER BY created_at ASC, id ASC LIMIT 1",
-  ).get() as { id: string; created_at: string } | undefined;
+  ).get() as { id: string; created_at: string } | null;
 
   const latestRow = db.prepare(
     "SELECT id, created_at FROM notes ORDER BY created_at DESC, id DESC LIMIT 1",
-  ).get() as { id: string; created_at: string } | undefined;
+  ).get() as { id: string; created_at: string } | null;
 
   const monthRows = db.prepare(`
     SELECT strftime('%Y-%m', created_at) AS month, COUNT(*) AS count
@@ -1553,6 +1579,15 @@ export function getVaultStats(
   const linkCountRow = db.prepare("SELECT COUNT(*) as c FROM links").get() as { c: number };
   const linkCount = linkCountRow.c;
 
+  // Total content bytes. CAST(content AS BLOB) forces SQLite's LENGTH() to
+  // count UTF-8 BYTES rather than characters (bare LENGTH on TEXT returns a
+  // char count, which undercounts multibyte content). COALESCE because SUM
+  // over zero rows is NULL. See VaultStats.contentBytes for the rationale.
+  const contentBytesRow = db
+    .prepare("SELECT COALESCE(SUM(LENGTH(CAST(content AS BLOB))), 0) as b FROM notes")
+    .get() as { b: number };
+  const contentBytes = contentBytesRow.b;
+
   return {
     totalNotes,
     earliestNote: earliestRow
@@ -1566,6 +1601,7 @@ export function getVaultStats(
     tagCount,
     attachmentCount,
     linkCount,
+    contentBytes,
   };
 }