@openparachute/vault 0.7.0-rc.8 → 0.7.1

package/src/routes.ts

@@ -11,7 +11,7 @@
  * and the Request, and returns a Response.
  */
 
-import type { Store, Note, QueryOpts } from "../core/src/types.ts";
+import type { Store, Note, QueryOpts, AggregateSpec } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import {
   collectUnknownTagWarnings,
@@ -22,9 +22,17 @@ 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,
+  getContentWikilinkWarnings,
+} 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, getNoteByTitle, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError, PathConflictError, getVaultMap } from "../core/src/notes.ts";
+import { normalizePath } from "../core/src/paths.ts";
 import {
   parseContentRange,
   applyContentRange,
@@ -55,6 +63,7 @@ import {
   scrubValidationStatusByScope,
   tagScopeForbidden,
   tagsWithinScope,
+  tagVisibleInScope,
 } from "./tag-scope.ts";
 import { ParentCycleError, InvalidFieldDefaultError, InvalidFieldTypeError } from "../core/src/tag-schemas.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
@@ -812,6 +821,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),
@@ -840,6 +852,58 @@ export function parseNotesQueryOpts(url: URL): {
   return { queryOpts, hasSearch, hasNear, hasCursor };
 }
 
+/**
+ * Parse the `?aggregate[group_by]=…&aggregate[op]=…&aggregate[field]=…`
+ * aggregation params (bracket-style, consistent with `meta[field][op]=`
+ * above) into an `AggregateSpec`. Absent entirely (none of the three keys
+ * present) → `{}` — no aggregate intent, the caller falls through to a
+ * normal query. `group_by` + `op` are required together when ANY of the
+ * three is present; `field` is optional at the parser level (its
+ * requiredness depends on `op`, enforced by `aggregateNotes` itself). Value
+ * validity beyond shape (indexed field, numeric type, sum-requires-field)
+ * is ALSO enforced by `aggregateNotes` — same FIELD_NOT_INDEXED /
+ * INVALID_QUERY contract every other query surface uses.
+ *
+ * Returns `{ aggregate? }` or `{ error }` (a 400 Response) on a malformed
+ * shape (missing `group_by`/`op`, or an unrecognized `op`).
+ */
+function parseAggregateParam(url: URL): { aggregate?: AggregateSpec; error?: Response } {
+  const groupBy = parseQuery(url, "aggregate[group_by]");
+  const op = parseQuery(url, "aggregate[op]");
+  const field = parseQuery(url, "aggregate[field]");
+  if (groupBy === null && op === null && field === null) return {};
+  if (groupBy === null || op === null) {
+    return {
+      error: json(
+        {
+          error: `aggregate requires both aggregate[group_by] and aggregate[op] — group_by is an indexed metadata field or "tag"; op is "count" or "sum".`,
+          code: "INVALID_QUERY",
+          error_type: "invalid_query",
+          field: "aggregate",
+          hint: `pass ?aggregate[group_by]=<field|tag>&aggregate[op]=<count|sum>[&aggregate[field]=<numeric field>]`,
+        },
+        400,
+      ),
+    };
+  }
+  if (op !== "count" && op !== "sum") {
+    return {
+      error: json(
+        {
+          error: `invalid aggregate[op]: "${op}" — must be "count" or "sum"`,
+          code: "INVALID_QUERY",
+          error_type: "invalid_query",
+          field: "aggregate.op",
+          got: op,
+          hint: `pass "count" or "sum"`,
+        },
+        400,
+      ),
+    };
+  }
+  return { aggregate: { group_by: groupBy, op, field: field ?? undefined } };
+}
+
 /**
  * Parse include_metadata query param.
  * - absent/null → undefined (all metadata, default)
@@ -897,6 +961,18 @@ function parseExpandParams(
  * differing only by extension (vault#330 S1). When the path is
  * ambiguous and no extension hint is supplied, `getNoteByPath` throws
  * `AmbiguousPathError` — REST handlers catch it and return 409.
+ *
+ * Title fallback (additive): when id AND path/extension both miss
+ * cleanly (no throw), tries an H1-title match via `getNoteByTitle` — the
+ * note whose first `# ` content line equals `idOrPath`, only when
+ * exactly one note has that title. Mirrors the MCP-layer `resolveNote`
+ * in core/src/mcp.ts and `[[wikilink]]` resolution (core/src/wikilinks.ts);
+ * exact id/path always wins first. Skipped (falls through to "not found")
+ * when `store.db` isn't available — the `Store` interface documents `db`
+ * as always present on the concrete class, but a handful of tests pass a
+ * minimal duck-typed stub (e.g. `handleViewNote`'s coverage in
+ * published.test.ts) that only implements `getNote`/`getNoteByPath`; this
+ * fallback must never turn that into a crash.
  */
 async function resolveNote(store: Store, idOrPath: string): Promise<Note | null> {
   const byId = await store.getNote(idOrPath);
@@ -906,7 +982,9 @@ async function resolveNote(store: Store, idOrPath: string): Promise<Note | null>
     const explicit = await store.getNoteByPath(extMatch[1]!, extMatch[2]!);
     if (explicit) return explicit;
   }
