@openparachute/vault 0.6.5-rc.9 → 0.7.0-rc.1

package/.parachute/module.json

@@ -12,6 +12,7 @@
   "focus": "core",
   "adminCapabilities": ["config", "credentials"],
   "startCmd": ["parachute-vault", "serve"],
+  "websocket": true,
   "scopes": {
     "defines": ["vault:read", "vault:write", "vault:admin"]
   },

package/core/src/contract-concurrency.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Contract suite — concurrency + write-path strengths (Wave 1 of the
+ * Reliability & Usability Program, umbrella #556). Encodes the 2026-07-09
+ * nine-persona deep test's verdict that "the storage/concurrency core is
+ * trustworthy — zero server errors, zero corruption, zero lost writes across
+ * ~100 hostile operations and a live two-writer session" (#556, #555 work
+ * item "document the strong contracts the deep test verified but that are
+ * currently unwritten selling points"). Every test here is a PASSING lock-in
+ * — there is no known-broken behavior in this file, only undocumented
+ * correctness worth pinning as contract before later waves touch adjacent
+ * code paths.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { ConflictError, PathConflictError } from "./notes.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("contract: concurrency — passing (lock in verified strengths)", () => {
+  it("sequential interleaved appends from two writers preserve call order and lose nothing (25-line pattern)", async () => {
+    const note = await store.createNote("", { id: "log" });
+
+    // Simulate two independent writers interleaving 25 appends each.
+    // Sequential (not truly parallel) — the contract under test is that
+    // SQL-level `content = content || ?` concatenation never drops or
+    // reorders a write relative to the order calls actually landed in,
+    // which is exactly what a real two-writer race also guarantees
+    // (see core.test.ts's "update-note append is atomic under concurrent
+    // calls" for the Promise.all interleaving twin of this test).
+    const expectedLines: string[] = [];
+    for (let i = 1; i <= 25; i++) {
+      const lineA = `writer-A line ${i}\n`;
+      await store.updateNote(note.id, { append: lineA });
+      expectedLines.push(lineA);
+
+      const lineB = `writer-B line ${i}\n`;
+      await store.updateNote(note.id, { append: lineB });
+      expectedLines.push(lineB);
+    }
+
+    const final = await store.getNote(note.id);
+    expect(final!.content).toBe(expectedLines.join(""));
+    // 50 appends, none lost: every planted line is present exactly once.
+    expect(final!.content.match(/writer-A line/g)?.length).toBe(25);
+    expect(final!.content.match(/writer-B line/g)?.length).toBe(25);
+  });
+
+  it("two updates racing on the same if_updated_at token: exactly one succeeds, the other gets a ConflictError", async () => {
+    const note = await store.createNote("v0", { id: "n1" });
+    const token = note.updatedAt!;
+
+    const first = await store.updateNote(note.id, { content: "v1 (writer A)", if_updated_at: token });
+    expect(first.content).toBe("v1 (writer A)");
+
+    let err: any;
+    try {
+      // Writer B read the note before writer A's update landed and is still
+      // holding the stale token — this must conflict, not silently overwrite.
+      await store.updateNote(note.id, { content: "v1 (writer B)", if_updated_at: token });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(ConflictError);
+    expect(err.note_id).toBe(note.id);
+    expect(err.expected_updated_at).toBe(token);
+    expect(err.current_updated_at).toBe(first.updatedAt);
+
+    // Writer A's write is the one that stuck.
+    const final = await store.getNote(note.id);
+    expect(final!.content).toBe("v1 (writer A)");
+  });
+
+  it("creating a note at an already-taken path throws PathConflictError — the prior note is untouched", async () => {
+    const original = await store.createNote("original owner", { path: "shared/path" });
+
+    let err: any;
+    try {
+      await store.createNote("racing creator", { path: "shared/path" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(PathConflictError);
+    expect(err.path).toBe("shared/path");
+
+    const survivor = await store.getNote(original.id);
+    expect(survivor!.content).toBe("original owner");
+  });
+
+  it("a metadata update merges rather than replaces — untouched top-level keys survive a partial patch", async () => {
+    const note = await store.createNote("has metadata", {
+      metadata: { keep: "me", also_keep: 42, drop_me: "bye" },
+    });
+
+    // mergeMetadata is the pure merge primitive the MCP/REST write paths
+    // call before handing the merged object to store.updateNote (the
+    // Store/engine-level updateNote itself replaces `metadata` wholesale —
+    // merge is a caller responsibility, exercised here directly).
+    const { mergeMetadata } = await import("./notes.js");
+    const merged = mergeMetadata(note.metadata as Record<string, unknown>, {
+      also_keep: 43,
+      drop_me: null,
+      new_key: "hello",
+    });
+    await store.updateNote(note.id, { metadata: merged, if_updated_at: note.updatedAt });
+
+    const after = await store.getNote(note.id);
+    expect(after!.metadata).toEqual({ keep: "me", also_keep: 43, new_key: "hello" });
+  });
+});

package/core/src/contract-taxonomy.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Contract suite — taxonomy integrity (Wave 1 of the Reliability & Usability
+ * Program, umbrella #556). Encodes the 2026-07-09 nine-persona deep test's
+ * WS3 findings (#552) as executable tests: PASSING tests lock in behavior
+ * that is correct today (the tag-expand axis, `delete-tag`'s "untag, don't
+ * delete notes" contract, and `renameTag`'s full cascade — note_tags,
+ * `parent_names` references in OTHER tags, and note body content); `test.todo`
+ * entries describe the target behavior for confirmed-broken cases, to be
+ * flipped to real assertions in a later wave. See #552 for the full write-up.
+ */
+
+import { describe, it, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+const idsOf = (notes: { id: string }[]) => new Set(notes.map((n) => n.id));
+
+describe("contract: taxonomy — passing (lock in current behavior)", () => {
+  it("expand axis 4-way discrimination: subtypes/namespace/both/exact each answer a distinct question", async () => {
+    // Two-axis corpus (mirrors tag-expand-axis.test.ts): `person` is a
+    // declared subtype of `entity` (parent_names) but not name-prefixed;
+    // `entity/archived` is name-prefixed under `entity` but NOT a declared
+    // subtype; `entity/person` is both.
+    await store.upsertTagRecord("entity", { description: "an entity" });
+    await store.upsertTagRecord("person", { parent_names: ["entity"] });
+    await store.upsertTagRecord("entity/archived", {});
+    await store.upsertTagRecord("entity/person", { parent_names: ["entity"] });
+
+    const nEntity = await store.createNote("literal entity", { tags: ["entity"] });
+    const nPerson = await store.createNote("a person (subtype)", { tags: ["person"] });
+    const nArchived = await store.createNote("filed under entity/", { tags: ["entity/archived"] });
+    const nBoth = await store.createNote("subtype AND filed", { tags: ["entity/person"] });
+
+    const subtypes = await store.queryNotes({ tags: ["entity"], expand: "subtypes" });
+    expect(idsOf(subtypes)).toEqual(new Set([nEntity.id, nPerson.id, nBoth.id]));
+
+    const namespace = await store.queryNotes({ tags: ["entity"], expand: "namespace" });
+    expect(idsOf(namespace)).toEqual(new Set([nEntity.id, nArchived.id, nBoth.id]));
+
+    const both = await store.queryNotes({ tags: ["entity"], expand: "both" });
+    expect(idsOf(both)).toEqual(new Set([nEntity.id, nPerson.id, nArchived.id, nBoth.id]));
+
+    const exact = await store.queryNotes({ tags: ["entity"], expand: "exact" });
+    expect(idsOf(exact)).toEqual(new Set([nEntity.id]));
+  });
+
+  it("delete-tag untags notes without deleting the notes themselves", async () => {
+    const note = await store.createNote("keep me", { tags: ["temp", "keeper"] });
+    const result = await store.deleteTag("temp");
+    expect(result).toEqual({ deleted: true, notes_untagged: 1 });
+
+    const survivor = await store.getNote(note.id);
+    expect(survivor).not.toBeNull();
+    expect(survivor!.content).toBe("keep me");
+    expect(survivor!.tags).toEqual(["keeper"]);
+    expect(survivor!.tags).not.toContain("temp");
+  });
+
+  it("renameTag cascades note_tags, other tags' parent_names, AND note body content in one atomic call", async () => {
+    // note_tags surface: a note directly tagged `proj`.
+    const tagged = await store.createNote("owns the proj tag", { tags: ["proj"] });
+    // parent_names surface: another tag declares `proj` as a parent.
+    await store.upsertTagRecord("proj", { description: "root project tag" });
+    await store.upsertTagRecord("special", { parent_names: ["proj"] });
+    // note-body surface: a note mentions `#proj` inline (not as a real tag).
+    const mentioning = await store.createNote("kickoff notes, see #proj for context", {});
+
+    const result = await store.renameTag("proj", "initiative");
+    expect("error" in result).toBe(false);
+    if ("error" in result) throw new Error("unreachable");
+    expect(result.renamed).toBeGreaterThanOrEqual(1);
+    expect(result.parent_refs_updated).toBeGreaterThanOrEqual(1);
+    expect(result.notes_rewritten).toBeGreaterThanOrEqual(1);
+
+    // 1. note_tags cascade.
+    const taggedAfter = await store.getNote(tagged.id);
+    expect(taggedAfter!.tags).toContain("initiative");
+    expect(taggedAfter!.tags).not.toContain("proj");
+
+    // 2. OTHER tags' parent_names cascade.
+    const specialAfter = await store.getTagRecord("special");
+    expect(specialAfter?.parent_names).toEqual(["initiative"]);
+
+    // 3. Note body content cascade.
+    const mentioningAfter = await store.getNote(mentioning.id);
+    expect(mentioningAfter!.content).toContain("#initiative");
+    expect(mentioningAfter!.content).not.toContain("#proj");
+
+    // The old tag name is fully retired — no longer a live tag row.
+    const oldRecord = await store.getTagRecord("proj");
+    expect(oldRecord).toBeNull();
+  });
+});
+
+describe("contract: taxonomy — todo (#552)", () => {
+  test.todo(
+    "#552: deleting a tag still referenced in another tag's parent_names errors unless cascade/detach is passed (today: store.deleteTag succeeds unconditionally and leaves the referencing tag's parent_names pointing at a now-nonexistent tag name — verified with a fresh parent/child fixture)",
+  );
+  test.todo(
+    "#552: a parent_names cycle (A declares parent B, then B declares parent A) is rejected at write time (today: store.upsertTagRecord accepts both writes with no cycle check — traversal elsewhere is cycle-safe, but the write itself is not honest about creating one)",
+  );
+  test.todo(
+    "#552: rename-tag is exposed as an MCP tool, not just a REST endpoint (today: POST /api/tags/:name/rename exists and store.renameTag is wired, but generateMcpTools has no rename-tag tool — an MCP-only agent cannot rename a tag)",
+  );
+  test.todo(
+    "#552: merge-tags is exposed as an MCP tool, not just a REST endpoint (today: POST /api/tags/merge exists and store.mergeTags is wired, but generateMcpTools has no merge-tags tool)",
+  );
+  test.todo(
+    "#552: a `vault doctor` integrity scan reports dangling parent_names references (today: no doctor/scan surface inspects parent_names for referential integrity — the delete-tag gap above goes undetected)",
+  );
+});

package/core/src/contract-typed-index.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Contract suite — typed indexes (Wave 1 of the Reliability & Usability
+ * Program, umbrella #556). Encodes the 2026-07-09 nine-persona deep test's
+ * WS4 findings (#553) as executable tests: PASSING tests lock in behavior
+ * that is correct today (well-typed integer-indexed range queries, the
+ * merge-patch metadata contract, and the state_transition compare-and-set
+ * conflict); `test.todo` entries describe the target behavior for
+ * confirmed-broken cases, to be flipped to real assertions in a later wave.
+ * See #553 for the full write-up.
+ *
+ * The TEXT-poisoning todo below was reproduced live before writing: declaring
+ * an indexed integer field and writing `metadata.n = "four"` succeeds with
+ * only an advisory `type_mismatch` warning, and the resulting row's generated
+ * column carries the raw TEXT value under SQLite's INTEGER-affinity
+ * coercion — which then sorts ABOVE every real integer (SQLite type
+ * ordering: NULL < INTEGER/REAL < TEXT < BLOB), so `{n: {gt: 100}}`
+ * incorrectly matches the poisoned row alongside genuine matches.
+ */
+
+import { describe, it, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { TransitionConflictError } from "./notes.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("contract: typed indexes — passing (lock in current behavior)", () => {
+  it("an integer-indexed field with well-typed integer values answers gte/lt correctly", async () => {
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    const low = await store.createNote("n=5", { tags: ["metric"], metadata: { n: 5 } });
+    const mid = await store.createNote("n=50", { tags: ["metric"], metadata: { n: 50 } });
+    const high = await store.createNote("n=200", { tags: ["metric"], metadata: { n: 200 } });
+
+    const gte50 = await store.queryNotes({ tags: ["metric"], metadata: { n: { gte: 50 } } });
+    expect(new Set(gte50.map((n) => n.id))).toEqual(new Set([mid.id, high.id]));
+
+    const lt50 = await store.queryNotes({ tags: ["metric"], metadata: { n: { lt: 50 } } });
+    expect(new Set(lt50.map((n) => n.id))).toEqual(new Set([low.id]));
+  });
+
+  it("merge-patch metadata preserves untouched fields, updates named fields, and RFC-7386-deletes null fields", async () => {
+    const note = await store.createNote("has metadata", {
+      metadata: { a: 1, b: 2, c: 3 },
+    });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+
+    const result: any = await updateNote.execute({
+      id: note.id,
+      metadata: { b: 20, c: null },
+      force: true,
+    });
+
+    expect(result.metadata).toEqual({ a: 1, b: 20 });
+  });
+
+  it("a state_transition compare-and-set conflicts when the note has already transitioned away from `from`", async () => {
+    const note = await store.createNote("workflow item", { metadata: { status: "draft" } });
+
+    const first = await store.updateNote(note.id, {
+      state_transition: { field: "status", from: "draft", to: "published" },
+    });
+    expect((first.metadata as any).status).toBe("published");
+
+    let err: any;
+    try {
+      // Same `from: "draft"` precondition — but the note is now "published",
+      // so this must conflict rather than silently no-op or overwrite.
+      await store.updateNote(note.id, {
+        state_transition: { field: "status", from: "draft", to: "archived" },
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(TransitionConflictError);
+    expect(err.field).toBe("status");
+    expect(err.expected_from).toBe("draft");
+    expect(err.current).toBe("published");
+
+    // The note's status is untouched by the rejected transition.
+    const after = await store.getNote(note.id);
+    expect((after!.metadata as any).status).toBe("published");
+  });
+});
+
+describe("contract: typed indexes — todo (#553)", () => {
+  test.todo(
+    `#553: a write of a TEXT value to an indexed integer field is REJECTED (today: it is accepted with only an advisory type_mismatch warning, and the poisoned row then silently matches {gt: 100}-style range queries via SQLite's TEXT-sorts-above-INTEGER type-affinity ordering — reproduced live: metadata.n = "four" on an indexed integer field succeeds, and query {n: {gt: 100}} incorrectly returns it)`,
+  );
+  test.todo(
+    `#553: an unset enum field stays ABSENT — no first-value backfill — so exists:false correctly matches a note that never set the field (today: applySchemaDefaults in core/src/mcp.ts backfills the schema's first enum value onto every note that gains the tag, so "never set" is indistinguishable from "explicitly set to the default" and exists:false never matches)`,
+  );
+  test.todo(
+    `#553: update-tag reports ALL invalid fields in one call AND states explicitly that no changes were applied (today: the cross-tag type/indexed-flag validation loop in core/src/mcp.ts throws on the FIRST offending field and never reports the rest, and the thrown Error's message doesn't say whether the tag's other, valid fields were partially applied — reproduced live: declaring two invalid fields in one update-tag call surfaces only the first field's error)`,
+  );
+  test.todo(
+    `#553: the indexed-field type list is honest about what's actually indexable (core/src/mcp.ts's update-tag field-type description advertises "string, boolean, integer, number, array, object" but indexed-fields.ts's TYPE_MAP only supports string/integer/boolean — "number" and the container types are accepted as declared but silently un-indexable)`,
+  );
+});

package/core/src/core.test.ts

@@ -4046,7 +4046,7 @@ describe("query-notes link expansion", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tag hierarchy via tags.parent_names (post-v14, patterns/tag-data-model.md)
+// Tag hierarchy via tags.parent_names (post-v14, docs/contracts/tag-data-model.md)
 // ---------------------------------------------------------------------------
 
 describe("tag hierarchy (tags.parent_names)", async () => {
@@ -5107,7 +5107,7 @@ describe("schema inheritance via parent_names (vault#270)", async () => {
   });
 });
 
-describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-tokens.md)", async () => {
+describe("expandTagsWithDescendants (tag-scoped tokens — docs/contracts/tag-scoped-tokens.md)", async () => {
   it("returns the union of root + every descendant per tags.parent_names", async () => {
     await store.upsertTagRecord("health/food", { parent_names: ["health"] });
     await store.upsertTagRecord("health/food/breakfast", { parent_names: ["health/food"] });
@@ -5143,10 +5143,10 @@ describe("expandTagsWithDescendants (tag-scoped tokens — patterns/tag-scoped-t
 });
 
 // ---------------------------------------------------------------------------
-// Tag record API — patterns/tag-data-model.md
+// Tag record API — docs/contracts/tag-data-model.md
 // ---------------------------------------------------------------------------
 
-describe("tag record API (patterns/tag-data-model.md)", async () => {
+describe("tag record API (docs/contracts/tag-data-model.md)", async () => {
   it("upsertTagRecord persists description + fields + relationships + parent_names", async () => {
     await store.upsertTagRecord("project", {
       description: "long-running deliverable",
@@ -5430,7 +5430,7 @@ describe("tag record API (patterns/tag-data-model.md)", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Schema migration v13 → v14 — patterns/tag-data-model.md
+// Schema migration v13 → v14 — docs/contracts/tag-data-model.md
 // ---------------------------------------------------------------------------
 
 describe("schema migration v13 → v14", async () => {
@@ -5809,7 +5809,7 @@ describe("schema migration v15 → v16", async () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tag-scope auth post-v14 — patterns/tag-scoped-tokens.md
+// Tag-scope auth post-v14 — docs/contracts/tag-scoped-tokens.md
 // ---------------------------------------------------------------------------
 
 describe("tag-scope auth (post-v14 hierarchy)", async () => {
@@ -5824,7 +5824,7 @@ describe("tag-scope auth (post-v14 hierarchy)", async () => {
   });
 
   it("orphan sub-tag fallback: token for `health` still sees `#health/food` even with no declared hierarchy", async () => {
-    // Per patterns/tag-scoped-tokens.md §Storage details, the auth check
+    // Per docs/contracts/tag-scoped-tokens.md §Storage details, the auth check
     // also splits on '/' and matches the root verbatim against the raw
     // allowlist. This survives the v14 source-of-truth swap because the
     // fallback lives in src/tag-scope.ts, not in the resolver.

package/core/src/mcp.ts

@@ -1408,7 +1408,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "update-tag",
       requiredVerb: "write",
-      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
+      description: "Create or update a tag's identity row: description, indexed-field schemas, relationship-vocabulary map, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-vault/docs/contracts/tag-data-model.md.",
       inputSchema: {
         type: "object",
         properties: {

package/core/src/schema.ts

@@ -41,7 +41,7 @@ CREATE TABLE IF NOT EXISTS notes (
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
 -- declarations. One row per tag; no notes-as-config sidecars for these
--- concerns. See parachute-patterns/patterns/tag-data-model.md.
+-- concerns. See docs/contracts/tag-data-model.md.
 --
 -- description    — human-readable blurb (markdown).
 -- fields         — JSON: indexed metadata field declarations per
@@ -136,7 +136,7 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- scoped_tags is a JSON-encoded array of root tag names that constrain the
 -- token's effective access (intersection with the scopes column). NULL
 -- means unscoped — full vault access per scopes. Introduced in v13 per
--- patterns/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
+-- docs/contracts/tag-scoped-tokens.md. Hierarchy expansion is applied at auth
 -- time via getTagDescendants; the column stores root names only.
 --
 -- vault_name (v16) binds the token to a single vault. NULL means the
@@ -443,7 +443,7 @@ export function initSchema(db: Database): void {
   // Migrate v13 → v14: tag-data-model reshape. Augment `tags` row with
   // description/fields/relationships/parent_names/timestamps; copy data
   // from the v6-era tag_schemas sidecar and from `_tags/<name>` config
-  // notes; drop tag_schemas after copy. See patterns/tag-data-model.md.
+  // notes; drop tag_schemas after copy. See docs/contracts/tag-data-model.md.
   migrateToV14(db);
 
   // Migrate v14 → v15: retire the `_schemas/<name>` and `_schema_defaults`
@@ -650,7 +650,7 @@ function migrateToV12(db: Database): void {
  * (current full-vault behavior); a JSON array of root tag names narrows the
  * token's access to notes carrying one of those tags or a sub-tag thereof
  * (hierarchy expansion via getTagDescendants at auth time). See
- * parachute-patterns/patterns/tag-scoped-tokens.md.
+ * docs/contracts/tag-scoped-tokens.md.
  */
 function migrateToV13(db: Database): void {
   if (hasTable(db, "tokens") && !hasColumn(db, "tokens", "scoped_tags")) {
@@ -659,7 +659,7 @@ function migrateToV13(db: Database): void {
 }
 
 /**
- * Migrate v13 → v14: tag-data-model reshape (patterns/tag-data-model.md).
+ * Migrate v13 → v14: tag-data-model reshape (docs/contracts/tag-data-model.md).
  *
  * Augments the `tags` table with five new columns and one timestamp pair,
  * then copies pre-existing data from two notes-as-config sidecars: