@openparachute/vault 0.4.4-rc.14 → 0.4.5

package/core/src/schema.ts

@@ -2,17 +2,25 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 17;
+export const SCHEMA_VERSION = 18;
 
 export const SCHEMA_SQL = `
--- Notes: the universal record
+-- Notes: the universal record.
+--
+-- extension (v18, vault#328) carries the file suffix the note should
+-- exhibit when serialized to disk — "md" by default, "csv"/"yaml"/"json"/
+-- "mdx"/etc. for non-markdown notes. Stored extension-less in the path
+-- column; on-disk uniqueness key is (path, extension). See
+-- core/src/portable-md.ts:supportsInlineFrontmatter for the
+-- frontmatter-vs-sidecar split.
 CREATE TABLE IF NOT EXISTS notes (
   id TEXT PRIMARY KEY,
   content TEXT DEFAULT '',
   path TEXT,
   metadata TEXT DEFAULT '{}',
   created_at TEXT NOT NULL,
-  updated_at TEXT
+  updated_at TEXT,
+  extension TEXT NOT NULL DEFAULT 'md'
 );
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
@@ -266,6 +274,11 @@ export function initSchema(db: Database): void {
   // as `tags.fields` if needed. See vault#267.
   migrateToV17(db);
 
+  // Migrate v17 → v18: add `notes.extension TEXT NOT NULL DEFAULT 'md'`.
+  // Backward-compat by construction — every existing row defaults to "md"
+  // (markdown), unchanged in meaning. See vault#328.
+  migrateToV18(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -793,6 +806,51 @@ function migrateToV17(db: Database): void {
   }
 }
 
+/**
+ * Migrate v17 → v18: add `notes.extension TEXT NOT NULL DEFAULT 'md'`
+ * (vault#328) AND widen the path-uniqueness index from `(path)` to
+ * `(path, extension)` so two notes can share a path differing only by
+ * extension (`Recipes/pasta` with both .md and .csv variants).
+ *
+ * Backward-compat by construction — every existing row defaults to "md",
+ * so the new composite-index uniqueness collapses to the v5
+ * "(path WHERE NOT NULL) is unique" behavior on existing data. Wrapped
+ * in BEGIN IMMEDIATE / COMMIT / ROLLBACK per the v14+ pattern.
+ */
+function migrateToV18(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+
+  // Two responsibilities (column add + index swap) — both idempotent
+  // individually. Wrap in one transaction so an upgrading v17 vault
+  // ends up at exactly v17 or v18, never partial.
+  const needsColumn = !hasColumn(db, "notes", "extension");
+  const indexes = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='index' AND name IN ('idx_notes_path_unique', 'idx_notes_path_ext_unique')",
+  ).all() as { name: string }[];
+  const hasOldUnique = indexes.some((r) => r.name === "idx_notes_path_unique");
+  const hasNewUnique = indexes.some((r) => r.name === "idx_notes_path_ext_unique");
+  if (!needsColumn && hasNewUnique && !hasOldUnique) return;
+
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    if (needsColumn) {
+      db.exec("ALTER TABLE notes ADD COLUMN extension TEXT NOT NULL DEFAULT 'md'");
+    }
+    if (hasOldUnique) {
+      db.exec("DROP INDEX idx_notes_path_unique");
+    }
+    if (!hasNewUnique) {
+      db.exec(
+        "CREATE UNIQUE INDEX idx_notes_path_ext_unique ON notes(path, extension) WHERE path IS NOT NULL",
+      );
+    }
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/store.ts

@@ -92,7 +92,7 @@ export class BunSqliteStore implements Store {
 
   // ---- Notes ----
 
-  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
+  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -113,8 +113,8 @@ export class BunSqliteStore implements Store {
     return noteOps.getNote(this.db, id);
   }
 
-  async getNoteByPath(path: string): Promise<Note | null> {
-    return noteOps.getNoteByPath(this.db, path);
+  async getNoteByPath(path: string, extension?: string): Promise<Note | null> {
+    return noteOps.getNoteByPath(this.db, path, extension);
   }
 
   async getNotes(ids: string[]): Promise<Note[]> {
@@ -128,6 +128,7 @@ export class BunSqliteStore implements Store {
       append?: string;
       prepend?: string;
       path?: string;
+      extension?: string;
       metadata?: Record<string, unknown>;
       created_at?: string;
       skipUpdatedAt?: boolean;
@@ -498,7 +499,7 @@ export class BunSqliteStore implements Store {
    * `syncAllWikilinks`, so adding the cache rebuild there is the natural
    * place.)
    */
-  async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
+  async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
     return noteOps.createNote(this.db, content, opts);
   }
 

package/core/src/types.ts

@@ -10,6 +10,14 @@ export interface Note {
   id: string;
   content: string;
   path?: string;
+  /**
+   * File extension (sans dot). Defaults to `"md"`. Controls the
+   * serialized file suffix on export — `.md`/`.mdx` carry frontmatter
+   * inline; `.csv`/`.yaml`/`.json`/etc. carry their metadata in a
+   * sidecar at `.parachute/notes-meta/<id>.yaml`. See vault#328 +
+   * `core/src/portable-md.ts:supportsInlineFrontmatter`.
+   */
+  extension?: string;
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
@@ -64,6 +72,13 @@ export interface QueryOpts {
   hasLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
+  /**
+   * Filter by file extension. Pass a single extension (e.g. `"csv"`) or
+   * an array (e.g. `["csv", "yaml", "json"]`). Extension is compared
+   * lower-case. Notes default to `"md"` so `extension: "md"` matches
+   * the existing markdown corpus. See vault#328.
+   */
+  extension?: string | string[];
   // Restrict results to a specific set of note IDs. The MCP `near` query uses
   // this to push graph-neighborhood scoping into the SQL WHERE clause so that
   // LIMIT and ORDER BY apply to the filtered set, not the whole notes table.
@@ -107,6 +122,7 @@ export interface QueryOpts {
 export interface NoteSummary {
   id: string;
   path?: string;
+  extension?: string;
   metadata?: Record<string, unknown>;
   createdAt: string;
   updatedAt?: string;
@@ -120,6 +136,7 @@ export interface NoteSummary {
 export interface NoteIndex {
   id: string;
   path?: string;
+  extension?: string;
   createdAt: string;
   updatedAt?: string;
   tags?: string[];
@@ -138,11 +155,18 @@ export interface HydratedLink extends Link {
 
 export interface Store {
   // Notes
-  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note>;
+  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
   getNote(id: string): Promise<Note | null>;
-  getNoteByPath(path: string): Promise<Note | null>;
+  /**
+   * Look up a note by path. Pass `extension` to disambiguate when
+   * multiple notes share a path differing only by extension (post-
+   * vault#328). When omitted and >1 row matches, throws
+   * `AmbiguousPathError` instead of silently picking one. See
+   * vault#330 S1.
+   */
+  getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from

package/core/src/wikilinks.ts

@@ -110,19 +110,57 @@ function stripCode(content: string): string {
  * Resolve a wikilink target to a note ID.
  *
  * Resolution order:
- * 1. Exact path match (case-insensitive)
- * 2. Basename match — target matches the last segment of a path
- *    (e.g., "README" matches "Projects/Parachute/README")
- *    Only if there's exactly one match (ambiguous = unresolved)
+ * 1. **Explicit-extension target**: `[[Foo.csv]]` matches the note with
+ *    `path: "Foo"` AND `extension: "csv"` (vault#328). Lets a reader
+ *    disambiguate when multiple notes share a path differing only by
+ *    extension. The trailing `.<ext>` must match a known
+ *    alphanumeric pattern (1–16 chars) — otherwise the dot is treated
+ *    as part of the path string and falls through to the existing
+ *    rules.
+ * 2. Exact path match (case-insensitive) — multiple matches resolve to
+ *    a single note when only ONE extension is in play; if `Foo.md` and
+ *    `Foo.csv` both exist, the link refuses to resolve and the caller
+ *    sees an unresolved-wikilink entry (vault#328 ambiguity policy).
+ * 3. Basename match — target matches the last segment of a path
+ *    (e.g., "README" matches "Projects/Parachute/README"). Same
+ *    cross-extension ambiguity policy as #2.
  */
 export function resolveWikilink(db: Database, target: string): string | null {
-  // 1. Exact match (case-insensitive)
+  // 1. Explicit extension form: `[[path.ext]]` where `.ext` is a
+  // pattern-matching tail (lowercase alphanumeric, 1–16 chars).
+  // Mirrors EXTENSION_PATTERN in core/src/notes.ts so the wikilink
+  // parser and the API surface share the same notion of "this looks
+  // like an extension."
+  const extMatch = target.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const pathPart = extMatch[1]!;
+    const extPart = extMatch[2]!.toLowerCase();
+    const explicit = db.prepare(
+      "SELECT id FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(pathPart, extPart) as { id: string } | undefined;
+    if (explicit) return explicit.id;
+    // No match for explicit (path, ext) — fall through to the looser
+    // rules so a literal note named `Recipe.v2` (where `v2` isn't an
+    // extension on a real note) can still resolve under exact-path
+    // match.
+  }
+
+  // 2. Exact match (case-insensitive). When multiple notes share a path
+  // (post-vault#328 this happens when `Foo.md` and `Foo.csv` both
+  // exist, since path is stored extension-less), refuse to resolve.
   const exact = db.prepare(
     "SELECT id FROM notes WHERE path = ? COLLATE NOCASE",
-  ).get(target) as { id: string } | undefined;
-  if (exact) return exact.id;
+  ).all(target) as { id: string }[];
+  if (exact.length === 1) return exact[0]!.id;
+  if (exact.length > 1) {
+    // Ambiguous — refuse-and-require-explicit-extension policy
+    // (vault#328). Returning null routes through the existing
+    // unresolved-wikilinks workflow, so the reader (or the indexer)
+    // sees the conflict.
+    return null;
+  }
 
-  // 2. Basename match — last path segment equals target
+  // 3. Basename match — last path segment equals target.
   // e.g., target "README" matches path "Projects/Parachute/README"
   const basename = db.prepare(`
     SELECT id FROM notes
