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

package/core/src/mcp.ts

@@ -5,9 +5,17 @@ import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
-import { collectUnknownTagWarnings, emptySearchWarning, ignoredParamWarning, type QueryWarning } from "./query-warnings.js";
+import {
+  collectUnknownTagWarnings,
+  emptySearchWarning,
+  ignoredParamWarning,
+  computeSearchDidYouMean,
+  searchDidYouMeanWarning,
+  type QueryWarning,
+} from "./query-warnings.js";
 import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMode } from "./search-query.js";
 import * as linkOps from "./links.js";
+import { resolveOrQueueLink, resolveStructuredLinkNote } from "./wikilinks.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
 import {
@@ -256,6 +264,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
 
 Defaults: include_content=true for single note, false for lists. include_links=false. tag_match="any".
 
+Each result carries \`validation_status\` when any tag it carries declares \`fields\` (vault#555) — same advisory-warnings shape create-note/update-note attach, now also on reads (an out-of-enum value on a non-strict field is stored and findable, but still surfaces its \`enum_mismatch\` warning here, not just on the write that introduced it). Absent entirely when no tag on the note declares a schema.
+
 Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bounded read of note content — the response carries the slice plus \`content_total_length\` and \`content_next_offset\` (null when complete). Loop, feeding \`content_next_offset\` back as \`content_offset\`, to read a note too large for one response.
 
 Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.
@@ -265,7 +275,9 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
 - Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.
 
-\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.`,
+\`search\` is literal-by-default (vault#551): your text is escaped and phrase-quoted before it reaches FTS5, so ordinary punctuation ("didn't", "eleven-day", "18.6") is matched as literal content instead of being parsed as query syntax (a bare hyphen used to mean NOT; an apostrophe or decimal point used to break the parse and silently return \`[]\`). Pass \`search_mode: "advanced"\` to opt back into raw FTS5 syntax (AND/OR/NOT, manual phrase quoting, prefix \`*\`) — a malformed advanced query now throws a structured error instead of silently returning \`[]\`. \`sort\` is honored under \`search\` too: omit it for relevance ranking (default), or pass "asc"/"desc" to order by \`created_at\` instead.
+
+\`search\` indexes BOTH a note's title (\`path\`) and its \`content\` (vault#551 WS2C, schema v25) — a title match is weighted far above a passing body mention, so a dedicated note on a topic outranks another note that merely references it. Every result carries a \`score\` field (higher = more relevant; only meaningful as a RELATIVE comparison within one result set). Word matching also stems regular English affixes ("firefighter" matches "firefighters", "microbe" matches "microbes") — irregular plurals with a consonant change ("wolf"/"wolves") aren't covered by stemming. A search that returns ZERO results may carry a \`search_did_you_mean\` warning suggesting the closest indexed term when one looks like a likely typo (only unscoped sessions — tag-scoped tokens never see it, since the suggestion is computed vault-wide).`,
       inputSchema: {
         type: "object",
         properties: {
@@ -322,7 +334,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           search: {
             type: "string",
             description:
-              'Full-text search query. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking.',
+              'Full-text search query, matched against BOTH a note\'s title (path) and its content — a title match ranks far above a passing body mention. Literal-by-default (vault#551): your text is escaped and phrase-quoted before reaching FTS5, so punctuation ("didn\'t", "eleven-day", "18.6") is matched as literal content rather than parsed as FTS5 query syntax. Pass `search_mode: "advanced"` for raw FTS5 syntax (boolean/phrase/prefix operators). `sort` is honored under search (see below) — default is relevance ranking. Matching stems regular affixes ("firefighter"/"firefighters") but not irregular plurals ("wolf"/"wolves"). Results carry a `score` field (higher = more relevant, relative within this result set only). A zero-result search may carry a `search_did_you_mean` warning (unscoped sessions only).',
           },
           search_mode: {
             type: "string",
@@ -449,6 +461,24 @@ Response shape (vault#550 — three variants, pick by what you passed):
           // `expand`).
           if (contentRange && !includeContent) throw contentRangeRequiresContent();
           let result: any = includeContent ? { ...note } : noteOps.toNoteIndex(note);
+          // --- Attach validation_status (vault#555 fix 3) ---
+          // Mirrors create/update-note's `attachValidationStatus` — additive,
+          // present only when at least one tag on the note declares
+          // `fields`. Before this, `validation_status` (including an
+          // `enum_mismatch` on a non-strict indexed field) was surfaced ONLY
+          // on the one-time create/update WRITE response; a caller reading
+          // the note back via `query-notes` (the natural way to re-check a
+          // value after write) saw nothing at all — contradicting the
+          // documented "advisory violations surface as warnings" for every
+          // read after the initial write.
+          {
+            const status = store.validateNoteAgainstSchemas({
+              path: note.path,
+              tags: note.tags,
+              metadata: note.metadata as Record<string, unknown> | undefined,
+            });
+            if (status) result.validation_status = status;
+          }
           if (expandCtx && includeContent && typeof result.content === "string") {
             // Mark the top-level note as already expanded so it can't recursively inline itself.
             expandCtx.expanded.add(note.id);
@@ -603,6 +633,20 @@ Response shape (vault#550 — three variants, pick by what you passed):
               mode,
               sort: params.sort as "asc" | "desc" | undefined,
             });
+            // Zero-result `did_you_mean` (vault#551 WS2B) — cheap (a bounded
+            // FTS5-vocabulary scan) and ONLY computed on the already-rare
+            // empty-result path, mirroring `unknown_tag`'s did_you_mean.
+            // Scope-unaware by construction (same as `collectUnknownTagWarnings`
+            // above) — safe here because `applyTagScopeWrappers`'s
+            // `query-notes` wrapper (`src/mcp-tools.ts`) strips the ENTIRE
+            // `warnings` array for a tag-scoped session before it reaches the
+            // caller, so this never leaks out-of-scope vocabulary to one.
+            if (results.length === 0) {
+              const suggestion = computeSearchDidYouMean(db, params.search as string);
+              if (suggestion) {
+                queryWarnings.push(searchDidYouMeanWarning(params.search as string, suggestion));
+              }
+            }
           }
         } else {
           // --- Structured query ---
@@ -715,6 +759,29 @@ Response shape (vault#550 — three variants, pick by what you passed):
           for (const n of output) applyContentRange(n, contentRange);
         }
 
+        // --- Attach validation_status (vault#555 fix 3) ---
+        // Same reasoning as the single-note path above — additive, present
+        // only when at least one tag on the note declares `fields`. Runs
+        // BEFORE metadata filtering so it sees the note's full metadata
+        // regardless of `include_metadata`; the `validation_status` key
+        // itself survives `filterMetadata` (which only touches `metadata`).
+        {
+          const statusById = new Map(
+            results.map((n) => [
+              n.id,
+              store.validateNoteAgainstSchemas({
+                path: n.path,
+                tags: n.tags,
+                metadata: n.metadata as Record<string, unknown> | undefined,
+              }),
+            ]),
+          );
+          for (const n of output as any[]) {
+            const status = statusById.get(n.id);
+            if (status) n.validation_status = status;
+          }
+        }
+
         // --- Apply metadata filtering ---
         if (includeMetadata !== undefined && includeMetadata !== true) {
           output = output.map((n: any) => filterMetadata(n, includeMetadata));
@@ -803,7 +870,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
               },
               required: ["target", "relationship"],
             },
-            description: "Links to create from this note",
+            description: "Links to create from this note. `target` resolves with the SAME semantics as a [[wikilink]] (vault#555) — ID, then exact path, then basename/title. A target created LATER in the same `notes` batch, or by a future call, resolves automatically (queued + backfilled) — the response carries an `unresolved_link` warning naming the target in the meantime; never silently dropped.",
           },
           created_at: { type: "string", description: "ISO timestamp (defaults to now)" },
           // Batch
@@ -835,6 +902,20 @@ Response shape (vault#550 — three variants, pick by what you passed):
         }
 
         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. Deferring makes
+        // within-batch forward-refs resolve exactly like a same-content
+        // [[wikilink]] already does. `pendingLinks` carries the SOURCE
+        // note id (known immediately — createNote assigns it synchronously)
+        // alongside each item's raw `links` array.
+        const pendingLinks: { sourceId: string; links: { target: string; relationship: string }[] }[] = [];
+        // Per-note `unresolved_link` warnings (vault#555 — "never silent").
+        // Populated in the second pass; folded into each note's response
+        // below, same pattern as `validation_status`.
+        const linkWarningsByNote = new Map<string, QueryWarning[]>();
         // Wrap multi-item batches in a SQLite transaction so a mid-batch
         // failure rolls back every prior insert — see #236. This guards
         // anything thrown from store.createNote / createLink (path
@@ -869,18 +950,37 @@ Response shape (vault#550 — three variants, pick by what you passed):
               via: writeVia,
             });
 
-            // Create explicit links (not wikilinks — those are automatic)
             if (item.links) {
-              for (const link of item.links as { target: string; relationship: string }[]) {
-                const target = resolveNote(db, 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(noteOps.getNote(db, 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 (typo, or a note that arrives in a later
+          // call) is queued for lazy resolution — it backfills automatically
+          // the moment a matching note is created — 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);
+              }
+            }
+          }
         };
         await (batched ? transactionAsync(db, runBatch) : runBatch());
 
@@ -911,8 +1011,17 @@ Response shape (vault#550 — three variants, pick by what you passed):
               })();
 
         // Attach `validation_status` from any tag's `fields` declaration that
-        // applies to this note, against the post-defaults state.
-        const final = refreshed.map((n) => attachValidationStatus(store, db, n));
+        // applies to this note, against the post-defaults state. Fold in any
+        // `unresolved_link` warnings collected above (vault#555) — additive,
+        // present only when this note's `links` had a target that didn't
+        // resolve.
+        const final = refreshed.map((n) => {
+          const validated = attachValidationStatus(store, db, n);
+          const warnings = linkWarningsByNote.get(n.id);
+          return warnings && warnings.length > 0
+            ? ({ ...validated, warnings } as Note & { warnings: QueryWarning[] })
+            : validated;
+        });
         return batch ? final : final[0];
       },
     },
