@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/routes.ts

@@ -11,13 +11,22 @@
  * and the Request, and returns a Response.
  */
 
-import type { Store, Note } from "../core/src/types.ts";
+import type { Store, Note, QueryOpts } from "../core/src/types.ts";
+import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import {
+  parseContentRange,
+  applyContentRange,
+  contentRangeRequiresContent,
+  type ContentRange,
+} from "../core/src/content-range.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import {
+  buildExpandVisibility,
+  filterHydratedLinksByTagScope,
   filterNotesByTagScope,
   noteWithinTagScope,
   tagScopeForbidden,
@@ -44,8 +53,16 @@ import {
 } from "../core/src/expand.ts";
 import { join, extname, normalize } from "path";
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
-import { vaultDir } from "./config.ts";
+import { assetsDir, readGlobalConfig, readVaultConfig } from "./config.ts";
 import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+// usage.ts imports `assetsDir` from config.ts (neutral ground), so this import
+// of invalidateUsageCache does NOT form a cycle — routes.ts → usage.ts only.
+import { invalidateUsageCache } from "./usage.ts";
+
+// Re-export `assetsDir` (now defined in config.ts) so the existing callers
+// that import it from this module — mirror-deps, mirror-routes, server,
+// triggers, cli — keep working unchanged.
+export { assetsDir };
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -71,11 +88,58 @@ function parseQuery(url: URL, key: string): string | null {
   return url.searchParams.get(key);
 }
 
+/**
+ * Parse `link_count_direction` (vault feedback #4). Defaults to "both";
+ * anything other than the three known values falls back to "both" so a
+ * typo silently degrades to the documented default rather than erroring.
+ *
+ * Tag-scope note (symmetric with the MCP param description): `linkCount`
+ * is a raw degree that MAY include edges to notes a tag-scoped token can't
+ * see — the tag-scope filter runs post-query, over the result notes, not
+ * their neighbors. Only the number leaks, not the neighbor.
+ */
+function parseLinkCountDirection(url: URL): "both" | "outbound" | "inbound" {
+  const v = url.searchParams.get("link_count_direction");
+  if (v === "outbound" || v === "inbound") return v;
+  return "both";
+}
+
 function parseQueryList(url: URL, key: string): string[] | undefined {
   const val = url.searchParams.get(key);
   return val ? val.split(",") : undefined;
 }
 
