@openparachute/vault 0.4.4-rc.12 → 0.4.4-rc.14

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 () => {
@@ -2811,58 +2833,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 +3906,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

@@ -381,34 +381,13 @@ 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 {
@@ -1255,7 +1234,7 @@ 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";
+export { ConflictError, PathConflictError, MAX_BATCH_SIZE } from "./notes.js";
 
 /**
  * Thrown by the `update-note` MCP tool (and the REST PATCH handler) when a

package/core/src/notes.ts

@@ -36,15 +36,11 @@ export function createNote(
   const metadata = opts?.metadata ? JSON.stringify(opts.metadata) : "{}";
   const path = normalizePath(opts?.path);
 
-  // Empty-note invariant (#213): reject `content+path both absent`. Three
-  // legit shapes — content-only, path-only, both — only the empty+empty
-  // combo is the runaway-client signature that flooded a deployment with
-  // 7,453 pathless empty notes in one MCP burst. `content` only is a
-  // legitimate un-pathed jot; `path` only is a wikilink placeholder or
-  // `_schemas/*` config note.
-  if (!content.trim() && path === null) {
-    throw new EmptyNoteError();
-  }
+  // 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.
 
   // `updated_at` is set to `created_at` on insert so a client whose optimistic
   // concurrency check falls back to `createdAt` on a never-updated note
@@ -156,39 +152,6 @@ export class PathConflictError extends Error {
  */
 export const MAX_BATCH_SIZE = 500;
 
-/**
- * Thrown by `createNote` / `updateNote` when the proposed note state has
- * neither content nor path. The vault accepts un-pathed jots (content only)
- * and path-only placeholders (wikilink stubs, `_schemas/*`), but a note
- * with neither is the runaway-client signature flagged in #213 — one MCP
- * burst flooded a deployment with 7,453 empty pathless rows. Surfaces as
- * 400 at the HTTP layer.
- */
-export class EmptyNoteError extends Error {
-  code = "EMPTY_NOTE" as const;
-  note_id: string | null;
-  /**
-   * Zero-based position in a batch call when the empty entry is rejected via
-   * the transport-layer pre-validation pass (HTTP `POST /api/notes` or MCP
-   * `create-note` with `notes: [...]`). `null` for single-update rejections
-   * and for Store-level throws that don't know their batch context.
-   */
-  item_index: number | null;
-
-  constructor(noteId: string | null = null, itemIndex: number | null = null) {
-    super(
-      noteId
-        ? `empty_note: update would leave note "${noteId}" with neither content nor path`
-        : itemIndex !== null
-          ? `empty_note: a note must have either content or a path (item index ${itemIndex})`
-          : `empty_note: a note must have either content or a path`,
-    );
-    this.name = "EmptyNoteError";
-    this.note_id = noteId;
-    this.item_index = itemIndex;
-  }
-}
-
 /**
  * Match bun:sqlite's UNIQUE-constraint error on the notes.path index. The
  * error class is `SQLiteError` but matching on the message is sufficient
@@ -236,36 +199,9 @@ export function updateNote(
     );
   }
 
-  // Empty-note invariant (#213): when this update touches content or path,
-  // reject if the post-state would be empty content + null path. We only
-  // enforce on transitions that actually touch the relevant fields, so
-  // metadata-only or tag-only updates against legacy empty rows still pass.
-  // Hook-style writes (skipUpdatedAt) are exempted — they're machine-level
-  // marker writes that legitimately may run against any shape of row.
-  const touchesContent = updates.content !== undefined
-    || updates.append !== undefined
-    || updates.prepend !== undefined;
-  const touchesPath = updates.path !== undefined;
-  if ((touchesContent || touchesPath) && !updates.skipUpdatedAt) {
-    const current = getNote(db, id);
-    if (current) {
-      let finalContent: string;
-      if (updates.content !== undefined) {
-        finalContent = updates.content;
-      } else if (touchesContent) {
-        finalContent = (updates.prepend ?? "") + current.content + (updates.append ?? "");
-      } else {
-        finalContent = current.content;
-      }
-      const finalPath = touchesPath ? normalizePath(updates.path) : (current.path ?? null);
-      if (!finalContent.trim() && !finalPath) {
-        throw new EmptyNoteError(id);
-      }
-    }
-    // If `current` is null we fall through — existing code paths handle the
-    // missing-row case downstream (the conditional UPDATE returns 0 rows;
-    // OC throws ConflictError; non-OC returns silently).
-  }
+  // Empty content is a valid state (vault#323) — see createNote. The
+  // matching guard that used to reject updates clearing both content
+  // and path has been removed.
 
   const sets: string[] = [];
   const values: (string | null)[] = [];

package/core/src/portable-md.test.ts

@@ -777,6 +777,10 @@ describe("portable-md round-trip — byte-equivalent re-export after blow-away i
     //   - Typed links (non-wikilink).
     //   - Multi-line metadata (vault#317 F1 path).
     //   - One note edited (created_at ≠ updated_at).
+    //   - Empty-content note (vault#323) — skeleton/draft shape that real
+    //     vaults legitimately carry. Pins the round-trip regression that
+    //     blocked stable promotion when the EMPTY_NOTE guard was still
+    //     rejecting these on import.
     await store.upsertTagSchema("project", {
       description: "A long-running effort",
       fields: { status: { type: "string", enum: ["active", "done"] } },
@@ -797,6 +801,14 @@ describe("portable-md round-trip — byte-equivalent re-export after blow-away i
       tags: ["project"],
     });
     await store.createNote("unpathed jot", { id: "01HX003" });
+    // Empty-content note with a path — the skeleton/organizing-only
+    // shape from vault#323. Export emits it as frontmatter + empty body;
+    // import must accept it.
+    await store.createNote("", {
+      id: "01HX004",
+      path: "Inbox/skeleton",
+      tags: ["project"],
+    });
     await store.createLink("01HX001", "01HX002", "derived-from", { source: "git://example" });
 
     // Force a divergence between created_at and updated_at on n1 so
@@ -815,10 +827,20 @@ describe("portable-md round-trip — byte-equivalent re-export after blow-away i
     // Blow-away import into a fresh store.
     const restored = new SqliteStore(new Database(":memory:"));
     const importStats = await importPortableVault(restored, { inDir: outA, blowAway: true });
-    expect(importStats.notes_created).toBe(3);
+    expect(importStats.notes_created).toBe(4);
     expect(importStats.schemas_restored).toBe(1);
     expect(importStats.links_restored).toBe(1);
 
+    // Empty-content note survives the round-trip — content is empty,
+    // path + tags persist. This is the load-bearing assertion for
+    // vault#323: prior to the EMPTY_NOTE drop, importPortableVault
+    // threw on the createNote("") call here.
+    const skeleton = await restored.getNote("01HX004");
+    expect(skeleton).not.toBeNull();
+    expect(skeleton!.content).toBe("");
+    expect(skeleton!.path).toBe("Inbox/skeleton");
+    expect(skeleton!.tags).toContain("project");
+
     // Second export from the restored store.
     const outB = join(tmpBase, "outB");
     await exportVaultToDir(restored, {

package/package.json

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

package/src/cli.ts

@@ -2558,6 +2558,23 @@ async function cmdImport(args: string[]) {
     process.exit(1);
   }
 
+  // Daemon-busy guard (vault#323): the import opens its own bun:sqlite
+  // connection, but a running daemon already holds the writer lock. The
+  // first createNote then trips SQLITE_BUSY mid-stream and leaves a
+  // partially-replayed vault. Refuse with a clear error rather than
+  // attempt-and-fail. WAL/concurrent-writer is a separate follow-up.
+  const globalConfig = readGlobalConfig();
+  const port = globalConfig.port || DEFAULT_PORT;
+  const health = await checkHealth(port);
+  if (health.status === "healthy" || health.status === "unhealthy") {
+    console.error(
+      `error: vault daemon is running on port ${port}; stop it first with:\n` +
+        `  parachute stop vault\n` +
+        `the import requires exclusive write access to the SQLite database.`,
+    );
+    process.exit(1);
+  }
+
   // Autodetect: portable-md export → `.parachute/vault.yaml` present.
   const isPortableMd = existsSync(join(fullPath, ".parachute", "vault.yaml"));
 

package/src/import-daemon-busy.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Integration test for vault#323: `parachute-vault import` refuses to run
+ * when a daemon is bound to the configured port. The import opens its
+ * own bun:sqlite connection; concurrent writers would otherwise trip
+ * SQLITE_BUSY mid-replay and leave a partially-imported vault.
+ *
+ * Pre-flights checkHealth(port) before any DB write; "healthy" or
+ * "unhealthy" (port bound, any HTTP response) means the daemon owns the
+ * writer lock, so we exit 1 with a clear error pointing at
+ * `parachute stop vault`.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { resolve } from "path";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const CLI = resolve(import.meta.dir, "cli.ts");
+
+async function runCli(
+  args: string[],
+  env: Record<string, string>,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  // Async spawn — the daemon-busy probe inside the CLI fetches the test
+  // process's stub server, so the parent event loop must keep servicing
+  // requests while the child runs. Bun.spawnSync blocks the event loop
+  // and the in-test server can't answer, which makes every probe time
+  // out into the "not listening" branch.
+  const proc = Bun.spawn({
+    cmd: ["bun", CLI, ...args],
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, ...env },
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { exitCode: exitCode ?? -1, stdout, stderr };
+}
+
+let home: string;
+let srcDir: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "import-daemon-busy-"));
+  srcDir = mkdtempSync(join(tmpdir(), "import-daemon-busy-src-"));
+  // Minimal portable-md export shape so autodetect picks the portable path.
+  mkdirSync(join(srcDir, ".parachute"), { recursive: true });
+  writeFileSync(
+    join(srcDir, ".parachute", "vault.yaml"),
+    "name: default\nexport_format_version: 1\n",
+  );
+  // Minimal vault tree so the "vault not found" guard doesn't short-circuit.
+  // PARACHUTE_HOME → <root>/vault/{config.yaml, data/<name>/vault.yaml}.
+  mkdirSync(join(home, "vault", "data", "default"), { recursive: true });
+  writeFileSync(
+    join(home, "vault", "data", "default", "vault.yaml"),
+    "name: default\n",
+  );
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+  rmSync(srcDir, { recursive: true, force: true });
+});
+
+describe("import daemon-busy guard (vault#323)", () => {
+  test("refuses with clear error + exit 1 when a server is bound to the configured port", async () => {
+    // Stand up a stub server that responds on /health so checkHealth
+    // returns either `healthy` or `unhealthy` — both signal that the
+    // port is owned by something. Either case triggers the guard.
+    // Bind to 127.0.0.1 explicitly so the subprocess's checkHealth
+    // (which probes 127.0.0.1:<port>) hits the same interface.
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response(JSON.stringify({ status: "ok" })),
+    });
+    try {
+      mkdirSync(join(home, "vault"), { recursive: true });
+      writeFileSync(join(home, "vault", "config.yaml"), `port: ${server.port}\n`);
+      const res = await runCli(
+        ["import", srcDir, "--vault", "default", "--yes"],
+        { PARACHUTE_HOME: home },
+      );
+      expect(res.exitCode).toBe(1);
+      expect(res.stderr).toMatch(/vault daemon is running on port/);
+      expect(res.stderr).toMatch(/parachute stop vault/);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("proceeds past the guard when nothing is listening on the configured port", async () => {
+    // Pick a port nothing's bound to. The daemon-busy message must NOT
+    // surface — that's the regression we're pinning.
+    const freePort = 1; // privileged, nothing should be listening here from this process
+    mkdirSync(join(home, "vault"), { recursive: true });
+    writeFileSync(join(home, "vault", "config.yaml"), `port: ${freePort}\n`);
+    const res = await runCli(
+      ["import", srcDir, "--vault", "default", "--yes"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(res.stderr).not.toMatch(/vault daemon is running on port/);
+  });
+});

package/src/routes.ts

@@ -636,35 +636,10 @@ export async function handleNotes(
         );
       }
 
-      // 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.
+      // least one tag inside the token's allowlist. 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)) {
@@ -713,17 +688,6 @@ export async function handleNotes(
             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;
       }
 
@@ -893,6 +857,26 @@ export async function handleNotes(
           if (tagsArr.length > 0) {
             await applySchemaDefaults(store, db, [created.id], tagsArr);
           }
+          // vault#321 F2 — apply `links.add` on the create branch.
+          // MCP's create-on-missing branch already did this
+          // (`core/src/mcp.ts` if_missing=create block); the REST side
+          // was missing it, producing a cross-surface inconsistency
+          // operators (Gitcoin's drift sync) would trip on. Mirror the
+          // MCP recipe exactly:
+          //   - `links.add` IS applied — drift sync can declare typed
+          //     links at upsert time and have them materialize.
+          //   - `links.remove` is ignored (nothing to remove on a
+          //     fresh note).
+          //   - Missing target notes skip silently (mirrors MCP).
+          const linksAdd = (body.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
+          if (linksAdd) {
+            for (const link of linksAdd) {
+              const target = await resolveNote(store, link.target);
+              if (target) {
+                await store.createLink(created.id, target.id, link.relationship, link.metadata);
+              }
+            }
+          }
           const final = await store.getNote(created.id);
           if (!final) return json({ error: "Note disappeared" }, 500);
           const validated = attachValidationStatus(store, db, final);
@@ -1124,20 +1108,6 @@ export async function handleNotes(
           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;
     }
   }

package/src/vault.test.ts

@@ -1883,36 +1883,30 @@ describe("HTTP /notes", async () => {
   });
 
   // -------------------------------------------------------------------------
-  // Empty-note guard + batch cap (#213) — runaway-client protection
+  // Empty content is a valid state (vault#323)
   // -------------------------------------------------------------------------
-
-  describe("empty-note guard (#213)", async () => {
-    test("POST bare {} body → 400 EmptyNoteError", async () => {
+  // Skeleton notes, drafts, organizing-only notes, and capture-then-fill
+  // flows all legitimately produce empty-content rows. The earlier #213
+  // guard rejected `content + path both absent` — we no longer enforce
+  // it because real vaults carry such rows and the round-trip import
+  // has to accept them.
+
+  describe("empty content is valid (vault#323)", async () => {
+    test("POST bare {} body → 201", async () => {
       const res = await handleNotes(mkReq("POST", "/notes", {}), store, "");
-      expect(res.status).toBe(400);
-      const body = await res.json() as any;
-      expect(body.error_type).toBe("empty_note");
-      expect(body.error).toBe("EmptyNoteError");
+      expect(res.status).toBe(201);
     });
 
-    test("POST batch with one empty entry → 400 EmptyNoteError, NOTHING created (atomic)", async () => {
-      // Pre-validate the batch before any DB writes so a mixed batch with one
-      // bad entry rolls back the whole call. The runaway-client signature
-      // (#213) is "thousands of empties" — partial-create semantics would
-      // still leak the prefix on every burst. Atomic is the only safe shape.
+    test("POST batch with mixed empty + content entries → 201, all created", async () => {
       const beforeCount = (await store.queryNotes({ path: "ok-1" })).length;
       const res = await handleNotes(
-        mkReq("POST", "/notes", { notes: [{ path: "ok-1" }, {}] }),
+        mkReq("POST", "/notes", { notes: [{ path: "ok-1" }, {}, { content: "third" }] }),
         store,
         "",
       );
-      expect(res.status).toBe(400);
-      const body = await res.json() as any;
-      expect(body.error_type).toBe("empty_note");
-      expect(body.item_index).toBe(1);
-      // ok-1 must NOT have been created — atomic rollback.
+      expect(res.status).toBe(201);
       const afterCount = (await store.queryNotes({ path: "ok-1" })).length;
-      expect(afterCount).toBe(beforeCount);
+      expect(afterCount).toBe(beforeCount + 1);
     });
 
     test("POST single content-only (path absent) → 201", async () => {
@@ -1924,9 +1918,7 @@ describe("HTTP /notes", async () => {
       expect(res.status).toBe(201);
     });
 
-    test("POST single path-only (content absent) → 201, no warning log", async () => {
-      // Path-only is a wikilink placeholder / `_schemas/*` shape — must
-      // remain accepted (per #223 design Q3).
+    test("POST single path-only (content absent) → 201", async () => {
       const res = await handleNotes(
         mkReq("POST", "/notes", { path: "wiki/placeholder" }),
         store,
@@ -1935,8 +1927,8 @@ describe("HTTP /notes", async () => {
       expect(res.status).toBe(201);
     });
 
-    test("PATCH that would clear both content and path → 400 EmptyNoteError", async () => {
-      const note = await store.createNote("starts with content", { id: "ep1" });
+    test("PATCH that clears both content and path → 200", async () => {
+      await store.createNote("starts with content", { id: "ep1" });
       const updated = await store.getNote("ep1");
       const res = await handleNotes(
         mkReq("PATCH", "/notes/ep1", {
@@ -1947,14 +1939,11 @@ describe("HTTP /notes", async () => {
         store,
         "/ep1",
       );
-      expect(res.status).toBe(400);
-      const body = await res.json() as any;
-      expect(body.error_type).toBe("empty_note");
-      expect(body.note_id).toBe("ep1");
+      expect(res.status).toBe(200);
     });
 
     test("PATCH that clears content but preserves path → 200", async () => {
-      const note = await store.createNote("body", { id: "ep2", path: "p2" });
+      await store.createNote("body", { id: "ep2", path: "p2" });
       const updated = await store.getNote("ep2");
       const res = await handleNotes(
         mkReq("PATCH", "/notes/ep2", {
@@ -1970,8 +1959,7 @@ describe("HTTP /notes", async () => {
 
   describe("batch atomicity (#236)", async () => {
     test("POST batch where mid-item triggers PATH_CONFLICT → 409, NOTHING created", async () => {
-      // The empty-note pre-walk catches `{}` before any DB write (#213); a
-      // path-conflict only surfaces on the actual INSERT, mid-loop. Without
+      // A path-conflict only surfaces on the actual INSERT, mid-loop. Without
       // the BEGIN/COMMIT wrap the prefix would have already landed by then.
       await store.createNote("existing", { path: "taken" });
       const beforeIds = (await store.queryNotes({})).map((n) => n.id).sort();
@@ -2998,6 +2986,105 @@ describe("HTTP PATCH /notes/:idOrPath if_missing=create (vault#309)", async () =
     const body = await res.json() as any;
     expect(body.created).toBe(false);
   });
+
+  // vault#321 F2 — REST create-on-missing branch applies links.add.
+  // MCP's create branch already did; REST was missing the
+  // link-creation pass entirely. Cross-surface inconsistency Gitcoin
+  // would trip on if they migrated from MCP to REST. The new pass
+  // mirrors MCP exactly (links.add applied, links.remove ignored,
+  // missing targets skip silently).
+  test("if_missing=create + links.add creates typed-link rows (vault#321 F2)", async () => {
+    // Two pre-existing target notes (different ids + paths) so the
+    // source can fan out to both.
+    await store.createNote("target A", { id: "t-a-321", path: "Targets/A" });
+    await store.createNote("target B", { id: "t-b-321", path: "Targets/B" });
+
+    const res = await handleNotes(
+      mkReq("PATCH", `/notes/${encodeURIComponent("Inbox/source-321")}`, {
+        content: "source body",
+        if_missing: "create",
+        links: {
+          add: [
+            { target: "t-a-321", relationship: "derived-from" },
+            { target: "Targets/B", relationship: "responds-to", metadata: { weight: 5 } },
+          ],
+        },
+      }),
+      store,
+      `/${encodeURIComponent("Inbox/source-321")}`,
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(true);
+
+    // Link rows exist + resolved targets correctly. We look up by the
+    // source's note id (the body returned by the create branch).
+    const sourceId = body.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-a-321");
+
+    const respondsTo = outboundLinks.find((l) => l.relationship === "responds-to");
+    expect(respondsTo).toBeDefined();
+    expect(respondsTo!.targetId).toBe("t-b-321");
+    expect(respondsTo!.metadata).toEqual({ weight: 5 });
+  });
+
+  test("if_missing=create + links.add silently skips when target does not exist (vault#321 F2)", async () => {
+    // Mirrors MCP: missing target → silent skip, no error. Sync loops
+    // that declare links to not-yet-imported notes shouldn't abort
+    // the whole upsert.
+    const res = await handleNotes(
+      mkReq("PATCH", `/notes/${encodeURIComponent("Inbox/source-missing-321")}`, {
+        content: "x",
+        if_missing: "create",
+        links: { add: [{ target: "does-not-exist", relationship: "derived-from" }] },
+      }),
+      store,
+      `/${encodeURIComponent("Inbox/source-missing-321")}`,
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(true);
+    // The note is created. No links resolved.
+    const links = await store.getLinks(body.id, { direction: "outbound" });
+    expect(links.filter((l) => l.relationship === "derived-from")).toHaveLength(0);
+  });
+
+  // vault#321 F3 — schema-conflict warning on REST create branch
+  // (mirror of the MCP test in core.test.ts). Same conflict-detection
+  // path runs on both surfaces via attachValidationStatus, but we pin
+  // both ends explicitly so a regression on either side surfaces
+  // immediately.
+  test("schema-conflict warning surfaces on REST create branch (vault#321 F3)", async () => {
+    await store.upsertTagSchema("kpi-rest-321", {
+      fields: { count: { type: "integer" } },
+    });
+    await store.upsertTagSchema("metric-rest-321", {
+      fields: { count: { type: "string" } }, // conflicting
+    });
+    const res = await handleNotes(
+      mkReq("PATCH", `/notes/${encodeURIComponent("Inbox/conflict-321")}`, {
+        content: "x",
+        if_missing: "create",
+        tags: ["kpi-rest-321", "metric-rest-321"],
+        metadata: { count: 5 },
+      }),
+      store,
+      `/${encodeURIComponent("Inbox/conflict-321")}`,
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(true);
+    const conflict = body.validation_status.warnings.find(
+      (w: any) => w.reason === "schema_conflict",
+    );
+    expect(conflict).toBeDefined();
+    expect(conflict.field).toBe("count");
+    expect(conflict.schema).toBe("kpi-rest-321");
+    expect(conflict.loser_schema).toBe("metric-rest-321");
+  });
 });
 
 describe("HTTP /tags", async () => {