@@ -1005,7 +1114,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
                 },
               },
             },
-            description: "Links to add/remove",
+            description: "Links to add/remove. `add[].target` resolves with the SAME semantics as a [[wikilink]] (vault#555) — ID, then exact path, then basename/title — and lazily backfills (queued) when the target arrives later; the response carries an `unresolved_link` warning naming the target in the meantime, never a silent drop.",
           },
           include_content: {
             type: "boolean",
@@ -1099,6 +1208,14 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
         // key this so the create-on-missing branch, which assigns the id
         // late, can register correctly.
         const echoLinkIds = new Set<string>();
+        // Structured `links.add` entries, deferred to a second pass AFTER
+        // every item in this batch has been created/updated (vault#555) —
+        // resolving inline would silently drop a link from item 0 to a note
+        // item 1 (later in the same batch) creates via `if_missing:
+        // "create"`. Same fix as create-note's `pendingLinks`.
+        const pendingLinks: { sourceId: string; links: { target: string; relationship: string; metadata?: Record<string, unknown> }[] }[] = [];
+        // Per-note `unresolved_link` warnings (vault#555 — "never silent").
+        const linkWarningsByNote = new Map<string, QueryWarning[]>();
         // Wrap multi-item batches in a SQLite transaction so any mid-batch
         // failure (precondition error, content_edit miss, ConflictError, …)
         // rolls back every prior mutation in the batch — see #236.
@@ -1189,13 +1306,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
                 });
                 const created = await store.createNote(content, createOpts);
                 await applySchemaDefaults(store, db, [created.id], created.tags ?? []);
