@openparachute/vault 0.4.4-rc.12 → 0.4.5

package/core/src/core.test.ts

@@ -189,15 +189,31 @@ describe("notes", async () => {
   });
 
   // -------------------------------------------------------------------------
-  // Empty-note invariant at the Store boundary (#213)
+  // Empty content is a valid state (vault#323)
   // -------------------------------------------------------------------------
+  // Skeleton notes, drafts saved before content, organizing-only notes,
+  // capture-then-fill flows. The earlier #213 guard rejected `content +
+  // path both absent` — we no longer enforce it because real vaults
+  // legitimately carry such rows and the round-trip import has to accept
+  // them.
+
+  it("createNote accepts empty content with no path", async () => {
+    const n = await store.createNote("");
+    expect(n.content).toBe("");
+    expect(n.path).toBeUndefined();
+  });
 
-  it("createNote rejects content+path both absent → EmptyNoteError", async () => {
-    await expect(store.createNote("")).rejects.toMatchObject({ code: "EMPTY_NOTE" });
-    await expect(store.createNote("   ")).rejects.toMatchObject({ code: "EMPTY_NOTE" });
-    await expect(store.createNote("", { metadata: { x: 1 } })).rejects.toMatchObject({
-      code: "EMPTY_NOTE",
-    });
+  it("createNote accepts whitespace-only content with no path", async () => {
+    const n = await store.createNote("   ");
+    expect(n.content).toBe("   ");
+  });
+
+  it("createNote empty-content note is queryable + survives round-trip", async () => {
+    const created = await store.createNote("", { metadata: { kind: "skeleton" } });
+    const fetched = await store.getNote(created.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.content).toBe("");
+    expect(fetched!.metadata).toMatchObject({ kind: "skeleton" });
   });
 
   it("createNote accepts content-only (un-pathed jot)", async () => {
@@ -212,18 +228,24 @@ describe("notes", async () => {
     expect(n.path).toBe("wiki/placeholder");
   });
 
-  it("updateNote rejects clearing both content and path → EmptyNoteError", async () => {
+  it("updateNote allows clearing both content and path", async () => {
     const n = await store.createNote("body", { path: "p" });
-    await expect(
-      store.updateNote(n.id, { content: "", path: "", if_updated_at: n.createdAt }),
-    ).rejects.toMatchObject({ code: "EMPTY_NOTE", note_id: n.id });
+    const updated = await store.updateNote(n.id, {
+      content: "",
+      path: "",
+      if_updated_at: n.createdAt,
+    });
+    expect(updated.content).toBe("");
+    expect(updated.path).toBeUndefined();
   });
 
-  it("updateNote rejects clearing content when path is already null", async () => {
+  it("updateNote allows clearing content when path is already null", async () => {
     const n = await store.createNote("body");
-    await expect(
-      store.updateNote(n.id, { content: "", if_updated_at: n.createdAt }),
-    ).rejects.toMatchObject({ code: "EMPTY_NOTE" });
+    const updated = await store.updateNote(n.id, {
+      content: "",
+      if_updated_at: n.createdAt,
+    });
+    expect(updated.content).toBe("");
   });
 
   it("updateNote allows clearing content when path is set (or being set)", async () => {
@@ -300,6 +322,142 @@ describe("updated_at backfill on init", async () => {
   });
 });
 
+// ---- Extension (vault#328 Phase 1: DB + Store) ----
+//
+// Three pinned behaviors:
+//   1. Migrations and inserts default to "md" — every existing row keeps
+//      its meaning after the v17 → v18 ALTER TABLE.
+//   2. Explicit extension on createNote persists end-to-end.
+//   3. queryNotes filters by extension (single string + array shapes).
+
+describe("notes.extension (vault#328)", async () => {
+  it("defaults to 'md' when not specified on createNote", async () => {
+    const note = await store.createNote("hello world");
+    expect(note.extension).toBe("md");
+    const fetched = await store.getNote(note.id);
+    expect(fetched!.extension).toBe("md");
+  });
+
+  it("persists explicit extension on createNote", async () => {
+    const note = await store.createNote("month,income\n2026-01,12000", {
+      path: "Tabular/budget",
+      extension: "csv",
+    });
+    expect(note.extension).toBe("csv");
+    const fetched = await store.getNote(note.id);
+    expect(fetched!.extension).toBe("csv");
+  });
+
+  it("backfills 'md' on existing rows after v17 → v18 migration", () => {
+    // Build a v17-shape vault by hand: create the notes table WITHOUT the
+    // `extension` column, insert a row, then run initSchema and assert
+    // the migration backfills "md".
+    const raw = new Database(":memory:");
+    raw.exec(`
+      CREATE TABLE notes (
+        id TEXT PRIMARY KEY,
+        content TEXT DEFAULT '',
+        path TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT
+      )
+    `);
+    raw.prepare(
+      "INSERT INTO notes (id, content, created_at, updated_at) VALUES (?, ?, ?, ?)",
+    ).run("legacy", "old content", "2024-01-01T00:00:00.000Z", "2024-01-01T00:00:00.000Z");
+
+    initSchema(raw); // applies v18 ALTER TABLE
+
+    const row = raw.prepare("SELECT extension FROM notes WHERE id = ?").get("legacy") as {
+      extension: string;
+    };
+    expect(row.extension).toBe("md");
+  });
+
+  it("updateNote changes extension on existing note", async () => {
+    const note = await store.createNote("hello", { path: "Foo" });
+    expect(note.extension).toBe("md");
+    const updated = await store.updateNote(note.id, { extension: "mdx" });
+    expect(updated.extension).toBe("mdx");
+    const fetched = await store.getNote(note.id);
+    expect(fetched!.extension).toBe("mdx");
+  });
+
+  it("queryNotes filters by extension (single string)", async () => {
+    await store.createNote("md note A", { path: "a", extension: "md" });
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    await store.createNote("md note B", { path: "c" }); // default md
+    const csv = await store.queryNotes({ extension: "csv" });
+    expect(csv).toHaveLength(1);
+    expect(csv[0]!.path).toBe("b");
+    const md = await store.queryNotes({ extension: "md" });
+    expect(md).toHaveLength(2);
+    expect(md.map((n) => n.path).sort()).toEqual(["a", "c"]);
+  });
+
+  it("queryNotes filters by extension (array — IN clause)", async () => {
+    await store.createNote("md note", { path: "a" });
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    await store.createNote("yaml note", { path: "c", extension: "yaml" });
+    await store.createNote("json note", { path: "d", extension: "json" });
+    const results = await store.queryNotes({ extension: ["csv", "yaml", "json"] });
+    expect(results).toHaveLength(3);
+    const paths = results.map((n) => n.path).sort();
+    expect(paths).toEqual(["b", "c", "d"]);
+  });
+
+  it("queryNotes extension filter is case-insensitive", async () => {
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    // Caller-supplied case shouldn't matter — stored as "csv", looked up as "CSV".
+    const results = await store.queryNotes({ extension: "CSV" });
+    expect(results).toHaveLength(1);
+  });
+
+  it("updateNote extension-only collision throws PathConflictError (vault#329 F1)", async () => {
+    // Two notes share `Foo` differing only by extension — legal under
+    // v18's composite (path, extension) uniqueness. Flip the md note's
+    // extension to "csv": that would collide with the existing csv
+    // row. The catch in updateNote must surface PATH_CONFLICT (not a
+    // raw SQLiteError) since the composite index fires UNIQUE on
+    // extension-only updates just like it does on path-only updates.
+    const md = await store.createNote("# md note", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    expect(
+      store.updateNote(md.id, { extension: "csv" }),
+    ).rejects.toMatchObject({ code: "PATH_CONFLICT", path: "Foo" });
+  });
+
+  it("getNoteByPath throws AmbiguousPathError when path matches multiple extensions (vault#330 S1)", async () => {
+    await store.createNote("# md", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    expect(store.getNoteByPath("Foo")).rejects.toMatchObject({
+      code: "AMBIGUOUS_PATH",
+      path: "Foo",
+    });
+  });
+
+  it("getNoteByPath returns the right note when extension is passed (vault#330 S1)", async () => {
+    await store.createNote("# md", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    const md = await store.getNoteByPath("Foo", "md");
+    const csv = await store.getNoteByPath("Foo", "csv");
+    expect(md!.id).toBe("foo-md");
+    expect(csv!.id).toBe("foo-csv");
+  });
+
+  it("getNoteByPath returns single match unchanged when no ambiguity (vault#330 S1 back-compat)", async () => {
+    await store.createNote("# only", { path: "Foo", id: "only" });
+    const note = await store.getNoteByPath("Foo");
+    expect(note!.id).toBe("only");
+  });
+
+  it("getNoteByPath returns null for unknown path (vault#330 S1 back-compat)", async () => {
+    const note = await store.getNoteByPath("DoesNotExist");
+    expect(note).toBeNull();
+  });
+});
+
 // ---- Tags ----
 
 describe("tags", async () => {
@@ -1567,6 +1725,91 @@ describe("MCP tools", async () => {
     expect(result[1].tags).toContain("doc");
   });
 
+  it("create-note accepts extension field (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = await createNote.execute({
+      content: "month,income\n2026-01,12000",
+      path: "Tabular/budget",
+      extension: "csv",
+    }) as any;
+    expect(result.extension).toBe("csv");
+  });
+
+  it("create-note defaults extension to 'md' when omitted (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = await createNote.execute({ content: "plain markdown" }) as any;
+    expect(result.extension).toBe("md");
+  });
+
+  it("create-note rejects invalid extension (uppercase, dot, reserved) (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    // Uppercase
+    expect(createNote.execute({ content: "x", extension: "CSV" })).rejects.toThrow(/invalid extension/);
+    // Dot
+    expect(createNote.execute({ content: "x", extension: "csv.bak" })).rejects.toThrow(/invalid extension/);
+    // Slash
+    expect(createNote.execute({ content: "x", extension: "foo/bar" })).rejects.toThrow(/invalid extension/);
+    // Reserved "parachute" prefix (lowercase — the pattern check passes,
+    // so the reserved-prefix guard is what fires).
+    expect(createNote.execute({ content: "x", extension: "parachute" })).rejects.toThrow(/reserved/);
+    expect(createNote.execute({ content: "x", extension: "parachutex" })).rejects.toThrow(/reserved/);
+    // Too long (>16)
+    expect(createNote.execute({ content: "x", extension: "a".repeat(17) })).rejects.toThrow(/invalid extension/);
+    // Empty
+    expect(createNote.execute({ content: "x", extension: "" })).rejects.toThrow(/non-empty/);
+  });
+
+  it("update-note changes extension (vault#328)", async () => {
+    const note = await store.createNote("hi", { path: "Foo" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({ id: note.id, extension: "mdx", force: true }) as any;
+    expect(result.extension).toBe("mdx");
+  });
+
+  it("update-note validates extension on update branch (vault#328)", async () => {
+    const note = await store.createNote("hi", { path: "Foo" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    expect(
+      updateNote.execute({ id: note.id, extension: "BAD", force: true }),
+    ).rejects.toThrow(/invalid extension/);
+  });
+
+  it("update-note if_missing=create honors extension (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "Tabular/new-budget",
+      content: "month,total\n2026-02,9000",
+      extension: "csv",
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.extension).toBe("csv");
+  });
+
+  it("query-notes filters by extension (vault#328)", async () => {
+    await store.createNote("md note", { path: "a" });
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    await store.createNote("yaml note", { path: "c", extension: "yaml" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+
+    // Single extension
+    const csv = await queryNotes.execute({ extension: "csv", include_content: true }) as any[];
+    expect(csv).toHaveLength(1);
+    expect(csv[0].path).toBe("b");
+
+    // Array shape
+    const both = await queryNotes.execute({ extension: ["csv", "yaml"], include_content: true }) as any[];
+    expect(both).toHaveLength(2);
+    expect(both.map((n) => n.path).sort()).toEqual(["b", "c"]);
+  });
+
   it("create-note with links resolves targets by path", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
@@ -2811,58 +3054,32 @@ describe("MCP tools", async () => {
     expect(r2.map((n) => n.content).sort()).toEqual(["a"]);
   });
 
-  // ---- empty-note + batch-cap MCP regressions (#213) ----
+  // ---- empty-note acceptance (vault#323) + batch-cap MCP ----
 
-  it("create-note rejects bare empty content with no path (EMPTY_NOTE)", async () => {
+  it("create-note accepts bare empty content with no path", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
-    let err: any;
-    try {
-      await createNote.execute({ content: "" });
-    } catch (e) {
-      err = e;
-    }
-    expect(err?.code).toBe("EMPTY_NOTE");
-  });
-
-  it("create-note batch rejects when any entry is empty content + no path (atomic, with item_index)", async () => {
-    const tools = generateMcpTools(store);
-    const createNote = tools.find((t) => t.name === "create-note")!;
-    const beforeCount = (await store.queryNotes({ search: "atomic-marker" })).length;
-    let err: any;
-    try {
-      await createNote.execute({
-        notes: [
-          { content: "atomic-marker first" },
-          { content: "" },
-        ],
-      });
-    } catch (e) {
-      err = e;
-    }
-    expect(err?.code).toBe("EMPTY_NOTE");
-    // The first item must NOT have been created — pre-validation rolls
-    // the whole batch back atomically. Partial-create would leak prefixes
-    // on every runaway-client burst (#213).
-    const afterCount = (await store.queryNotes({ search: "atomic-marker" })).length;
-    expect(afterCount).toBe(beforeCount);
-    // Parity with HTTP route: MCP callers with multi-item batches need to
-    // know which entry triggered the rejection. The bad entry is at index 1.
-    expect(err.item_index).toBe(1);
+    const result = await createNote.execute({ content: "" }) as any;
+    expect(result).toBeTruthy();
+    const note = Array.isArray(result) ? result[0] : result;
+    expect(note.content).toBe("");
+    const fetched = await store.getNote(note.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.content).toBe("");
   });
 
-  it("create-note single empty has null item_index (not a batch position)", async () => {
+  it("create-note batch with mixed empty + content entries succeeds end-to-end", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
-    let err: any;
-    try {
-      await createNote.execute({ content: "" });
-    } catch (e) {
-      err = e;
-    }
-    expect(err?.code).toBe("EMPTY_NOTE");
-    // Single-call (no `notes` array) — there's no batch position to report.
-    expect(err.item_index).toBeNull();
+    const result = await createNote.execute({
+      notes: [
+        { content: "first" },
+        { content: "" },
+        { content: "third" },
+      ],
+    }) as any[];
+    expect(result).toHaveLength(3);
+    expect(result.map((n) => n.content)).toEqual(["first", "", "third"]);
   });
 
   it("create-note batch over MAX_BATCH_SIZE rejects with BATCH_TOO_LARGE", async () => {
@@ -3910,6 +4127,77 @@ describe("update-note if_missing=create (vault#309)", async () => {
     const all = await store.queryNotes({ limit: 100 });
     expect(all.filter((n) => n.path === "Inbox/sync-target")).toHaveLength(1);
   });
+
+  // vault#321 F3 — schema-conflict warning surfaces on the create
+  // branch. The branch reuses `attachValidationStatus` so the
+  // conflict-detection logic should fire, but pre-fold it wasn't
+  // pinned. Two tags directly applied to the new note, each
+  // declaring the same field with conflicting specs → schema_conflict
+  // warning (the existing `resolveNoteSchemas` walk produces this for
+  // both inheritance chains AND multi-tag direct application).
+  it("schema-conflict warning surfaces on create branch (vault#321 F3)", async () => {
+    await store.upsertTagSchema("kpi", {
+      fields: { count: { type: "integer" } },
+    });
+    await store.upsertTagSchema("metric", {
+      fields: { count: { type: "string" } }, // conflicting spec
+    });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/conflicting-tags",
+      content: "x",
+      tags: ["kpi", "metric"],
+      metadata: { count: 5 },
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    const conflict = result.validation_status.warnings.find(
+      (w: any) => w.reason === "schema_conflict",
+    );
+    expect(conflict).toBeDefined();
+    expect(conflict.field).toBe("count");
+    // First-tag-wins precedence (kpi → integer). The loser_schema
+    // field names metric.
+    expect(conflict.schema).toBe("kpi");
+    expect(conflict.loser_schema).toBe("metric");
+  });
+
+  // vault#321 F4 — links.add on the create branch is applied. The
+  // implementation at mcp.ts:644-650 was present pre-fold; this
+  // test pins it so a future regression breaking Gitcoin's
+  // upsert-with-typed-links workflow goes red.
+  it("links.add applied on create branch (vault#321 F4)", async () => {
+    // Two pre-existing target notes the new source links to.
+    await store.createNote("A", { id: "t-mcp-a-321", path: "Targets/A-mcp" });
+    await store.createNote("B", { id: "t-mcp-b-321", path: "Targets/B-mcp" });
+
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/mcp-source-321",
+      content: "source body",
+      if_missing: "create",
+      links: {
+        add: [
+          { target: "t-mcp-a-321", relationship: "derived-from" },
+          { target: "Targets/B-mcp", relationship: "responds-to", metadata: { weight: 5 } },
+        ],
+      },
+    }) as any;
+    expect(result.created).toBe(true);
+
+    const sourceId = result.id as string;
+    const outboundLinks = await store.getLinks(sourceId, { direction: "outbound" });
+    const derivedFrom = outboundLinks.find((l) => l.relationship === "derived-from");
+    expect(derivedFrom).toBeDefined();
+    expect(derivedFrom!.targetId).toBe("t-mcp-a-321");
+
+    const respondsTo = outboundLinks.find((l) => l.relationship === "responds-to");
+    expect(respondsTo).toBeDefined();
+    expect(respondsTo!.targetId).toBe("t-mcp-b-321");
+    expect(respondsTo!.metadata).toEqual({ weight: 5 });
+  });
 });
 
 // ---------------------------------------------------------------------------

package/core/src/mcp.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
-import { filterMetadata, MAX_BATCH_SIZE } from "./notes.js";
+import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -26,14 +26,33 @@ export interface McpToolDef {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve a note identifier — tries ID first, then case-insensitive path match.
- * Works everywhere a note reference is accepted.
+ * Resolve a note identifier — tries ID first, then case-insensitive
+ * path match. Works everywhere a note reference is accepted.
+ *
+ * Path-with-extension form (vault#330 S1): a trailing `.<ext>` matching
+ * the extension pattern (`/^[a-z0-9]{1,16}$/i`) is parsed as
+ * `(path, extension)` to disambiguate notes that share a path
+ * differing only by extension. Mirrors the wikilink ambiguity policy
+ * from vault#328.
+ *
+ * On ambiguous path with no extension hint, `getNoteByPath` throws
+ * `AmbiguousPathError` — `resolveNote` propagates it so MCP / REST
+ * handlers can surface a clear 4xx rather than picking arbitrarily.
  */
 function resolveNote(db: Database, idOrPath: string): Note | null {
   // Try ID match first (fast, indexed)
   const byId = noteOps.getNote(db, idOrPath);
   if (byId) return byId;
-  // Fallback to path match
+  // Path-with-extension form: `Tabular/budget.csv` → (path="Tabular/
+  // budget", extension="csv"). Only kicks in when the suffix looks
+  // like an extension AND a `(path, ext)` row exists. Fall through to
+  // the no-extension lookup if not (so `Recipe.v2` where `v2` isn't a
+  // real extension still finds Recipe.v2 by exact-path).
+  const extMatch = idOrPath.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const explicit = noteOps.getNoteByPath(db, extMatch[1]!, extMatch[2]!);
+    if (explicit) return explicit;
+  }
   return noteOps.getNoteByPath(db, idOrPath);
 }
 
@@ -133,6 +152,13 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
           path_prefix: { type: "string", description: "Path prefix match (e.g., 'Projects/')" },
+          extension: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Filter by file extension (vault#328). Pass a single extension (e.g. \"csv\") or an array (e.g. [\"csv\", \"yaml\", \"json\"]). Notes default to \"md\"; case-insensitive match.",
+          },
           search: { type: "string", description: "Full-text search query" },
           metadata: {
             type: "object",
@@ -264,6 +290,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             hasLinks: params.has_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            extension: params.extension as string | string[] | undefined,
             // Push the near-scope into the SQL WHERE so that LIMIT and ORDER
             // BY apply to the neighborhood. Without this, queryNotes would
             // fetch the first `limit` notes by created_at and then post-
@@ -339,6 +366,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           // Single note fields
           content: { type: "string", description: "Note content (markdown). Wikilinks like [[Target]] auto-resolve." },
           path: { type: "string", description: "Note path (e.g., 'Projects/README')" },
+          extension: { type: "string", description: "File extension (vault#328). Default \"md\". Use \"csv\"/\"yaml\"/\"json\"/\"mdx\"/etc. for non-markdown notes. Lowercase alphanumeric, 1–16 chars; no '.' or '/'. The \"parachute\" prefix is reserved." },
           metadata: { type: "object", description: "Metadata fields" },
           tags: { type: "array", items: { type: "string" }, description: "Tags to apply" },
           links: {
@@ -362,6 +390,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               properties: {
                 content: { type: "string" },
                 path: { type: "string" },
+                extension: { type: "string", description: "File extension (vault#328). See top-level docs." },
                 metadata: { type: "object" },
                 tags: { type: "array", items: { type: "string" } },
                 links: { type: "array" },
@@ -381,43 +410,30 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           throw new BatchTooLargeError(items.length);
         }
 
-        // Empty-note pre-validation (#213): make mixed batches atomic for
-        // the empty-note case. The Store will throw EmptyNoteError on the
-        // empty entry, but in a sequential batch loop the prefix would have
-        // already committed before we hit it. Pre-walk so the whole call
-        // either creates everything or nothing. The error carries
-        // `item_index` so MCP callers with multi-item batches can pinpoint
-        // the bad entry — parity with the HTTP route's response shape.
-        // TODO: tighten batch input type — `items[i] as any` mirrors the
-        // top-of-call cast at `params.notes as any[]`. A typed McpCreateNoteInput
-        // would let us drop both casts.
-        for (let i = 0; i < items.length; i++) {
-          const item = items[i] as any;
-          const content = ((item?.content as string | undefined) ?? "").toString();
-          const rawPath = item?.path;
-          const pathEmpty = rawPath === undefined || rawPath === null
-            || (typeof rawPath === "string" && rawPath.trim() === "");
-          if (!content.trim() && pathEmpty) {
-            throw new noteOps.EmptyNoteError(null, batch ? i : null);
-          }
-        }
-
         const created: Note[] = [];
         // Wrap multi-item batches in a SQLite transaction so a mid-batch
-        // failure rolls back every prior insert — see #236. The pre-walk
-        // above catches empty-note cases; this guards anything thrown from
-        // store.createNote / createLink (path conflict, etc.). Single-item
-        // calls skip the wrap to avoid colliding with concurrent callers
-        // on the shared bun:sqlite connection.
+        // failure rolls back every prior insert — see #236. This guards
+        // anything thrown from store.createNote / createLink (path
+        // conflict, etc.). Single-item calls skip the wrap to avoid
+        // colliding with concurrent callers on the shared bun:sqlite
+        // connection.
         const batched = items.length > 1;
         if (batched) db.exec("BEGIN");
         try {
           for (const item of items) {
+            // Validate extension up front (vault#328). Throwing here while
+            // we're inside the BEGIN block on a batch rolls back the
+            // transaction in the outer catch — the same behavior as a
+            // path conflict mid-batch.
+            const extension = item.extension !== undefined
+              ? validateExtension(item.extension)
+              : undefined;
             const note = await store.createNote(item.content as string ?? "", {
               path: item.path as string | undefined,
               tags: item.tags as string[] | undefined,
               metadata: item.metadata as Record<string, unknown> | undefined,
               created_at: item.created_at as string | undefined,
+              ...(extension !== undefined ? { extension } : {}),
             });
 
             // Create explicit links (not wikilinks — those are automatic)
@@ -488,6 +504,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Find-and-replace one occurrence. Errors if `old_text` is not found or matches multiple locations. Mutually exclusive with `content` and `append`/`prepend`.",
           },
           path: { type: "string", description: "New path" },
+          extension: { type: "string", description: "Change the note's file extension (vault#328). Allowed but caller-owned — you're responsible for content validity if you switch a non-empty note's extension. Lowercase alphanumeric, 1–16 chars; \"parachute\" prefix reserved." },
           metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
           created_at: { type: "string", description: "New created_at timestamp" },
           if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
@@ -552,6 +569,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                   required: ["old_text", "new_text"],
                 },
                 path: { type: "string" },
+                extension: { type: "string", description: "Change the note's file extension (vault#328). See top-level docs." },
                 metadata: { type: "object" },
                 created_at: { type: "string" },
                 if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item or the item is `append`/`prepend`-only." },
@@ -638,6 +656,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               // caller's intent.
               const idLooksLikePath = idOrPath.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPath);
               const explicitPath = typeof item.path === "string" ? item.path as string : undefined;
+              // Validate extension before reaching the Store — same
+              // contract as the create-note tool.
+              const createExt = item.extension !== undefined
+                ? validateExtension(item.extension)
+                : undefined;
               const createOpts: Parameters<Store["createNote"]>[1] = {
                 ...(idLooksLikePath ? { path: explicitPath ?? idOrPath } : { id: idOrPath, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
                 ...(item.tags && Array.isArray((item.tags as any).add)
@@ -647,6 +670,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                     : {}),
                 ...(item.metadata !== undefined ? { metadata: item.metadata as Record<string, unknown> } : {}),
                 ...(item.created_at !== undefined ? { created_at: item.created_at as string } : {}),
+                ...(createExt !== undefined ? { extension: createExt } : {}),
               };
               const content = (item.content as string | undefined) ?? "";
               const created = await store.createNote(content, createOpts);
@@ -776,6 +800,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             if (item.prepend !== undefined) updates.prepend = item.prepend;
           }
           if (item.path !== undefined) updates.path = item.path;
+          if (item.extension !== undefined) {
+            updates.extension = validateExtension(item.extension);
+          }
           if (item.metadata !== undefined) {
             // Merge metadata (don't replace wholesale)
             const existing = (note.metadata as Record<string, unknown>) ?? {};
@@ -1254,8 +1281,10 @@ function normalizeTags(tag: unknown): string[] | undefined {
 }
 
 // Re-exported for backward compat; defined in notes.ts alongside the
-// conditional-UPDATE implementation that raises it.
-export { ConflictError, PathConflictError, EmptyNoteError, MAX_BATCH_SIZE } from "./notes.js";
+// conditional-UPDATE implementation that raises it. AmbiguousPathError
+// joins the set (vault#331 N2) so external callers can `instanceof`
+// it without crossing module boundaries.
+export { ConflictError, PathConflictError, AmbiguousPathError, MAX_BATCH_SIZE } from "./notes.js";
 
 /**
  * Thrown by the `update-note` MCP tool (and the REST PATCH handler) when a