+/**
+ * Parse `?content_offset=` / `?content_length=` (content range — bounded
+ * reads for large notes; unit is UTF-8 bytes, see core/src/content-range.ts
+ * for the codepoint-boundary slicing rules). Returns `{ range: null }` when
+ * neither param is present (response byte-identical to the no-pagination
+ * shape), or `{ error }` (400 INVALID_QUERY) on invalid values or when the
+ * response shape excludes content — range params on a content-less shape
+ * error loudly rather than silently no-op, same policy as `?expand=`.
+ */
+function parseContentRangeQuery(
+  url: URL,
+  includeContent: boolean,
+): { range: ContentRange | null; error?: Response } {
+  try {
+    const range = parseContentRange(
+      parseQuery(url, "content_offset") ?? undefined,
+      parseQuery(url, "content_length") ?? undefined,
+    );
+    if (range && !includeContent) throw contentRangeRequiresContent();
+    return { range };
+  } catch (e: any) {
+    // Duck-type on `name` — core is a separate module, so `instanceof`
+    // is fragile across bundling boundaries (same note as the QueryError
+    // handling in the structured-query path below).
+    if (e && e.name === "QueryError") {
+      return { range: null, error: json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400) };
+    }
+    throw e;
+  }
+}
+
 /**
  * Parse the extension query parameter (vault#328). Two accepted shapes:
  *   - `?extension=csv` (single value → string)
@@ -353,6 +417,180 @@ function parseMetaBrackets(url: URL): {
   return result;
 }
 
+/**
+ * Parse the `?metadata=<json>` alias on GET /api/notes — the JSON-object form
+ * of the metadata filter, symmetric with the nested `metadata` object MCP
+ * forwards verbatim (`core/src/mcp.ts`). The value is a JSON object of the form
+ * `{"field":{"op":value}}` (operator query) or `{"field":value}` (shorthand
+ * equality via the engine's json_extract fallback).
+ *
+ * This exists because the bracket grammar (`?meta[field][op]=value`) couldn't
+ * see a `metadata=` param at all — it was silently dropped, and the query
+ * returned ALL tag-matching notes (a silent wrong result, not an error).
+ *
+ * We do NOT validate operators here — the parsed object lowers straight into
+ * `queryNotes`, where `validateOperatorObject` raises a loud 400 on unknown
+ * operators (caught by the QueryError handler in handleNotes). We only enforce
+ * that the param parses and is a non-null, non-array plain object; anything
+ * else is a malformed filter the engine can't consume.
+ *
+ * An empty object (`metadata={}`) carries no filter intent, so it's treated as
+ * absent: it sets no metadata filter AND doesn't trip the both-forms guard, so
+ * it composes harmlessly with bracket params.
+ *
+ * Returns `{ metadata?, error? }`. When `error` is set the caller returns it
+ * directly (already shaped as a 400 with `error` + `code`).
+ */
+function parseMetadataJsonAlias(url: URL): {
+  metadata?: Record<string, unknown>;
+  error?: Response;
+} {
+  const raw = parseQuery(url, "metadata");
+  if (raw === null) return {};
+
+  const malformed = (detail: string): Response =>
+    json(
+      {
+        error: `metadata query param must be a JSON object of the form {"field":{"op":value}} — ${detail}`,
+        code: "INVALID_QUERY",
+      },
+      400,
+    );
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return { error: malformed(`failed to parse: ${e instanceof Error ? e.message : String(e)}`) };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const got = Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed;
+    return { error: malformed(`got ${got}`) };
+  }
+  // Empty object → no filter intent. Return absent so it neither sets a
+  // metadata filter nor trips the both-forms guard in the handler.
+  if (Object.keys(parsed).length === 0) return {};
+  return { metadata: parsed as Record<string, unknown> };
+}
+
+/**
+ * Parse + validate the `?expand=` tag-expansion axis (vault tag `expand` axis).
+ * Shared by `parseNotesQueryOpts` (structured + subscribe) AND the full-text
+ * search branch of `handleNotes` (which bypasses `parseNotesQueryOpts`), so the
+ * enum lives in exactly one place and `GET /notes?search=...&expand=bogus` is
+ * validated identically to the structured path.
+ *
+ * Returns `{ expand }` (undefined when absent/empty → store defaults to
+ * "subtypes") or `{ error }` (a 400 Response) on an unknown value.
+ */
+export function parseExpandParam(url: URL): { expand?: TagExpandMode; error?: Response } {
+  const expandParam = parseQuery(url, "expand");
+  if (expandParam === null || expandParam === "") return {};
+  if (!(TAG_EXPAND_MODES as readonly string[]).includes(expandParam)) {
+    return {
+      error: json(
+        {
+          error: `invalid \`expand\` value "${expandParam}" — must be one of ${TAG_EXPAND_MODES.map((m) => `"${m}"`).join(", ")}. Omit for the default ("subtypes": parent_names descendants).`,
+          code: "INVALID_QUERY",
+        },
+        400,
+      ),
+    };
+  }
+  return { expand: expandParam as TagExpandMode };
+}
+
+/**
+ * Parse the shared notes-query parameters (tags / excludeTags / path /
+ * pathPrefix / extension / metadata filters / date filters / sort / paging /
+ * cursor) into a `QueryOpts`, plus flags for the query shapes that the live
+ * subscription endpoint must reject (`search`, `near`, `cursor`).
+ *
+ * Factored out of `handleNotesInner`'s structured-query branch so the
+ * `/subscribe` route evaluates the SAME predicate the snapshot query does —
+ * predicate parity by construction, not copy-paste. `handleNotesInner` keeps
+ * its own inline parsing for the single-note (`id`) and full-text (`search`)
+ * branches; this helper covers the structured-query shape both endpoints share.
+ *
+ * Returns `{ error }` (a 400 Response) on a malformed metadata filter, exactly
+ * as the inline code did. `hasSearch` is surfaced from the raw `search` param
+ * (this helper does not itself build a search query — the caller routes that).
+ */
+export function parseNotesQueryOpts(url: URL): {
+  queryOpts?: QueryOpts;
+  hasSearch: boolean;
+  hasNear: boolean;
+  hasCursor: boolean;
+  error?: Response;
+} {
+  const hasSearch = parseQuery(url, "search") !== null && parseQuery(url, "search") !== "";
+  const hasNear = parseQuery(url, "near[note_id]") !== null;
+  const cursorParam = parseQuery(url, "cursor");
+  const hasCursor = cursorParam !== null && cursorParam !== "";
+
+  const tags = parseQueryList(url, "tag");
+  const bracket = parseMetaBrackets(url);
+  if (bracket.error) return { hasSearch, hasNear, hasCursor, error: bracket.error };
+  const metadataAlias = parseMetadataJsonAlias(url);
+  if (metadataAlias.error) return { hasSearch, hasNear, hasCursor, error: metadataAlias.error };
+  if (metadataAlias.metadata && bracket.metadata) {
+    return {
+      hasSearch,
+      hasNear,
+      hasCursor,
+      error: json(
+        {
+          error: "pass metadata filters as either the JSON `metadata=` param or bracket `meta[field][op]=` form, not both.",
+          code: "INVALID_QUERY",
+        },
+        400,
+      ),
+    };
+  }
+
+  // Tag-expansion axis (vault tag `expand` axis). Optional; absent →
+  // "subtypes" (resolved at the store, kept undefined here so it stays
+  // byte-identical to pre-axis behavior). Unknown value → 400 via the shared
+  // helper (same shape the search branch uses).
+  const expandParsed = parseExpandParam(url);
+  if (expandParsed.error) return { hasSearch, hasNear, hasCursor, error: expandParsed.error };
+  const expand = expandParsed.expand;
+
+  const queryOpts: QueryOpts = {
+    tags,
+    tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+    expand,
+    excludeTags: parseQueryList(url, "exclude_tag"),
+    hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
+    hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
+    path: parseQuery(url, "path") ?? undefined,
+    pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
+    extension: parseExtensionFilter(url),
+    metadata: bracket.metadata ?? metadataAlias.metadata,
+    ...(bracket.dateFilter
+      ? { dateFilter: bracket.dateFilter }
+      : parseQuery(url, "date_field")
+        ? {
+            dateFilter: {
+              field: parseQuery(url, "date_field")!,
+              from: parseQuery(url, "date_from") ?? undefined,
+              to: parseQuery(url, "date_to") ?? undefined,
+            },
+          }
+        : {
+            dateFrom: parseQuery(url, "date_from") ?? undefined,
+            dateTo: parseQuery(url, "date_to") ?? undefined,
+          }),
+    sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
+    orderBy: parseQuery(url, "order_by") ?? undefined,
+    limit: parseInt10(parseQuery(url, "limit")) ?? 50,
+    offset: parseInt10(parseQuery(url, "offset")),
+    cursor: cursorParam ?? undefined,
+  };
+
+  return { queryOpts, hasSearch, hasNear, hasCursor };
+}
+
 /**
  * Parse include_metadata query param.
  * - absent/null → undefined (all metadata, default)
@@ -373,10 +611,20 @@ function parseIncludeMetadata(url: URL): boolean | string[] | undefined {
 /**
  * Parse expand_links/expand_depth/expand_mode from query params, returning
  * an (ExpandContext, depth) pair if expansion is requested, else null.
+ *
+ * `tagScope` (security review): when the caller is tag-scoped, an `isVisible`
+ * predicate is built from the SAME tag-scope allowlist the rest of the
+ * handler uses and injected into the expand context. The expander then
+ * leaves any `[[wikilink]]` whose target is out of scope UNRESOLVED — so
+ * `expand_links=true` can never inline out-of-scope note content (and the
+ * out-of-scope case is byte-indistinguishable from a missing target). For
+ * an unscoped token the predicate is `undefined` and expansion behaves
+ * exactly as before.
  */
 function parseExpandParams(
   url: URL,
   db: any,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): { ctx: ExpandContext; depth: number } | null {
   if (!parseBool(parseQuery(url, "expand_links"), false)) return null;
   const modeRaw = parseQuery(url, "expand_mode");
@@ -388,7 +636,8 @@ function parseExpandParams(
       MAX_EXPAND_DEPTH,
     ),
   );
-  return { ctx: { db, mode, expanded: new Set() }, depth };
+  const isVisible = buildExpandVisibility(tagScope.allowed, tagScope.raw);
+  return { ctx: { db, mode, expanded: new Set(), ...(isVisible ? { isVisible } : {}) }, depth };
 }
 
 
