@openparachute/vault 0.5.1-rc.2 → 0.5.2-rc.1

package/core/src/mcp.ts

@@ -99,13 +99,31 @@ 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;
+}
+
 /**
  * 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[] {
+export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
   const db: Database = (store as any).db;
+  const expandVisibility = opts?.expandVisibility;
 
   return [
 
@@ -178,7 +196,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 +235,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 +264,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 +294,26 @@ 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[]` (output-filter, not hop-guard): core
+        // is scope-unaware, so this BFS walks the FULL graph from the anchor —
+        // including out-of-scope intermediate hops. For a tag-scoped session
+        // the server's `applyTagScopeWrappers` (mcp-tools.ts) tag-filters the
+        // RESULT list AFTER execute, so out-of-scope notes never survive into
+        // the response — no content/ids leak. This is ASYMMETRIC with
+        // `find-path`, which guards every hop (it returns the path itself, so
+        // an out-of-scope intermediary would be a leak there). The asymmetry is
+        // deliberate; tracked at vault#439.
         let nearScope: Set<string> | null = null;
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
@@ -390,6 +444,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[] = [];
@@ -543,7 +610,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 +634,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 +676,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 +703,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 +729,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 +826,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 +993,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 +1022,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 +1134,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 +1156,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 +1221,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) {
@@ -1382,6 +1480,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

@@ -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
@@ -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,
   };
 }