-  return await store.getNoteByPath(idOrPath);
+  const byPath = await store.getNoteByPath(idOrPath);
+  if (byPath) return byPath;
+  return store.db ? getNoteByTitle(store.db, idOrPath) : null;
 }
 
 async function requireNote(store: Store, idOrPath: string): Promise<Note> {
@@ -1017,6 +1095,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);
         }
@@ -1224,6 +1309,87 @@ async function handleNotesInner(
           400,
         );
       }
+
+      // Aggregation / rollup mode (top new-feature ask from a UX round).
+      // Mutually exclusive with cursor/near — a rollup returns one row per
+      // group, not a paginated/graph-scoped note list — so reject those
+      // combos loudly before touching the DB, then short-circuit: none of
+      // the normal-query output machinery below (expand, include_links,
+      // metadata filtering, ...) applies to rollup rows.
+      const aggregateParsed = parseAggregateParam(url);
+      if (aggregateParsed.error) return aggregateParsed.error;
+      if (aggregateParsed.aggregate) {
+        if (cursorMode) {
+          return json(
+            {
+              error: "aggregate is incompatible with cursor pagination — a rollup has no watermark to page through.",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "aggregate",
+              hint: "drop `cursor` when using `aggregate`",
+            },
+            400,
+          );
+        }
+        if (nearNoteIdEarly) {
+          return json(
+            {
+              error: "aggregate is incompatible with near (graph neighborhood).",
+              code: "INVALID_QUERY",
+              error_type: "invalid_query",
+              field: "aggregate",
+              hint: "drop `near` when using `aggregate`",
+            },
+            400,
+          );
+        }
+        try {
+          let rows;
+          if (tagScope.raw === null) {
+            rows = await store.aggregateNotes({ ...queryOpts, aggregate: aggregateParsed.aggregate });
+          } else {
+            // Tag-scoped: filter to visible notes FIRST — fetch every note
+            // the OTHER filters match (unpaginated, same `limit: 1000000`
+            // "get everything" convention core's `syncAllWikilinks` uses),
+            // narrow via the SAME `filterNotesByTagScope` every other read
+            // path applies, THEN aggregate over just that visible id set
+            // (reusing the `ids` filter `near` already pushes into SQL).
+            const allMatches = await store.queryNotes({ ...queryOpts, limit: 1000000, offset: 0 });
+            const visible = filterNotesByTagScope(allMatches, tagScope.allowed, tagScope.raw);
+            rows = visible.length === 0
+              ? []
+              : await store.aggregateNotes({ ids: visible.map((n) => n.id), aggregate: aggregateParsed.aggregate });
+            // That note-level narrowing isn't sufficient on its own under
+            // `group_by: "tag"`: a note can be in scope via one tag while
+            // ALSO carrying an out-of-scope co-tag, and a tag rollup's
+            // `group` values ARE tag names — the co-tag would otherwise
+            // surface directly as a group. Scrub group NAMES too, mirroring
+            // the MCP wrapper's identical fix (src/mcp-tools.ts).
+            if (aggregateParsed.aggregate.group_by === "tag") {
+              rows = rows.filter(
+                (r: any) => typeof r?.group === "string" && tagVisibleInScope(r.group, tagScope.allowed, tagScope.raw),
+              );
+            }
+          }
+          return json(rows);
+        } catch (e: any) {
+          if (e && e.name === "QueryError") {
+            return json(
+              {
+                error: e.message,
+                code: e.code ?? "INVALID_QUERY",
+                error_type: e.error_type ?? "invalid_query",
+                ...(e.field !== undefined ? { field: e.field } : {}),
+                ...(e.got !== undefined ? { got: e.got } : {}),
+                ...(e.hint !== undefined ? { hint: e.hint } : {}),
+              },
+              400,
+            );
+          }
+          throw e;
+        }
+      }
+
       // Warnings channel (vault#550). `unknown_tag` stays structured-query
       // only (skipped entirely for a tag-scoped session:
       // `collectUnknownTagWarnings` resolves `did_you_mean` against the