@@ -150,17 +188,39 @@ export interface WikilinkResolution {
 
 /**
  * Resolve a wikilink target with full detail — single match, ambiguous, or unresolved.
+ * Mirrors `resolveWikilink`'s resolution order, including the explicit-
+ * extension form `[[Foo.csv]]` introduced by vault#328.
  */
 export function resolveWikilinkDetailed(db: Database, target: string): WikilinkResolution {
-  // 1. Exact match (case-insensitive)
+  // 1. Explicit-extension form: `[[path.ext]]`.
+  const extMatch = target.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const pathPart = extMatch[1]!;
+    const extPart = extMatch[2]!.toLowerCase();
+    const explicit = db.prepare(
+      "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(pathPart, extPart) as { id: string; path: string } | undefined;
+    if (explicit) {
+      return { resolved: true, note_id: explicit.id, path: explicit.path, candidates: [] };
+    }
+  }
+
+  // 2. Exact path match (case-insensitive). Multiple matches → ambiguous.
   const exact = db.prepare(
-    "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE",
-  ).get(target) as { id: string; path: string } | undefined;
-  if (exact) {
-    return { resolved: true, note_id: exact.id, path: exact.path, candidates: [] };
+    "SELECT id, path, extension FROM notes WHERE path = ? COLLATE NOCASE",
+  ).all(target) as { id: string; path: string; extension: string }[];
+  if (exact.length === 1) {
+    return { resolved: true, note_id: exact[0]!.id, path: exact[0]!.path, candidates: [] };
+  }
+  if (exact.length > 1) {
+    return {
+      resolved: false,
+      ambiguous: true,
+      candidates: exact.map((r) => ({ note_id: r.id, path: r.path })),
+    };
   }
 
-  // 2. Basename match
+  // 3. Basename match
   const basename = db.prepare(`
     SELECT id, path FROM notes
     WHERE path IS NOT NULL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.4-rc.14",
+  "version": "0.4.5",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/published.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
 import { handleViewNote } from "./routes.ts";
+import { SqliteStore } from "../core/src/store.ts";
 
 // Redirect URL builder — mirrors the logic in server.ts
 function buildRedirectUrl(reqUrl: string, noteId: string, prefix = ""): string {
@@ -211,4 +213,19 @@ describe("handleViewNote", async () => {
     const resp = await handleViewNote(store, "n1", { publishedTag: "public" });
     expect(resp.status).toBe(404);
   });
+
+  it("returns 409 ambiguous_path when bare path resolves to multiple notes (vault#331 N1)", async () => {
+    // Real SqliteStore so the v18 composite (path, extension) uniqueness
+    // index lets two notes coexist at the same path with different
+    // extensions — the scenario AmbiguousPathError is built for.
+    const store = new SqliteStore(new Database(":memory:"));
+    await store.createNote("# md", { id: "vn-md", path: "Foo", tags: ["publish"] });
+    await store.createNote("a,b\n1,2", { id: "vn-csv", path: "Foo", extension: "csv", tags: ["publish"] });
+    const resp = await handleViewNote(store, "Foo", { authenticated: true });
+    expect(resp.status).toBe(409);
+    const body = await resp.json() as any;
+    expect(body.error_type).toBe("ambiguous_path");
+    expect(body.path).toBe("Foo");
+    expect(body.candidates).toHaveLength(2);
+  });
 });

package/src/routes.ts

@@ -13,7 +13,7 @@
 
 import type { Store, Note } from "../core/src/types.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE } from "../core/src/notes.ts";
+import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.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";
@@ -75,6 +75,25 @@ function parseQueryList(url: URL, key: string): string[] | undefined {
   return val ? val.split(",") : undefined;
 }
 
+/**
+ * Parse the extension query parameter (vault#328). Two accepted shapes:
+ *   - `?extension=csv` (single value → string)
+ *   - `?extension=csv&extension=yaml` OR `?extension=csv,yaml`
+ *     (repeated or comma-list → array)
+ * Returns undefined when absent so the queryNotes filter is skipped.
+ * Validation lives at the engine layer — bad strings result in zero
+ * matches rather than 400, mirroring how `path` works.
+ */
+function parseExtensionFilter(url: URL): string | string[] | undefined {
+  const all = url.searchParams.getAll("extension");
+  if (all.length === 0) return undefined;
+  // Flatten comma-lists inside each param.
+  const flat = all.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+  if (flat.length === 0) return undefined;
+  if (flat.length === 1) return flat[0]!;
+  return flat;
+}
+
 function parseInt10(val: string | null): number | undefined {
   if (!val) return undefined;
   const n = parseInt(val, 10);
@@ -373,11 +392,21 @@ function parseExpandParams(
 
 
 /**
- * Resolve a note by ID or path. Tries ID first, then case-insensitive path.
+ * Resolve a note by ID or path. Tries ID first, then case-insensitive
+ * path. A trailing `.<ext>` matching the extension pattern is parsed
+ * as `(path, extension)` to disambiguate notes sharing a path
+ * differing only by extension (vault#330 S1). When the path is
+ * ambiguous and no extension hint is supplied, `getNoteByPath` throws
+ * `AmbiguousPathError` — REST handlers catch it and return 409.
  */
 async function resolveNote(store: Store, idOrPath: string): Promise<Note | null> {
   const byId = await store.getNote(idOrPath);
   if (byId) return byId;
+  const extMatch = idOrPath.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const explicit = await store.getNoteByPath(extMatch[1]!, extMatch[2]!);
+    if (explicit) return explicit;
+  }
   return await store.getNoteByPath(idOrPath);
 }
 
@@ -398,12 +427,49 @@ class NotFoundError extends Error {
 // Notes — GET/POST/PATCH/DELETE /api/notes[/:idOrPath]
 // ---------------------------------------------------------------------------
 
+/**
+ * Convert a thrown `AmbiguousPathError` (vault#330 S1) into a structured
+ * 409 JSON response. Shared by every handler that calls `resolveNote`
+ * with a user-supplied path — handleNotes, handleFindPath,
+ * handleViewNote. Returns null when the error isn't an
+ * AmbiguousPathError so the caller can re-throw / fall through.
+ */
+function ambiguousPathResponse(e: any): Response | null {
+  if (!e || e.code !== "AMBIGUOUS_PATH") return null;
+  return json(
+    {
+      error_type: "ambiguous_path",
+      error: "ambiguous_path",
+      path: e.path,
+      candidates: e.candidates,
+      message: e.message,
+    },
+    409,
+  );
+}
+
 export async function handleNotes(
   req: Request,
   store: Store,
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
+  try {
+    return await handleNotesInner(req, store, subpath, vault, tagScope);
+  } catch (e: any) {
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
+    throw e;
+  }
+}
+
+async function handleNotesInner(
+  req: Request,
+  store: Store,
+  subpath: string,
+  vault?: string,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -508,6 +574,12 @@ export async function handleNotes(
           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).
@@ -660,12 +732,19 @@ export async function handleNotes(
       if (batched) db.exec("BEGIN");
       try {
         for (const item of items) {
+          // Validate extension before reaching the Store (vault#328).
+          // Thrown inside the BEGIN block — outer catch rolls the batch
+          // back, same shape as the path-conflict path.
+          const extension = item.extension !== undefined
+            ? validateExtension(item.extension)
+            : undefined;
           const note = await store.createNote(item.content ?? "", {
             id: item.id,
             path: item.path,
             tags: item.tags,
             metadata: item.metadata,
             created_at: item.createdAt ?? item.created_at,
+            ...(extension !== undefined ? { extension } : {}),
           });
 
           // Create explicit links
@@ -688,6 +767,12 @@ export async function handleNotes(
             409,
           );
         }
+        if (e && e.code === "INVALID_EXTENSION") {
+          return json(
+            { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
+            400,
+          );
+        }
         throw e;
       }
 
@@ -845,12 +930,17 @@ export async function handleNotes(
           }
           const idLooksLikePath = idOrPathStr.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPathStr);
           const explicitPath = typeof body.path === "string" ? body.path as string : undefined;
+          // Validate extension before reaching the Store (vault#328).
+          const createExt = body.extension !== undefined
+            ? validateExtension(body.extension)
+            : undefined;
           const createOpts: Parameters<Store["createNote"]>[1] = {
             ...(idLooksLikePath ? { path: explicitPath ?? idOrPathStr } : { id: idOrPathStr, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
             ...(tagsArr.length > 0 ? { tags: tagsArr } : {}),
             ...(body.metadata !== undefined ? { metadata: body.metadata as Record<string, unknown> } : {}),
             ...(body.created_at !== undefined ? { created_at: body.created_at as string } : {}),
             ...(body.createdAt !== undefined ? { created_at: body.createdAt as string } : {}),
+            ...(createExt !== undefined ? { extension: createExt } : {}),
           };
           const content = (body.content as string | undefined) ?? "";
           const created = await store.createNote(content, createOpts);
@@ -1019,6 +1109,11 @@ export async function handleNotes(
         if (body.prepend !== undefined) updates.prepend = body.prepend;
       }
       if (body.path !== undefined) updates.path = body.path;
+      if (body.extension !== undefined) {
+        // Validate up front (vault#328). Throws ExtensionValidationError
+        // which the outer catch converts to a 400.
+        updates.extension = validateExtension(body.extension);
+      }
       if (body.metadata !== undefined) {
         const existing = (note.metadata as Record<string, unknown>) ?? {};
         updates.metadata = { ...existing, ...body.metadata };
@@ -1108,6 +1203,12 @@ export async function handleNotes(
           409,
         );
       }
+      if (e && e.code === "INVALID_EXTENSION") {
+        return json(
+          { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
+          400,
+        );
+      }
       throw e;
     }
   }
@@ -1448,6 +1549,11 @@ export async function handleFindPath(
     return json(result);
   } catch (e: any) {
     if (e instanceof NotFoundError) return json({ error: e.message }, 404);
+    // vault#331 N1 — surface AmbiguousPathError from resolveNote as 409
+    // mirroring the handleNotes path. Without this, an ambiguous source/
+    // target path on /api/find-path bubbled to a server-level 500.
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
     throw e;
   }
 }
@@ -1640,7 +1746,19 @@ export async function handleViewNote(
   options: { authenticated?: boolean; publishedTag?: string } = {},
 ): Promise<Response> {
   const { authenticated = false, publishedTag = "publish" } = options;
-  const note = await resolveNote(store, idOrPath);
+  let note: Note | null;
+  try {
+    note = await resolveNote(store, idOrPath);
+  } catch (e: any) {
+    // vault#331 N1 — surface AmbiguousPathError as 409. The HTML view
+    // route doesn't otherwise return JSON, but the structured body is
+    // the right shape for the API contract; a human reader hitting
+    // this URL gets the JSON inline (rare — the bare path form is
+    // mostly an API consumer's mistake).
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
+    throw e;
+  }
   if (!note) {
     return new Response("Not Found", { status: 404, headers: { "Content-Type": "text/plain" } });
   }