-                // Apply links.add if the caller declared any.
+                // Defer links.add resolution to the second pass (vault#555)
+                // — same reasoning as create-note.
                 const linksAdd = (item.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
                 if (linksAdd) {
-                  for (const link of linksAdd) {
-                    const target = resolveNote(db, link.target);
-                    if (target) await store.createLink(created.id, target.id, link.relationship, link.metadata);
-                  }
+                  pendingLinks.push({ sourceId: created.id, links: linksAdd });
                 }
                 const fresh = noteOps.getNote(db, created.id) ?? created;
                 updated.push(fresh);
@@ -1303,7 +1418,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const resolvedLinksToRemove: { targetId: string; relationship: string }[] = [];
             if (linksRemove) {
               for (const link of linksRemove) {
-                const target = resolveNote(db, 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) {
@@ -1377,8 +1492,25 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               enforceStrict({ path: note.path, tags: [...projectedTags], metadata: projectedMeta });
             }
 
+            // vault#555 fix 2 — tag and link mutations must bump `updated_at`
+            // too, not just core-field (content/path/metadata) changes. Before
+            // this, a tags-only or links-only call with `force: true` (no
+            // `if_updated_at`) left `updates` completely empty — the branch
+            // below skipped `store.updateNote` ENTIRELY, so `updated_at` never
+            // moved even though tags/note_tags or links genuinely changed.
+            // (A tags-only call that happened to pass `if_updated_at` already
+            // worked by accident — it populated `updates.if_updated_at` — which
+            // is why this was easy to miss in ad hoc testing.) This breaks
+            // cursor polling (`ORDER BY updated_at`) and any `updated_at`-based
+            // sync filter: the mutation is real but invisible to a
+            // since-last-check loop.
+            const hasTagMutation = ((item.tags as any)?.add?.length ?? 0) > 0
+              || ((item.tags as any)?.remove?.length ?? 0) > 0;
+            const hasLinkMutation = (item.links as any)?.add !== undefined
+              || (item.links as any)?.remove !== undefined;
+
             let result: Note;
-            if (Object.keys(updates).length > 0) {
+            if (Object.keys(updates).length > 0 || hasTagMutation || hasLinkMutation) {
               // Write-attribution (vault#298): stamp the most-recent-write
               // columns on the same UPDATE that bumps `updated_at`. Only set when
               // there's a real change to write (the empty-updates branch below
@@ -1389,7 +1521,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               // store.updateNote routes through noteOps.updateNote, which runs
               // the UPDATE (with optional `AND updated_at IS ?`) atomically and
               // throws ConflictError on mismatch. No mutations have happened
-              // yet, so a throw here leaves the note untouched.
+              // yet, so a throw here leaves the note untouched. `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
+              // (not the true no-op/precondition-only branch, which only fires
+              // when the caller passes ZERO fields AND no mutation is pending).
               result = await store.updateNote(note.id, updates);
             } else {
               result = note;
@@ -1410,15 +1548,10 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               await store.untagNote(note.id, tagsOp.remove);
             }
 
-            // --- Add links ---
+            // --- Add links (deferred to the second pass — vault#555) ---
             const linksAdd = (item.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
             if (linksAdd) {
-              for (const link of linksAdd) {
-                const target = resolveNote(db, link.target);
-                if (target) {
-                  await store.createLink(note.id, target.id, link.relationship, link.metadata);
-                }
-              }
+              pendingLinks.push({ sourceId: note.id, links: linksAdd });
             }
 
             // Echo links if this update mutated them (`links.add`/`links.remove`)
@@ -1431,6 +1564,32 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             // Re-read for final state
             updated.push(noteOps.getNote(db, note.id) ?? result);
           }
+
+          // --- Resolve structured `links.add` (vault#555) ---
+          // Deferred until every item in this batch has been created/
+          // updated — same [[wikilink]] semantics (ID or path/title match),
+          // now tried against the FULL post-batch note set so a forward-ref
+          // to a sibling item resolves. A target that still doesn't resolve
+          // is queued for lazy resolution (backfills when a matching note
+          // is created later) and surfaces an `unresolved_link` warning —
+          // never silently dropped.
+          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, link.metadata);
+              } 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);
+              }
+            }
+          }
         };
         await (batched ? transactionAsync(db, runBatch) : runBatch());
 
