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

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 } 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,
@@ -52,10 +59,11 @@ import {
   scrubParentCycleError,
   scrubReferencingTagsByScope,
   scrubTagFieldViolationsByScope,
+  scrubValidationStatusByScope,
   tagScopeForbidden,
   tagsWithinScope,
 } from "./tag-scope.ts";
-import { ParentCycleError, InvalidFieldDefaultError } from "../core/src/tag-schemas.ts";
+import { ParentCycleError, InvalidFieldDefaultError, InvalidFieldTypeError } from "../core/src/tag-schemas.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
 
 /**
@@ -811,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),
@@ -1016,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);
         }
@@ -1335,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);
@@ -1352,6 +1371,34 @@ async function handleNotesInner(
       if (contentRange.range && includeContent) {
         for (const n of output) applyContentRange(n, contentRange.range);
       }
+      // vault#555 fix 3 — attach validation_status on reads too (mirrors
+      // MCP query-notes). Additive, present only when a tag declares
+      // `fields`. Runs BEFORE metadata filtering so it sees full metadata
+      // regardless of `include_metadata`. Scrubbed for a tag-scoped caller
+      // (vault#555 auth review) so an out-of-scope co-tag's schema shape
+      // doesn't leak — `results` here is already scope-filtered, but a
+      // surviving note may carry an out-of-scope co-tag whose schema would
+      // otherwise appear in its validation_status. No-op when unscoped.
+      {
+        const statusById = new Map(
+          results.map((n) => [
+            n.id,
+            scrubValidationStatusByScope(
+              store.validateNoteAgainstSchemas({
+                path: n.path,
+                tags: n.tags,
+                metadata: n.metadata as Record<string, unknown> | undefined,
+              }),
+              tagScope.allowed,
+              tagScope.raw,
+            ),
+          ]),
+        );
+        for (const n of output as any[]) {
+          const status = statusById.get(n.id);
+          if (status) n.validation_status = status;
+        }
+      }
       if (inclMeta !== undefined && inclMeta !== true) {
         output = output.map((n: any) => filterMetadata(n, inclMeta));
       }
@@ -1398,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 };
@@ -1416,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);
         }
@@ -1475,13 +1529,111 @@ async function handleNotesInner(
       }
 
       const created: Note[] = [];
+      // Structured `links` are resolved in a second pass, after every note
+      // in this batch has been created (vault#555) — resolving inline (the
+      // old behavior) meant a link from item 0 to item 1's path silently
+      // dropped, since item 1 didn't exist yet at the moment item 0's links
+      // were processed. Mirrors the MCP create-note fix exactly (both
+      // 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) {
@@ -1491,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, {
@@ -1498,28 +1670,67 @@ 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);
 
-          // Create explicit links
           if (item.links) {
-            for (const link of item.links as { target: string; relationship: string }[]) {
-              const target = await resolveNote(store, link.target);
-              if (target) await store.createLink(note.id, target.id, link.relationship);
-            }
+            pendingLinks.push({ sourceId: note.id, links: item.links as { target: string; relationship: string }[] });
           }
 
           created.push((await store.getNote(note.id)) ?? note);
         }
+
+        // --- Resolve structured links (vault#555) ---
+        // Same semantics as [[wikilinks]]: ID or path/title match, tried now
+        // 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.
+        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);
+            } else {
+              const list = linkWarningsByNote.get(sourceId) ?? [];
+              list.push({
+                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);
+            }
+          }
+        }
       };
       try {
         await (batched ? transactionAsync(db, runBatch) : runBatch());
@@ -1567,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);
@@ -1584,8 +1799,37 @@ async function handleNotesInner(
       // Attach `validation_status` so HTTP create-note matches the MCP
       // surface (vault#287). `attachValidationStatus` returns the note
       // unchanged when no tag declares fields, so vaults without any tag
-      // schemas see no behavior change.
-      const final = refreshed.map((n) => attachValidationStatus(store, db, n));
+      // 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. `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);
+        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);
     }
 
@@ -1741,6 +1985,24 @@ async function handleNotesInner(
     const contentRange = parseContentRangeQuery(url, includeContent);
     if (contentRange.error) return contentRange.error;
     let result: any = includeContent ? { ...note } : toNoteIndex(note);
+    // vault#555 fix 3 — mirror the MCP query-notes fix: attach
+    // validation_status on reads too, not just on the one-time create/update
+    // write response. See core/src/mcp.ts's query-notes handler for the
+    // full rationale. Scrubbed for a tag-scoped caller (vault#555 auth
+    // review) so an out-of-scope co-tag's schema shape doesn't leak — no-op
+    // for unscoped callers (tagScope.raw === null).
+    {
+      const status = scrubValidationStatusByScope(
+        store.validateNoteAgainstSchemas({
+          path: note.path,
+          tags: note.tags,
+          metadata: note.metadata as Record<string, unknown> | undefined,
+        }),
+        tagScope.allowed,
+        tagScope.raw,
+      );
+      if (status) result.validation_status = status;
+    }
     const expand = parseExpandParams(url, db, tagScope);
     if (expand && includeContent && typeof result.content === "string") {
       expand.ctx.expanded.add(note.id);
@@ -1834,22 +2096,35 @@ 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.
+          const createWarnings: QueryWarning[] = [];
           if (linksAdd) {
             for (const link of linksAdd) {
-              const target = await resolveNote(store, link.target);
-              if (target) {
-                await store.createLink(created.id, target.id, link.relationship, link.metadata);
+              const targetId = resolveOrQueueLink(db, created.id, link.target, link.relationship);
+              if (targetId) {
+                await store.createLink(created.id, targetId, link.relationship, link.metadata);
+              } else {
+                createWarnings.push({
+                  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,
+                });
               }
             }
           }
           const final = await store.getNote(created.id);
           if (!final) return json({ error: "Note disappeared", error_type: "internal_error" }, 500);
-          const validated = attachValidationStatus(store, db, final);
+          const validated: any = attachValidationStatus(store, db, final);
+          if (createWarnings.length > 0) validated.warnings = createWarnings;
           const includeContentResp = body.include_content !== false;
           if (includeContentResp) return json({ ...validated, created: true });
           const lean: any = toNoteIndex(validated);
           const vs = (validated as any).validation_status;
           if (vs !== undefined) lean.validation_status = vs;
+          if (createWarnings.length > 0) lean.warnings = createWarnings;
           lean.created = true;
           return json(lean);
         }
@@ -1992,7 +2267,7 @@ async function handleNotesInner(
       const resolvedLinksToRemove: { targetId: string; relationship: string }[] = [];
       if (linksRemove) {
         for (const link of linksRemove) {
-          const target = await resolveNote(store, link.target);
+          const target = resolveStructuredLinkNote(db, link.target);
           if (!target) continue;
           resolvedLinksToRemove.push({ targetId: target.id, relationship: link.relationship });
           if (link.relationship === "wikilink" && target.path) {
@@ -2069,9 +2344,21 @@ async function handleNotesInner(
         gateStrictWrite(store, writeCtx, { path: note.path, tags: [...projectedTags], metadata: projectedMeta });
       }
 
-      if (Object.keys(updates).length > 0) {
+      // vault#555 fix 2 — tag and link mutations must bump `updated_at` too,
+      // not just core-field (content/path/metadata) changes. Mirrors the MCP
+      // `update-note` fix exactly: a tags-only or links-only PATCH with
+      // `force: true` (no `if_updated_at`) left `updates` empty, so
+      // `store.updateNote` was never even called and `updated_at` never
+      // 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;
+      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.
+        // write columns on the same UPDATE that bumps updated_at. `updates`
+        // may carry no core fields at all (a pure tag/link mutation) — that's
+        // fine: `noteOps.updateNote` unconditionally SETs
+        // `updated_at`/`last_updated_by`/`last_updated_via` whenever
+        // `skipUpdatedAt` isn't set, so this still issues a real UPDATE.
         updates.actor = writeCtx.actor;
         updates.via = writeCtx.via;
         await store.updateNote(note.id, updates);
@@ -2091,11 +2378,24 @@ async function handleNotesInner(
         await store.untagNote(note.id, body.tags.remove);
       }
 
-      // Add links
+      // 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.
+      const linkWarnings: QueryWarning[] = [];
       if (body.links?.add) {
         for (const link of body.links.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[]) {
-          const target = await resolveNote(store, link.target);
-          if (target) await store.createLink(note.id, target.id, link.relationship, link.metadata);
+          const targetId = resolveOrQueueLink(db, note.id, link.target, link.relationship);
+          if (targetId) {
+            await store.createLink(note.id, targetId, link.relationship, link.metadata);
+          } else {
+            linkWarnings.push({
+              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,
+            });
+          }
         }
       }
 
@@ -2130,6 +2430,7 @@ async function handleNotesInner(
           tagScope.raw,
         );
       }
+      if (linkWarnings.length > 0) validated.warnings = linkWarnings;
       const includeContentResp = body.include_content !== false;
       // `created: false` is appended to every update-path response so
       // sync-loop callers using `if_missing: "create"` can distinguish
@@ -2142,6 +2443,7 @@ async function handleNotesInner(
       // Carry the link echo across the lean conversion — `toNoteIndex`
       // drops unknown fields, same as the `validation_status` recipe above.
       if (validated.links !== undefined) lean.links = validated.links;
+      if (linkWarnings.length > 0) lean.warnings = linkWarnings;
       lean.created = false;
       return json(lean);
     } catch (e: any) {
@@ -2642,11 +2944,22 @@ export async function handleTags(
     // — silent 200s on main — is non-indexed type conflicts and indexed-flag
     // conflicts. See `collectCrossTagFieldViolations`'s doc comment.
     if (body.fields && typeof body.fields === "object" && !Array.isArray(body.fields)) {
+      const incomingFields = body.fields as Record<string, tagSchemaOps.TagFieldSchema>;
+      // vault#555 fix 5 — fold the own-field `default`/`type` checks into
+      // the SAME bundled report as the cross-tag ones. Before this, a bad
+      // `default` (and, since fix 4 added the check, an unrecognized
+      // `type`) went through `store.upsertTagRecord`'s fail-fast pre-
+      // validate below INSTEAD — a single-violation 400 that silently never
+      // mentioned any OTHER bad field in the same call. `unsupported_
+      // indexed_type`/`invalid_field_name` deliberately stay OUT of this
+      // bundle — REST's established single-violation `400
+      // invalid_indexed_field` contract for those two is unchanged
+      // (vault#478; see `collectCrossTagFieldViolations`'s doc comment).
       const fieldViolations = tagSchemaOps.collectCrossTagFieldViolations(
         store.db,
         putTagName,
-        body.fields as Record<string, tagSchemaOps.TagFieldSchema>,
-      );
+        incomingFields,
+      ).concat(tagSchemaOps.collectOwnFieldDefaultAndTypeViolations(incomingFields));
       if (fieldViolations.length > 0) {
         // Tag-scope scrub (vault#554 auth-and-scope fold): the write is
         // still rejected, but a violation whose conflicting declarer is
@@ -2694,15 +3007,26 @@ export async function handleTags(
       if (err instanceof InvalidFieldDefaultError) {
         // vault#553 Decision B — a declared `default` doesn't conform to its
         // own field's type/enum. Own-field error (no cross-tag data), so no
-        // scrub needed. Mirrors IndexedFieldError's 400 shape/posture — see
-        // store.upsertTagRecord's pre-validate comment for why REST hits
-        // this (fail-fast, single violation) while MCP's update-tag usually
-        // reports it bundled via `TagFieldConflictError` instead.
+        // scrub needed. DEFENSE-IN-DEPTH ONLY as of vault#555 fix 5 — the
+        // pre-check above (`collectOwnFieldDefaultAndTypeViolations`) now
+        // catches every `invalid_default` BEFORE reaching `store.upsertTagRecord`
+        // and reports it bundled via `tag_field_conflict` 422 instead; this
+        // branch only fires for a caller that somehow bypasses that pre-check.
         return json(
           { error: err.message, error_type: "invalid_field_default", field: err.field },
           400,
         );
       }
+      if (err instanceof InvalidFieldTypeError) {
+        // vault#555 fix 4 — a declared `type` isn't one of the six
+        // recognized values. Same defense-in-depth posture as
+        // InvalidFieldDefaultError above — the pre-check catches this in
+        // the normal path and reports it bundled instead.
+        return json(
+          { error: err.message, error_type: "invalid_field_type", field: err.field, type: err.type, valid_types: err.valid_types },
+          400,
+        );
+      }
       if (err instanceof ParentCycleError) {
         // vault#552: parent_names would close a cycle. Nothing was
         // persisted. Scope-scrub the cycle path for a tag-scoped caller —

package/src/tag-field-conflict-scope.test.ts

@@ -330,4 +330,48 @@ describe("invalid_indexed_field × tag scope — the 400 door is scrubbed too (w
     expect(caught).toBeInstanceOf(IndexedFieldError);
     expect(caught.message).toContain("mine-too");
   });
+
+  // vault#555 fix 4/5 — `invalid_type` and `invalid_default` are own-field
+  // violations (no `other_tag`, no cross-tag data to leak) so
+  // `scrubTagFieldViolationsByScope` is a documented no-op for them by
+  // construction. Pin that a scoped caller still gets the FULL violation
+  // (field/reason/message) — nothing accidentally strips it.
+  test("invalid_type and invalid_default violations pass through the scope-scrub untouched (no other_tag to scrub)", async () => {
+    seedVault("journal");
+    getVaultStore("journal");
+
+    // REST
+    const res = await handleTags(
+      new Request("http://localhost/api/tags/mine", {
+        method: "PUT",
+        body: JSON.stringify({
+          fields: {
+            weird: { type: "frobnicator" },
+            bad_default: { type: "string", enum: ["a", "b"], default: "zzz" },
+          },
+        }),
+      }),
+      getVaultStore("journal"),
+      "/mine",
+      { allowed: new Set(["mine"]), raw: ["mine"] },
+    );
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.violations).toHaveLength(2);
+    const byField = new Map(body.violations.map((v: any) => [v.field, v]));
+    expect(byField.get("weird").reason).toBe("invalid_type");
+    expect(byField.get("weird").other_tag).toBeUndefined();
+    expect(byField.get("bad_default").reason).toBe("invalid_default");
+
+    // MCP
+    const tool = await updateTagTool("journal", ["mine"]);
+    let caught: any;
+    try {
+      await tool.execute({ tag: "mine", fields: { weird: { type: "frobnicator" } } });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught.violations).toHaveLength(1);
+    expect(caught.violations[0].reason).toBe("invalid_type");
+  });
 });