@openparachute/vault 0.7.0-rc.8 → 0.7.0-rc.9

package/core/src/wikilinks.ts

@@ -306,6 +306,50 @@ export function listUnresolvedWikilinks(db: Database, limit = 50): { unresolved:
   return { unresolved, count: total };
 }
 
+/** One note's dangling outbound link, as surfaced on a note read (vault#555). */
+export interface BrokenLink {
+  target: string;
+  relationship: string;
+}
+
+/**
+ * Batch-fetch each note's pending `unresolved_wikilinks` rows — the
+ * `include_broken_links` surfacing on `query-notes` / `GET /notes`. ONE
+ * query for the whole page (mirrors `getLinksHydratedForNotes`'s batching),
+ * not one per note. Returns a map with an entry (possibly `[]`) for every
+ * requested id whenever the table exists; when the table has never been
+ * created (no note in this vault has ever had a broken link) every id maps
+ * to `[]` without a query attempt.
+ */
+export function getUnresolvedLinksForNotes(db: Database, noteIds: string[]): Map<string, BrokenLink[]> {
+  const result = new Map<string, BrokenLink[]>(noteIds.map((id) => [id, []]));
+  if (noteIds.length === 0) return result;
+
+  const rows: { source_id: string; target_path: string; relationship: string }[] = [];
+  try {
+    ensureRelationshipColumn(db);
+    for (const chunk of chunkForInClause(noteIds)) {
+      const placeholders = chunk.map(() => "?").join(", ");
+      rows.push(...db.prepare(
+        `SELECT source_id, target_path, relationship FROM unresolved_wikilinks WHERE source_id IN (${placeholders})`,
+      ).all(...chunk) as typeof rows);
+    }
+  } catch {
+    // Table doesn't exist — every id already maps to [] above.
+    return result;
+  }
+
+  for (const row of rows) {
+    result.get(row.source_id)?.push({ target: row.target_path, relationship: row.relationship || WIKILINK_REL });
+  }
+  return result;
+}
+
+/** Single-note convenience wrapper around {@link getUnresolvedLinksForNotes}. */
+export function getUnresolvedLinksForNote(db: Database, noteId: string): BrokenLink[] {
+  return getUnresolvedLinksForNotes(db, [noteId]).get(noteId) ?? [];
+}
+
 // ---------------------------------------------------------------------------
 // Sync — maintain wikilink-based links for a note
 // ---------------------------------------------------------------------------

package/package.json

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

package/src/mcp-tools.ts

@@ -174,6 +174,20 @@ export function generateScopedMcpTools(
         )
     : undefined;
 
+  // Tag-scope guard for `create-note` `if_exists` (vault#555 auth-review
+  // must-fix): the core `if_exists` upsert resolves the target path VAULT-WIDE
+  // and returns/updates/replaces the found note, so a scoped caller could
+  // read/overwrite an out-of-scope note by naming its path. Inject a
+  // visibility predicate the core `applyExistingNote` consults on the RESOLVED
+  // existing note — covering BOTH the proactive check AND the concurrent-INSERT
+  // race backstop (a wrapper-only pre-check misses the latter). Reads from the
+  // SAME shared `allowedHolder` the create-note wrapper's `getAllowed()`
+  // populates before core's execute runs. Unscoped sessions install no
+  // predicate (unchanged). Same closure as `expandVisibility`.
+  const ifExistsVisible = scoped
+    ? (note: Note) => noteWithinTagScope(note, allowedHolder.value, rawTags)
+    : undefined;
+
   // Write-attribution (vault#298). Every write through an MCP session arrives
   // on the `mcp` channel — so we REFINE the auth's base `via` (the generic
   // credential class) to `mcp` here, where the path/channel is known. The