@@ -474,7 +723,7 @@ async function handleNotesInner(
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
-  const db = (store as any).db;
+  const db = store.db;
 
   // ---- Collection routes (no ID in path) ----
   if (subpath === "") {
@@ -494,19 +743,37 @@ async function handleNotesInner(
           return json({ error: "Note not found", id }, 404);
         }
         const includeContent = parseBool(parseQuery(url, "include_content"), true);
+        const contentRange = parseContentRangeQuery(url, includeContent);
+        if (contentRange.error) return contentRange.error;
         let result: any = includeContent ? { ...note } : toNoteIndex(note);
-        const expand = parseExpandParams(url, db);
+        const expand = parseExpandParams(url, db, tagScope);
         if (expand && includeContent && typeof result.content === "string") {
           expand.ctx.expanded.add(note.id);
           result.content = expandContent(result.content, expand.ctx, expand.depth);
         }
+        // Content range applies to the FINAL returned content (post-
+        // expansion) — the window the client pages through is the same
+        // document it would have received unpaged.
+        if (contentRange.range && includeContent) applyContentRange(result, contentRange.range);
         result = filterMetadata(result, parseIncludeMetadata(url));
         if (parseBool(parseQuery(url, "include_links"), false)) {
-          result.links = linkOps.getLinksHydrated(db, note.id);
+          // Tag-scope: drop links whose neighbor is out of scope so the
+          // hydrated sourceNote/targetNote summaries can't leak out-of-scope
+          // ids/paths/tags. No-op for unscoped tokens.
+          result.links = filterHydratedLinksByTagScope(
+            linkOps.getLinksHydrated(db, note.id),
+            tagScope.allowed,
+            tagScope.raw,
+          );
         }
         if (parseBool(parseQuery(url, "include_attachments"), false)) {
           result.attachments = await store.getAttachments(note.id);
         }
+        // linkCount injected after filterMetadata on purpose — same as
+        // links/attachments above; filterMetadata only touches `metadata`.
+        if (parseBool(parseQuery(url, "include_link_count"), false)) {
+          result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url)).get(note.id) ?? 0;
+        }
         return json(result);
       }
 