@@ -1336,6 +1502,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 +1594,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 +1618,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 +1686,122 @@ 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[]>();
+      const pushLinkWarning = (noteId: string, warning: QueryWarning): void => {
+        const list = linkWarningsByNote.get(noteId) ?? [];
+        list.push(warning);
+        linkWarningsByNote.set(noteId, list);
+      };
+      // Content wikilinks whose note+content pair needs an `unresolved_link`/
+      // `ambiguous_link` warning check (vault#570) — deferred to the same
+      // second pass as `pendingLinks` for the same forward-ref-within-batch
+      // reason (a content `[[wikilink]]` to a batch sibling created later
+      // resolves via the pending-wikilink backfill by the time this runs).
+      const contentWikilinkNotes: { noteId: string; content: string }[] = [];
+      // `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,
+          });
+        }
+
+        // Content-wikilink warnings (vault#570) — this branch's content
+        // update (if any) already ran `syncWikilinks` inside
+        // `store.updateNote` above; queue for the shared second-pass
+        // classification below.
+        if (updates.content !== undefined) {
+          contentWikilinkNotes.push({ noteId: result.id, content: updates.content });
+        }
+
+        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 +1811,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,22 +1838,48 @@ 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 }[] });
           }
 
+          // Content-wikilink warnings (vault#570) — `store.createNote` above
+          // already ran `syncWikilinks` (gated on `content` truthy, same
+          // condition here); queue for the shared second-pass classification.
+          if (item.content) {
+            contentWikilinkNotes.push({ noteId: note.id, content: item.content });
+          }
+
           created.push((await store.getNote(note.id)) ?? note);
         }
 
@@ -1559,24 +1888,40 @@ async function handleNotesInner(
         // that every sibling note in this batch exists. A target that still
         // doesn't resolve is queued for lazy resolution (backfills
         // automatically when a matching note is created later) and surfaces
-        // an `unresolved_link` warning naming the target — never silent.
+        // an `unresolved_link` warning naming the target. A target that
+        // matched ≥2 notes (vault#570) is neither linked nor queued —
+        // surfaces a distinct `ambiguous_link` warning instead. Never silent.
         for (const { sourceId, links } of pendingLinks) {
           for (const link of links) {
-            const targetId = resolveOrQueueLink(db, sourceId, link.target, link.relationship);
-            if (targetId) {
-              await store.createLink(sourceId, targetId, link.relationship);
+            const outcome = resolveOrQueueLink(db, sourceId, link.target, link.relationship);
+            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,
+              });
             } else {
-              const list = linkWarningsByNote.get(sourceId) ?? [];
-              list.push({
+              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,
               });
-              linkWarningsByNote.set(sourceId, list);
             }
           }
         }
+
+        // --- Content-wikilink warnings (vault#570) ---
+        // Same forward-ref-aware timing as the structured-links pass above.
+        for (const { noteId, content } of contentWikilinkNotes) {
+          for (const warning of getContentWikilinkWarnings(db, noteId, content)) {
+            pushLinkWarning(noteId, warning);
+          }
+        }
       };
       try {
         await (batched ? transactionAsync(db, runBatch) : runBatch());
@@ -1624,6 +1969,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 +1992,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);
     }
 