@@ -1452,9 +1611,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           // when triggered — mirrors the GET / query-notes shape exactly via
           // the shared `linkOps.getLinksHydrated` call. vault feedback #8.
           const echoLinks = echoLinkIds.has(n.id);
+          // `unresolved_link` warnings (vault#555) — additive, present only
+          // when this note's `links.add` had a target that didn't resolve.
+          const warnings = linkWarningsByNote.get(n.id);
           if (includeContent) {
             const full: any = { ...validated, created };
             if (echoLinks) full.links = linkOps.getLinksHydrated(db, n.id);
+            if (warnings && warnings.length > 0) full.warnings = warnings;
             return full as Note & { created: boolean };
           }
           const lean: any = noteOps.toNoteIndex(validated);
@@ -1464,6 +1627,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           // Carry the link echo across the lean conversion — `toNoteIndex`
           // drops unknown fields.
           if (echoLinks) lean.links = linkOps.getLinksHydrated(db, n.id);
+          if (warnings && warnings.length > 0) lean.warnings = warnings;
           return lean;
         });
         return batch ? final : final[0];
@@ -1592,7 +1756,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             additionalProperties: {
               type: "object",
               properties: {
-                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object — all six are accepted for storage + advisory validation. Only string/integer/boolean are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field)." },
+                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object — all six are accepted for storage + advisory validation; any OTHER value is rejected outright (error_type invalid_field_type, vault#555 — bundled with every other violation in the same call, see the `update-tag` tool description). Only string/integer/boolean are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field)." },
                 description: { type: "string" },
                 enum: { type: "array", items: { type: "string" }, description: "Allowed values. Does NOT auto-backfill — a note that omits this field stays without it unless `default` is also set (vault#553; the pre-0.7.0 behavior of silently defaulting to the first enum value is retired). Set `default` explicitly if you want backfill." },
                 default: { description: "Explicit backfill value (vault#553) applied when a note gains this tag without setting the field. Must conform to this field's own `type` (and `enum`, if declared) — a non-conforming default is rejected (invalid_default / invalid_field_default) rather than silently stored. Omit entirely to leave the field ABSENT (not backfilled) on notes that don't set it — this is what makes `exists:false` a trustworthy \"never set\" query." },

package/core/src/notes.ts

@@ -22,7 +22,12 @@ import {
 import { getIndexedField, releaseField } from "./indexed-fields.js";
 import { computeExpandedTagCounts, loadTagHierarchy, stripTagHash } from "./tag-hierarchy.js";
 import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
-import { buildLiteralSearchQuery, type SearchMode } from "./search-query.js";
+import {
+  buildLiteralSearchQuery,
+  SEARCH_WEIGHT_PATH,
+  SEARCH_WEIGHT_CONTENT,
+  type SearchMode,
+} from "./search-query.js";
 
 let idCounter = 0;
 
@@ -1336,12 +1341,41 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
  *     invariant is ever broken it still surfaces as an honest error, not a
  *     500. Signals a vault bug worth reporting.
  */
+/**
+ * FTS5's own error text for a syntax mistake is written for someone who
+ * already knows FTS5's grammar — "no such column: espresso" for a bare
+ * leading `-espresso` (NOT with no left-hand term — FTS5's `-`/`NOT` is a
+ * BINARY operator, so a lone `-token` with nothing before it gets
+ * misparsed as `column:term` filter syntax and fails looking for a column
+ * named after the token) is confusing/leaky rather than actionable: it
+ * reads as if a column literally named "espresso" was expected, which
+ * exposes FTS5-internal parsing behavior instead of explaining the actual
+ * mistake (vault#551 WS2B item 4 — interim harness finding). Detected
+ * generically off the FTS5 error text (`/no such column:/i`) rather than
+ * re-parsing the query ourselves, since the SAME message also covers the
+ * other real cause (an explicit `column:term` filter naming a column that
+ * isn't one of `notes_fts`'s declared columns, `path`/`content`) — the hint
+ * below covers both without claiming to know which one happened.
+ */
+function advancedModeColumnHint(causeMessage: string): string | null {
+  if (!/no such column:/i.test(causeMessage)) return null;
+  return (
+    `FTS5 read part of this query as column-filter syntax ("column:term") or as a ` +
+    `leading "-" with no term to its left — NOT/"-" is a BINARY operator in FTS5 ` +
+    `("good -bad", not "-bad" alone). Indexed columns are "path" and "content". ` +
+    `Add a preceding positive term before a NOT, quote the phrase to search it ` +
+    `literally, or use search_mode:"literal" (the default) to skip advanced syntax entirely.`
+  );
+}
+
 function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): QueryError {
   const causeMessage = err instanceof Error ? err.message : String(err);
+  const columnHint = mode === "advanced" ? advancedModeColumnHint(causeMessage) : null;
   const hint =
-    mode === "advanced"
+    columnHint ??
+    (mode === "advanced"
       ? `FTS5 rejected this as advanced query syntax (${causeMessage}). Fix the syntax, or omit search_mode:"advanced" for literal (punctuation-safe) search.`
-      : `FTS5 rejected the escaped literal query (${causeMessage}) — this should be impossible after literal-mode escaping + control-char sanitization; please report it as a vault bug.`;
+      : `FTS5 rejected the escaped literal query (${causeMessage}) — this should be impossible after literal-mode escaping + control-char sanitization; please report it as a vault bug.`);
   return new QueryError(`invalid search syntax: ${causeMessage}`, "INVALID_QUERY", {
     error_type: "invalid_search_syntax",
     field: "search",
@@ -1377,20 +1411,33 @@ export function searchNotes(
     ftsQuery = query;
   }
 
+  // Weighted bm25 relevance expression (vault#551 WS2C, schema v25):
+  // `notes_fts` now indexes `path` (title, column 0) then `content` (body,
+  // column 1) — SEARCH_WEIGHT_PATH/SEARCH_WEIGHT_CONTENT bias ranking so a
+  // title match outranks a passing body mention. Raw SQLite bm25 is
+  // negative-is-better; `-1.0 * bm25(...)` flips it so bigger is more
+  // relevant (see `Note.score`'s doc comment for the external contract).
+  // The weights are our own numeric constants (not user input) interpolated
+  // directly — bm25()'s weight arguments are positional per-column
+  // multipliers, not general SQL expressions callers can influence.
+  const scoreExpr = `(-1.0 * bm25(notes_fts, ${SEARCH_WEIGHT_PATH}, ${SEARCH_WEIGHT_CONTENT}))`;
+
   // `sort` honored under search (vault#551 WS2A item 3): default stays FTS5
-  // relevance (`rank`, unchanged); an EXPLICIT `sort: "asc"|"desc"` switches
-  // to `created_at` ordering. Checked against the literal string values (not
-  // truthiness) so an absent `sort` can never accidentally match a branch.
-  // `n.id ${direction}` is appended as a deterministic tiebreaker — same
-  // rationale as `queryNotes` (two notes at the same created_at millisecond
-  // would otherwise return in arbitrary/unstable order). `rank` needs no
-  // tiebreaker (bm25 score is effectively unique per row).
+  // relevance (the weighted `score` expression); an EXPLICIT
+  // `sort: "asc"|"desc"` switches to `created_at` ordering. Checked against
+  // the literal string values (not truthiness) so an absent `sort` can
+  // never accidentally match a branch. `n.id ${direction}` is appended as a
+  // deterministic tiebreaker in every branch — two notes at the same
+  // created_at millisecond (structured-sort branches) OR with an
+  // identical weighted score (relevance branch — much more likely than
+  // with unweighted `rank`, since many notes share "zero path matches")
+  // would otherwise return in arbitrary/unstable order.
   const orderBy =
     opts?.sort === "asc"
       ? "n.created_at ASC, n.id ASC"
       : opts?.sort === "desc"
         ? "n.created_at DESC, n.id DESC"
-        : "rank";
+        : "score DESC, n.id ASC";
 
   if (opts?.tags && opts.tags.length > 0) {
     // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
@@ -1406,14 +1453,14 @@ export function searchNotes(
       // DISTINCT over full rows. The FTS join itself is 1:1 on rowid.
       const tagPlaceholders = searchTags.map(() => "?").join(", ");
       const rows = db.prepare(`
-        SELECT n.* FROM notes n
+        SELECT n.*, ${scoreExpr} AS score FROM notes n
         JOIN notes_fts fts ON fts.rowid = n.rowid
         WHERE notes_fts MATCH ?
           AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
         ORDER BY ${orderBy}
         LIMIT ?
-      `).all(ftsQuery, ...searchTags, limit) as NoteRow[];
-      return notesWithTags(db, rows);
+      `).all(ftsQuery, ...searchTags, limit) as (NoteRow & { score: number })[];
+      return notesWithTags(db, rows, scoresById(rows));
     } catch (err) {
       // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
       // advanced mode expects it (the caller passed raw syntax); literal
@@ -1429,27 +1476,44 @@ export function searchNotes(
 
   try {
     const rows = db.prepare(`
-      SELECT n.* FROM notes n
+      SELECT n.*, ${scoreExpr} AS score FROM notes n
       JOIN notes_fts fts ON fts.rowid = n.rowid
       WHERE notes_fts MATCH ?
       ORDER BY ${orderBy}
       LIMIT ?
-    `).all(ftsQuery, limit) as NoteRow[];
-    return notesWithTags(db, rows);
+    `).all(ftsQuery, limit) as (NoteRow & { score: number })[];
+    return notesWithTags(db, rows, scoresById(rows));
   } catch (err) {
     if (err instanceof QueryError) throw err;
     throw searchSyntaxError(query, err, mode);
   }
 }
 
-/** Map rows → Notes with tags hydrated in one batched query. */
-function notesWithTags(db: Database, rows: NoteRow[]): Note[] {
+/**
+ * Map rows → Notes with tags hydrated in one batched query. `scores`
+ * (vault#551 WS2C) is an optional id → weighted-bm25-score map, attached
+ * onto each returned `Note.score` when present — ONLY `searchNotes`'s two
+ * callers pass it; every other caller (plain `queryNotes`, `getNotesByIds`,
+ * ...) omits it and gets byte-identical output to before `score` existed.
+ */
+function notesWithTags(db: Database, rows: NoteRow[], scores?: Map<string, number>): Note[] {
   const notes = rows.map(rowToNote);
   const tagsById = getNoteTagsForNotes(db, notes.map((n) => n.id));
-  for (const note of notes) note.tags = tagsById.get(note.id) ?? [];
+  for (const note of notes) {
+    note.tags = tagsById.get(note.id) ?? [];
+    if (scores) {
+      const s = scores.get(note.id);
+      if (s !== undefined) note.score = s;
+    }
+  }
   return notes;
 }
 
+/** Build an id → score map from search result rows carrying a `score` column. */
+function scoresById(rows: (NoteRow & { score: number })[]): Map<string, number> {
+  return new Map(rows.map((r) => [r.id, r.score]));
+}
+
 // ---- Tag Operations ----
 
 export function tagNote(db: Database, noteId: string, tags: string[]): void {
@@ -1862,11 +1926,17 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       const candidates = db
         .prepare(`SELECT id, content FROM notes WHERE content IS NOT NULL AND content != '' AND (${orClauses})`)
         .all(...params) as { id: string; content: string }[];
-      const updateStmt = db.prepare("UPDATE notes SET content = ? WHERE id = ?");
+      // vault#555 fix 2 — this content rewrite is a real persisted-state
+      // change (the note's `#oldtag` references literally became
+      // `#newtag`) and must bump `updated_at` like any other content
+      // write, or a cursor/sync-poll loop never sees it. Shares the one
+      // `now` timestamp for the whole cascade (same convention as the
+      // tag-row rename pass above).
+      const updateStmt = db.prepare("UPDATE notes SET content = ?, updated_at = ? WHERE id = ?");
       for (const row of candidates) {
         const next = rewriteNoteBody(row.content, renames);
         if (next === row.content) continue;
-        updateStmt.run(next, row.id);
+        updateStmt.run(next, now, row.id);
         notesRewritten++;
       }
     }
@@ -1881,11 +1951,13 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       const candidates = db
         .prepare(`SELECT id, path FROM notes WHERE path IS NOT NULL AND (${orClauses})`)
         .all(...params) as { id: string; path: string }[];
-      const updateStmt = db.prepare("UPDATE notes SET path = ? WHERE id = ?");
+      // vault#555 fix 2 — same reasoning as the content rewrite above: a
+      // path rewrite is a real persisted-state change.
+      const updateStmt = db.prepare("UPDATE notes SET path = ?, updated_at = ? WHERE id = ?");
       for (const row of candidates) {
         const next = rewriteTagConfigPath(row.path, renames);
         if (next === row.path) continue;
-        updateStmt.run(next, row.id);
+        updateStmt.run(next, now, row.id);
         pathsRenamed++;
       }
     }
@@ -2120,6 +2192,7 @@ export function toNoteIndex(note: Note): NoteIndex {
     metadata: note.metadata,
     byteSize,
     preview,
+    ...(note.score !== undefined ? { score: note.score } : {}),
   };
 }