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

package/core/src/links.ts

@@ -267,12 +267,16 @@ export function getLinksHydratedForNotes(
  * most two index scans regardless of page size. The IN-list is chunked to
  * stay under SQLite's bound-variable limit on very large pages.
  *
+ * With a visibility predicate, callers supply visible note ids and only rows
+ * whose other endpoint is visible count. The indexed selects return neighbour
+ * ids instead of grouped counts; absent the predicate, SQL is unchanged.
  * Returns 0 for ids with no links (every requested id is present in the map).
  */
 export function getLinkCounts(
   db: Database,
   noteIds: string[],
   direction: "both" | "outbound" | "inbound" = "both",
+  visible?: (noteId: string) => boolean,
 ): Map<string, number> {
   const counts = new Map<string, number>();
   if (noteIds.length === 0) return counts;
@@ -290,6 +294,28 @@ export function getLinkCounts(
   for (const chunk of chunkForInClause(ids)) {
     const placeholders = chunk.map(() => "?").join(", ");
 
+    // Scoped callers supply visible page-note ids. Count a row only when
+    // its other endpoint is visible too; a visible self-loop still adds 2.
+    if (visible) {
+      if (wantOutbound) {
+        const rows = db.prepare(
+          `SELECT source_id AS id, target_id AS other FROM links WHERE source_id IN (${placeholders})`,
+        ).all(...chunk) as { id: string; other: string }[];
+        for (const row of rows) {
+          if (visible(row.other)) counts.set(row.id, counts.get(row.id)! + 1);
+        }
+      }
+      if (wantInbound) {
+        const rows = db.prepare(
+          `SELECT target_id AS id, source_id AS other FROM links WHERE target_id IN (${placeholders})`,
+        ).all(...chunk) as { id: string; other: string }[];
+        for (const row of rows) {
+          if (visible(row.other)) counts.set(row.id, counts.get(row.id)! + 1);
+        }
+      }
+      continue;
+    }
+
     if (wantOutbound) {
       const rows = db.prepare(
         `SELECT source_id AS id, COUNT(*) AS c FROM links
@@ -314,6 +340,23 @@ export function getLinkCounts(
   return counts;
 }
 
+/** Lift both has_links polarities from SQL under scope (vault#714). */
+export function sqlHasLinks(wanted: boolean | undefined, scoped: boolean): boolean | undefined {
+  return scoped ? undefined : wanted;
+}
+
+/** Presence and degree share one oracle; narrowing can shorten a scoped page. */
+export function narrowByVisibleLinks<T extends { id: string }>(
+  db: Database,
+  notes: T[],
+  wanted: boolean | undefined,
+  visible: ((noteId: string) => boolean) | undefined,
+): T[] {
+  if (wanted === undefined || !visible || notes.length === 0) return notes;
+  const counts = getLinkCounts(db, notes.map((n) => n.id), "both", visible);
+  return notes.filter((n) => (counts.get(n.id)! > 0) === wanted);
+}
+
 // ---- Deeper Link Queries ----
 
 export interface TraversalNode {

package/core/src/mcp-manifest.ts

@@ -65,6 +65,8 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
 Broken links (vault#555): a \`[[wikilink]]\` or structured \`links\` target that never resolved to a note used to be invisible — silently dropped from the response with no signal it existed. Pass \`has_broken_links: true\`/\`false\` to filter notes by whether they have any dangling outbound link, and/or \`include_broken_links: true\` to attach each note's pending targets as \`broken_links: [{target, relationship}]\` (empty array when none). Both read the vault's pending-resolution table — the same source \`create-note\`/\`update-note\`'s \`unresolved_link\` warning draws from; a target created later (this session or any future one) backfills the edge automatically and the note drops out of \`has_broken_links: true\`.
 
+Ambiguous links (vault#581): the twin of the above, for a target that matched TOO MANY notes rather than none — \`[[Dup]]\` when two notes share that basename or H1 title. No link is created and none is guessed at; before #581 that was visible only in the write-time \`ambiguous_link\` warning, so a later audit couldn't find it. Pass \`has_ambiguous_links: true\`/\`false\` to filter, and/or \`include_ambiguous_links: true\` to attach \`ambiguous_links: [{target, relationship, candidate_count}]\` (empty array when none). Disjoint from \`has_broken_links\`: dangling = matched nothing, ambiguous = matched several. The record is persisted, so it survives restarts — and it self-heals: delete or rename one of the colliding notes and the link resolves for real (the note drops out of \`has_ambiguous_links: true\`); delete them ALL and it demotes to an ordinary broken link. (For a tag-scoped session that demotion has already happened at read time — see \`has_broken_links\`.)
+
 Response shape (vault#550 — three variants, pick by what you passed):
 - Default (no \`cursor\`, no warnings): a bare array of notes.
 - Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
@@ -119,8 +121,9 @@ Response shape (vault#550 — three variants, pick by what you passed):
             description: "Alias for `exclude_tags` (singular). Same shape and semantics — accepts a single tag or an array.",
           },
           has_tags: { type: "boolean", description: "Presence filter: true = only notes with at least one tag; false = only untagged notes. Ignored when `tag` is set." },
-          has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction)." },
-          has_broken_links: { type: "boolean", description: "Presence filter (vault#555): true = only notes with at least one dangling outbound link — a [[wikilink]] or structured `links` target that never resolved to a note; false = only notes with none. Backed by the unresolved_wikilinks table (same data `doctor`/list-unresolved surfaces); safe on a vault where no link has ever gone unresolved (true matches nothing, false is a no-op)." },
+          has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction). For a TAG-SCOPED session both endpoints must be visible. Both polarities are decided after the page is drawn, so a scoped page may be shorter than `limit` while more results remain; this filter does not participate in a scoped cursor query hash." },
+          has_broken_links: { type: "boolean", description: "Presence filter (vault#555): true = only notes with at least one dangling outbound link — a [[wikilink]] or structured `links` target that never resolved to a note; false = only notes with none. Backed by the unresolved_wikilinks table (same data `doctor`/list-unresolved surfaces); safe on a vault where no link has ever gone unresolved (true matches nothing, false is a no-op). For a TAG-SCOPED session both polarities are answered on the notes the session can see (vault#239): a target whose candidates are ALL out of scope matches nothing in that session's sub-vault, so it counts as broken there even though the vault-wide record calls it ambiguous or a content wikilink resolves to an invisible note. Resolved structured links cannot recover the original caller string and are not named as broken — otherwise the note would only become broken once the last invisible candidate was deleted. Decided after the page is drawn, so a scoped page may come back shorter than `limit` while more results remain." },
+          has_ambiguous_links: { type: "boolean", description: "Presence filter (vault#581): true = only notes with at least one AMBIGUOUS outbound link — a [[wikilink]] or structured `links` target that matched TWO OR MORE notes, so no link was created and none was guessed at; false = only notes with none. Disjoint from `has_broken_links` (dangling = matched nothing; ambiguous = matched too much). Backed by the ambiguous_wikilinks table — the same source `create-note`/`update-note`'s `ambiguous_link` warning draws from; safe on a vault where no link has ever been ambiguous (true matches nothing, false is a no-op). For a TAG-SCOPED session both polarities are answered on the notes the session can see — a collision between a visible and an invisible note is neither reported by `true` nor excluded by `false` — so a scoped page may come back shorter than `limit` while more results remain." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
           path_prefix: { type: "string", description: "Path prefix match (e.g., 'Projects/')" },
           exclude_path_prefix: {
@@ -173,7 +176,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           last_updated_by: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write was attributed to this principal. Exact match; indexed." },
           created_via: { type: "string", description: "Write-attribution filter (vault#298): only notes FIRST written through this interface/channel — e.g. `mcp`, `surface:<name>`, `agent:<id>`, `nostr:<64-hex-pubkey>`, `operator`, `api`. `nostr:<pubkey>` (vault#698) is the Nostr key that SIGNED the request, and is the axis that tells two agents apart when they share one hub user (`created_by`). Emitted by BOTH doors — self-hosted hub (parachute-hub#937) and cloud (parachute-cloud#277). Exact match; indexed." },
           last_updated_via: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write came through this interface/channel — same vocabulary as `created_via`, including `nostr:<64-hex-pubkey>` for the signing key. Exact match; indexed." },
-          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Two special values need no declaration: `link_count` sorts by link DEGREE (both-directions raw row count), matching the `include_link_count` field for every note; `updated_at` (vault#585) sorts on the integer `updated_at_ms` mirror column — correct on non-canonical/imported timestamps — with `id` as the tiebreaker. Direction is taken from `sort` (default 'asc'); for other fields `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. Two special values need no declaration: `link_count` sorts by link DEGREE (both-directions raw row count), matching the `include_link_count` field for unscoped both-direction counts. Under tag scope ordering still uses GLOBAL degree and may disagree with `linkCount`; `updated_at` (vault#585) sorts on the integer `updated_at_ms` mirror column — correct on non-canonical/imported timestamps — with `id` as the tiebreaker. Direction is taken from `sort` (default 'asc'); for other fields `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: {
@@ -237,17 +240,18 @@ Response shape (vault#550 — three variants, pick by what you passed):
             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_broken_links: { type: "boolean", description: "Include each note's dangling outbound links as `broken_links: [{target, relationship}]` (default: false; vault#555). `target` is the unresolved path/title the [[wikilink]] or structured `links` entry named; `relationship` is \"wikilink\" for content-parsed links or the caller's own relationship string for a structured link. Empty array when the note has none. One batched query per request regardless of page size — mirrors `has_broken_links` (same backing table) and `include_links`." },
+          include_broken_links: { type: "boolean", description: "Include each note's dangling outbound links as `broken_links: [{target, relationship}]` (default: false; vault#555). `target` is the unresolved path/title the [[wikilink]] or structured `links` entry named; `relationship` is \"wikilink\" for content-parsed links or the caller's own relationship string for a structured link. Empty array when the note has none. One batched query per request regardless of page size — mirrors `has_broken_links` (same backing table) and `include_links`. For a TAG-SCOPED session this also lists a target whose candidates are all out of scope, including a content wikilink resolved to an invisible note (vault#239, vault#714). Resolved structured links to invisible targets are suppressed but not named as broken: their original caller string is no longer stored, and the hidden target path must not be disclosed." },
+          include_ambiguous_links: { type: "boolean", description: "Include each note's ambiguous outbound links as `ambiguous_links: [{target, relationship, candidate_count}]` (default: false; vault#581). `target` is the path/title the [[wikilink]] or structured `links` entry named; `relationship` is \"wikilink\" for content-parsed links or the caller's own relationship string; `candidate_count` is how many notes it matched. For a TAG-SCOPED session the candidates are re-counted within the session's scope, and a target with fewer than two visible candidates is omitted — a scoped reader gets exactly what an unscoped one would get on a vault holding only the notes it can see. Empty array when the note has none. One batched query per request regardless of page size — mirrors `has_ambiguous_links` (same backing table) and `include_broken_links`." },
           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.",
+              "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, only edges with BOTH endpoints visible count, in every direction; a visible self-loop still counts as 2. Scoped counts select neighbour ids over the same indexes; unscoped counts are unchanged.",
           },
           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.",
+              "Which edges `include_link_count` counts: both (default), outbound only (source_id), or inbound only (target_id). For tag-scoped tokens only edges with both endpoints visible count in all three directions. order_by=link_count always uses GLOBAL both-directions degree, even under scope, and may disagree with linkCount.",
           },
           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." },

package/core/src/mcp.ts

@@ -23,7 +23,15 @@ import {
   resolveStructuredLinkNote,
   getUnresolvedLinksForNote,
   getUnresolvedLinksForNotes,
+  narrowByVisibleBrokenness,
+  sqlHasBrokenLinks,
+  getAmbiguousLinksForNote,
+  getAmbiguousLinksForNotes,
+  narrowByVisibleAmbiguity,
+  sqlHasAmbiguousLinks,
   getContentWikilinkWarnings,
+  ambiguousLinkWarning,
+  unresolvedLinkWarning,
 } from "./wikilinks.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -143,6 +151,17 @@ function structuredError(
   return Object.assign(new Error(message), fields);
 }
 
+function requireNoteReference(value: unknown): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw structuredError("`id` is required", {
+      error_type: "missing_required_field",
+      field: "id",
+      hint: "pass the note's id or path (or its unique H1 title)",
+    });
+  }
+  return value;
+}
+
 /**
  * Resolve a note identifier — tries ID first, then case-insensitive
  * path match, then (additive fallback) an H1-title match. Works
@@ -470,6 +489,23 @@ export interface GenerateMcpToolsOpts {
    * path with no extra fetch.
    */
   aggregateVisibility?: (note: Note) => boolean;
+  /**
+   * `ambiguityVisible` (vault#581 auth review) is an OPTIONAL per-note
+   * predicate gating everything the ambiguous-links surface discloses.
+   * `candidate_count` is derived VAULT-WIDE, so a stored `2` on a `[[Dup]]`
+   * split across scopes tells a tag-scoped reader that a note it cannot see
+   * exists — and `has_ambiguous_links: true` would let it sweep its whole
+   * in-scope corpus for such collisions. When provided, each persisted row
+   * is re-resolved and its candidates narrowed to the visible ones: a row
+   * is disclosed only when ≥2 remain, `candidate_count` is the visible
+   * count, and `has_ambiguous_links` is answered against that same narrowed
+   * view (see `narrowByVisibleAmbiguity` / `sqlHasAmbiguousLinks` in
+   * core/src/wikilinks.ts). Same contract as `nearTraversable`: core stays
+   * scope-unaware and only invokes the injected `(noteId) => boolean`
+   * closure. Omitted (unscoped / internal callers) → the persisted counts
+   * are returned as-is and the SQL filter answers directly, unchanged.
+   */
+  ambiguityVisible?: (noteId: string) => boolean;
   /**
    * `AttachmentTicketProvider` seam (vault attachment-tickets design,
    * Wave 1 — D10 "tools omitted when unwired"). When provided,
@@ -549,6 +585,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
   const nearTraversable = opts?.nearTraversable;
   const ifExistsVisible = opts?.ifExistsVisible;
   const aggregateVisibility = opts?.aggregateVisibility;
+  const ambiguityVisible = opts?.ambiguityVisible;
   // Write-attribution (vault#298) — captured once at tool-generation time
   // (a fresh tool set is generated per MCP request, so this is request-scoped)
   // and folded into every create/update the tools perform.
@@ -600,6 +637,32 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     {
       name: "query-notes",
       execute: async (params) => {
+        // --- Ambiguous-links scope split (vault#581 auth review) ---
+        // `requestedHasAmbiguous` is what the caller asked for;
+        // `sqlHasAmbiguous` is what is safe to push into SQL for a reader
+        // that will be narrowed by `narrowByVisibleAmbiguity` afterwards
+        // (`true` is a superset and stays; `false` is lifted). Identical for
+        // an unscoped reader, where no predicate is injected and the SQL
+        // filter alone is the whole answer.
+        const requestedHasAmbiguous = params.has_ambiguous_links as boolean | undefined;
+        const sqlHasAmbiguous = sqlHasAmbiguousLinks(requestedHasAmbiguous, Boolean(ambiguityVisible));
+
+        // --- Broken-links scope split (vault#239) ---
+        // Same shape as the ambiguity split above, one polarity stricter:
+        // NEITHER `true` nor `false` is safe to push into SQL for a scoped
+        // reader, because a note can be broken in that reader's sub-vault
+        // while carrying no `unresolved_wikilinks` row at all (its target's
+        // only candidates are invisible, so the row sits in
+        // `ambiguous_wikilinks`). `sqlHasBrokenLinks` lifts both and
+        // `narrowByVisibleBrokenness` re-decides per note. Identical for an
+        // unscoped reader, where the SQL filter alone is the whole answer.
+        const requestedHasBroken = params.has_broken_links as boolean | undefined;
+        const sqlHasBroken = sqlHasBrokenLinks(requestedHasBroken, Boolean(ambiguityVisible));
+
+        // vault#714: degree and presence use the same visible-edge count.
+        const requestedHasLinks = params.has_links as boolean | undefined;
+        const sqlLinks = linkOps.sqlHasLinks(requestedHasLinks, Boolean(ambiguityVisible));
+
         // --- Link expansion config (shared across single + list paths) ---
         const expandLinks = params.expand_links === true;
         const expandMode = (params.expand_mode as ExpandMode) ?? "full";
@@ -671,7 +734,10 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             result.links = linkOps.getLinksHydrated(db, note.id);
           }
           if (params.include_broken_links) {
-            result.broken_links = getUnresolvedLinksForNote(db, note.id);
+            result.broken_links = getUnresolvedLinksForNote(db, note.id, ambiguityVisible);
+          }
+          if (params.include_ambiguous_links) {
+            result.ambiguous_links = getAmbiguousLinksForNote(db, note.id, ambiguityVisible);
           }
           if (params.include_attachments) {
             result.attachments = await store.getAttachments(note.id);
@@ -680,7 +746,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           // 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;
+            result.linkCount = linkOps.getLinkCounts(db, [note.id], dir, ambiguityVisible).get(note.id) ?? 0;
           }
           return result;
         }
@@ -815,8 +881,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             expand,
             excludeTags: aggExcludeTags,
             hasTags: params.has_tags as boolean | undefined,
-            hasLinks: params.has_links as boolean | undefined,
-            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            hasLinks: sqlLinks,
+            hasBrokenLinks: sqlHasBroken,
+            hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -842,7 +909,28 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           // set (reusing the `ids` semijoin `near` already pushes into SQL).
           // Core stays scope-unaware — it only invokes the plain closure.
           const aggAllMatches = await store.queryNotes({ ...aggFilterOpts, limit: 1000000 });
-          const aggVisibleIds = aggAllMatches.filter(aggregateVisibility).map((n) => n.id);
+          // vault#581 auth review: a rollup over `has_ambiguous_links` is the
+          // same oracle as the note-level filter (a non-zero count still
+          // reveals the collision), so narrow the visible id set by the
+          // reader's own view of each row before aggregating.
+          // vault#239: the `has_broken_links` rollup is the same oracle for
+          // the same reason — re-decide brokenness on the sub-vault too.
+          const aggVisibleIds = linkOps.narrowByVisibleLinks(
+            db,
+            narrowByVisibleBrokenness(
+              db,
+              narrowByVisibleAmbiguity(
+                db,
+                aggAllMatches.filter(aggregateVisibility),
+                requestedHasAmbiguous,
+                ambiguityVisible,
+              ),
+              requestedHasBroken,
+              ambiguityVisible,
+            ),
+            requestedHasLinks,
+            ambiguityVisible,
+          ).map((n) => n.id);
           // Always run the rollup, even on an empty visible set: ungrouped
           // count (vault#626) must return `[{group:null,value:0}]`, not `[]`.
           return await store.aggregateNotes({ ids: aggVisibleIds, aggregate: aggregateSpec });
@@ -938,8 +1026,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             expand,
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
-            hasLinks: params.has_links as boolean | undefined,
-            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            hasLinks: sqlLinks,
+            hasBrokenLinks: sqlHasBroken,
+            hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -1021,8 +1110,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               expand,
               excludeTags,
               hasTags: params.has_tags as boolean | undefined,
-              hasLinks: params.has_links as boolean | undefined,
-              hasBrokenLinks: params.has_broken_links as boolean | undefined,
+              hasLinks: sqlLinks,
+              hasBrokenLinks: sqlHasBroken,
+              hasAmbiguousLinks: sqlHasAmbiguous,
               path: params.path as string | undefined,
               pathPrefix: params.path_prefix as string | undefined,
               excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -1090,8 +1180,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             expand,
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
-            hasLinks: params.has_links as boolean | undefined,
-            hasBrokenLinks: params.has_broken_links as boolean | undefined,
+            hasLinks: sqlLinks,
+            hasBrokenLinks: sqlHasBroken,
+            hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
             excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
@@ -1148,6 +1239,18 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           results = results.filter((n) => nearScope!.has(n.id));
         }
 
+        // vault#581 auth review — the `has_ambiguous_links` filter must
+        // answer on the reader's OWN sub-vault, not the whole vault. No-op
+        // unscoped (no predicate injected) and when the filter wasn't asked
+        // for. See `narrowByVisibleAmbiguity` for the superset contract and
+        // the page-shortening effect.
+        results = narrowByVisibleAmbiguity(db, results, requestedHasAmbiguous, ambiguityVisible);
+        // vault#239 — same rule for `has_broken_links`: the SQL filter was
+        // lifted for a scoped reader, so the real predicate is applied here
+        // on that reader's own sub-vault. No-op unscoped.
+        results = narrowByVisibleBrokenness(db, results, requestedHasBroken, ambiguityVisible);
+        results = linkOps.narrowByVisibleLinks(db, results, requestedHasLinks, ambiguityVisible);
+
         // --- Format output ---
         const includeContent = params.include_content === true; // default false for list
         // Range params require content in the response — on lists that
@@ -1214,12 +1317,12 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         // 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);
+          const counts = linkOps.getLinkCounts(db, output.map((n: any) => n.id), dir, ambiguityVisible);
           for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
         }
 
         // --- Hydrate links/attachments/broken-links per note if requested ---
-        if (params.include_links || params.include_attachments || params.include_broken_links) {
+        if (params.include_links || params.include_attachments || params.include_broken_links || params.include_ambiguous_links) {
           // 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
@@ -1229,13 +1332,18 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             : null;
           // Same one-batched-query-for-the-page shape as links (vault#555).
           const brokenLinksByNote = params.include_broken_links
-            ? getUnresolvedLinksForNotes(db, (output as any[]).map((n: any) => n.id))
+            ? getUnresolvedLinksForNotes(db, (output as any[]).map((n: any) => n.id), ambiguityVisible)
+            : null;
+          // Same one-batched-query-for-the-page shape for the ambiguity twin (vault#581).
+          const ambiguousLinksByNote = params.include_ambiguous_links
+            ? getAmbiguousLinksForNotes(db, (output as any[]).map((n: any) => n.id), ambiguityVisible)
             : null;
           const enrichedOut: any[] = [];
           for (const n of output as any[]) {
             const enriched: any = { ...n };
             if (linksByNote) enriched.links = linksByNote.get(n.id) ?? [];
             if (brokenLinksByNote) enriched.broken_links = brokenLinksByNote.get(n.id) ?? [];
+            if (ambiguousLinksByNote) enriched.ambiguous_links = ambiguousLinksByNote.get(n.id) ?? [];
             if (params.include_attachments) enriched.attachments = await store.getAttachments(n.id);
             enrichedOut.push(enriched);
           }
@@ -1559,20 +1667,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               if (outcome.status === "resolved") {
                 await store.createLink(sourceId, outcome.note_id, link.relationship);
               } else if (outcome.status === "ambiguous") {
-                pushLinkWarning(sourceId, {
-                  code: "ambiguous_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") matched ${outcome.candidates.length} notes — ambiguous, no link created. Use a more specific path or the note's ID to disambiguate.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                  candidate_count: outcome.candidates.length,
-                });
+                pushLinkWarning(sourceId, ambiguousLinkWarning(link.target, link.relationship, outcome.candidates.length));
               } else {
-                pushLinkWarning(sourceId, {
-                  code: "unresolved_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                });
+                pushLinkWarning(sourceId, unresolvedLinkWarning(link.target, link.relationship));
               }
             }
           }
@@ -1730,7 +1827,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             // branch using this same item's payload. Otherwise mirror the
             // existing `requireNote` behavior (throw "Note not found").
             // vault#309.
-            const resolved = resolveNote(db, item.id as string);
+            const idOrPath = requireNoteReference(item.id);
+            const resolved = resolveNote(db, idOrPath);
             if (!resolved) {
               if (item.if_missing === "create") {
                 // Treat the update payload as a create payload. Minimum:
@@ -1765,7 +1863,6 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
                 //     processed and used by Gitcoin's sync; the
                 //     misleading wording is fixed here so a future
                 //     reader doesn't trust it and break the workflow.
-                const idOrPath = item.id as string;
                 // Heuristic: if `path` isn't set AND the `id` looks like a
                 // path (contains "/" or doesn't match a typical opaque-id
                 // shape), use it as the path too. Otherwise treat it as a
@@ -2118,20 +2215,9 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               if (outcome.status === "resolved") {
                 await store.createLink(sourceId, outcome.note_id, link.relationship, link.metadata);
               } else if (outcome.status === "ambiguous") {
-                pushLinkWarning(sourceId, {
-                  code: "ambiguous_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") matched ${outcome.candidates.length} notes — ambiguous, no link created. Use a more specific path or the note's ID to disambiguate.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                  candidate_count: outcome.candidates.length,
-                });
+                pushLinkWarning(sourceId, ambiguousLinkWarning(link.target, link.relationship, outcome.candidates.length));
               } else {
-                pushLinkWarning(sourceId, {
-                  code: "unresolved_link",
-                  message: `link target "${link.target}" (relationship "${link.relationship}") did not resolve to any note — queued and will backfill automatically if a matching note is created later.`,
-                  target: link.target,
-                  relationship: link.relationship,
-                });
+                pushLinkWarning(sourceId, unresolvedLinkWarning(link.target, link.relationship));
               }
             }
           }
@@ -2193,7 +2279,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     {
       name: "delete-note",
       execute: async (params) => {
-        const note = requireNote(db, params.id as string);
+        const note = requireNote(db, requireNoteReference(params.id));
         await store.deleteNote(note.id);
         return { deleted: true, id: note.id };
       },
@@ -3032,4 +3118,3 @@ export class BatchTooLargeError extends Error {
     this.got = got;
   }
 }
-

package/core/src/notes.ts

@@ -1053,8 +1053,9 @@ export function buildFilterConditions(db: Database, opts: QueryOpts): { conditio
   // Presence: has_broken_links (vault#555) — a dangling outbound wikilink or
   // structured `links` target that never resolved. The `unresolved_wikilinks`
   // table is created lazily (see wikilinks.ts:ensureUnresolvedTable) only when
-  // a link actually goes unresolved — a vault where nothing ever has won't
-  // have the table at all. Check existence first rather than reference it
+  // a link actually goes unresolved — migrateToV28 heals a pre-#555 2-column
+  // table at boot but does NOT create the table on a vault that never queued
+  // one. Check existence first rather than reference it
   // unconditionally: a read-only query filter shouldn't have the side effect
   // of creating a table, and a bare `EXISTS`/`NOT EXISTS` against a missing
   // table would throw "no such table" instead of the correct empty answer.
@@ -1076,6 +1077,28 @@ export function buildFilterConditions(db: Database, opts: QueryOpts): { conditio
     }
   }
 
+  // Presence: has_ambiguous_links (vault#581) — an outbound `[[wikilink]]` or
+  // structured `links`/`reference` target that matched ≥2 notes, so no link
+  // was created. Same lazily-created-table dance as `has_broken_links` above
+  // (`ambiguous_wikilinks` is only created once a link actually goes
+  // ambiguous), and for the same reasons: a read-only filter must not create
+  // the table, and a bare EXISTS against a missing one throws instead of
+  // answering "none".
+  if (opts.hasAmbiguousLinks !== undefined) {
+    const ambiguousTableExists = db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'ambiguous_wikilinks'",
+    ).get() !== null;
+    if (!ambiguousTableExists) {
+      if (opts.hasAmbiguousLinks) conditions.push("0 = 1");
+    } else {
+      conditions.push(
+        opts.hasAmbiguousLinks
+          ? `EXISTS (SELECT 1 FROM ambiguous_wikilinks ual WHERE ual.source_id = n.id)`
+          : `NOT EXISTS (SELECT 1 FROM ambiguous_wikilinks ual WHERE ual.source_id = n.id)`,
+      );
+    }
+  }
+
   // ID set filter — used by `near` to push neighborhood scoping into SQL so
   // that LIMIT applies to the neighborhood, not the whole notes table.
   if (opts.ids !== undefined) {
@@ -1694,6 +1717,7 @@ function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
     hasTags: opts.hasTags,
     hasLinks: opts.hasLinks,
     hasBrokenLinks: opts.hasBrokenLinks,
+    hasAmbiguousLinks: opts.hasAmbiguousLinks,
     path: opts.path,
     pathPrefix: opts.pathPrefix,
     excludePathPrefix: opts.excludePathPrefix,
@@ -2767,6 +2791,8 @@ export function mergeTags(
     const deleteNoteTagsStmt = db.prepare("DELETE FROM note_tags WHERE tag_name = ?");
     const deleteTagStmt = db.prepare("DELETE FROM tags WHERE name = ?");
     const countStmt = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?");
+    const sourceNoteIdsStmt = db.prepare("SELECT note_id FROM note_tags WHERE tag_name = ?");
+    const affectedIds = new Set<string>();
 
     for (const source of uniqueSources) {
       const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(source);
@@ -2775,6 +2801,11 @@ export function mergeTags(
         continue;
       }
       const before = (countStmt.get(source) as { c: number }).c;
+      // Collect BEFORE the delete so we can bump updated_at on every note
+      // whose tags actually change (vault#567).
+      for (const row of sourceNoteIdsStmt.all(source) as { note_id: string }[]) {
+        affectedIds.add(row.note_id);
+      }
       retagStmt.run(target, source);
       deleteNoteTagsStmt.run(source);
       // Dropping the tag row drops its identity (description, fields,
@@ -2783,6 +2814,24 @@ export function mergeTags(
       deleteTagStmt.run(source);
       merged[source] = before;
     }
+
+    // vault#567: a tags-only `update-note` already bumps `updated_at` so
+    // cursor/sync consumers see the retag. `merge-tags` used to skip the
+    // bump (flood-avoidance), which made the equivalent bulk retag
+    // invisible to since-last-check loops. Bump every note that actually
+    // lost a source tag; notes that never carried a merged-away source
+    // are left untouched. `updated_at_ms` moves with `updated_at`
+    // (vault#586) so the cursor keyset surfaces the change.
+    if (affectedIds.size > 0) {
+      const now = new Date().toISOString();
+      const nowMs = timestampToMs(now) ?? Date.now();
+      const bumpStmt = db.prepare(
+        "UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?",
+      );
+      for (const id of affectedIds) {
+        bumpStmt.run(now, nowMs, id);
+      }
+    }
   });
 
   return { merged, target };