@@ -197,10 +211,11 @@ export function generateScopedMcpTools(
 
   const tools = generateMcpTools(
     store,
-    expandVisibility || nearTraversable || writeContext || strictBypass
+    expandVisibility || nearTraversable || ifExistsVisible || writeContext || strictBypass
       ? {
           ...(expandVisibility ? { expandVisibility } : {}),
           ...(nearTraversable ? { nearTraversable } : {}),
+          ...(ifExistsVisible ? { ifExistsVisible } : {}),
           ...(writeContext ? { writeContext } : {}),
           ...(strictBypass ? { strictBypass } : {}),
           ...(onStrictBypass ? { onStrictBypass } : {}),
@@ -498,6 +513,13 @@ function applyTagScopeWrappers(
         return forbidden("create-note: every note must carry at least one tag in the token's allowlist");
       }
     }
+    // `if_exists` scope enforcement (vault#555 auth-review must-fix) is NOT
+    // done here as a wrapper pre-check — that would miss core's concurrent-
+    // INSERT race backstop. Instead the `ifExistsVisible` predicate wired into
+    // generateMcpTools above fires INSIDE core's `applyExistingNote`, covering
+    // both the proactive site and the race-backstop site with one guard. The
+    // `await getAllowed()` at the top of this wrapper populates the shared
+    // `allowedHolder` the predicate reads, before core's execute runs.
     return await orig(params);
   });
 
