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

package/core/src/link-count.test.ts

@@ -299,3 +299,32 @@ describe("query-notes MCP surface: include_link_count", () => {
     for (const n of ordered) expect(typeof n.linkCount).toBe("number");
   });
 });
+
+
+describe("vault#714 scoped link degree", () => {
+  async function seedScope() {
+    for (const id of ["a", "b", "hidden"]) await store.createNote(id, { id });
+    await store.createLink("a", "b", "visible");
+    await store.createLink("a", "hidden", "hidden-out");
+    await store.createLink("hidden", "a", "hidden-in");
+  }
+  for (const [direction, expected] of [["both", 1], ["outbound", 1], ["inbound", 0]] as const) {
+    it(`vault#714 scoped ${direction}`, async () => {
+      await seedScope();
+      expect(getLinkCounts(db, ["a"], direction, (id) => id !== "hidden").get("a")).toBe(expected);
+    });
+  }
+  it("vault#714 visible self-loop remains degree two", async () => {
+    await seedScope(); await store.createLink("b", "b", "self");
+    expect(getLinkCounts(db, ["b"], "both", (id) => id === "b").get("b")).toBe(2);
+  });
+  it("vault#714 absent predicate preserves global degree", async () => {
+    await seedScope();
+    expect(getLinkCounts(db, ["a"], "both")).toEqual(new Map([["a", 3]]));
+    expect(getLinkCounts(db, ["a"], "both", undefined)).toEqual(getLinkCounts(db, ["a"], "both"));
+  });
+  it("vault#714 repeated ids and typed rows retain row-count semantics", async () => {
+    await seedScope(); await store.createLink("a", "b", "second");
+    expect(getLinkCounts(db, ["a", "a"], "both", (id) => id !== "hidden").get("a")).toBe(2);
+  });
+});

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

