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

package/core/src/core.test.ts

@@ -3796,6 +3796,122 @@ describe("schema validation (tags.fields)", async () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// update-note `if_missing: "create"` — idempotent upsert (vault#309)
+// ---------------------------------------------------------------------------
+
+describe("update-note if_missing=create (vault#309)", async () => {
+  let store: SqliteStore;
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("creates the note when missing + carries created: true", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/2026-05-13-meeting",
+      content: "agenda body",
+      tags: ["meeting"],
+      metadata: { priority: "high" },
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.path).toBe("Inbox/2026-05-13-meeting");
+    expect(result.content).toBe("agenda body");
+    expect(result.tags).toContain("meeting");
+    expect(result.metadata?.priority).toBe("high");
+
+    // And the row landed.
+    const fetched = await store.getNoteByPath("Inbox/2026-05-13-meeting");
+    expect(fetched).not.toBeNull();
+  });
+
+  it("updates the note when present + carries created: false", async () => {
+    await store.createNote("original", { path: "p", metadata: { v: 1 } });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "p",
+      content: "updated body",
+      metadata: { v: 2 },
+      if_missing: "create",
+      force: true, // bypass OC since this is an unconditional update
+    }) as any;
+    expect(result.created).toBe(false);
+    expect(result.content).toBe("updated body");
+    expect(result.metadata?.v).toBe(2);
+  });
+
+  it("without if_missing, missing note errors (current behavior — back-compat)", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    await expect(update.execute({
+      id: "nope",
+      content: "x",
+      force: true,
+    })).rejects.toThrow(/Note not found/);
+  });
+
+  it("create branch applies tag-schema defaults when the new tag declares fields", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/new-task",
+      content: "do the thing",
+      tags: ["task"],
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    // Schema defaults populated metadata.priority on insert.
+    expect(result.metadata?.priority).toBeDefined();
+  });
+
+  it("create branch surfaces validation warnings just like create-note", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const result = await update.execute({
+      id: "Inbox/bad-task",
+      content: "x",
+      tags: ["task"],
+      metadata: { priority: "ULTRA" },
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.validation_status?.warnings?.[0]?.reason).toBe("enum_mismatch");
+  });
+
+  it("idempotent: second call with same id + same content updates without error", async () => {
+    const tools = generateMcpTools(store);
+    const update = tools.find((t) => t.name === "update-note")!;
+    const first = await update.execute({
+      id: "Inbox/sync-target",
+      content: "v1",
+      if_missing: "create",
+    }) as any;
+    expect(first.created).toBe(true);
+
+    const second = await update.execute({
+      id: "Inbox/sync-target",
+      content: "v2",
+      if_missing: "create",
+      force: true,
+    }) as any;
+    expect(second.created).toBe(false);
+    expect(second.content).toBe("v2");
+
+    // Only one row exists.
+    const all = await store.queryNotes({ limit: 100 });
+    expect(all.filter((n) => n.path === "Inbox/sync-target")).toHaveLength(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Schema inheritance via parent_names + `_default` universal parent — vault#270
 // ---------------------------------------------------------------------------

package/core/src/mcp.ts

@@ -614,11 +614,21 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               //   - `item.content` / `item.path` / `item.tags` /
               //     `item.metadata` / `item.created_at` → forwarded.
               //   - `if_updated_at` / `force` / `content_edit` /
-              //     `append` / `prepend` / `links` are
-              //     update-only — silently ignored on the create branch.
-              //     (Content-edit on a non-existent note is a nonsense
-              //     combination; the caller's intent on missing-note is
-              //     "create the row", not "patch in this section".)
+              //     `append` / `prepend` are update-only — silently
+              //     ignored on the create branch. (Content-edit on a
+              //     non-existent note is a nonsense combination; the
+              //     caller's intent on missing-note is "create the
+              //     row", not "patch in this section".)
+              //   - `links.remove` is also ignored on create (nothing
+              //     to remove on a fresh note).
+              //   - `links.add` IS applied below — the drift sync can
+              //     declare typed links at upsert time and have them
+              //     materialize alongside the create. See vault#320
+              //     reviewer F1 — the prior comment claimed all
+              //     `links` were ignored, but `links.add` was already
+              //     processed and used by Gitcoin's sync; the
+              //     misleading wording is fixed here so a future
+              //     reader doesn't trust it and break the workflow.
               const idOrPath = item.id as string;
               // Heuristic: if `path` isn't set AND the `id` looks like a
               // path (contains "/" or doesn't match a typical opaque-id

package/package.json

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

package/src/routes.ts

@@ -854,15 +854,64 @@ export async function handleNotes(
   // PATCH /notes/:idOrPath — update (content, path, metadata, tags, links)
   if (method === "PATCH") {
     try {
+      // Body is parsed up front so the `if_missing: "create"` branch
+      // (vault#309) can fire when the note doesn't exist. Pre-#309
+      // shape parsed the body only after the not-found check.
+      const body = await req.json() as any;
       const note = await resolveNote(store, idOrPath);
-      if (!note) throw new NotFoundError(`Note not found: "${idOrPath}"`);
+      if (!note) {
+        // vault#309 — `if_missing: "create"` turns this PATCH into a
+        // create using the same payload. POST /notes is the canonical
+        // create surface, but supporting it inline on PATCH lets sync
+        // loops use one endpoint for both branches. Returns the
+        // created note with `created: true` and HTTP 200 (not 201 —
+        // the response shape is "the note as it now exists," same
+        // contract as the update path; `created: true` carries the
+        // signal).
+        if (body.if_missing === "create") {
+          const idOrPathStr = idOrPath;
+          // Tag-scope check on the create branch: the prospective
+          // tag set must still satisfy scope. Compute from body.tags
+          // (create-shape: an array, not the {add,remove} dict).
+          const tagsArr = Array.isArray(body.tags)
+            ? body.tags as string[]
+            : Array.isArray(body.tags?.add) ? body.tags.add as string[] : [];
+          if (tagScope.allowed && !tagsWithinScope(tagsArr, tagScope.allowed, tagScope.raw)) {
+            return tagScopeForbidden(tagScope.raw ?? []);
+          }
+          const idLooksLikePath = idOrPathStr.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPathStr);
+          const explicitPath = typeof body.path === "string" ? body.path as string : 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 } : {}),
+          };
+          const content = (body.content as string | undefined) ?? "";
+          const created = await store.createNote(content, createOpts);
+          if (tagsArr.length > 0) {
+            await applySchemaDefaults(store, db, [created.id], tagsArr);
+          }
+          const final = await store.getNote(created.id);
+          if (!final) return json({ error: "Note disappeared" }, 500);
+          const validated = attachValidationStatus(store, db, final);
+          const includeContentResp = body.include_content !== false;
+          if (includeContentResp) return json({ ...validated, created: true });
+          const lean: any = toNoteIndex(validated);
+          const vs = (validated as any).validation_status;
+          if (vs !== undefined) lean.validation_status = vs;
+          lean.created = true;
+          return json(lean);
+        }
+        throw new NotFoundError(`Note not found: "${idOrPath}"`);
+      }
       // Tag-scope: existing note must be in scope. Mirror the read-side
       // 404-not-403 stance — a token can't see (and therefore can't
       // discover-then-modify) notes outside its allowlist.
       if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
         throw new NotFoundError(`Note not found: "${idOrPath}"`);
       }
-      const body = await req.json() as any;
       // Tag-scope: post-update tag set must still satisfy scope. Compute
       // the prospective tag set (existing − removed + added) and reject
       // before any write if it would drift outside the allowlist. This
@@ -1035,10 +1084,15 @@ export async function handleNotes(
       if (updatedNote === null) return json({ error: "Note disappeared" }, 404);
       const validated = attachValidationStatus(store, db, updatedNote);
       const includeContentResp = body.include_content !== false;
-      if (includeContentResp) return json(validated);
+      // `created: false` is appended to every update-path response so
+      // sync-loop callers using `if_missing: "create"` can distinguish
+      // the two branches without a separate query (vault#309). The
+      // create-branch response above carries `created: true`.
+      if (includeContentResp) return json({ ...validated, created: false });
       const lean: any = toNoteIndex(validated);
       const vs = (validated as any).validation_status;
       if (vs !== undefined) lean.validation_status = vs;
+      lean.created = false;
       return json(lean);
     } catch (e: any) {
       if (e instanceof NotFoundError) return json({ error: e.message }, 404);

package/src/vault.test.ts

@@ -2926,6 +2926,80 @@ describe("HTTP POST /notes — validation_status attachment (vault#287)", async
   });
 });
 