@@ -1915,15 +2287,25 @@ async function handleNotesInner(
           //     fresh note).
           //   - Missing target notes skip silently (mirrors MCP).
           const linksAdd = (body.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
-          // `unresolved_link` warnings (vault#555) — a target that doesn't
-          // resolve is queued for lazy resolution (backfills automatically
-          // when a matching note is created later), never silently dropped.
+          // `unresolved_link` / `ambiguous_link` warnings (vault#555, vault#570)
+          // — a target that doesn't resolve is queued for lazy resolution
+          // (backfills automatically when a matching note is created later),
+          // and a target matching ≥2 notes is neither linked nor queued.
+          // Never silently dropped.
           const createWarnings: QueryWarning[] = [];
           if (linksAdd) {
             for (const link of linksAdd) {
-              const targetId = resolveOrQueueLink(db, created.id, link.target, link.relationship);
-              if (targetId) {
-                await store.createLink(created.id, targetId, link.relationship, link.metadata);
+              const outcome = resolveOrQueueLink(db, created.id, link.target, link.relationship);
+              if (outcome.status === "resolved") {
+                await store.createLink(created.id, outcome.note_id, link.relationship, link.metadata);
+              } else if (outcome.status === "ambiguous") {
+                createWarnings.push({
+                  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,
+                });
               } else {
                 createWarnings.push({
                   code: "unresolved_link",
@@ -1934,6 +2316,13 @@ async function handleNotesInner(
               }
             }
           }
+          // Content-wikilink warnings (vault#570) — `store.createNote` above
+          // already ran `syncWikilinks`; this is the single-note (non-batch)
+          // create path, so there's no batch-sibling forward-ref to wait for
+          // — compute right away against the committed content.
+          if (content) {
+            createWarnings.push(...getContentWikilinkWarnings(db, created.id, content));
+          }
           const final = await store.getNote(created.id);
           if (!final) return json({ error: "Note disappeared", error_type: "internal_error" }, 500);
           const validated: any = attachValidationStatus(store, db, final);
@@ -2171,6 +2560,14 @@ async function handleNotesInner(
       // moved despite a real tags/note_tags or links change.
       const hasTagMutation = (body.tags?.add?.length ?? 0) > 0 || (body.tags?.remove?.length ?? 0) > 0;
       const hasLinkMutation = body.links?.add !== undefined || body.links?.remove !== undefined;
+      // Content-wikilink warnings (vault#570) gate on the SAME condition
+      // `store.updateNote`/`syncWikilinks` use to decide whether to re-sync
+      // content wikilinks at all — a tags/links-only PATCH must not
+      // spuriously re-warn about pre-existing broken links this call never
+      // touched.
+      const contentChanged = updates.content !== undefined
+        || updates.append !== undefined
+        || updates.prepend !== undefined;
       if (Object.keys(updates).length > 0 || hasTagMutation || hasLinkMutation) {
         // Write-attribution (vault#298) — REST update. Stamp the most-recent-
         // write columns on the same UPDATE that bumps updated_at. `updates`
@@ -2197,16 +2594,25 @@ async function handleNotesInner(
         await store.untagNote(note.id, body.tags.remove);
       }
 
-      // Add links. `unresolved_link` warnings (vault#555) — a target that
-      // doesn't resolve is queued for lazy resolution (backfills
-      // automatically when a matching note is created later), never
-      // silently dropped.
+      // Add links. `unresolved_link` / `ambiguous_link` warnings (vault#555,
+      // vault#570) — a target that doesn't resolve is queued for lazy
+      // resolution (backfills automatically when a matching note is created
+      // later); a target matching ≥2 notes is neither linked nor queued.
+      // Never silently dropped.
       const linkWarnings: QueryWarning[] = [];
       if (body.links?.add) {
         for (const link of body.links.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[]) {
-          const targetId = resolveOrQueueLink(db, note.id, link.target, link.relationship);
-          if (targetId) {
-            await store.createLink(note.id, targetId, link.relationship, link.metadata);
+          const outcome = resolveOrQueueLink(db, note.id, link.target, link.relationship);
+          if (outcome.status === "resolved") {
+            await store.createLink(note.id, outcome.note_id, link.relationship, link.metadata);
+          } else if (outcome.status === "ambiguous") {
+            linkWarnings.push({
+              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,
+            });
           } else {
             linkWarnings.push({
               code: "unresolved_link",
@@ -2228,6 +2634,13 @@ async function handleNotesInner(
       // `toNoteIndex` drops unknown fields).
       const updatedNote = await store.getNote(note.id);
       if (updatedNote === null) return json({ error: "Note disappeared", error_type: "not_found" }, 404);
+      // Content-wikilink warnings (vault#570) — `store.updateNote` above
+      // already ran `syncWikilinks` when `contentChanged`; this PATCH
+      // handles a single note (no batch-sibling forward-ref to wait for),
+      // so compute right away against the committed content.
+      if (contentChanged) {
+        linkWarnings.push(...getContentWikilinkWarnings(db, note.id, updatedNote.content));
+      }
       const validated: any = attachValidationStatus(store, db, updatedNote);
       // Echo hydrated links when a link mutation was part of this request,
       // OR the caller explicitly asked for them via `?include_links=true`
@@ -3043,6 +3456,13 @@ export async function handleVault(
    * configured AND available), which is what a surface gates its mic on.
    */
   resolveCapability: () => Promise<TranscriptionCapability> = resolveTranscriptionCapability,
+  /**
+   * Tag-scope allowlist (front-door structural map). Threaded from
+   * routing.ts the same way every other read handler gets it. Unscoped
+   * (`NO_TAG_SCOPE`) by default so every pre-existing call site — none of
+   * which pass this — is unaffected.
+   */
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): Promise<Response> {
   const url = new URL(req.url);
 
@@ -3052,6 +3472,16 @@ export async function handleVault(
     // and available. `minutes_remaining` is omitted (cloud/plan concern;
     // self-host is unmetered). This is the field Notes gates the mic on.
     result.transcription = await resolveCapability();
+    // Front-door structural map — ALWAYS included (unlike `stats`, which is
+    // include_stats-gated): three cheap grouped-COUNT queries, so a fresh
+    // reader orients in one call. Scope-aware: a tag-scoped token's map
+    // covers only notes reachable through an in-scope tag (`tagFilter`
+    // restricts the underlying query rather than post-hoc filtering an
+    // unscoped rollup — see `getVaultMap`'s doc comment for why).
+    result.map =
+      tagScope.raw === null
+        ? getVaultMap(store.db)
+        : getVaultMap(store.db, { tagFilter: [...(tagScope.allowed ?? [])] });
     if (parseBool(parseQuery(url, "include_stats"), false)) {
       result.stats = await store.getVaultStats();
     }