@@ -529,15 +796,27 @@ async function handleNotesInner(
       if (search) {
         const searchTags = parseQueryList(url, "tag");
         const limit = parseInt10(parseQuery(url, "limit")) ?? 50;
-        const rawResults = await store.searchNotes(search, { tags: searchTags, limit });
+        // Tag-expansion axis (vault tag `expand` axis). This branch bypasses
+        // `parseNotesQueryOpts`, so validate `?expand=` here too — otherwise
+        // `GET /notes?search=x&expand=bogus` would silently ignore the bad
+        // value. The validated mode is threaded into the search tag-narrowing.
+        const tagExpand = parseExpandParam(url);
+        if (tagExpand.error) return tagExpand.error;
+        const rawResults = await store.searchNotes(search, {
+          tags: searchTags,
+          limit,
+          expand: tagExpand.expand,
+        });
         // Tag-scope: drop any result the token isn't permitted to see. Filter
         // happens after the store query so an empty post-filter list still
         // returns 200 [] (consistent with "no matches"), not 403.
         const results = filterNotesByTagScope(rawResults, tagScope.allowed, tagScope.raw);
         const includeContent = parseBool(parseQuery(url, "include_content"), false);
+        const contentRange = parseContentRangeQuery(url, includeContent);
+        if (contentRange.error) return contentRange.error;
         const inclMeta = parseIncludeMetadata(url);
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
-        const expand = parseExpandParams(url, db);
+        const expand = parseExpandParams(url, db, tagScope);
         if (expand && includeContent) {
           for (const n of output) expand.ctx.expanded.add(n.id);
           for (const n of output) {
@@ -546,9 +825,25 @@ async function handleNotesInner(
             }
           }
         }
+        // Content range — per-note, post-expansion (see core/src/content-range.ts).
+        if (contentRange.range && includeContent) {
+          for (const n of output) applyContentRange(n, contentRange.range);
+        }
         if (inclMeta !== undefined && inclMeta !== true) {
           output = output.map((n: any) => filterMetadata(n, inclMeta));
         }
+        // Opt-in link degree (vault feedback #4) — one batch count, same as
+        // the structured-query path. Runs AFTER filterMetadata on purpose
+        // (filterMetadata only touches `metadata`, so linkCount survives —
+        // don't casually swap the order).
+        if (parseBool(parseQuery(url, "include_link_count"), false)) {
+          const counts = linkOps.getLinkCounts(
+            db,
+            output.map((n: any) => n.id),
+            parseLinkCountDirection(url),
+          );
+          for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+        }
         return json(output);
       }
 
@@ -564,7 +859,7 @@ async function handleNotesInner(
       //
       //   - **Flat date params** (DEPRECATED): `?date_field=created_at&
       //     date_from=…&date_to=…` and the legacy `?date_from=…&date_to=…`.
-      //     Still functional through 0.5.x; planned removal in 0.6.0
+      //     Still functional through 0.5.x; planned removal in a later 0.x
       //     (vault#288). New consumers should use bracket-style.
       //
       // Precedence on overlap: bracket-style wins. If a caller passes both
@@ -577,15 +872,16 @@ async function handleNotesInner(
       // Surface asymmetry: REST flattens to a query string; MCP takes a
       // nested `date_filter: { field, from, to }` object directly. Both
       // lower to the same store-level `dateFilter` shape.
-      const tags = parseQueryList(url, "tag");
-      const bracket = parseMetaBrackets(url);
-      if (bracket.error) return bracket.error;
-      // Opaque cursor for "since last checked" agent loops (vault#313).
-      // When present, switches the response shape to {notes, next_cursor}
-      // and routes through queryNotesPaged for keyset pagination. Mutually
-      // exclusive with the `near` graph-neighborhood scope (rebuilding the
-      // neighborhood per page isn't stable) — rejected below.
+      // Structured-query parsing is shared with the live `/subscribe` route
+      // (see `parseNotesQueryOpts`) so both endpoints lower an identical query
+      // string to the same `QueryOpts` — predicate parity by construction.
+      const parsed = parseNotesQueryOpts(url);
+      if (parsed.error) return parsed.error;
+      const queryOpts = parsed.queryOpts!;
       const cursorParam = parseQuery(url, "cursor");
+      // Opaque cursor for "since last checked" agent loops (vault#313) is
+      // mutually exclusive with the `near` graph-neighborhood scope (rebuilding
+      // the neighborhood per page isn't stable).
       const nearNoteIdEarly = parseQuery(url, "near[note_id]");
       if (cursorParam && nearNoteIdEarly) {
         return json(
@@ -598,48 +894,6 @@ async function handleNotesInner(
       }
       let results: Note[];
       let nextCursor: string | null = null;
-      const queryOpts = {
-        tags,
-        tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
-        excludeTags: parseQueryList(url, "exclude_tag"),
-        hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
-        hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
-        path: parseQuery(url, "path") ?? undefined,
-        pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
-        // Extension filter (vault#328). Accepts repeated `extension=`
-        // params for the array form: `?extension=csv&extension=yaml`.
-        // `parseQueryList` already returns undefined when no params
-        // are present, so the filter is silently skipped on a plain
-        // GET without the extension query.
-        extension: parseExtensionFilter(url),
-        metadata: bracket.metadata,
-        // Date-range precedence chain (highest to lowest):
-        //   1. Bracket-style `meta[created_at][gte]=…` (canonical).
-        //   2. Flat `date_field=…&date_from=…&date_to=…` (deprecated).
-        //   3. Legacy `date_from=…&date_to=…` (no date_field, deprecated)
-        //      — filters on `n.created_at` by definition.
-        // The engine rejects combinations of `dateFilter` with the legacy
-        // `dateFrom`/`dateTo`, so we never set both shapes simultaneously.
-        ...(bracket.dateFilter
-          ? { dateFilter: bracket.dateFilter }
-          : parseQuery(url, "date_field")
-            ? {
-                dateFilter: {
-                  field: parseQuery(url, "date_field")!,
-                  from: parseQuery(url, "date_from") ?? undefined,
-                  to: parseQuery(url, "date_to") ?? undefined,
-                },
-              }
-            : {
-                dateFrom: parseQuery(url, "date_from") ?? undefined,
-                dateTo: parseQuery(url, "date_to") ?? undefined,
-              }),
-        sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
-        orderBy: parseQuery(url, "order_by") ?? undefined,
-        limit: parseInt10(parseQuery(url, "limit")) ?? 50,
-        offset: parseInt10(parseQuery(url, "offset")),
-        cursor: cursorParam ?? undefined,
-      };
       try {
         if (cursorParam) {
           const page = await store.queryNotesPaged(queryOpts);
@@ -677,7 +931,24 @@ async function handleNotesInner(
         }
         const depth = Math.min(parseInt10(parseQuery(url, "near[depth]")) ?? 2, 5);
         const relationship = parseQuery(url, "near[relationship]") ?? undefined;
-        const traversed = linkOps.traverseLinks(db, anchor.id, { max_depth: depth, relationship });
+        // Tag-scope policy for `near[]` (vault#439 — hop-guard, symmetric with
+        // find-path): for a tag-scoped token the BFS refuses to traverse
+        // THROUGH out-of-scope notes — scope is a wall, not a sieve. So a token
+        // scoped to ["work"] can't reach an in-scope note at depth 2 via a
+        // #personal intermediary at depth 1; that note is simply unreachable.
+        // The `filterNotesByTagScope` pass below still runs (defense in depth),
+        // but the wall makes it redundant for the `near[]` result set.
+        // Unscoped tokens (`tagScope.raw === null`) install no predicate → the
+        // FULL graph is walked exactly as before, behavior unchanged.
+        const isTraversable = tagScope.raw
+          ? (id: string) =>
+              noteWithinTagScope(
+                { id, tags: getNoteTags(db, id) } as Note,
+                tagScope.allowed,
+                tagScope.raw,
+              )
+          : undefined;
+        const traversed = linkOps.traverseLinks(db, anchor.id, { max_depth: depth, relationship, isTraversable });
         const nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         results = results.filter((n) => nearScope.has(n.id));
       }
@@ -688,11 +959,14 @@ async function handleNotesInner(
       results = filterNotesByTagScope(results, tagScope.allowed, tagScope.raw);
 
       const includeContent = parseBool(parseQuery(url, "include_content"), false);
+      const contentRange = parseContentRangeQuery(url, includeContent);
+      if (contentRange.error) return contentRange.error;
       const includeLinks = parseBool(parseQuery(url, "include_links"), false);
       const includeAttachments = parseBool(parseQuery(url, "include_attachments"), false);
+      const includeLinkCount = parseBool(parseQuery(url, "include_link_count"), false);
       const inclMeta = parseIncludeMetadata(url);
       let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
-      const expand = parseExpandParams(url, db);
+      const expand = parseExpandParams(url, db, tagScope);
       if (expand && includeContent) {
         for (const n of output) expand.ctx.expanded.add(n.id);
         for (const n of output) {
@@ -701,9 +975,31 @@ async function handleNotesInner(
           }
         }
       }
+      // Content range — per-note, post-expansion (see core/src/content-range.ts).
+      if (contentRange.range && includeContent) {
+        for (const n of output) applyContentRange(n, contentRange.range);
+      }
       if (inclMeta !== undefined && inclMeta !== true) {
         output = output.map((n: any) => filterMetadata(n, inclMeta));
       }
+      // Opt-in link degree (vault feedback #4). ONE batch count over all
+      // result ids — NOT a per-note query — so the field stays O(2 index
+      // scans) per request regardless of page size. Mutates `output` in
+      // place; injected on the same objects the enrichment loop below
+      // touches, the same way `links`/`attachments` are surfaced.
+      // Ordering: this runs AFTER the filterMetadata pass above on purpose —
+      // filterMetadata only touches the `metadata` key, so a linkCount
+      // injected here survives. Don't casually swap the order; injecting
+      // before filterMetadata would still survive today but couples the two
+      // to filterMetadata's current narrow behavior.
+      if (includeLinkCount) {
+        const counts = linkOps.getLinkCounts(
+          db,
+          output.map((n: any) => n.id),
+          parseLinkCountDirection(url),
+        );
+        for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+      }
 
       // Graph format — reshape into { nodes, edges }
       if (parseQuery(url, "format") === "graph") {
@@ -711,8 +1007,9 @@ async function handleNotesInner(
         const nodes = output.map((n: any) => ({ id: n.id, path: n.path ?? null, tags: n.tags ?? [] }));
         const edges: { source: string; target: string; relationship: string }[] = [];
         if (includeLinks) {
+          const linksByNote = linkOps.getLinksHydratedForNotes(db, results.map((n) => n.id));
           for (const n of results) {
-            for (const link of linkOps.getLinksHydrated(db, n.id)) {
+            for (const link of linksByNote.get(n.id) ?? []) {
               // Only include edges where source is this note and target is in the result set
               if (link.sourceId === n.id && resultIds.has(link.targetId)) {
                 edges.push({ source: link.sourceId, target: link.targetId, relationship: link.relationship });
@@ -724,10 +1021,23 @@ async function handleNotesInner(
       }
 
       if (includeLinks || 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;
         const enrichedOut: any[] = [];
         for (const n of output) {
           const enriched: any = { ...n };
-          if (includeLinks) enriched.links = linkOps.getLinksHydrated(db, n.id);
+          if (linksByNote) {
+            // Tag-scope: strip out-of-scope-neighbor links (no-op unscoped).
+            enriched.links = filterHydratedLinksByTagScope(
+              linksByNote.get(n.id) ?? [],
+              tagScope.allowed,
+              tagScope.raw,
+            );
+          }
           if (includeAttachments) enriched.attachments = await store.getAttachments(n.id);
           enrichedOut.push(enriched);
         }
@@ -830,19 +1140,33 @@ async function handleNotesInner(
         throw e;
       }
 
-      // Apply tag schema defaults
+      // Apply tag schema defaults, then re-read the notes whose metadata was
+      // actually default-filled so the response reflects the final on-disk
+      // state (the `created` entries were read before `applySchemaDefaults`
+      // ran). Mirrors the MCP create-note path (vault#316). Batched re-read
+      // (`getNotes` = one `WHERE id IN (...)`), skipped when no defaults
+      // applied so the common no-defaults path adds zero extra reads.
+      const mutatedIds = new Set<string>();
       for (const note of created) {
         if (note.tags?.length) {
-          await applySchemaDefaults(store, db, [note.id], note.tags);
+          for (const id of await applySchemaDefaults(store, db, [note.id], note.tags)) {
+            mutatedIds.add(id);
+          }
         }
       }
+      const refreshed =
+        mutatedIds.size === 0
+          ? created
+          : (() => {
+              const byId = new Map(getNotes(db, [...mutatedIds]).map((n) => [n.id, n]));
+              return created.map((n) => byId.get(n.id) ?? n);
+            })();
 
       // Attach `validation_status` so HTTP create-note matches the MCP
-      // surface (vault#287). Mirrors the MCP create-note attach site at
-      // `core/src/mcp.ts:451`. `attachValidationStatus` returns the note
+      // 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 = created.map((n) => attachValidationStatus(store, db, n));
+      const final = refreshed.map((n) => attachValidationStatus(store, db, n));
       return json(body.notes ? final : final[0], 201);
     }
 
@@ -882,7 +1206,14 @@ async function handleNotesInner(
       // Explicit `transcribe: true` wins — if the caller asked, we honor that
       // regardless of the auto-transcribe toggle (back-compat).
       const explicitOptIn = body.transcribe === true;
-      const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType);
+      // Per-vault auto-transcribe: read THIS vault's `auto_transcribe.enabled`
+      // (vault.yaml) and pass it as the precedence-winning toggle. A vault that
+      // set its own value uses it; one that left it unset falls through to the
+      // global toggle inside `shouldAutoTranscribe` (per-vault → global → true).
+      const perVaultEnabled = vault
+        ? readVaultConfig(vault)?.auto_transcribe?.enabled
+        : undefined;
+      const autoOptIn = !explicitOptIn && shouldAutoTranscribe(body.mimeType, { perVaultEnabled });
       const attMeta = (explicitOptIn || autoOptIn)
         ? {
             transcribe_status: "pending" as const,
@@ -942,22 +1273,26 @@ async function handleNotesInner(
     return json({ error: "Method not allowed" }, 405);
   }
 
-  // POST /notes/:idOrPath/retry-transcription — vault#353 design Q5.
+  // POST /notes/:idOrPath/retry-transcription — vault#353 design Q5 + finding F.
   //
-  // Re-runs the auto-transcribe pipeline against the original audio
-  // attachment recorded in the transcript note's `transcript_attachment_id`
-  // frontmatter. Only valid on transcript notes (the target idOrPath must
-  // be a transcript note with `transcript_status: "failed"`); calling on
-  // anything else returns 400 with a clear reason.
+  // Re-runs transcription against a failed audio attachment. Two target
+  // shapes, dispatched in handleRetryTranscription by whether the note carries
+  // `transcript_status` frontmatter:
+  //   - Auto-flow (vault#353): target is a `<audio>.transcript.md` note with
+  //     `transcript_status: "failed"`; audio located via
+  //     `transcript_attachment_id`, origin preserved as "auto".
+  //   - Legacy in-body memo (finding F): target is the memo note itself (no
+  //     `transcript_status`); finds its own failed attachment, resets it
+  //     preserving `transcribe_origin: "legacy"`, and re-arms `transcribe_stub`.
   //
   // Wire shape:
   //   POST .../notes/<idOrPath>/retry-transcription
-  //   →  202 { attachment_id, transcript_path } when re-enqueued
-  //      400 invalid_target          (not a transcript note)
-  //      400 not_failed              (transcript already succeeded; nothing to retry)
-  //      404 attachment_missing      (transcript_attachment_id row deleted)
+  //   →  202 { attachment_id, attachment_path, transcript_note_id, worker }
+  //      400 not_failed              (auto-flow: transcript already succeeded)
+  //      400 missing_attachment_id   (auto-flow: transcript_attachment_id absent)
+  //      400 no_failed_attachment    (legacy: no failed audio attachment to retry)
+  //      404 attachment_missing      (auto-flow: transcript_attachment_id row deleted)
   //      404 audio_missing           (audio file unlinked from disk)
-  //      503 scribe_unavailable      (no worker configured this boot)
   if (sub === "/retry-transcription") {
     if (method !== "POST") return json({ error: "Method not allowed" }, 405);
     if (!vault) return json({ error: "Vault context required" }, 400);
@@ -979,19 +1314,31 @@ async function handleNotesInner(
       return json({ error: "Not found" }, 404);
     }
     const includeContent = parseBool(parseQuery(url, "include_content"), true);
+    const contentRange = parseContentRangeQuery(url, includeContent);
+    if (contentRange.error) return contentRange.error;
     let result: any = includeContent ? { ...note } : toNoteIndex(note);
-    const expand = parseExpandParams(url, db);
+    const expand = parseExpandParams(url, db, tagScope);
     if (expand && includeContent && typeof result.content === "string") {
       expand.ctx.expanded.add(note.id);
       result.content = expandContent(result.content, expand.ctx, expand.depth);
     }
+    // Content range applies to the FINAL returned content (post-expansion).
+    if (contentRange.range && includeContent) applyContentRange(result, contentRange.range);
     result = filterMetadata(result, parseIncludeMetadata(url));
     if (parseBool(parseQuery(url, "include_links"), false)) {
-      result.links = linkOps.getLinksHydrated(db, note.id);
+      // Tag-scope: drop out-of-scope-neighbor links (no-op unscoped).
+      result.links = filterHydratedLinksByTagScope(
+        linkOps.getLinksHydrated(db, note.id),
+        tagScope.allowed,
+        tagScope.raw,
+      );
     }
     if (parseBool(parseQuery(url, "include_attachments"), false)) {
       result.attachments = await store.getAttachments(note.id);
     }
+    if (parseBool(parseQuery(url, "include_link_count"), false)) {
+      result.linkCount = linkOps.getLinkCounts(db, [note.id], parseLinkCountDirection(url)).get(note.id) ?? 0;
+    }
     return json(result);
   }
 
@@ -1256,7 +1603,27 @@ async function handleNotesInner(
       // `toNoteIndex` drops unknown fields).
       const updatedNote = await store.getNote(note.id);
       if (updatedNote === null) return json({ error: "Note disappeared" }, 404);
-      const validated = attachValidationStatus(store, db, updatedNote);
+      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`
+      // (vault feedback #8). Previously the update response omitted links
+      // entirely (`getNote` populates tags but not links), forcing callers
+      // to re-GET with `?include_links=true` just to confirm a link they
+      // had just added/removed. Additive field, scoped to UPDATE: present
+      // only when mutated or requested. Mirrors the GET / query-notes
+      // hydration call form exactly (`linkOps.getLinksHydrated`).
+      const linkMutated = body.links?.add !== undefined || body.links?.remove !== undefined;
+      const includeLinksResp = linkMutated || parseBool(parseQuery(url, "include_links"), false);
+      if (includeLinksResp) {
+        // Tag-scope: strip out-of-scope-neighbor links from the echoed set
+        // (no-op unscoped). A write token tag-scoped to #work mustn't learn
+        // about a #personal note it happened to link to.
+        validated.links = filterHydratedLinksByTagScope(
+          linkOps.getLinksHydrated(db, updatedNote.id),
+          tagScope.allowed,
+          tagScope.raw,
+        );
+      }
       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
@@ -1266,6 +1633,9 @@ async function handleNotesInner(
       const lean: any = toNoteIndex(validated);
       const vs = (validated as any).validation_status;
       if (vs !== undefined) lean.validation_status = vs;
+      // 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;
       lean.created = false;
       return json(lean);
     } catch (e: any) {
@@ -1418,7 +1788,7 @@ export async function handleTags(
     // that token's allowlist. Aggregate matches across sources for a single
     // 409 envelope.
     const referenced: { source: string; tokens: { id: string; label: string }[] }[] = [];
-    const db = (store as any).db;
+    const db = store.db;
     for (const src of sources) {
       const tokens = findTokensReferencingTag(db, src as string);
       if (tokens.length > 0) referenced.push({ source: src as string, tokens });
@@ -1513,10 +1883,12 @@ export async function handleTags(
       parent_names?: unknown;
     };
 
-    // Validate relationships shape + cardinality vocabulary up front so
-    // a bad payload returns 400, not a thrown 500.
+    // Validate the relationships payload up front so a bad payload returns
+    // 400, not a thrown 500. `relationships` is an opaque vocabulary map
+    // (relationship-name → arbitrary JSON the app interprets); we only check
+    // that it's a JSON object (a map), then persist verbatim.
     let relationshipsPatch:
-      | Record<string, tagSchemaOps.TagRelationship>
+      | tagSchemaOps.TagRelationshipMap
       | null
       | undefined;
     if (body.relationships === null) {
@@ -1580,7 +1952,7 @@ export async function handleTags(
     // tag would silently orphan the token's allowlist. Fail closed (409)
     // and name the offending tokens so the operator can revoke or re-mint
     // before retrying. patterns/tag-scoped-tokens.md §Dependencies.
-    const referenced_by = findTokensReferencingTag((store as any).db, tagName);
+    const referenced_by = findTokensReferencingTag(store.db, tagName);
     if (referenced_by.length > 0) {
       return json(
         {
@@ -1615,7 +1987,7 @@ export async function handleFindPath(
   const target = parseQuery(url, "target");
   if (!source || !target) return json({ error: "source and target parameters are required" }, 400);
 
-  const db = (store as any).db;
+  const db = store.db;
   try {
     const sourceNote = await resolveNote(store, source);
     if (!sourceNote) return json({ error: `Note not found: "${source}"` }, 404);
@@ -1661,16 +2033,36 @@ type VaultConfigLike = {
   name: string;
   description?: string;
   audio_retention?: "keep" | "until_transcribed" | "never";
+  auto_transcribe?: { enabled?: boolean };
 };
 
 const VALID_AUDIO_RETENTION = ["keep", "until_transcribed", "never"] as const;
 
+/**
+ * Resolve the effective auto-transcribe toggle for a vault's GET response, the
+ * SAME resolution `shouldAutoTranscribe` uses at the decision point:
+ * **per-vault → global → true**. A vault that set its own `auto_transcribe`
+ * shows that; one that left it unset shows the server-wide default (itself
+ * default-ON). This keeps the GET in lock-step with what the worker actually
+ * does, with no field-name drift.
+ */
+function resolveAutoTranscribeEnabled(vaultConfig: VaultConfigLike): boolean {
+  return (
+    vaultConfig.auto_transcribe?.enabled
+    ?? readGlobalConfig().auto_transcribe?.enabled
+    ?? true
+  );
+}
+
 function vaultResponse(vaultConfig: VaultConfigLike): Record<string, unknown> {
   return {
     name: vaultConfig.name,
     description: vaultConfig.description ?? null,
     config: {
       audio_retention: vaultConfig.audio_retention ?? "keep",
+      auto_transcribe: {
+        enabled: resolveAutoTranscribeEnabled(vaultConfig),
+      },
     },
   };
 }
@@ -1694,7 +2086,7 @@ export async function handleVault(
   if (req.method === "PATCH") {
     const body = await req.json() as {
       description?: string;
-      config?: { audio_retention?: string };
+      config?: { audio_retention?: string; auto_transcribe?: { enabled?: unknown } };
     };
     let dirty = false;
 
@@ -1718,6 +2110,28 @@ export async function handleVault(
       dirty = true;
     }
 
+    // auto_transcribe.enabled — PER-VAULT toggle persisted to THIS vault's
+    // vault.yaml (via `persist`, the same writeVaultConfig path as
+    // description/audio_retention). Flipping it for vault X affects only X;
+    // scribe's "link to vault X" PATCHes this and never touches other vaults.
+    // The worker reads the same per-vault field (per-vault → global → true).
+    // Validate the shape: when `auto_transcribe` is present it must carry a
+    // boolean `enabled`.
+    if (body.config?.auto_transcribe !== undefined) {
+      const enabled = body.config.auto_transcribe?.enabled;
+      if (typeof enabled !== "boolean") {
+        return json(
+          {
+            error: "invalid_auto_transcribe",
+            message: "auto_transcribe.enabled must be a boolean",
+          },
+          400,
+        );
+      }
+      vaultConfig.auto_transcribe = { ...vaultConfig.auto_transcribe, enabled };
+      dirty = true;
+    }
+
     if (dirty && persist) persist();
     return json(vaultResponse(vaultConfig));
   }
@@ -1729,12 +2143,32 @@ export async function handleVault(
 // Unresolved wikilinks — REST-only (admin/maintenance)
 // ---------------------------------------------------------------------------
 
-export function handleUnresolvedWikilinks(req: Request, store: Store): Response {
+export function handleUnresolvedWikilinks(
+  req: Request,
+  store: Store,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Response {
   const url = new URL(req.url);
   const limitStr = url.searchParams.get("limit");
   const limit = limitStr ? parseInt(limitStr, 10) : 50;
-  const db = (store as any).db;
-  return Response.json(listUnresolvedWikilinks(db, limit));
+  const db = store.db;
+  const result = listUnresolvedWikilinks(db, limit);
+
+  // Unscoped token → return as-is (unchanged behavior).
+  if (tagScope.raw === null) return Response.json(result);
+
+  // Tag-scope confidentiality (security review): each unresolved row carries
+  // a `source_id` (+ `source_path`) plus the raw `target_path` wikilink
+  // string. For a tag-scoped token, surface ONLY rows whose SOURCE note is
+  // within the token's tag scope — otherwise we'd leak out-of-scope note IDs
+  // and the wikilink target strings those notes contain. Filter the page and
+  // recompute `count` from the filtered set so the aggregate total of
+  // out-of-scope rows doesn't leak either.
+  const filtered = result.unresolved.filter((row) => {
+    const note = getNote(db, row.source_id);
+    return note !== null && noteWithinTagScope(note, tagScope.allowed, tagScope.raw);
+  });
+  return Response.json({ unresolved: filtered, count: filtered.length });
 }
 
 // ---------------------------------------------------------------------------
@@ -1923,21 +2357,35 @@ ${rendered}
 // ---------------------------------------------------------------------------
 
 /**
- * Re-enqueue the original audio attachment for a `transcript_status: failed`
- * transcript note. Steps:
+ * Re-enqueue the original audio attachment for a failed transcription.
  *
- *   1. Validate target is a transcript note (`transcript_status` set in
- *      metadata) AND that status is `failed`.
- *   2. Find the original audio attachment by id from
- *      `transcript_attachment_id` frontmatter. 404 if the row's gone.
- *   3. Validate the audio file still exists on disk (retention=keep is
- *      assumed by the retry contract; retention=until_transcribed unlinks
- *      only on success, retention=never unlinks on failure — that last one
- *      explicitly breaks retry, by design).
- *   4. Reset `transcribe_status = "pending"`, clear backoff + error fields.
- *      The auto-origin marker is preserved so the worker writes a transcript
- *      note (overwriting this one in place).
- *   5. Kick the worker if registered; otherwise the sweep picks it up.
+ * Two target shapes are accepted:
+ *
+ *   - **Auto-flow (vault#353):** the target is a `<audio>.transcript.md` note
+ *     carrying `transcript_status` frontmatter. Requires that status be
+ *     `failed`; locates the audio via `transcript_attachment_id`; preserves
+ *     `transcribe_origin: "auto"` so a retried success overwrites this
+ *     transcript note in place. Behavior is byte-identical to the original
+ *     vault#353 contract.
+ *
+ *   - **Legacy in-body memo (finding F):** the target is the memo note
+ *     itself — no `transcript_status` frontmatter. The original capture body
+ *     holds `![[<audio>]]` + a `_Transcription unavailable._` marker (written
+ *     by the worker on terminal failure). We find the note's own failed audio
+ *     attachment, reset it to pending **preserving `transcribe_origin:
+ *     "legacy"`** (forcing "auto" would switch to the sibling-transcript-note
+ *     shape and orphan the in-body embed), and **re-stamp `transcribe_stub:
+ *     true`** on the note. The stub re-arm is load-bearing: the legacy success
+ *     path early-returns unless `transcribe_stub === true`, so without it the
+ *     retried success would never write the transcript back into the body.
+ *     On success the worker replaces the `_Transcription unavailable._` marker
+ *     with the transcript in place, yielding the same final shape a first-try
+ *     success would.
+ *
+ * Common steps for both: validate the audio attachment row exists (404 if
+ * gone) and its file is still on disk (404 if unlinked — e.g. retention=never
+ * already dropped it), reset the transcribe_status fields, then kick the
+ * worker if registered (otherwise the sweep picks it up).
  */
 async function handleRetryTranscription(
   store: Store,
@@ -1945,15 +2393,13 @@ async function handleRetryTranscription(
   vault: string,
 ): Promise<Response> {
   const meta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+
+  // Legacy in-body memo: no `transcript_status` frontmatter. The note owns
+  // the failed audio attachment directly; there's no sibling transcript note.
   if (typeof meta.transcript_status !== "string") {
-    return json(
-      {
-        error: "invalid_target",
-        message: "Target note is not a transcript note (no transcript_status frontmatter).",
-      },
-      400,
-    );
+    return handleRetryLegacyInBody(store, note, vault);
   }
+
   if (meta.transcript_status !== "failed") {
     return json(
       {
@@ -2040,13 +2486,171 @@ async function handleRetryTranscription(
   );
 }
 
+/**
+ * Retry path for a legacy in-body voice memo (finding F). The target note is
+ * the memo itself (no `transcript_status` frontmatter); it directly owns the
+ * audio attachment whose transcription failed.
+ *
+ * Steps:
+ *   1. Find the note's own audio attachment with `transcribe_status ===
+ *      "failed"`. 400 `no_failed_attachment` if none — there's nothing to
+ *      retry.
+ *   2. Validate the audio file is still on disk (404 `audio_missing`).
+ *   3. Reset the attachment to pending, **preserving `transcribe_origin:
+ *      "legacy"`** (never force "auto" — that switches to the sibling-
+ *      transcript-note shape and orphans the in-body `![[memo]]` embed).
+ *   4. **Re-stamp `transcribe_stub: true`** on the note. The legacy worker
+ *      success path early-returns unless the note carries this flag (it was
+ *      cleared when the failure marker was written), so re-arming it is what
+ *      lets the retried success replace the `_Transcription unavailable._`
+ *      marker with the transcript.
+ *   5. Kick the worker if registered; otherwise the sweep picks it up.
+ */
+async function handleRetryLegacyInBody(
+  store: Store,
+  note: Note,
+  vault: string,
+): Promise<Response> {
+  const attachments = await store.getAttachments(note.id);
+  const failed = attachments.find((a) => {
+    const m = (a.metadata as Record<string, unknown> | undefined) ?? {};
+    return m.transcribe_status === "failed";
+  });
+  if (!failed) {
+    return json(
+      {
+        error: "no_failed_attachment",
+        message:
+          "Target note is not a transcript note and has no audio attachment with a failed transcription to retry.",
+      },
+      400,
+    );
+  }
+
+  // Audio file existence + safety: defense-in-depth against a bad attachment
+  // row pointing outside the vault assets dir. Same guard as the worker.
+  const assetsRoot = assetsDir(vault);
+  const audioFilePath = normalize(join(assetsRoot, failed.path));
+  if (!audioFilePath.startsWith(normalize(assetsRoot)) || !existsSync(audioFilePath)) {
+    return json(
+      {
+        error: "audio_missing",
+        message: `Original audio file at "${failed.path}" no longer exists on disk.`,
+      },
+      404,
+    );
+  }
+
+  // Reset the attachment back to pending. Preserve `transcribe_origin:
+  // "legacy"` (a default of `undefined` is also legacy, but make it explicit
+  // so a retried row reads unambiguously) — forcing "auto" here would make
+  // the worker materialize a sibling transcript note instead of patching the
+  // in-body embed, orphaning the memo.
+  const attMeta = { ...(failed.metadata ?? {}) } as Record<string, unknown>;
+  attMeta.transcribe_status = "pending";
+  attMeta.transcribe_requested_at = new Date().toISOString();
+  attMeta.transcribe_origin = "legacy";
+  delete attMeta.transcribe_backoff_until;
+  delete attMeta.transcribe_error;
+  delete attMeta.transcribe_error_code;
+  delete attMeta.transcribe_attempts;
+  await store.setAttachmentMetadata(failed.id, attMeta);
+
+  // Re-arm the stub on the note. The worker's legacy success path gates on
+  // `transcribe_stub === true` and CLEARED it when it wrote the failure
+  // marker; without re-stamping it the retried success early-returns and
+  // never writes the transcript back into the body. Use skipUpdatedAt so the
+  // note's modification time still reflects user intent, matching the
+  // worker's own note writes.
+  //
+  // OC-guarded (vault#435): this read-transform-write would otherwise clobber
+  // a user edit landing between `resolveNote` (above) and this write. Thread
+  // `if_updated_at` and retry once on conflict — re-read, re-apply the
+  // metadata-only re-stamp against the fresh note, write with the fresh
+  // precondition. A second conflict surfaces as 409 so the user can retry.
+  // Only the `transcribe_stub` flag is stamped (never content), so re-applying
+  // against the fresh note is always the correct surgical transform.
+  const restampStub = (current: Note): Record<string, unknown> => ({
+    ...((current.metadata as Record<string, unknown> | undefined) ?? {}),
+    transcribe_stub: true,
+  });
+  try {
+    try {
+      await store.updateNote(note.id, {
+        metadata: restampStub(note),
+        skipUpdatedAt: true,
+        if_updated_at: note.updatedAt,
+      });
+    } catch (err: any) {
+      if (!err || err.code !== "CONFLICT") throw err;
+      // Conflict — re-read, re-apply the stub re-stamp, retry once.
+      const fresh = await store.getNote(note.id);
+      if (!fresh) {
+        return json(
+          { error: "note_missing", message: "Target note disappeared during retry." },
+          404,
+        );
+      }
+      await store.updateNote(fresh.id, {
+        metadata: restampStub(fresh),
+        skipUpdatedAt: true,
+        if_updated_at: fresh.updatedAt,
+      });
+    }
+  } catch (err: any) {
+    if (err && err.code === "CONFLICT") {
+      // Double conflict — the note kept changing under us. It's a user-facing
+      // request; return 409 so the caller can retry against fresh state. The
+      // attachment was already reset to pending above; a successful re-stamp
+      // on the user's next retry (or the next sweep, if they re-arm the stub)
+      // will let the worker patch the transcript in.
+      return json(
+        {
+          error_type: "conflict",
+          error: "conflict",
+          note_id: note.id,
+          current_updated_at: err.current_updated_at ?? null,
+          your_updated_at: err.expected_updated_at,
+          // Mirror the standard PATCH 409 shape (see the notes-update handler
+          // above) — both `your_updated_at` and `expected_updated_at` carry the
+          // same value, kept for shape-congruence with existing callers.
+          expected_updated_at: err.expected_updated_at,
+          message:
+            "Note was modified concurrently while arming the retry; re-fetch and try again.",
+        },
+        409,
+      );
+    }
+    throw err;
+  }
+
+  const { getTranscriptionWorker } = await import("./transcription-registry.ts");
+  const worker = getTranscriptionWorker();
+  if (worker) {
+    const fresh = await store.getAttachment(failed.id) ?? failed;
+    void worker.kick(vault, fresh);
+  }
+
+  return json(
+    {
+      status: "queued",
+      attachment_id: failed.id,
+      attachment_path: failed.path,
+      transcript_note_id: note.id,
+      worker: worker ? "kicked" : "sweep-only",
+    },
+    202,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Storage (file upload/serve) — kept as-is, Daily needs it
+//
+// `assetsDir` moved to config.ts (next to the other path helpers) to break the
+// usage.ts↔routes.ts import cycle; it's re-exported from this module's top so
+// existing importers are unaffected.
 // ---------------------------------------------------------------------------
 
-export function assetsDir(vault: string): string {
-  return process.env.ASSETS_DIR ?? join(vaultDir(vault), "assets");
-}
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
 
 // Storage allowlist policy:
@@ -2112,10 +2716,41 @@ export async function handleStorage(
     const relativePath = `${date}/${filename}`;
     const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
 
+    // Invalidate the usage dir-walk cache for this vault — the new attachment
+    // changed the assets-directory footprint, so the next /.parachute/usage
+    // read must re-walk rather than report a stale (smaller) number. Without
+    // this hook the cache's 60s TTL would briefly under-report after an
+    // upload. (usage.ts:invalidateUsageCache is a no-op-cheap map delete.)
+    invalidateUsageCache(vault);
+
     return json({ path: relativePath, size: buffer.length, mimeType }, 201);
   }
 
-  const fileMatch = path.match(/^\/([^/]+)\/(.+)$/);
+  // Decode percent-encoding BEFORE matching. `path` arrives from
+  // `url.pathname`, which (per WHATWG) keeps an encoded `%2F` slash literal —
+  // so a caller requesting `/api/storage/<date>%2F<file>` would never satisfy
+  // the literal-slash match below and would fall through to the 404. Decoding
+  // first accepts both the literal-slash and `%2F`-encoded forms, and yields
+  // the literal-slash path that the DB stores (`${date}/${filename}`) so the
+  // tag-scope reverse-lookup matches. This intentionally diverges from the
+  // single-note routes, which decode their *first* segment only and therefore
+  // REQUIRE `%2F` for slashes-in-an-id — a trap-grade asymmetry we accept here
+  // because storage paths are always multi-segment date/file pairs.
+  //
+  // Guard-safety (verified): the traversal guard below operates on the
+  // post-`normalize(join())` filesystem path, so a decoded `..` is still
+  // caught → 403. Decode is idempotent for today's unencoded callers
+  // (filenames are `<Date.now()>-<uuid>.<ext>` — no stray `%`). A malformed
+  // `%` (e.g. `2026%2`) throws → 404, consistent with the no-existence-oracle
+  // stance (and an improvement over the prior catch-all 500).
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(path);
+  } catch {
+    return json({ error: "Not found" }, 404);
+  }
+
+  const fileMatch = decodedPath.match(/^\/([^/]+)\/(.+)$/);
   if (req.method === "GET" && fileMatch) {
     const reqPath = `${fileMatch[1]}/${fileMatch[2]}`;
     const filePath = normalize(join(assets, reqPath));
@@ -2178,9 +2813,12 @@ export async function handleStorage(
 // Tag schema defaults — same logic as core/src/mcp.ts applySchemaDefaults
 // ---------------------------------------------------------------------------
 
-async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tags: string[]): Promise<void> {
+// Returns the IDs of notes whose metadata was actually default-filled, so
+// the caller can re-read ONLY the mutated notes (and skip the re-read when
+// nothing changed). Mirrors the core/src/mcp.ts contract.
+async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tags: string[]): Promise<string[]> {
   const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return;
+  if (Object.keys(schemas).length === 0) return [];
 
   const defaults: Record<string, unknown> = {};
   for (const tag of tags) {
@@ -2192,8 +2830,9 @@ async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tag
       }
     }
   }
-  if (Object.keys(defaults).length === 0) return;
+  if (Object.keys(defaults).length === 0) return [];
 
+  const mutated: string[] = [];
   for (const noteId of noteIds) {
     const note = await store.getNote(noteId);
     if (!note) continue;
@@ -2207,7 +2846,9 @@ async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tag
       metadata: { ...existing, ...missing },
       skipUpdatedAt: true,
     });
+    mutated.push(noteId);
   }
+  return mutated;
 }
 
 function defaultForField(field: { type: string; enum?: string[] }): unknown {