@@ -825,8 +847,8 @@ function buildManageTokenTool(
       ":admin'. List + revoke are scoped to tokens this session minted; " +
       "CLI/REST-minted tokens are not surfaced here.\n\n" +
       "Actions (discriminator: `action`):\n" +
-      "- `mint` — { scope: string|string[], ttl_seconds?: number, description?: string } → { action: \"mint\", token, jti, expires_at }\n" +
-      "- `revoke` — { jti: string } → { action: \"revoke\", ok: boolean }\n" +
+      "- `mint` — { scope: string|string[], ttl_seconds?: number, description?: string } → { action: \"mint\", token, jti, expires_at, scopes, scoped_tags, vault_name } (vault#555: scopes/scoped_tags/vault_name were previously undocumented here)\n" +
+      "- `revoke` — { jti: string } → { action: \"revoke\", ok: boolean, already_revoked?: boolean } — idempotent; a jti not in this session's ledger, or already revoked, still returns ok:true. A genuine failure additionally carries error/message (and, for a hub-side rejection, hub_status).\n" +
       "- `list` — (no inputs) → { action: \"list\", tokens: [...] }",
     inputSchema: {
       type: "object",

package/src/routes.ts

@@ -22,9 +22,16 @@ import {
   type QueryWarning,
 } from "../core/src/query-warnings.ts";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "../core/src/search-query.ts";
-import { listUnresolvedWikilinks, resolveOrQueueLink, resolveStructuredLinkNote } from "../core/src/wikilinks.ts";
+import {
+  listUnresolvedWikilinks,
+  resolveOrQueueLink,
+  resolveStructuredLinkNote,
+  getUnresolvedLinksForNote,
+  getUnresolvedLinksForNotes,
+} from "../core/src/wikilinks.ts";
 import { transactionAsync } from "../core/src/txn.ts";
-import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError, PathConflictError } from "../core/src/notes.ts";
+import { normalizePath } from "../core/src/paths.ts";
 import {
   parseContentRange,
   applyContentRange,
@@ -812,6 +819,9 @@ export function parseNotesQueryOpts(url: URL): {
     excludeTags: parseQueryList(url, "exclude_tag"),
     hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
     hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
+    // Presence filter on dangling outbound wikilinks/structured links
+    // (vault#555) — see core/src/types.ts QueryOpts.hasBrokenLinks.
+    hasBrokenLinks: parseBoolOrUndef(parseQuery(url, "has_broken_links")),
     path: parseQuery(url, "path") ?? undefined,
     pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
     extension: parseExtensionFilter(url),
@@ -1017,6 +1027,13 @@ async function handleNotesInner(
             tagScope.raw,
           );
         }
+        if (parseBool(parseQuery(url, "include_broken_links"), false)) {
+          // No tag-scope filtering needed (unlike include_links above): a
+          // broken-link `target` never resolved to a note, so there's no
+          // neighbor identity/content to leak — just the string this note's
+          // own [[wikilink]]/structured link already named.
+          result.broken_links = getUnresolvedLinksForNote(db, note.id);
+        }
         if (parseBool(parseQuery(url, "include_attachments"), false)) {
           result.attachments = await store.getAttachments(note.id);
         }
@@ -1336,6 +1353,7 @@ async function handleNotesInner(
       const contentRange = parseContentRangeQuery(url, includeContent);
       if (contentRange.error) return contentRange.error;
       const includeLinks = parseBool(parseQuery(url, "include_links"), false);
+      const includeBrokenLinks = parseBool(parseQuery(url, "include_broken_links"), false);
       const includeAttachments = parseBool(parseQuery(url, "include_attachments"), false);
       const includeLinkCount = parseBool(parseQuery(url, "include_link_count"), false);
       const inclMeta = parseIncludeMetadata(url);
@@ -1427,13 +1445,19 @@ async function handleNotesInner(
         );
       }
 
-      if (includeLinks || includeAttachments) {
+      if (includeLinks || includeBrokenLinks || includeAttachments) {
         // Whole-page link hydration in a constant number of queries — the
         // per-note variant cost (1 link query + 1 summary query + N tag
         // queries) × page size. 2026-06-10 perf measurements.
         const linksByNote = includeLinks
           ? linkOps.getLinksHydratedForNotes(db, output.map((n: any) => n.id))
           : null;
+        // Same batched-per-page shape as links (vault#555). No tag-scope
+        // filtering needed — a broken-link `target` never resolved to a
+        // note, so there's no neighbor identity to leak.
+        const brokenLinksByNote = includeBrokenLinks
+          ? getUnresolvedLinksForNotes(db, output.map((n: any) => n.id))
+          : null;
         const enrichedOut: any[] = [];
         for (const n of output) {
           const enriched: any = { ...n };
@@ -1445,6 +1469,7 @@ async function handleNotesInner(
               tagScope.raw,
             );
           }
+          if (brokenLinksByNote) enriched.broken_links = brokenLinksByNote.get(n.id) ?? [];
           if (includeAttachments) enriched.attachments = await store.getAttachments(n.id);
           enrichedOut.push(enriched);
         }
@@ -1512,13 +1537,103 @@ async function handleNotesInner(
       // layers share `resolveOrQueueLink` from core/wikilinks.ts).
       const pendingLinks: { sourceId: string; links: { target: string; relationship: string }[] }[] = [];
       const linkWarningsByNote = new Map<string, QueryWarning[]>();
+      // `if_exists` bookkeeping (vault#555) — mirrors core/src/mcp.ts's
+      // create-note tool exactly (same contract, independent REST-layer
+      // reimplementation sharing the same core primitives). See that file's
+      // doc comments for the full rationale.
+      const existedMap = new Map<string, boolean>();
+      const noMutateIds = new Set<string>();
+      const recordExistedBranch = (resultNote: Note, noMutate: boolean): void => {
+        existedMap.set(resultNote.id, true);
+        if (noMutate) noMutateIds.add(resultNote.id);
+        created.push(resultNote);
+      };
+      const applyExistingNote = async (
+        item: any,
+        existingNote: Note,
+        mode: "ignore" | "update" | "replace",
+      ): Promise<{ note: Note; noMutate: boolean }> => {
+        // CRITICAL scope guard (vault#555 auth-review must-fix): `existingNote`
+        // was resolved VAULT-WIDE by path (store.getNoteByPath) at BOTH call
+        // sites below (proactive + race-backstop). The batch's incoming-tag
+        // pre-validation guards only each item's OWN tags — NOT this resolved
+        // note — so without this a token scoped to `public` could READ (ignore)
+        // or OVERWRITE (update/replace) a note carrying only an out-of-scope
+        // tag `secret` just by naming its path. When the note is outside the
+        // caller's tag scope, treat it as a path conflict — the path is taken,
+        // but invisible to this caller — throwing BEFORE any read/mutation so
+        // we never expose content or write. `noteWithinTagScope` is a no-op for
+        // unscoped tokens (tagScope.raw === null → always true). The throw
+        // propagates to runBatch's PATH_CONFLICT catch → 409 path_conflict,
+        // byte-identical to a genuine conflict (leaks nothing about WHY).
+        if (!noteWithinTagScope(existingNote, tagScope.allowed, tagScope.raw)) {
+          throw new PathConflictError(existingNote.path ?? "");
+        }
+        if (mode === "ignore") {
+          return { note: existingNote, noMutate: true };
+        }
+        const updates: { content?: string; metadata?: Record<string, unknown> } = {};
+        if (mode === "update") {
+          if (item.content !== undefined) updates.content = item.content;
+          if (item.metadata !== undefined) {
+            updates.metadata = mergeMetadata(
+              existingNote.metadata as Record<string, unknown> | null | undefined,
+              item.metadata,
+            );
+          }
+        } else {
+          // "replace" — PUT semantics: content/metadata become exactly this
+          // payload (empty default when omitted), never merged.
+          updates.content = item.content ?? "";
+          updates.metadata = item.metadata ?? {};
+        }
+
+        const incomingTags: string[] = item.tags ?? [];
+        const projectedTags = new Set<string>([...(existingNote.tags ?? []), ...incomingTags]);
+        const projectedMetadata = updates.metadata ?? ((existingNote.metadata as Record<string, unknown>) ?? {});
+        gateStrictWrite(store, writeCtx, { path: existingNote.path, tags: [...projectedTags], metadata: projectedMetadata });
+
+        // vault#555 fix 2 (W8 fix-2 bug class, generalist must-fix): gate the
+        // core UPDATE on the tag/link mutation too, not just `updates` — a
+        // tags-only/links-only "update" leaves `updates` empty, and skipping
+        // store.updateNote would freeze `updated_at` even though store.tagNote
+        // genuinely mutates the note (breaking cursor polling + updated_at
+        // sync). Mirrors the update-note/PATCH hasTagMutation||hasLinkMutation
+        // gate. "replace" always sets content+metadata, so it was unaffected.
+        const hasLinkMutation = item.links !== undefined;
+        let result: Note = existingNote;
+        if (Object.keys(updates).length > 0 || incomingTags.length > 0 || hasLinkMutation) {
+          result = await store.updateNote(existingNote.id, {
+            ...updates,
+            actor: writeCtx.actor,
+            via: writeCtx.via,
+          });
+        }
+
+        if (incomingTags.length > 0) {
+          await store.tagNote(result.id, incomingTags);
+          // Redundant with the outer batch loop's applySchemaDefaults (this
+          // note isn't in `noMutateIds` — only "ignore" hits are), but harmless
+          // (idempotent) — kept so the update/replace branch is self-contained.
+          await applySchemaDefaults(store, db, [result.id], incomingTags);
+        }
+
+        if (item.links) {
+          pendingLinks.push({ sourceId: result.id, links: item.links as { target: string; relationship: string }[] });
+        }
+
+        return { note: (await store.getNote(result.id)) ?? result, noMutate: false };
+      };
+
       // Wrap multi-item batches in a SQLite transaction so a mid-batch
       // failure (path conflict, etc.) rolls back every prior insert. Without
       // this, callers got half-applied batches where the prefix landed and
       // the offending entry surfaced the 409 — see #236. Single-item posts
       // are already atomic at the store layer and skip the wrap so they
       // don't collide with concurrent single-item callers on the shared
-      // bun:sqlite connection.
+      // bun:sqlite connection. A caught PATH_CONFLICT (the if_exists race
+      // backstop below) does NOT roll back the transaction — only a throw
+      // that escapes `runBatch` does (see core/src/txn.ts).
       const batched = items.length > 1;
       const runBatch = async (): Promise<void> => {
         for (const item of items) {
@@ -1528,6 +1643,26 @@ async function handleNotesInner(
           const extension = item.extension !== undefined
             ? validateExtension(item.extension)
             : undefined;
+          const effectiveExtension = extension ?? "md";
+          const ifExists: string = item.if_exists ?? "error";
+          const upsertMode = ifExists === "ignore" || ifExists === "update" || ifExists === "replace";
+
+          // Proactive existence check (vault#555) — only possible with a
+          // path. Handles the common, non-racing case cleanly: skips the
+          // raw-item strict gate below (it would validate the wrong shape —
+          // see `applyExistingNote`) and goes straight to the collision
+          // branch. The catch below is the backstop for a true race.
+          let existingNote: Note | null = null;
+          if (upsertMode && item.path) {
+            const normalized = normalizePath(item.path);
+            existingNote = normalized ? await store.getNoteByPath(normalized, effectiveExtension) : null;
+          }
+          if (existingNote) {
+            const { note: resultNote, noMutate } = await applyExistingNote(item, existingNote, ifExists as "ignore" | "update" | "replace");
+            recordExistedBranch(resultNote, noMutate);
+            continue;
+          }
+
           // Strict-schema gate (vault#299) — reject before any write so a
           // mid-batch violation rolls back the batch transaction.
           gateStrictWrite(store, writeCtx, {
@@ -1535,17 +1670,36 @@ async function handleNotesInner(
             tags: item.tags,
             metadata: item.metadata,
           });
-          const note = await store.createNote(item.content ?? "", {
-            id: item.id,
-            path: item.path,
-            tags: item.tags,
-            metadata: item.metadata,
-            created_at: item.createdAt ?? item.created_at,
-            ...(extension !== undefined ? { extension } : {}),
-            // Write-attribution (vault#298) — REST batch create.
-            actor: writeCtx.actor,
-            via: writeCtx.via,
-          });
+          let note: Note;
+          try {
+            note = await store.createNote(item.content ?? "", {
+              id: item.id,
+              path: item.path,
+              tags: item.tags,
+              metadata: item.metadata,
+              created_at: item.createdAt ?? item.created_at,
+              ...(extension !== undefined ? { extension } : {}),
+              // Write-attribution (vault#298) — REST batch create.
+              actor: writeCtx.actor,
+              via: writeCtx.via,
+            });
+          } catch (err: any) {
+            // Race backstop (vault#555): a concurrent writer's INSERT
+            // committed between our proactive check and this one.
+            // Re-resolve the now-existing row and fall through to the SAME
+            // branch a proactive hit would have taken.
+            if (upsertMode && err?.code === "PATH_CONFLICT") {
+              const winner = await store.getNoteByPath(err.path, effectiveExtension);
+              if (winner) {
+                const { note: resultNote, noMutate } = await applyExistingNote(item, winner, ifExists as "ignore" | "update" | "replace");
+                recordExistedBranch(resultNote, noMutate);
+                continue;
+              }
+            }
+            throw err;
+          }
+
+          if (upsertMode) existedMap.set(note.id, false);
 
           if (item.links) {
             pendingLinks.push({ sourceId: note.id, links: item.links as { target: string; relationship: string }[] });
@@ -1624,6 +1778,10 @@ async function handleNotesInner(
       // applied so the common no-defaults path adds zero extra reads.
       const mutatedIds = new Set<string>();
       for (const note of created) {
+        // "ignore" hits (vault#555) promise ZERO mutation, including
+        // schema-default backfill of a since-added default the existing
+        // note predates — skip them entirely.
+        if (noMutateIds.has(note.id)) continue;
         if (note.tags?.length) {
           for (const id of await applySchemaDefaults(store, db, [note.id], note.tags)) {
             mutatedIds.add(id);
@@ -1643,12 +1801,35 @@ async function handleNotesInner(
       // unchanged when no tag declares fields, so vaults without any tag
       // schemas see no behavior change. Fold in any `unresolved_link`
       // warnings (vault#555) — additive, present only when this note's
-      // `links` had a target that didn't resolve.
+      // `links` had a target that didn't resolve. `existed` (vault#555) is
+      // attached ONLY for items whose `if_exists` actually engaged — the
+      // default "error" path's response shape is untouched.
       const final = refreshed.map((n) => {
         const validated = attachValidationStatus(store, db, n);
         const warnings = linkWarningsByNote.get(n.id);
-        return warnings && warnings.length > 0 ? { ...validated, warnings } : validated;
+        const existed = existedMap.get(n.id);
+        let out: any = validated;
+        if (warnings && warnings.length > 0) out = { ...out, warnings };
+        if (existed !== undefined) out = { ...out, existed };
+        return out;
       });
+
+      // Batch summary (vault#555) — compact shape instead of N full note
+      // objects. Batch-only (a `notes` array); `summary` is ignored on a
+      // single-note POST. Mirrors the MCP create-note tool exactly.
+      if (body.notes && body.summary === true) {
+        return json(
+          {
+            created: final.filter((n: any) => n.existed !== true).length,
+            ids: final.map((n: any) => n.id),
+            // Reserved for future partial-batch-failure reporting — a batch
+            // create is all-or-nothing today, so this is always empty.
+            failed: [] as unknown[],
+          },
+          201,
+        );
+      }
+
       return json(body.notes ? final : final[0], 201);
     }