@@ -121,8 +121,8 @@ 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). 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 — 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_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/')" },
@@ -176,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: {
@@ -240,18 +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`. For a TAG-SCOPED session this also lists a target whose candidates are all out of scope, which is broken in that session's sub-vault (vault#239)." },
+          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

@@ -659,6 +659,10 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         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";
@@ -742,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;
         }
@@ -877,7 +881,7 @@ 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,
+            hasLinks: sqlLinks,
             hasBrokenLinks: sqlHasBroken,
             hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
@@ -911,15 +915,20 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           // 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 = narrowByVisibleBrokenness(
+          const aggVisibleIds = linkOps.narrowByVisibleLinks(
             db,
-            narrowByVisibleAmbiguity(
+            narrowByVisibleBrokenness(
               db,
-              aggAllMatches.filter(aggregateVisibility),
-              requestedHasAmbiguous,
+              narrowByVisibleAmbiguity(
+                db,
+                aggAllMatches.filter(aggregateVisibility),
+                requestedHasAmbiguous,
+                ambiguityVisible,
+              ),
+              requestedHasBroken,
               ambiguityVisible,
             ),
-            requestedHasBroken,
+            requestedHasLinks,
             ambiguityVisible,
           ).map((n) => n.id);
           // Always run the rollup, even on an empty visible set: ungrouped
@@ -1017,7 +1026,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             expand,
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
-            hasLinks: params.has_links as boolean | undefined,
+            hasLinks: sqlLinks,
             hasBrokenLinks: sqlHasBroken,
             hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
@@ -1101,7 +1110,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               expand,
               excludeTags,
               hasTags: params.has_tags as boolean | undefined,
-              hasLinks: params.has_links as boolean | undefined,
+              hasLinks: sqlLinks,
               hasBrokenLinks: sqlHasBroken,
               hasAmbiguousLinks: sqlHasAmbiguous,
               path: params.path as string | undefined,
@@ -1171,7 +1180,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             expand,
             excludeTags,
             hasTags: params.has_tags as boolean | undefined,
-            hasLinks: params.has_links as boolean | undefined,
+            hasLinks: sqlLinks,
             hasBrokenLinks: sqlHasBroken,
             hasAmbiguousLinks: sqlHasAmbiguous,
             path: params.path as string | undefined,
@@ -1240,6 +1249,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         // 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
@@ -1307,7 +1317,7 @@ 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;
         }
 

package/core/src/wikilinks.ts

@@ -492,6 +492,42 @@ export function listZeroVisibleAmbiguousAsUnresolved(
   return out;
 }
 
+/**
+ * Resolved-to-invisible content wikilinks, shaped for the scoped unresolved
+ * listing (vault#714). Bounded and non-exhaustive: scan at most 2000 edges,
+ * fetch content only for sources with a hidden target, and stop at limit.
+ * Structured links cannot recover their original caller string from links;
+ * never disclose the hidden target's stored path as a replacement.
+ */
+export function listResolvedToInvisibleAsUnresolved(
+  db: Database,
+  visible: (noteId: string) => boolean,
+  limit = 50,
+): UnresolvedWikilink[] {
+  if (limit <= 0) return [];
+  const rows = db.prepare(
+    "SELECT source_id, target_id, relationship FROM links ORDER BY source_id, target_id LIMIT ?",
+  ).all(Math.min(2000, Math.max(200, limit * 20))) as { source_id: string; target_id: string; relationship: string }[];
+  const sources = new Set<string>();
+  const out: UnresolvedWikilink[] = [];
+  for (const row of rows) {
+    if (visible(row.target_id) || sources.has(row.source_id)) continue;
+    sources.add(row.source_id);
+    const note = db.prepare("SELECT path, content FROM notes WHERE id = ?").get(row.source_id) as { path: string | null; content: string } | null;
+    if (!note) continue;
+    const seen = new Set<string>();
+    for (const { target } of parseWikilinks(note.content)) {
+      if (visibleResolutionCount(db, target, WIKILINK_REL, visible) > 0) continue;
+      const key = target.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ source_id: row.source_id, source_path: note.path ?? undefined, target_path: target, relationship: WIKILINK_REL });
+      if (out.length >= limit) return out;
+    }
+  }
+  return out;
+}
+
 /** One note's dangling outbound link, as surfaced on a note read (vault#555). */
 export interface BrokenLink {
   target: string;
@@ -522,7 +558,10 @@ export interface BrokenLink {
  *
  * Cost: one extra query plus one re-resolution per ambiguous row, and only
  * for scoped readers — the same profile the ambiguity surface accepts, on a
- * table that is rare by nature. An unscoped reader does no extra work.
+ * table that is rare by nature. Scoped reads also scan outbound edges for
+ * the requested page, fetching content only for sources with hidden targets
+ * and re-resolving their own bracket text (vault#714). An unscoped reader
+ * does no extra work.
  */
 export function getUnresolvedLinksForNotes(
   db: Database,
@@ -573,6 +612,34 @@ export function getUnresolvedLinksForNotes(
       seen.add(key);
       result.get(row.source_id)?.push({ target: row.target_path, relationship });
     }
+
+    // vault#714: the persisted edge may resolve only to a hidden note.
+    // Reparse the source's own brackets, never the hidden target's path.
+    const hiddenTargetSources = new Set<string>();
+    for (const chunk of chunkForInClause(noteIds)) {
+      const placeholders = chunk.map(() => "?").join(", ");
+      const links = db.prepare(
+        `SELECT source_id, target_id FROM links WHERE source_id IN (${placeholders})`,
+      ).all(...chunk) as { source_id: string; target_id: string }[];
+      for (const link of links) {
+        if (!visible(link.target_id)) hiddenTargetSources.add(link.source_id);
+      }
+    }
+    for (const chunk of chunkForInClause([...hiddenTargetSources])) {
+      const placeholders = chunk.map(() => "?").join(", ");
+      const notes = db.prepare(
+        `SELECT id, content FROM notes WHERE id IN (${placeholders})`,
+      ).all(...chunk) as { id: string; content: string }[];
+      for (const note of notes) {
+        for (const { target } of parseWikilinks(note.content)) {
+          if (visibleResolutionCount(db, target, WIKILINK_REL, visible) > 0) continue;
+          const key = `${note.id}\u0000${WIKILINK_REL}\u0000${target.toLowerCase()}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          result.get(note.id)?.push({ target, relationship: WIKILINK_REL });
+        }
+      }
+    }
   }
   return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.9-rc.3",
