@openparachute/vault 0.3.1 → 0.4.0

package/src/routes.ts

@@ -1,11 +1,13 @@
 /**
  * REST API route handlers for the multi-vault server.
  *
- * Mirrors the 9 MCP tools:
+ * Mirrors the MCP tools:
  *   /api/notes          — query-notes, create-note, update-note, delete-note
  *   /api/tags           — list-tags, update-tag, delete-tag
+ *   /api/note-schemas   — list/upsert/delete note_schemas + nested mappings
  *   /api/find-path      — find-path
  *   /api/vault          — vault-info
+ * (synthesize-notes is MCP-only; agents call it through the MCP transport.)
  *
  * Each handler receives a Store instance (already resolved for the vault)
  * and the Request, and returns a Response.
@@ -13,9 +15,28 @@
 
 import type { Store, Note } from "../core/src/types.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { toNoteIndex, filterMetadata } from "../core/src/notes.ts";
+import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE } from "../core/src/notes.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
+import { MAPPING_KINDS, type SchemaMappingKind, type NoteSchemaField } from "../core/src/note-schemas.ts";
+import {
+  filterNotesByTagScope,
+  noteWithinTagScope,
+  tagScopeForbidden,
+  tagsWithinScope,
+} from "./tag-scope.ts";
+import { findTokensReferencingTag } from "./token-store.ts";
+
+/**
+ * Tag-scope context threaded through handlers. `allowed` is the
+ * pre-expanded set of permitted tags (root + descendants), `raw` is the
+ * original allowlist for error messages. Both null when the token is
+ * unscoped — handlers fast-path on `allowed === null` and behave
+ * identically to the pre-tag-scope code path.
+ */
+export type TagScopeCtx = { allowed: Set<string> | null; raw: string[] | null };
+
+const NO_TAG_SCOPE: TagScopeCtx = { allowed: null, raw: null };
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -132,6 +153,7 @@ export async function handleNotes(
   store: Store,
   subpath: string,
   vault?: string,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -148,6 +170,12 @@ export async function handleNotes(
       if (id) {
         const note = await resolveNote(store, id);
         if (!note) return json({ error: "Note not found", id }, 404);
+        // Tag-scope: a token can't see what its allowlist excludes. Surface
+        // as 404 (not 403) — the existence of the note is itself information
+        // we shouldn't leak across the scope boundary.
+        if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+          return json({ error: "Note not found", id }, 404);
+        }
         const includeContent = parseBool(parseQuery(url, "include_content"), true);
         let result: any = includeContent ? { ...note } : toNoteIndex(note);
         const expand = parseExpandParams(url, db);
@@ -169,7 +197,11 @@ export async function handleNotes(
       if (search) {
         const searchTags = parseQueryList(url, "tag");
         const limit = parseInt10(parseQuery(url, "limit")) ?? 50;
-        const results = await store.searchNotes(search, { tags: searchTags, limit });
+        const rawResults = await store.searchNotes(search, { tags: searchTags, limit });
+        // 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 inclMeta = parseIncludeMetadata(url);
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
@@ -189,6 +221,13 @@ export async function handleNotes(
       }
 
       // Structured query
+      //
+      // Surface asymmetry: REST uses three flat query params
+      // (`date_field`, `date_from`, `date_to`) while MCP takes a nested
+      // `date_filter: { field, from, to }` object. Both lower to the same
+      // store-level `dateFilter` shape — the difference is just that query
+      // strings are flat by nature. This mirrors the broader REST/MCP
+      // pattern across the API and is intentional, not a fix-it-up TODO.
       const tags = parseQueryList(url, "tag");
       let results: Note[];
       try {
@@ -201,8 +240,22 @@ export async function handleNotes(
           path: parseQuery(url, "path") ?? undefined,
           pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
           metadata: undefined, // metadata filter not practical in query params
-          dateFrom: parseQuery(url, "date_from") ?? undefined,
-          dateTo: parseQuery(url, "date_to") ?? undefined,
+          // `date_field=<name>&date_from=...&date_to=...` activates the
+          // generalized filter (filters on the named indexed field). Without
+          // `date_field`, `date_from`/`date_to` keep their legacy meaning of
+          // filtering on `created_at` (vault ingestion time).
+          ...(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,
@@ -223,6 +276,10 @@ export async function handleNotes(
       if (nearNoteId) {
         const anchor = await resolveNote(store, nearNoteId);
         if (!anchor) return json({ error: "Anchor note not found", note_id: nearNoteId }, 404);
+        // Tag-scope: anchor must itself be visible to this token.
+        if (!noteWithinTagScope(anchor, tagScope.allowed, tagScope.raw)) {
+          return json({ error: "Anchor note not found", note_id: nearNoteId }, 404);
+        }
         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 });
@@ -230,6 +287,11 @@ export async function handleNotes(
         results = results.filter((n) => nearScope.has(n.id));
       }
 
+      // Tag-scope: drop any result outside the allowlist before shaping
+      // output. Same semantics as the search path — empty result is 200 [],
+      // not 403.
+      results = filterNotesByTagScope(results, tagScope.allowed, tagScope.raw);
+
       const includeContent = parseBool(parseQuery(url, "include_content"), false);
       const includeLinks = parseBool(parseQuery(url, "include_links"), false);
       const includeAttachments = parseBool(parseQuery(url, "include_attachments"), false);
@@ -285,25 +347,110 @@ export async function handleNotes(
       const body = await req.json() as any;
       const items: any[] = body.notes ?? [body];
 
-      const created: Note[] = [];
-      for (const item of items) {
-        const note = await store.createNote(item.content ?? "", {
-          id: item.id,
-          path: item.path,
-          tags: item.tags,
-          metadata: item.metadata,
-          created_at: item.createdAt ?? item.created_at,
-        });
+      // Batch cap (#213): refuse oversized batches before doing any work. 500
+      // is the cap (Benjamin's number) — tighter blast radius than 1000 for
+      // the runaway-client case that flooded a deployment with 7,453 notes.
+      if (items.length > MAX_BATCH_SIZE) {
+        return json(
+          {
+            error_type: "batch_too_large",
+            error: "BatchTooLarge",
+            message: `max ${MAX_BATCH_SIZE} notes per request, got ${items.length}`,
+            limit: MAX_BATCH_SIZE,
+          },
+          413,
+        );
+      }
 
-        // Create explicit links
-        if (item.links) {
-          for (const link of item.links as { target: string; relationship: string }[]) {
-            const target = await resolveNote(store, link.target);
-            if (target) await store.createLink(note.id, target.id, link.relationship);
+      // Empty-note pre-validation (#213): walk the batch first and reject the
+      // whole request if any item would be content+path empty. This makes
+      // mixed batches atomic for the empty-note case — no caller gets a
+      // half-applied batch where the prefix landed and the empty entry
+      // surfaced the 400. Mirrors the Store-level invariant exactly.
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const content = (item?.content ?? "").toString();
+        const rawPath = item?.path;
+        const pathEmpty = rawPath === undefined || rawPath === null
+          || (typeof rawPath === "string" && rawPath.trim() === "");
+        if (!content.trim() && pathEmpty) {
+          return json(
+            {
+              error_type: "empty_note",
+              error: "EmptyNoteError",
+              message: `empty_note: a note must have either content or a path (item index ${i})`,
+              item_index: i,
+            },
+            400,
+          );
+        }
+      }
+
+      // Tag-scope pre-validation: every new note in the batch must carry at
+      // least one tag inside the token's allowlist. Same atomic-batch
+      // discipline as the empty-note check — reject the whole request before
+      // any DB write so a tag-scoped token can't accidentally land a partial
+      // batch with an in-scope prefix.
+      if (tagScope.allowed) {
+        for (let i = 0; i < items.length; i++) {
+          if (!tagsWithinScope(items[i]?.tags, tagScope.allowed, tagScope.raw)) {
+            return tagScopeForbidden(tagScope.raw ?? []);
           }
         }
+      }
 
-        created.push((await store.getNote(note.id)) ?? note);
+      const created: Note[] = [];
+      // Wrap multi-item batches in a SQLite transaction so a mid-batch
+      // failure (path conflict, etc.) rolls back every prior insert. Without
+      // this, callers got half-applied batches where the prefix landed and
+      // the offending entry surfaced the 409 — see #236. Single-item posts
+      // are already atomic at the store layer and skip the wrap so they
+      // don't collide with concurrent single-item callers on the shared
+      // bun:sqlite connection.
+      const batched = items.length > 1;
+      if (batched) db.exec("BEGIN");
+      try {
+        for (const item of items) {
+          const note = await store.createNote(item.content ?? "", {
+            id: item.id,
+            path: item.path,
+            tags: item.tags,
+            metadata: item.metadata,
+            created_at: item.createdAt ?? item.created_at,
+          });
+
+          // Create explicit links
+          if (item.links) {
+            for (const link of item.links as { target: string; relationship: string }[]) {
+              const target = await resolveNote(store, link.target);
+              if (target) await store.createLink(note.id, target.id, link.relationship);
+            }
+          }
+
+          created.push((await store.getNote(note.id)) ?? note);
+        }
+        if (batched) db.exec("COMMIT");
+      } catch (e: any) {
+        if (batched) db.exec("ROLLBACK");
+        // Duck-type for module-boundary robustness (matches the PATCH branch).
+        if (e && e.code === "PATH_CONFLICT") {
+          return json(
+            { error_type: "path_conflict", error: "path_conflict", path: e.path, message: e.message },
+            409,
+          );
+        }
+        if (e && e.code === "EMPTY_NOTE") {
+          return json(
+            {
+              error_type: "empty_note",
+              error: "EmptyNoteError",
+              message: e.message,
+              item_index: e.item_index ?? null,
+            },
+            400,
+          );
+        }
+        throw e;
       }
 
       // Apply tag schema defaults
@@ -323,7 +470,7 @@ export async function handleNotes(
   const idMatch = subpath.match(/^\/([^/]+)(\/.*)?$/);
   if (!idMatch) return json({ error: "Not found" }, 404);
 
-  const idOrPath = decodeURIComponent(idMatch[1]);
+  const idOrPath = decodeURIComponent(idMatch[1]!);
   const sub = idMatch[2] ?? "";
 
   // Attachments sub-routes (keep as-is — Daily needs them)
@@ -331,6 +478,9 @@ export async function handleNotes(
     if (method === "POST") {
       const note = await resolveNote(store, idOrPath);
       if (!note) return json({ error: "Not found" }, 404);
+      if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+        return json({ error: "Not found" }, 404);
+      }
       const body = await req.json() as { path: string; mimeType: string; transcribe?: boolean };
       if (!body.path || !body.mimeType) return json({ error: "path and mimeType are required" }, 400);
 
@@ -361,6 +511,9 @@ export async function handleNotes(
     if (method === "GET") {
       const note = await resolveNote(store, idOrPath);
       if (!note) return json({ error: "Not found" }, 404);
+      if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+        return json({ error: "Not found" }, 404);
+      }
       return json(await store.getAttachments(note.id));
     }
     return json({ error: "Method not allowed" }, 405);
@@ -372,6 +525,9 @@ export async function handleNotes(
     if (method === "DELETE") {
       const note = await resolveNote(store, idOrPath);
       if (!note) return json({ error: "Not found" }, 404);
+      if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+        return json({ error: "Not found" }, 404);
+      }
       const result = await store.deleteAttachment(note.id, attId);
       if (!result.deleted) return json({ error: "Not found" }, 404);
       // Unlink the storage file only if no other attachment still references
@@ -395,6 +551,9 @@ export async function handleNotes(
   if (method === "GET") {
     const note = await resolveNote(store, idOrPath);
     if (!note) return json({ error: "Not found" }, 404);
+    if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+      return json({ error: "Not found" }, 404);
+    }
     const includeContent = parseBool(parseQuery(url, "include_content"), true);
     let result: any = includeContent ? { ...note } : toNoteIndex(note);
     const expand = parseExpandParams(url, db);
@@ -417,13 +576,60 @@ export async function handleNotes(
     try {
       const note = await resolveNote(store, idOrPath);
       if (!note) throw new NotFoundError(`Note not found: "${idOrPath}"`);
+      // Tag-scope: existing note must be in scope. Mirror the read-side
+      // 404-not-403 stance — a token can't see (and therefore can't
+      // discover-then-modify) notes outside its allowlist.
+      if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+        throw new NotFoundError(`Note not found: "${idOrPath}"`);
+      }
       const body = await req.json() as any;
+      // Tag-scope: post-update tag set must still satisfy scope. Compute
+      // the prospective tag set (existing − removed + added) and reject
+      // before any write if it would drift outside the allowlist. This
+      // covers the bot-untags-its-only-allowlisted-tag escape route.
+      if (tagScope.allowed) {
+        const removed = new Set<string>((body.tags?.remove as string[] | undefined) ?? []);
+        const projected = new Set<string>((note.tags ?? []).filter((t) => !removed.has(t)));
+        for (const t of (body.tags?.add as string[] | undefined) ?? []) projected.add(t);
+        if (!tagsWithinScope([...projected], tagScope.allowed, tagScope.raw)) {
+          return tagScopeForbidden(tagScope.raw ?? []);
+        }
+      }
+
+      // --- Validate mutual exclusion of content modes ---
+      const hasContent = body.content !== undefined;
+      const hasAppendPrepend = body.append !== undefined || body.prepend !== undefined;
+      const hasContentEdit = body.content_edit !== undefined;
+      const contentModes = (hasContent ? 1 : 0) + (hasAppendPrepend ? 1 : 0) + (hasContentEdit ? 1 : 0);
+      if (contentModes > 1) {
+        return json(
+          {
+            error: "mutually_exclusive",
+            message: "`content`, `append`/`prepend`, and `content_edit` are mutually exclusive — pick one mode of content update.",
+          },
+          400,
+        );
+      }
 
       // --- Safety-by-default: refuse mutations without a precondition ---
       // Mirror the MCP tool: require `if_updated_at` unless the caller
       // explicitly sets `force: true`. 428 Precondition Required is the
       // RFC 6585 status for exactly this case.
-      if (body.if_updated_at === undefined && body.force !== true) {
+      //
+      // Append/prepend-only updates are exempt — SQL-atomic concatenation
+      // is no-conflict-by-design. Tag/link mutations are *not* exempt
+      // (#201): they're idempotent set-ops, but still represent a
+      // non-content change the caller should observe before re-asserting.
+      const isAppendOnly = hasAppendPrepend
+        && !hasContent
+        && !hasContentEdit
+        && body.path === undefined
+        && body.metadata === undefined
+        && body.created_at === undefined
+        && body.createdAt === undefined
+        && body.tags === undefined
+        && body.links === undefined;
+      if (!isAppendOnly && body.if_updated_at === undefined && body.force !== true) {
         return json(
           {
             error_type: "precondition_required",
@@ -437,10 +643,40 @@ export async function handleNotes(
         );
       }
 
+      // --- Resolve content_edit into a full content string ---
+      let contentOverride = body.content as string | undefined;
+      if (hasContentEdit) {
+        const ce = body.content_edit as { old_text?: unknown; new_text?: unknown };
+        if (typeof ce?.old_text !== "string" || typeof ce?.new_text !== "string") {
+          return json(
+            { error: "bad_request", message: "`content_edit` requires { old_text: string, new_text: string }." },
+            400,
+          );
+        }
+        const idx = note.content.indexOf(ce.old_text);
+        if (idx < 0) {
+          // 422 Unprocessable Entity, not 404: the note exists, the request is
+          // syntactically valid, but the search string can't be applied to the
+          // current content. Returning 404 implied "note doesn't exist" and
+          // confused operators chasing a missing record (#202).
+          return json(
+            { error: "unprocessable_content", message: `content_edit: \`old_text\` not found in note "${note.id}". Re-read and retry.` },
+            422,
+          );
+        }
+        const second = note.content.indexOf(ce.old_text, idx + 1);
+        if (second >= 0) {
+          return json(
+            { error: "ambiguous", message: `content_edit: \`old_text\` matches multiple times in note "${note.id}" — must match exactly once. Add surrounding context.` },
+            409,
+          );
+        }
+        contentOverride = note.content.slice(0, idx) + ce.new_text + note.content.slice(idx + ce.old_text.length);
+      }
+
       // --- Plan bracket cleanup for wikilink removals (no DB writes yet) ---
       // The actual link deletions happen only after the core UPDATE succeeds,
       // so a conflict leaves the note untouched.
-      let contentOverride = body.content as string | undefined;
       const linksRemove = body.links?.remove as { target: string; relationship: string }[] | undefined;
       const resolvedLinksToRemove: { targetId: string; relationship: string }[] = [];
       if (linksRemove) {
@@ -449,7 +685,12 @@ export async function handleNotes(
           if (!target) continue;
           resolvedLinksToRemove.push({ targetId: target.id, relationship: link.relationship });
           if (link.relationship === "wikilink" && target.path) {
-            const current = contentOverride ?? note.content;
+            // Materialize the prospective content for append/prepend callers
+            // so we don't fight the SQL-atomic path with a JS-level rewrite.
+            const current = contentOverride
+              ?? (hasAppendPrepend
+                ? (body.prepend as string ?? "") + note.content + (body.append as string ?? "")
+                : note.content);
             const cleaned = removeWikilinkBrackets(current, target.path);
             if (cleaned !== current) contentOverride = cleaned;
           }
@@ -458,7 +699,12 @@ export async function handleNotes(
 
       // --- Core update (runs the if_updated_at check atomically) ---
       const updates: any = {};
-      if (contentOverride !== undefined) updates.content = contentOverride;
+      if (contentOverride !== undefined) {
+        updates.content = contentOverride;
+      } else if (hasAppendPrepend) {
+        if (body.append !== undefined) updates.append = body.append;
+        if (body.prepend !== undefined) updates.prepend = body.prepend;
+      }
       if (body.path !== undefined) updates.path = body.path;
       if (body.metadata !== undefined) {
         const existing = (note.metadata as Record<string, unknown>) ?? {};
@@ -521,6 +767,27 @@ export async function handleNotes(
           409,
         );
       }
+      // Path-rename collision — schema's UNIQUE(path) tripped. Issue #126.
+      if (e && e.code === "PATH_CONFLICT") {
+        return json(
+          { error_type: "path_conflict", error: "path_conflict", path: e.path, message: e.message },
+          409,
+        );
+      }
+      // Empty-note guard from the Store boundary (#213) — the proposed update
+      // would clear both content AND path. Surface as 400 so callers can fix
+      // the request without retrying.
+      if (e && e.code === "EMPTY_NOTE") {
+        return json(
+          {
+            error_type: "empty_note",
+            error: "EmptyNoteError",
+            message: e.message,
+            note_id: e.note_id ?? null,
+          },
+          400,
+        );
+      }
       throw e;
     }
   }
@@ -529,6 +796,11 @@ export async function handleNotes(
   if (method === "DELETE") {
     const note = await resolveNote(store, idOrPath);
     if (!note) return json({ error: "Not found" }, 404);
+    // Tag-scope: can't delete what you can't read. 404 (not 403) for the
+    // same no-leak reason as the read paths.
+    if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+      return json({ error: "Not found" }, 404);
+    }
     await store.deleteNote(note.id);
     return json({ deleted: true, id: note.id });
   }
@@ -541,7 +813,12 @@ export async function handleNotes(
 //        POST /api/tags/:name/rename
 // ---------------------------------------------------------------------------
 
-export async function handleTags(req: Request, store: Store, subpath = ""): Promise<Response> {
+export async function handleTags(
+  req: Request,
+  store: Store,
+  subpath = "",
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
   const url = new URL(req.url);
 
   // GET /tags — list all, or get single tag detail
@@ -549,27 +826,49 @@ export async function handleTags(req: Request, store: Store, subpath = ""): Prom
     const singleTag = parseQuery(url, "tag");
 
     if (singleTag) {
+      // Tag-scope: a tag-scoped token can only see tags reachable from its
+      // allowlist (root + descendants per the parent_names hierarchy).
+      // Anything else 404s — same "no leak" stance as note reads.
+      if (tagScope.allowed && !tagScope.allowed.has(singleTag)) {
+        return json({ error: "Tag not found", tag: singleTag }, 404);
+      }
       const allTags = await store.listTags();
       const found = allTags.find((t) => t.name === singleTag);
-      const schema = await store.getTagSchema(singleTag);
+      const record = await store.getTagRecord(singleTag);
       return json({
         name: singleTag,
         count: found?.count ?? 0,
-        description: schema?.description ?? null,
-        fields: schema?.fields ?? null,
+        description: record?.description ?? null,
+        fields: record?.fields ?? null,
+        relationships: record?.relationships ?? null,
+        parent_names: record?.parent_names ?? null,
+        created_at: record?.created_at ?? null,
+        updated_at: record?.updated_at ?? null,
       });
     }
 
     const tags = await store.listTags();
+    const filtered = tagScope.allowed
+      ? tags.filter((t) => tagScope.allowed!.has(t.name))
+      : tags;
     if (parseBool(parseQuery(url, "include_schema"), false)) {
-      const schemas = await store.getTagSchemaMap();
-      return json(tags.map((t) => ({
-        ...t,
-        description: schemas[t.name]?.description ?? null,
-        fields: schemas[t.name]?.fields ?? null,
-      })));
+      const records = new Map(
+        (await store.listTagRecords()).map((r) => [r.tag, r] as const),
+      );
+      return json(filtered.map((t) => {
+        const r = records.get(t.name);
+        return {
+          ...t,
+          description: r?.description ?? null,
+          fields: r?.fields ?? null,
+          relationships: r?.relationships ?? null,
+          parent_names: r?.parent_names ?? null,
+          created_at: r?.created_at ?? null,
+          updated_at: r?.updated_at ?? null,
+        };
+      }));
     }
-    return json(tags);
+    return json(filtered);
   }
 
   // POST /tags/merge — atomic multi-source merge into a target tag.
@@ -588,6 +887,37 @@ export async function handleTags(req: Request, store: Store, subpath = ""): Prom
     if (typeof target !== "string" || target.length === 0) {
       return json({ error: "target must be a non-empty string" }, 400);
     }
+    // Tag-scope: every source AND the target must be inside the allowlist.
+    // A merge that pulls notes out of a token's scope (or pushes notes into
+    // it) is a privilege escalation; refuse the whole op.
+    if (tagScope.allowed) {
+      for (const t of [...sources, target]) {
+        if (!tagScope.allowed.has(t)) {
+          return tagScopeForbidden(tagScope.raw ?? []);
+        }
+      }
+    }
+    // Same dependency check as DELETE /tags/:name — merging consumes every
+    // source tag, so a source referenced by a tag-scoped token would orphan
+    // 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;
+    for (const src of sources) {
+      const tokens = findTokensReferencingTag(db, src as string);
+      if (tokens.length > 0) referenced.push({ source: src as string, tokens });
+    }
+    if (referenced.length > 0) {
+      return json(
+        {
+          error: "TagInUseByTokens",
+          error_type: "tag_in_use_by_tokens",
+          message: `Cannot merge: ${referenced.length} source tag(s) referenced by tag-scoped token(s); revoke or re-mint them first.`,
+          referenced_by: referenced,
+        },
+        409,
+      );
+    }
     const result = await store.mergeTags(sources, target);
     return json(result);
   }
@@ -596,13 +926,34 @@ export async function handleTags(req: Request, store: Store, subpath = ""): Prom
   const renameMatch = subpath.match(/^\/([^/]+)\/rename$/);
   if (renameMatch) {
     if (req.method !== "POST") return json({ error: "Method not allowed" }, 405);
-    const oldName = decodeURIComponent(renameMatch[1]);
+    const oldName = decodeURIComponent(renameMatch[1]!);
     const body = (await req.json().catch(() => null)) as { new_name?: unknown } | null;
     if (!body) return json({ error: "Invalid JSON body" }, 400);
     const newName = body.new_name;
     if (typeof newName !== "string" || newName.length === 0) {
       return json({ error: "new_name must be a non-empty string" }, 400);
     }
+    if (tagScope.allowed && (!tagScope.allowed.has(oldName) || !tagScope.allowed.has(newName))) {
+      return tagScopeForbidden(tagScope.raw ?? []);
+    }
+    // Same dependency check as DELETE / merge — until vault#240 ships the
+    // rename→token cascade, fail-closed on referenced names so the rename
+    // can't silently orphan a token's allowlist (the JSON-stored old name
+    // would no longer match anything). When the cascade lands this becomes
+    // an unconditional cascade + audit log entry per patterns#26 §Lifecycle.
+    const referenced_by = findTokensReferencingTag((store as any).db, oldName);
+    if (referenced_by.length > 0) {
+      return json(
+        {
+          error: "TagInUseByTokens",
+          error_type: "tag_in_use_by_tokens",
+          message: `Tag "${oldName}" is referenced by ${referenced_by.length} tag-scoped token(s); revoke or re-mint them before renaming. (vault#240 will replace this with an automatic cascade.)`,
+          tag: oldName,
+          referenced_by,
+        },
+        409,
+      );
+    }
     const result = await store.renameTag(oldName, newName);
     if ("error" in result) {
       if (result.error === "not_found") return json({ error: "not_found", tag: oldName }, 404);
@@ -623,47 +974,297 @@ export async function handleTags(req: Request, store: Store, subpath = ""): Prom
   // Routes with tag name
   const nameMatch = subpath.match(/^\/([^/]+)$/);
   if (!nameMatch) return json({ error: "Not found" }, 404);
-  const tagName = decodeURIComponent(nameMatch[1]);
+  const tagName = decodeURIComponent(nameMatch[1]!);
 
-  // GET /tags/:name — single tag detail
+  // GET /tags/:name — single tag detail (full record)
   if (req.method === "GET") {
+    if (tagScope.allowed && !tagScope.allowed.has(tagName)) {
+      return json({ error: "Tag not found", tag: tagName }, 404);
+    }
     const allTags = await store.listTags();
     const found = allTags.find((t) => t.name === tagName);
-    const schema = await store.getTagSchema(tagName);
+    const record = await store.getTagRecord(tagName);
     return json({
       name: tagName,
       count: found?.count ?? 0,
-      description: schema?.description ?? null,
-      fields: schema?.fields ?? null,
+      description: record?.description ?? null,
+      fields: record?.fields ?? null,
+      relationships: record?.relationships ?? null,
+      parent_names: record?.parent_names ?? null,
+      created_at: record?.created_at ?? null,
+      updated_at: record?.updated_at ?? null,
     });
   }
 
-  // PUT /tags/:name — upsert tag schema (description + fields)
+  // PUT /tags/:name — upsert tag identity row. Body accepts any combination
+  // of { description, fields, relationships, parent_names }; omitted keys
+  // are preserved, explicit null clears. See patterns/tag-data-model.md.
   if (req.method === "PUT") {
-    const body = await req.json() as { description?: string; fields?: Record<string, unknown> };
-    const existing = await store.getTagSchema(tagName);
-    const mergedFields = { ...existing?.fields, ...(body.fields as any) };
-    const schema = await store.upsertTagSchema(tagName, {
-      description: body.description ?? existing?.description,
-      fields: Object.keys(mergedFields).length > 0 ? mergedFields : undefined,
+    if (tagScope.allowed && !tagScope.allowed.has(tagName)) {
+      return tagScopeForbidden(tagScope.raw ?? []);
+    }
+    const body = (await req.json()) as {
+      description?: string | null;
+      fields?: Record<string, unknown> | null;
+      relationships?: Record<string, unknown> | null;
+      parent_names?: unknown;
+    };
+
+    // Validate relationships shape + cardinality vocabulary up front so
+    // a bad payload returns 400, not a thrown 500.
+    let relationshipsPatch:
+      | Record<string, tagSchemaOps.TagRelationship>
+      | null
+      | undefined;
+    if (body.relationships === null) {
+      relationshipsPatch = null;
+    } else if (body.relationships !== undefined) {
+      try {
+        relationshipsPatch = tagSchemaOps.validateRelationships(body.relationships);
+      } catch (err) {
+        return json(
+          { error: (err as Error).message, error_type: "invalid_relationships" },
+          400,
+        );
+      }
+    }
+
+    let parentNamesPatch: string[] | null | undefined;
+    if (body.parent_names === null) {
+      parentNamesPatch = null;
+    } else if (body.parent_names !== undefined) {
+      if (!Array.isArray(body.parent_names)) {
+        return json({ error: "parent_names must be an array of tag names" }, 400);
+      }
+      const cleaned = (body.parent_names as unknown[]).filter(
+        (p): p is string => typeof p === "string" && p.length > 0,
+      );
+      parentNamesPatch = cleaned.length > 0 ? cleaned : null;
+    }
+
+    // Field merge mirrors MCP update-tag — preserves prior keys when the
+    // payload only declares new ones.
+    let fieldsPatch:
+      | Record<string, tagSchemaOps.TagFieldSchema>
+      | null
+      | undefined;
+    if (body.fields === null) {
+      fieldsPatch = null;
+    } else if (body.fields !== undefined) {
+      const existing = await store.getTagSchema(tagName);
+      const merged: Record<string, tagSchemaOps.TagFieldSchema> = {
+        ...(existing?.fields ?? {}),
+        ...(body.fields as Record<string, tagSchemaOps.TagFieldSchema>),
+      };
+      fieldsPatch = Object.keys(merged).length > 0 ? merged : null;
+    }
+
+    const result = await store.upsertTagRecord(tagName, {
+      ...(body.description !== undefined ? { description: body.description } : {}),
+      ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
+      ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),
+      ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
     });
-    return json(schema);
+    return json(result);
   }
 
-  // DELETE /tags/:name — delete tag + schema from all notes
+  // DELETE /tags/:name — delete tag + identity row + remove from all notes
   if (req.method === "DELETE") {
-    await store.deleteTagSchema(tagName);
+    if (tagScope.allowed && !tagScope.allowed.has(tagName)) {
+      return tagScopeForbidden(tagScope.raw ?? []);
+    }
+    // Tag-scoped tokens reference root tags by name; deleting a referenced
+    // 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);
+    if (referenced_by.length > 0) {
+      return json(
+        {
+          error: "TagInUseByTokens",
+          error_type: "tag_in_use_by_tokens",
+          message: `Tag "${tagName}" is referenced by ${referenced_by.length} tag-scoped token(s); revoke or re-mint them before deleting.`,
+          tag: tagName,
+          referenced_by,
+        },
+        409,
+      );
+    }
     return json(await store.deleteTag(tagName));
   }
 
   return json({ error: "Method not allowed" }, 405);
 }
 
+// ---------------------------------------------------------------------------
+// Note schemas — GET/PUT/DELETE /api/note-schemas[/:name],
+//                GET/POST/DELETE /api/note-schemas/:name/mappings
+// ---------------------------------------------------------------------------
+
+export async function handleNoteSchemas(
+  req: Request,
+  store: Store,
+  subpath = "",
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
+  const url = new URL(req.url);
+
+  // Tag-scope filter for `tag`-kind mappings. `path_prefix` mappings carry no
+  // tag-axis information so they're always visible/writable. The single-tag
+  // check delegates to `tagsWithinScope` so the string-form fallback in
+  // patterns/tag-scoped-tokens.md §Storage details is honored end-to-end.
+  const mappingInScope = (m: { match_kind: SchemaMappingKind; match_value: string }): boolean => {
+    if (m.match_kind !== "tag") return true;
+    return tagsWithinScope([m.match_value], tagScope.allowed, tagScope.raw);
+  };
+
+  // GET /note-schemas — list all
+  if (req.method === "GET" && subpath === "") {
+    const schemas = await store.listNoteSchemas();
+    if (parseBool(parseQuery(url, "include_mappings"), false)) {
+      const allMappings = (await store.listSchemaMappings()).filter(mappingInScope);
+      const byName = new Map<string, typeof allMappings>();
+      for (const m of allMappings) {
+        const list = byName.get(m.schema_name) ?? [];
+        list.push(m);
+        byName.set(m.schema_name, list);
+      }
+      return json(schemas.map((s) => ({ ...s, mappings: byName.get(s.name) ?? [] })));
+    }
+    return json(schemas);
+  }
+
+  // /note-schemas/:name(/mappings)
+  const mappingsMatch = subpath.match(/^\/([^/]+)\/mappings$/);
+  if (mappingsMatch) {
+    const schemaName = decodeURIComponent(mappingsMatch[1]!);
+
+    // GET /note-schemas/:name/mappings
+    if (req.method === "GET") {
+      const mappings = (await store.listSchemaMappings({ schema_name: schemaName })).filter(mappingInScope);
+      return json(mappings);
+    }
+
+    // POST /note-schemas/:name/mappings — body: { match_kind, match_value }
+    if (req.method === "POST") {
+      const body = (await req.json().catch(() => null)) as
+        | { match_kind?: unknown; match_value?: unknown }
+        | null;
+      if (!body) return json({ error: "Invalid JSON body" }, 400);
+      const match_kind = body.match_kind;
+      const match_value = body.match_value;
+      if (typeof match_kind !== "string" || !MAPPING_KINDS.includes(match_kind as SchemaMappingKind)) {
+        return json(
+          { error: `match_kind must be one of: ${MAPPING_KINDS.join(", ")}`, error_type: "invalid_match_kind" },
+          400,
+        );
+      }
+      if (typeof match_value !== "string" || match_value.length === 0) {
+        return json({ error: "match_value must be a non-empty string" }, 400);
+      }
+      // Tag-scope write gate: a tag mapping for an out-of-scope tag would let
+      // a tag-scoped token bind a schema to a tag it can't see. Mirrors the
+      // vault#241 write-gate shape (403 + tag_scope_violation envelope).
+      if (!mappingInScope({ match_kind: match_kind as SchemaMappingKind, match_value })) {
+        return tagScopeForbidden(tagScope.raw ?? []);
+      }
+      // Validate FK explicitly so a bad schema_name surfaces as 404 (not a
+      // raw SQLITE_CONSTRAINT 500).
+      if (!(await store.getNoteSchema(schemaName))) {
+        return json({ error: "Schema not found", schema_name: schemaName }, 404);
+      }
+      await store.setSchemaMapping(schemaName, match_kind as SchemaMappingKind, match_value);
+      return json({ ok: true, schema_name: schemaName, match_kind, match_value }, 201);
+    }
+
+    // DELETE /note-schemas/:name/mappings?match_kind=...&match_value=...
+    // Query params (not URL segments) because match_value can contain slashes
+    // for path-prefix mappings.
+    if (req.method === "DELETE") {
+      const match_kind = parseQuery(url, "match_kind");
+      const match_value = parseQuery(url, "match_value");
+      if (!match_kind || !MAPPING_KINDS.includes(match_kind as SchemaMappingKind)) {
+        return json(
+          { error: `match_kind must be one of: ${MAPPING_KINDS.join(", ")}`, error_type: "invalid_match_kind" },
+          400,
+        );
+      }
+      if (!match_value) {
+        return json({ error: "match_value query parameter is required" }, 400);
+      }
+      if (!mappingInScope({ match_kind: match_kind as SchemaMappingKind, match_value })) {
+        return tagScopeForbidden(tagScope.raw ?? []);
+      }
+      const deleted = await store.deleteSchemaMapping(
+        schemaName,
+        match_kind as SchemaMappingKind,
+        match_value,
+      );
+      return json({ deleted, schema_name: schemaName, match_kind, match_value });
+    }
+
+    return json({ error: "Method not allowed" }, 405);
+  }
+
+  // /note-schemas/:name (no nested segment)
+  const nameMatch = subpath.match(/^\/([^/]+)$/);
+  if (!nameMatch) return json({ error: "Not found" }, 404);
+  const name = decodeURIComponent(nameMatch[1]!);
+
+  // GET /note-schemas/:name — single (with mappings)
+  if (req.method === "GET") {
+    const schema = await store.getNoteSchema(name);
+    if (!schema) return json({ error: "Schema not found", name }, 404);
+    const mappings = (await store.listSchemaMappings({ schema_name: name })).filter(mappingInScope);
+    return json({ ...schema, mappings });
+  }
+
+  // PUT /note-schemas/:name — partial-upsert (mirrors update-tag shape)
+  if (req.method === "PUT") {
+    const body = (await req.json().catch(() => null)) as {
+      description?: string | null;
+      fields?: Record<string, unknown> | null;
+      required?: unknown;
+    } | null;
+    if (!body) return json({ error: "Invalid JSON body" }, 400);
+
+    const patch: { description?: string | null; fields?: Record<string, NoteSchemaField> | null; required?: string[] | null } = {};
+    if (body.description === null) patch.description = null;
+    else if (body.description !== undefined) patch.description = body.description;
+    if (body.fields === null) patch.fields = null;
+    else if (body.fields !== undefined) patch.fields = body.fields as Record<string, NoteSchemaField>;
+    if (body.required === null) patch.required = null;
+    else if (body.required !== undefined) {
+      if (!Array.isArray(body.required)) {
+        return json({ error: "required must be an array of field names" }, 400);
+      }
+      patch.required = (body.required as unknown[]).filter(
+        (x): x is string => typeof x === "string",
+      );
+    }
+
+    const result = await store.upsertNoteSchema(name, patch);
+    return json(result);
+  }
+
+  // DELETE /note-schemas/:name — drop schema; FK CASCADE drops its mappings.
+  if (req.method === "DELETE") {
+    const deleted = await store.deleteNoteSchema(name);
+    return json({ deleted, name });
+  }
+
+  return json({ error: "Method not allowed" }, 405);
+}
+
 // ---------------------------------------------------------------------------
 // Find-path — GET /api/find-path?source=...&target=...
 // ---------------------------------------------------------------------------
 
-export async function handleFindPath(req: Request, store: Store): Promise<Response> {
+export async function handleFindPath(
+  req: Request,
+  store: Store,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
   if (req.method !== "GET") return json({ error: "Method not allowed" }, 405);
 
   const url = new URL(req.url);
@@ -675,11 +1276,28 @@ export async function handleFindPath(req: Request, store: Store): Promise<Respon
   try {
     const sourceNote = await resolveNote(store, source);
     if (!sourceNote) return json({ error: `Note not found: "${source}"` }, 404);
+    if (!noteWithinTagScope(sourceNote, tagScope.allowed, tagScope.raw)) {
+      return json({ error: `Note not found: "${source}"` }, 404);
+    }
     const targetNote = await resolveNote(store, target);
     if (!targetNote) return json({ error: `Note not found: "${target}"` }, 404);
+    if (!noteWithinTagScope(targetNote, tagScope.allowed, tagScope.raw)) {
+      return json({ error: `Note not found: "${target}"` }, 404);
+    }
     const maxDepth = Math.min(parseInt10(parseQuery(url, "max_depth")) ?? 5, 10);
 
+    // Tag-scope on the *path* itself: every intermediate hop must also be
+    // within scope. A reachable target via an out-of-scope hop is not a
+    // permitted answer — surface as "no path" (null).
     const result = linkOps.findPath(db, sourceNote.id, targetNote.id, { max_depth: maxDepth });
+    if (result && tagScope.allowed) {
+      for (const id of result.path) {
+        const hop = await store.getNote(id);
+        if (!hop || !noteWithinTagScope(hop, tagScope.allowed, tagScope.raw)) {
+          return json(null);
+        }
+      }
+    }
     return json(result);
   } catch (e: any) {
     if (e instanceof NotFoundError) return json({ error: e.message }, 404);
@@ -789,7 +1407,7 @@ function renderMarkdown(md: string): string {
   let inCodeBlock = false;
 
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
+    const line = lines[i]!;
 
     if (line.trimStart().startsWith("```")) {
       if (inCodeBlock) {
@@ -815,15 +1433,15 @@ function renderMarkdown(md: string): string {
 
     const headerMatch = trimmed.match(/^(#{1,6})\s+(.+)/);
     if (headerMatch) {
-      const level = headerMatch[1].length;
-      out.push(`<h${level}>${inlineMarkdown(escapeHtml(headerMatch[2]))}</h${level}>`);
+      const level = headerMatch[1]!.length;
+      out.push(`<h${level}>${inlineMarkdown(escapeHtml(headerMatch[2]!))}</h${level}>`);
       continue;
     }
 
     if (trimmed.startsWith("- ") || trimmed.startsWith("* ")) {
       const items: string[] = [trimmed.slice(2)];
       while (i + 1 < lines.length) {
-        const next = lines[i + 1].trim();
+        const next = lines[i + 1]!.trim();
         if (next.startsWith("- ") || next.startsWith("* ")) {
           items.push(next.slice(2));
           i++;
@@ -949,9 +1567,17 @@ export function assetsDir(vault: string): string {
 }
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
 
+// Storage allowlist policy:
+//   - audio + image + .pdf (knowledge-vault content: papers, scans, receipts)
+//     + .mp4 (mobile capture default; iOS records mp4, not webm).
+//   - .svg and .html are deliberately excluded — both can embed `<script>`
+//     tags, which would turn an upload into a same-origin XSS vector when
+//     the asset is served back from /storage/. If a future use case needs
+//     SVG, sanitize on read (strip <script>/<foreignObject>) and revisit.
 const ALLOWED_EXTENSIONS = new Set([
   ".wav", ".mp3", ".m4a", ".ogg", ".webm",
   ".png", ".jpg", ".jpeg", ".gif", ".webp",
+  ".pdf", ".mp4",
 ]);
 
 const MIME_TYPES: Record<string, string> = {
@@ -965,6 +1591,8 @@ const MIME_TYPES: Record<string, string> = {
   ".jpeg": "image/jpeg",
   ".gif": "image/gif",
   ".webp": "image/webp",
+  ".pdf": "application/pdf",
+  ".mp4": "video/mp4",
 };
 
 export async function handleStorage(req: Request, path: string, vault: string): Promise<Response> {
@@ -984,7 +1612,7 @@ export async function handleStorage(req: Request, path: string, vault: string):
       return json({ error: `File type ${ext} not allowed` }, 400);
     }
 
-    const date = new Date().toISOString().split("T")[0];
+    const date = new Date().toISOString().split("T")[0]!;
     const dir = join(assets, date);
     mkdirSync(dir, { recursive: true });