+// vault#309 — HTTP PATCH /notes/:id with if_missing: "create" mirrors
+// the MCP update-note path. Sync loops (Gitcoin Brain et al) use this
+// for idempotent upsert without a separate query-first round trip.
+
+describe("HTTP PATCH /notes/:idOrPath if_missing=create (vault#309)", async () => {
+  test("missing note + if_missing=create creates and returns created: true", async () => {
+    const res = await handleNotes(
+      mkReq("PATCH", `/notes/${encodeURIComponent("Inbox/m309a")}`, {
+        content: "agenda body",
+        tags: ["meeting309"],
+        metadata: { priority: "high" },
+        if_missing: "create",
+      }),
+      store,
+      `/${encodeURIComponent("Inbox/m309a")}`,
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(true);
+    expect(body.path).toBe("Inbox/m309a");
+    expect(body.content).toBe("agenda body");
+    expect(body.tags).toContain("meeting309");
+    expect(body.metadata.priority).toBe("high");
+    // And the row landed.
+    expect(await store.getNoteByPath("Inbox/m309a")).not.toBeNull();
+  });
+
+  test("existing note + if_missing=create updates and returns created: false", async () => {
+    await store.createNote("original", { path: "m309b", metadata: { v: 1 } });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/m309b", {
+        content: "updated body",
+        metadata: { v: 2 },
+        if_missing: "create",
+        force: true,
+      }),
+      store,
+      "/m309b",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(false);
+    expect(body.content).toBe("updated body");
+    expect(body.metadata.v).toBe(2);
+  });
+
+  test("missing note without if_missing returns 404 (back-compat)", async () => {
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/m309c-nope", {
+        content: "x",
+        force: true,
+      }),
+      store,
+      "/m309c-nope",
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("regular update path now also carries created: false (response shape extended)", async () => {
+    await store.createNote("body", { path: "m309d" });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/m309d", {
+        content: "new body",
+        force: true,
+      }),
+      store,
+      "/m309d",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(false);
+  });
+});
+
 describe("HTTP /tags", async () => {
   test("GET /tags lists all tags", async () => {
     await store.createNote("A", { tags: ["daily"] });