+  "version": "0.7.9-rc.4",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/release-plan.test.ts

@@ -11,8 +11,10 @@
 import { describe, expect, test } from "bun:test";
 import {
   compareVersions,
+  coreVersion,
   decidePublish,
   distTagFor,
+  matchingRcVersions,
   readRegistry,
   unpublishedDrift,
 } from "../scripts/release-plan.ts";
@@ -193,13 +195,81 @@ describe("decidePublish", () => {
       {
         versionExists: false,
         currentDistTagVersion: "0.7.8",
-        publishedVersions: ["0.7.8"],
+        publishedVersions: ["0.7.8", "0.7.9-rc.1"],
       },
       { branch: "main" },
     );
     expect(d).toMatchObject({ publish: true });
   });
 
+  test("a stable without a matching rc is refused — vault#697", () => {
+    // Hub 0.7.13–0.7.16 shipped @latest with no rc of the same X.Y.Z.
+    // Vault's previous plan (and the inline shell it replaced) did the same.
+    const d = decidePublish(
+      "0.7.9",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.8",
+        publishedVersions: ["0.7.8", "0.7.8-rc.2"],
+      },
+      { branch: "main" },
+    );
+    expect(d).toMatchObject({ refuse: true });
+    expect("refuse" in d && d.reason).toMatch(/0\.7\.9-rc/);
+    expect("refuse" in d && d.reason).toMatch(/suffix-drop|Cut an rc first/i);
+  });
+
+  test("a stable whose only published rcs are a different X.Y.Z is still refused", () => {
+    const d = decidePublish(
+      "0.7.9",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.8",
+        publishedVersions: ["0.7.8", "0.7.8-rc.1"],
+      },
+      { branch: "main" },
+    );
+    expect(d).toMatchObject({ refuse: true });
+  });
+
+  test("a stable with a matching rc publishes from main", () => {
+    const d = decidePublish(
+      "0.7.9",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.8",
+        publishedVersions: ["0.7.8", "0.7.9-rc.1"],
+      },
+      { branch: "main" },
+    );
+    expect(d).toMatchObject({ publish: true });
+  });
+
+  test("omitted publishedVersions still refuses a stable when latest already exists", () => {
+    const d = decidePublish(
+      "0.7.9",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.8",
+      },
+      { branch: "main" },
+    );
+    expect(d).toMatchObject({ refuse: true });
+  });
+
+  test("an rc publishes even with no prior rc of the same core", () => {
+    const d = decidePublish(
+      "0.7.9-rc.1",
+      {
+        versionExists: false,
+        currentDistTagVersion: "0.7.8-rc.5",
+        publishedVersions: ["0.7.8", "0.7.8-rc.5"],
+      },
+      { branch: "next" },
+    );
+    expect(d).toMatchObject({ publish: true });
+  });
+
   test("a tag push of a stable does NOT override the main-only gate", () => {
     const d = decidePublish(
       "0.7.9",
@@ -281,6 +351,25 @@ describe("readRegistry", () => {
   });
 });
 
+describe("matchingRcVersions", () => {
+  test("matches only the same X.Y.Z rc chain", () => {
+    expect(
+      matchingRcVersions("0.7.9", ["0.7.8", "0.7.8-rc.1", "0.7.9-rc.1", "0.7.9-rc.2"]),
+    ).toEqual(["0.7.9-rc.1", "0.7.9-rc.2"]);
+  });
+
+  test("a prerelease still matches siblings of its core", () => {
+    expect(matchingRcVersions("0.7.9-rc.3", ["0.7.9-rc.1", "0.7.8-rc.1"])).toEqual(["0.7.9-rc.1"]);
+  });
+});
+
+describe("coreVersion", () => {
+  test("strips the rc suffix and leaves a stable alone", () => {
+    expect(coreVersion("0.7.9-rc.1")).toBe("0.7.9");
+    expect(coreVersion("0.7.9")).toBe("0.7.9");
+  });
+});
+
 describe("unpublishedDrift", () => {
   test("no commits → not drifted", () => {
     expect(unpublishedDrift([]).drifted).toBe(false);

package/src/routes.ts

@@ -32,6 +32,7 @@ import {
   getUnresolvedLinksForNote,
   getUnresolvedLinksForNotes,
   listZeroVisibleAmbiguousAsUnresolved,
+  listResolvedToInvisibleAsUnresolved,
   narrowByVisibleBrokenness,
   sqlHasBrokenLinks,
   getAmbiguousLinksForNote,
@@ -1026,7 +1027,7 @@ export function parseNotesQueryOpts(url: URL, tagScope: TagScopeCtx = NO_TAG_SCO
     expand,
     excludeTags: parseQueryList(url, "exclude_tag"),
     hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
-    hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
+    hasLinks: linkOps.sqlHasLinks(parseBoolOrUndef(parseQuery(url, "has_links")), tagScope.raw !== null),
     // Presence filter on dangling outbound wikilinks/structured links
     // (vault#555) — see core/src/types.ts QueryOpts.hasBrokenLinks.
     // vault#239: for a TAG-SCOPED reader NEITHER polarity is safe to push
@@ -1376,7 +1377,7 @@ async function handleNotesInner(
         // linkCount injected after filterMetadata on purpose — same as
         // links/attachments above; filterMetadata only touches `metadata`.
         if (parseBool(parseQuery(url, "include_link_count"), false)) {
-          result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url)).get(note.id) ?? 0;
+          result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url), ambiguityVisibilityFor(db, tagScope)).get(note.id) ?? 0;
         }
         return json(result);
       }
@@ -1451,7 +1452,26 @@ async function handleNotesInner(
               embeddingsPendingWarning(semanticResult.pendingCount, semanticResult.totalCandidates),
             );
           }
-          const filtered = filterNotesByTagScope(semanticResult.notes, tagScope.allowed, tagScope.raw);
+          let filtered = filterNotesByTagScope(semanticResult.notes, tagScope.allowed, tagScope.raw);
+          // Apply the same scoped presence filters as the structured list.
+          filtered = narrowByVisibleAmbiguity(
+            db,
+            filtered,
+            parseBoolOrUndef(parseQuery(url, "has_ambiguous_links")),
+            ambiguityVisibilityFor(db, tagScope),
+          );
+          filtered = narrowByVisibleBrokenness(
+            db,
+            filtered,
+            parseBoolOrUndef(parseQuery(url, "has_broken_links")),
+            ambiguityVisibilityFor(db, tagScope),
+          );
+          filtered = linkOps.narrowByVisibleLinks(
+            db,
+            filtered,
+            parseBoolOrUndef(parseQuery(url, "has_links")),
+            ambiguityVisibilityFor(db, tagScope),
+          );
           const includeContent = parseBool(parseQuery(url, "include_content"), false);
           const contentRange = parseContentRangeQuery(url, includeContent);
           if (contentRange.error) return contentRange.error;
@@ -1477,7 +1497,7 @@ async function handleNotesInner(
             output = output.map((n: any) => filterMetadata(n, inclMeta));
           }
           if (parseBool(parseQuery(url, "include_link_count"), false)) {
-            const counts = linkOps.getLinkCounts(db, output.map((n: any) => n.id), parseLinkCountDirection(url));
+            const counts = linkOps.getLinkCounts(db, output.map((n: any) => n.id), parseLinkCountDirection(url), ambiguityVisibilityFor(db, tagScope));
             for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
           }
           return jsonWithWarnings(output, semanticWarnings);
@@ -1646,7 +1666,26 @@ async function handleNotesInner(
         // Tag-scope: drop any result the token isn't permitted to see. Filter
         // happens after the store query so an empty post-filter list still
         // returns 200 [] (consistent with "no matches"), not 403.
-        const results = filterNotesByTagScope(rawResults, tagScope.allowed, tagScope.raw);
+        let results = filterNotesByTagScope(rawResults, tagScope.allowed, tagScope.raw);
+        // Apply the same scoped presence filters as the structured list.
+        results = narrowByVisibleAmbiguity(
+          db,
+          results,
+          parseBoolOrUndef(parseQuery(url, "has_ambiguous_links")),
+          ambiguityVisibilityFor(db, tagScope),
+        );
+        results = narrowByVisibleBrokenness(
+          db,
+          results,
+          parseBoolOrUndef(parseQuery(url, "has_broken_links")),
+          ambiguityVisibilityFor(db, tagScope),
+        );
+        results = linkOps.narrowByVisibleLinks(
+          db,
+          results,
+          parseBoolOrUndef(parseQuery(url, "has_links")),
+          ambiguityVisibilityFor(db, tagScope),
+        );
         const includeContent = parseBool(parseQuery(url, "include_content"), false);
         const contentRange = parseContentRangeQuery(url, includeContent);
         if (contentRange.error) return contentRange.error;
@@ -1680,6 +1719,7 @@ async function handleNotesInner(
             db,
             output.map((n: any) => n.id),
             parseLinkCountDirection(url),
+            ambiguityVisibilityFor(db, tagScope),
           );
           for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
         }
@@ -1807,6 +1847,12 @@ async function handleNotesInner(
               parseBoolOrUndef(parseQuery(url, "has_broken_links")),
               ambiguityVisibilityFor(db, tagScope),
             );
+            visible = linkOps.narrowByVisibleLinks(
+              db,
+              visible,
+              parseBoolOrUndef(parseQuery(url, "has_links")),
+              ambiguityVisibilityFor(db, tagScope),
+            );
             // Always run the rollup, even on an empty visible set: ungrouped
             // count (vault#626) must return `[{group:null,value:0}]`, not `[]`.
             rows = await store.aggregateNotes({ ids: visible.map((n) => n.id), aggregate: aggregateParsed.aggregate });
@@ -1980,6 +2026,12 @@ async function handleNotesInner(
         parseBoolOrUndef(parseQuery(url, "has_broken_links")),
         ambiguityVisibilityFor(db, tagScope),
       );
+      results = linkOps.narrowByVisibleLinks(
+        db,
+        results,
+        parseBoolOrUndef(parseQuery(url, "has_links")),
+        ambiguityVisibilityFor(db, tagScope),
+      );
 
       const includeContent = parseBool(parseQuery(url, "include_content"), false);
       const contentRange = parseContentRangeQuery(url, includeContent);
@@ -2059,6 +2111,7 @@ async function handleNotesInner(
           db,
           output.map((n: any) => n.id),
           parseLinkCountDirection(url),
+          ambiguityVisibilityFor(db, tagScope),
         );
         for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
       }
@@ -2826,7 +2879,7 @@ async function handleNotesInner(
       result.attachments = await store.getAttachments(note.id);
     }
     if (parseBool(parseQuery(url, "include_link_count"), false)) {
-      result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url)).get(note.id) ?? 0;
+      result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url), ambiguityVisibilityFor(db, tagScope)).get(note.id) ?? 0;
     }
     return json(result);
   }
@@ -4264,9 +4317,16 @@ export function handleUnresolvedWikilinks(
   // target); the two tables are disjoint by construction, so this only
   // guards against a stale row.
   const seen = new Set(filtered.map((r) => `${r.source_id}\u0000${r.relationship}\u0000${r.target_path.toLowerCase()}`));
-  const collapsed = listZeroVisibleAmbiguousAsUnresolved(db, ambiguityVisibilityFor(db, tagScope)!, limit)
-    .filter((row) => inScope(row)
-      && !seen.has(`${row.source_id}\u0000${row.relationship}\u0000${row.target_path.toLowerCase()}`));
+  const visible = ambiguityVisibilityFor(db, tagScope)!;
+  const collapsed = [
+    ...listZeroVisibleAmbiguousAsUnresolved(db, visible, limit),
+    ...listResolvedToInvisibleAsUnresolved(db, visible, limit),
+  ].filter((row) => {
+    const key = `${row.source_id}\u0000${row.relationship}\u0000${row.target_path.toLowerCase()}`;
+    if (!inScope(row) || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
 
   const merged = [...filtered, ...collapsed].slice(0, limit);
   return Response.json({ unresolved: merged, count: merged.length });