@openparachute/vault 0.7.2-rc.4 → 0.7.2-rc.5

package/core/src/core.test.ts

@@ -4572,6 +4572,390 @@ describe("MCP tools", async () => {
       expect(afterLink!.targetId).toBe(alice.id);
       expect(afterLink!.createdAt).toBe(beforeLink!.createdAt);
     });
+
+    it("regression guard: cardinality:'one' (scalar) reference field still creates exactly one edge", async () => {
+      const alice = await store.createNote("Alice", { id: "alice" });
+      await store.upsertTagSchema("task", { fields: { assignee: { type: "reference", cardinality: "one" } } });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        metadata: { assignee: "alice" },
+      }) as any;
+
+      const links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "assignee");
+      expect(links).toHaveLength(1);
+      expect(links[0]!.targetId).toBe(alice.id);
+    });
+
+    // ---- Gap #2: cardinality:"many" (array) reference fields (vault#typed-reference-field) ----
+
+    it("cardinality:'many' reference field creates one link per array element, deduped, with no spurious type_mismatch warning", async () => {
+      const carol = await store.createNote("Carol", { path: "People/Carol" });
+      const dave = await store.createNote("Dave", { path: "People/Dave" });
+      await store.upsertTagSchema("task", {
+        fields: { collaborators: { type: "reference", cardinality: "many" } },
+      });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const result = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        // "People/Carol" appears twice — duplicate elements must dedupe to one edge.
+        metadata: { collaborators: ["People/Carol", "People/Dave", "People/Carol"] },
+      }) as any;
+
+      // No spurious type_mismatch — an array is exactly what cardinality:"many" asks
+      // for; pre-fix, valueMatchesType's "reference" case only accepted strings.
+      expect(result.validation_status.warnings).toEqual([]);
+
+      const links = (await store.getLinks(result.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(links).toHaveLength(2);
+      expect(new Set(links.map((l) => l.targetId))).toEqual(new Set([carol.id, dave.id]));
+
+      // Traversable via find-path, same as a scalar reference link.
+      const findPath = tools.find((t) => t.name === "find-path")!;
+      const path = await findPath.execute({ source: result.id, target: carol.id }) as any;
+      expect(path?.path).toEqual([result.id, carol.id]);
+    });
+
+    it("update-note changing a cardinality:'many' reference array adds the new link, drops the removed one, and leaves the unchanged one alone", async () => {
+      const carol = await store.createNote("Carol", { path: "People/Carol" });
+      const dave = await store.createNote("Dave", { path: "People/Dave" });
+      const erin = await store.createNote("Erin", { path: "People/Erin" });
+      await store.upsertTagSchema("task", {
+        fields: { collaborators: { type: "reference", cardinality: "many" } },
+      });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        metadata: { collaborators: ["People/Carol", "People/Dave"] },
+      }) as any;
+
+      let links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(links).toHaveLength(2);
+      const carolLinkBefore = links.find((l) => l.targetId === carol.id)!;
+
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+      // Drop Dave, add Erin, keep Carol.
+      await updateNote.execute({
+        id: note.id,
+        metadata: { collaborators: ["People/Carol", "People/Erin"] },
+        force: true,
+      });
+
+      links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(links).toHaveLength(2);
+      expect(new Set(links.map((l) => l.targetId))).toEqual(new Set([carol.id, erin.id]));
+      // Dropped — Dave's link is gone.
+      expect(links.some((l) => l.targetId === dave.id)).toBe(false);
+      // Unchanged — Carol's edge is the SAME row (createdAt preserved), proving a
+      // real diff (not a blanket clear-and-recreate under the relationship).
+      const carolLinkAfter = links.find((l) => l.targetId === carol.id)!;
+      expect(carolLinkAfter.createdAt).toBe(carolLinkBefore.createdAt);
+    });
+
+    it("an unresolved array element is queued and backfills when its target note is created later, without disturbing already-resolved siblings", async () => {
+      const carol = await store.createNote("Carol", { path: "People/Carol" });
+      await store.upsertTagSchema("task", {
+        fields: { collaborators: { type: "reference", cardinality: "many" } },
+      });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        metadata: { collaborators: ["People/Carol", "People/Not Yet Created"] },
+      }) as any;
+
+      let links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(links).toHaveLength(1); // only Carol resolves so far
+      expect(links[0]!.targetId).toBe(carol.id);
+
+      const queryNotes = tools.find((t) => t.name === "query-notes")!;
+      const broken = await queryNotes.execute({ has_broken_links: true }) as any[];
+      expect(broken.map((n: any) => n.id)).toContain(note.id);
+
+      const target = await store.createNote("here now", { path: "People/Not Yet Created" });
+
+      links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(links).toHaveLength(2);
+      expect(new Set(links.map((l) => l.targetId))).toEqual(new Set([carol.id, target.id]));
+    });
+
+    it("an array element resolving to the note itself creates a self-loop link, matching scalar self-reference behavior", async () => {
+      await store.upsertTagSchema("task", {
+        fields: { collaborators: { type: "reference", cardinality: "many" } },
+      });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        path: "Tasks/Self",
+        metadata: { collaborators: ["Tasks/Self"] },
+      }) as any;
+
+      const links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(links).toHaveLength(1);
+      expect(links[0]!.targetId).toBe(note.id);
+    });
+
+    it("an ambiguous array element (matches ≥2 notes) is neither linked nor queued, mirroring the scalar ambiguous contract", async () => {
+      await store.createNote("Shared Title", { path: "A/Shared Title" });
+      await store.createNote("Shared Title", { path: "B/Shared Title" });
+      const target = await store.createNote("Target", { path: "People/Target" });
+      await store.upsertTagSchema("task", {
+        fields: { collaborators: { type: "reference", cardinality: "many" } },
+      });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        metadata: { collaborators: ["Shared Title", "People/Target"] },
+      }) as any;
+
+      const links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      // Only the unambiguous element links; "Shared Title" is neither linked nor queued.
+      expect(links).toHaveLength(1);
+      expect(links[0]!.targetId).toBe(target.id);
+
+      const queryNotes = tools.find((t) => t.name === "query-notes")!;
+      const broken = await queryNotes.execute({ has_broken_links: true }) as any[];
+      expect(broken.map((n: any) => n.id)).not.toContain(note.id);
+    });
+
+    // ---- Gap #3: schema-after-data backfill (vault#typed-reference-field) ----
+
+    it("declaring type:'reference' via update-tag after notes already carry the value backfills links for existing notes (scalar and array)", async () => {
+      const alice = await store.createNote("Alice", { path: "People/Alice" });
+      const bob = await store.createNote("Bob", { path: "People/Bob" });
+      const carol = await store.createNote("Carol", { path: "People/Carol" });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+
+      // Written BEFORE the tag declares these fields as `reference` — plain
+      // untyped metadata, no schema applies at write time, so no link is created.
+      const scalarNote = await createNote.execute({
+        content: "Scalar task",
+        tags: ["task"],
+        metadata: { manager: "People/Alice" },
+      }) as any;
+      const arrayNote = await createNote.execute({
+        content: "Array task",
+        tags: ["task"],
+        metadata: { collaborators: ["People/Bob", "People/Carol"] },
+      }) as any;
+
+      expect((await store.getLinks(scalarNote.id, { direction: "outbound" })).length).toBe(0);
+      expect((await store.getLinks(arrayNote.id, { direction: "outbound" })).length).toBe(0);
+
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      await updateTag.execute({
+        tag: "task",
+        fields: {
+          manager: { type: "reference" },
+          collaborators: { type: "reference", cardinality: "many" },
+        },
+      });
+
+      const scalarLinks = (await store.getLinks(scalarNote.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "manager");
+      expect(scalarLinks).toHaveLength(1);
+      expect(scalarLinks[0]!.targetId).toBe(alice.id);
+
+      const arrayLinks = (await store.getLinks(arrayNote.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(arrayLinks).toHaveLength(2);
+      expect(new Set(arrayLinks.map((l) => l.targetId))).toEqual(new Set([bob.id, carol.id]));
+
+      // Idempotency: a LATER update-tag call that declares a NEW reference
+      // field re-triggers the tag's whole backfill walk (see
+      // `backfillReferenceFieldLinks` — it re-syncs every reference field on
+      // each note, not just the newly-added one). Already-synced links must
+      // not duplicate.
+      await updateTag.execute({
+        tag: "task",
+        fields: { reviewer: { type: "reference" } },
+      });
+
+      const scalarLinksAfter = (await store.getLinks(scalarNote.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "manager");
+      expect(scalarLinksAfter).toHaveLength(1);
+      const arrayLinksAfter = (await store.getLinks(arrayNote.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(arrayLinksAfter).toHaveLength(2);
+    });
+
+    it("declaring type:'reference' on a PARENT tag backfills links for notes carrying a descendant (child) tag", async () => {
+      const alice = await store.createNote("Alice", { path: "People/Alice" });
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      // `subtask` is a child of `task` via parent_names — schema inheritance
+      // (vault#270) means `subtask` notes are in `task`'s effective walk.
+      await updateTag.execute({ tag: "subtask", parent_names: ["task"] });
+
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const note = await createNote.execute({
+        content: "Child task",
+        tags: ["subtask"],
+        metadata: { manager: "People/Alice" },
+      }) as any;
+
+      expect((await store.getLinks(note.id, { direction: "outbound" })).length).toBe(0);
+
+      await updateTag.execute({ tag: "task", fields: { manager: { type: "reference" } } });
+
+      const links = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "manager");
+      expect(links).toHaveLength(1);
+      expect(links[0]!.targetId).toBe(alice.id);
+    });
+
+    // ---- Round-4 review fixes (2026-07-10) ----
+
+    it("BLOCKER 1: the schema-declaration backfill walks ALL notes, not the first 100", async () => {
+      // One shared target every note references.
+      const target = await store.createNote("Target", { path: "People/Target" });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+
+      // 120 notes each carrying a `manager` value BEFORE the field is a
+      // reference — exceeds queryNotes' default LIMIT 100.
+      const noteIds: string[] = [];
+      for (let i = 0; i < 120; i++) {
+        const n = await createNote.execute({
+          content: `Task ${i}`,
+          tags: ["task"],
+          metadata: { manager: "People/Target" },
+        }) as any;
+        noteIds.push(n.id);
+      }
+
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      await updateTag.execute({ tag: "task", fields: { manager: { type: "reference" } } });
+
+      // EVERY one of the 120 notes must have a manager edge — a 100-cap would
+      // leave 20 unlinked (the silent-half-graph this feature prevents).
+      let linked = 0;
+      for (const id of noteIds) {
+        const links = (await store.getLinks(id, { direction: "outbound" }))
+          .filter((l) => l.relationship === "manager" && l.targetId === target.id);
+        if (links.length === 1) linked++;
+      }
+      expect(linked).toBe(120);
+    });
+
+    it("BLOCKER 2: re-declaring an ALREADY-reference field via update-tag heals notes whose links were never built", async () => {
+      const alice = await store.createNote("Alice", { path: "People/Alice" });
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag")!;
+      const createNote = tools.find((t) => t.name === "create-note")!;
+
+      // Field is declared reference from the start, and a note is written.
+      await updateTag.execute({ tag: "task", fields: { manager: { type: "reference" } } });
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        metadata: { manager: "People/Alice" },
+      }) as any;
+      expect((await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "manager")).toHaveLength(1);
+
+      // Simulate a pre-fix vault: the edge was never built. Delete it directly,
+      // leaving the metadata value in place but the graph edge missing.
+      await store.deleteLink(note.id, alice.id, "manager");
+      expect((await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "manager")).toHaveLength(0);
+
+      // Re-declare the SAME already-reference field — the documented heal path.
+      // A transition-keyed trigger would no-op here; the fix fires the backfill
+      // for any reference field in the declared schema.
+      await updateTag.execute({ tag: "task", fields: { manager: { type: "reference" } } });
+
+      const healed = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "manager");
+      expect(healed).toHaveLength(1);
+      expect(healed[0]!.targetId).toBe(alice.id);
+    });
+
+    it("NIT 3: dropping an array element reconciles against RESOLVED targets — a since-renamed target's stale edge is dropped, and an aliased-same-target edge survives", async () => {
+      const dave = await store.createNote("Dave", { path: "People/Dave" });
+      const erin = await store.createNote("Erin", { path: "People/Erin" });
+      await store.upsertTagSchema("task", {
+        fields: { collaborators: { type: "reference", cardinality: "many" } },
+      });
+      const tools = generateMcpTools(store);
+      const createNote = tools.find((t) => t.name === "create-note")!;
+      const updateNote = tools.find((t) => t.name === "update-note")!;
+
+      // --- Corner (a): a still-present element whose target is renamed after
+      // linking; then a DIFFERENT element is dropped. The renamed target's
+      // stale edge must be reconciled away (the old re-resolve-removed-value
+      // approach left it forever).
+      const note = await createNote.execute({
+        content: "Ship it",
+        tags: ["task"],
+        metadata: { collaborators: ["People/Dave", "People/Erin"] },
+      }) as any;
+      expect((await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators")).toHaveLength(2);
+
+      // Rename Dave's target note — the raw value "People/Dave" no longer resolves.
+      await updateNote.execute({ id: dave.id, path: "People/David", force: true });
+
+      // Drop Erin (a different element); keep the now-stale "People/Dave".
+      await updateNote.execute({
+        id: note.id,
+        metadata: { collaborators: ["People/Dave"] },
+        force: true,
+      });
+
+      const afterA = (await store.getLinks(note.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      // Erin dropped; Dave's stale edge (target renamed, value no longer
+      // resolves) reconciled away → zero edges, not a lingering stale one.
+      expect(afterA.some((l) => l.targetId === erin.id)).toBe(false);
+      expect(afterA.some((l) => l.targetId === dave.id)).toBe(false);
+
+      // --- Corner (c): two elements ALIAS the same target (path + H1 title).
+      // Dropping one alias must keep the shared edge (still referenced by the
+      // survivor), not delete it.
+      const carol = await store.createNote("# Carol\n\nbody", { path: "People/Carol" });
+      const aliasNote = await createNote.execute({
+        content: "Alias task",
+        tags: ["task"],
+        // "People/Carol" (path) and "Carol" (H1 title) both resolve to carol.
+        metadata: { collaborators: ["People/Carol", "Carol"] },
+      }) as any;
+      let aliasLinks = (await store.getLinks(aliasNote.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(aliasLinks).toHaveLength(1);
+      expect(aliasLinks[0]!.targetId).toBe(carol.id);
+
+      // Drop the title alias, keep the path alias → the shared edge survives.
+      await updateNote.execute({
+        id: aliasNote.id,
+        metadata: { collaborators: ["People/Carol"] },
+        force: true,
+      });
+      aliasLinks = (await store.getLinks(aliasNote.id, { direction: "outbound" }))
+        .filter((l) => l.relationship === "collaborators");
+      expect(aliasLinks).toHaveLength(1);
+      expect(aliasLinks[0]!.targetId).toBe(carol.id);
+    });
   });
 
   it("find-path works with ID/path resolution", async () => {

package/core/src/schema-defaults.ts

@@ -348,7 +348,7 @@ function jsonTypeOf(value: unknown): string {
   return typeof value; // "string" | "number" | "boolean" | "object" | ...
 }
 
-function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
+function valueMatchesType(value: unknown, type: SchemaField["type"], cardinality?: SchemaField["cardinality"]): boolean {
   if (type === undefined) return true;
   switch (type) {
     case "string":
@@ -373,7 +373,22 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
     // the write path (core/src/store.ts) separately resolves this value to
     // a note and maintains a graph link; see tag-schemas.ts's
     // `VALID_FIELD_TYPES` doc comment for the full contract.
+    //
+    // `cardinality: "many"` (vault#typed-reference-field gap #2) is a
+    // one-to-MANY reference field — the value is an ARRAY of reference
+    // strings, one per linked note, not a single string. Validate the
+    // shape a "many" reference actually takes: an array whose elements are
+    // ALL non-empty-typed strings (per-item type check — the ARRAY shape
+    // itself is separately covered by the `cardinality_mismatch` check
+    // below in `validateNote`, so this only needs to judge element types).
+    // Without this branch, EVERY valid `cardinality:"many"` reference write
+    // fired a self-contradictory `type_mismatch` ("should be reference, got
+    // array") — an array is exactly what "many" asks for; only a
+    // non-string ELEMENT should ever fail this check.
     case "reference":
+      if (cardinality === "many") {
+        return Array.isArray(value) && value.every((item) => typeof item === "string");
+      }
       return typeof value === "string";
   }
 }
@@ -435,7 +450,7 @@ export function validateNote(
 
     if (absent) continue;
 
-    if (spec.type && !valueMatchesType(value, spec.type)) {
+    if (spec.type && !valueMatchesType(value, spec.type, spec.cardinality)) {
       // Decision A (vault#553): an INDEXED field's type is a query
       // contract — a type-mismatched write poisons range-query ordering
       // (SQLite's TEXT-sorts-above-INTEGER affinity) regardless of whether

package/core/src/store.ts

@@ -15,8 +15,10 @@ import {
   resolveUnresolvedWikilinks,
   resolveOrQueueLink,
   clearQueuedLink,
+  clearQueuedLinkTarget,
   requeueInboundWikilinksForDelete,
 } from "./wikilinks.js";
+import { chunkForInClause } from "./sql-in.js";
 import { pathTitle } from "./paths.js";
 import { timestampToMs } from "./cursor.js";
 import { transaction } from "./txn.js";
@@ -24,6 +26,7 @@ import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
   getTagExpansion,
+  getTagDescendants,
   stripTagHash,
   TAG_CONFIG_PREFIX,
   DEFAULT_TAG_NAME,
@@ -45,6 +48,36 @@ import {
 import type { SearchMode } from "./search-query.js";
 import { runDoctorScan, type DoctorReport, type DoctorScanOpts } from "./doctor.js";
 
+/**
+ * Normalize a `type: "reference"` field value (scalar OR array — see
+ * `BunSqliteStore.syncReferenceFieldArrayLinks`) into a Set of non-empty,
+ * trimmed string elements. A bare scalar string becomes a one-element set
+ * (so a cardinality transition between scalar and array diffs correctly
+ * against the other side); a non-array/non-string value (undefined, null,
+ * number, object, …) becomes the empty set; array elements that aren't
+ * non-empty strings are dropped (they can never resolve to a link target).
+ * Set semantics absorb both element ORDER and DUPLICATE entries, matching
+ * how the underlying `links` table's UNIQUE(source_id, target_id,
+ * relationship) would collapse duplicate-target elements anyway.
+ */
+function referenceValueToSet(value: unknown): Set<string> {
+  const out = new Set<string>();
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === "string" && item.trim() !== "") out.add(item);
+    }
+  } else if (typeof value === "string" && value.trim() !== "") {
+    out.add(value);
+  }
+  return out;
+}
+
+function setsEqual(a: Set<string>, b: Set<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const v of a) if (!b.has(v)) return false;
+  return true;
+}
+
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
  * synchronous; the public Store API is async so the same interface
@@ -115,7 +148,8 @@ export class BunSqliteStore implements Store {
   /**
    * Auto-link sync for `type: "reference"` schema fields
    * (vault#typed-reference-field — see `docs/design/typed-reference-field.md`
-   * for the full design + known gaps).
+   * for the full design; gaps #2/#3 closed below, see the doc for what
+   * remains open).
    *
    * A `reference`-typed field is BOTH an indexed value (handled by the
    * ordinary metadata write — no special casing needed there, see
@@ -130,27 +164,35 @@ export class BunSqliteStore implements Store {
    *
    * Called from `createNote`/`updateNote`/`createNotes` — the single
    * chokepoint both MCP and REST funnel through — AFTER the note row itself
-   * is written, so `note.tags`/`note.metadata` reflect the final state.
+   * is written, so `note.tags`/`note.metadata` reflect the final state. This
+   * is the WRITE-PATH (reconciling) sync; the gap #3 schema-declaration
+   * backfill is a separate, purely-additive path
+   * ({@link backfillReferenceFieldLinks}), so a `update-tag` re-declare never
+   * churns already-correct edges.
    *
    * `priorMetadata` is the note's metadata BEFORE this write (`undefined` on
-   * create). For each reference field, if its value is unchanged from
-   * `priorMetadata`, nothing is touched — the existing link (if any) already
-   * reflects it, and re-running the resolve/queue machinery on every
-   * unrelated write (e.g. a content-only edit) would be wasted work. When
-   * the value DID change (set, changed, or removed), every existing link +
-   * queued forward-ref under that field's relationship name is cleared
-   * first, then re-established from the new value — this makes the field's
-   * current value the single source of truth for "this field's link"
-   * without needing to track the specific prior target.
+   * create). For each SCALAR reference
+   * field, if its value is unchanged from `priorMetadata`, nothing is
+   * touched — the existing link (if any) already reflects it, and
+   * re-running the resolve/queue machinery on every unrelated write (e.g. a
+   * content-only edit) would be wasted work. When the value DID change (set,
+   * changed, or removed), every existing link + queued forward-ref under
+   * that field's relationship name is cleared first, then re-established
+   * from the new value — this makes the field's current value the single
+   * source of truth for "this field's link" without needing to track the
+   * specific prior target.
    *
-   * Known gaps (see the design doc): only scalar (`cardinality: "one"`,
-   * the default) reference values are linked — an array value is left as a
-   * validated-like-string-per-item... actually an array value simply isn't
-   * a string, so no link is created for it (the write still succeeds; a
-   * `type_mismatch`/`cardinality_mismatch` warning surfaces via the normal
-   * `validation_status` path). A tag gaining a `reference` field declaration
-   * does NOT retroactively link notes that already carry a matching value —
-   * only writes that actually touch the field (going forward) sync.
+   * A `cardinality: "many"` (array) value takes a different path —
+   * {@link syncReferenceFieldArrayLinks} — since a relationship name can now
+   * back MULTIPLE edges (one per element) rather than at most one, so
+   * "clear everything under this relationship, recreate" would be wrong: it
+   * would drop+recreate edges for elements that didn't even change. That
+   * method diffs old-vs-new array membership (a Set, so element order and
+   * duplicate entries don't matter) and only touches what actually changed.
+   * Dispatched whenever EITHER side of the comparison is an array — this
+   * also correctly handles a field transitioning between scalar and array
+   * shape (e.g. a schema's `cardinality` changes), by treating a scalar side
+   * as a one-element set.
    */
   private syncReferenceFieldLinks(
     note: Note,
@@ -167,6 +209,12 @@ export class BunSqliteStore implements Store {
 
       const nextValue = metadata[fieldName];
       const priorValue = prior[fieldName];
+
+      if (Array.isArray(nextValue) || Array.isArray(priorValue)) {
+        this.syncReferenceFieldArrayLinks(note.id, fieldName, nextValue, priorValue);
+        continue;
+      }
+
       if (nextValue === priorValue) continue; // unchanged — link (if any) already reflects it
 
       // Re-establish this field's link from scratch: drop whatever it
@@ -200,6 +248,205 @@ export class BunSqliteStore implements Store {
     }
   }
 
+  /**
+   * The `cardinality: "many"` counterpart of the scalar sync above (vault
+   * typed-reference-field gap #2, docs/design/typed-reference-field.md).
+   * ONE link per array element, all sharing `relationship = fieldName` — the
+   * `links` table's `UNIQUE(source_id, target_id, relationship)` naturally
+   * dedupes distinct elements resolving to the same target, and distinct
+   * elements resolving to distinct targets coexist as separate rows under
+   * the same relationship name.
+   *
+   * `nextValue`/`priorValue` are read as SETS of non-empty, trimmed string
+   * elements (via {@link referenceValueToSet}) — a non-array scalar
+   * contributes a one-element set (so a cardinality transition diffs
+   * correctly), non-string/empty elements are dropped (they can never
+   * resolve to a link target; `valueMatchesType` already flags them via the
+   * normal `type_mismatch` path if the schema disagrees), and DUPLICATE
+   * elements collapse to one (a `["carol","carol"]` array creates exactly
+   * one edge to carol, matching how `createLink`'s own UNIQUE constraint
+   * would collapse it anyway).
+   *
+   * Reconciles against the RESOLVED next-set, NOT a raw-value diff (round-4
+   * review NIT 3). Resolving every element of the new array yields the exact
+   * set of `target_id`s the field's edges under this relationship SHOULD
+   * point at; existing edges are then reconciled TO that set:
+   * - Delete every existing edge under `(noteId, relationship)` whose
+   *   `target_id` is NOT in the resolved next-set. Reconciling on resolved
+   *   TARGETS (not by re-resolving each removed raw string) is what makes
+   *   the three corners the raw-value diff got wrong come out right:
+   *   (a) a removed element whose target was renamed/deleted since — its
+   *   edge's `target_id` is simply absent from the next-set, so it's
+   *   dropped (the raw-value approach re-resolved the stale string, missed,
+   *   and left the edge forever); (b) a removed element now ambiguous —
+   *   same, dropped by target; (c) two elements ALIASING the same target
+   *   (a path and its H1 title both resolving to one note) — removing one
+   *   alias keeps the shared edge, because the surviving alias still
+   *   resolves that `target_id` INTO the next-set (the raw-value approach
+   *   deleted the shared edge when it processed the removed alias, then
+   *   never recreated it because the surviving alias looked "unchanged").
+   * - Create every resolved next-set edge via `createLink`'s `INSERT OR
+   *   IGNORE` — an already-present edge (an element unchanged across the
+   *   update) is untouched, so it KEEPS its original `created_at`.
+   * - A next-set element that doesn't resolve is queued exactly like a
+   *   scalar reference (self-links and ambiguous matches follow the same
+   *   contract: a self element creates a self-loop; an ambiguous one is
+   *   neither linked nor queued, vault#570). Queued forward-refs for
+   *   elements DROPPED from the array (in prior, absent from next) are
+   *   cleared per-element via {@link clearQueuedLinkTarget} — NOT the
+   *   blanket {@link clearQueuedLink}, which would also drop OTHER elements'
+   *   still-pending queue rows under the same relationship.
+   *
+   * Two sets that are IDENTICAL (regardless of original order/duplicates in
+   * either array) short-circuit to a no-op — mirrors the scalar path's
+   * unchanged-value fast path.
+   */
+  private syncReferenceFieldArrayLinks(
+    noteId: string,
+    fieldName: string,
+    nextValue: unknown,
+    priorValue: unknown,
+  ): void {
+    const nextSet = referenceValueToSet(nextValue);
+    const priorSet = referenceValueToSet(priorValue);
+
+    if (setsEqual(nextSet, priorSet)) return; // same membership — nothing to do
+
+    // Resolve the ENTIRE next-set (queuing misses) → the target ids the
+    // field's edges under this relationship should point at right now.
+    const desiredTargetIds = new Set<string>();
+    for (const value of nextSet) {
+      const outcome = resolveOrQueueLink(this.db, noteId, value, fieldName);
+      if (outcome.status === "resolved") desiredTargetIds.add(outcome.note_id);
+    }
+
+    // Reconcile existing edges to the desired target set (see the doc comment
+    // for why deleting by resolved TARGET, not by re-resolved raw value, is
+    // what fixes the rename / ambiguous / aliasing corners).
+    const existing = linkOps.getLinks(this.db, noteId, { direction: "outbound" });
+    for (const link of existing) {
+      if (link.relationship !== fieldName) continue;
+      if (!desiredTargetIds.has(link.targetId)) {
+        linkOps.deleteLink(this.db, noteId, link.targetId, fieldName);
+      }
+    }
+
+    // Create every desired edge — INSERT OR IGNORE keeps an unchanged
+    // element's row (and its `created_at`) intact.
+    for (const targetId of desiredTargetIds) {
+      linkOps.createLink(this.db, noteId, targetId, fieldName);
+    }
+
+    // Drop queued forward-refs for elements removed from the array. A
+    // still-present-but-unresolved element stays queued (re-queued
+    // idempotently above).
+    for (const value of priorSet) {
+      if (!nextSet.has(value)) clearQueuedLinkTarget(this.db, noteId, fieldName, value);
+    }
+  }
+
+  /**
+   * Gap #3 backfill (vault typed-reference-field,
+   * docs/design/typed-reference-field.md): when `update-tag`'s persisted
+   * schema for `tag` includes one or more `type: "reference"` fields,
+   * existing notes that already carry a value for such a field may predate
+   * the declaration (or predate the gap #2 array-link fix) and sit unlinked
+   * — only a future write that actually touches the field would otherwise
+   * sync it. This walks every note carrying `tag` (or a descendant, via
+   * schema inheritance — same scope `countConformanceViolations` uses for
+   * its own schema-change impact walk) and materializes the missing links
+   * for each note's CURRENT value of the declared reference field(s).
+   *
+   * `referenceFieldNames` is the set of fields THIS `update-tag` persisted
+   * as `type: "reference"` (round-4 review NIT 5) — the walk syncs ONLY
+   * those, never every reference field the note happens to carry from OTHER
+   * co-tags/ancestors, so declaring a reference field on tag A can't churn
+   * an unrelated reference field contributed by tag B on a note carrying
+   * both. Fired for ANY reference field in the declared schema, not just a
+   * type-transition (round-4 review BLOCKER 2), so re-declaring an
+   * already-reference field HEALS notes whose links were never built —
+   * exactly what UPGRADING tells operators to do. Safe to re-run: the
+   * backfill is purely ADDITIVE + idempotent (see
+   * {@link backfillOneReferenceField}).
+   *
+   * Walks the FULL matching note set — the id sweep is unbounded (round-4
+   * review BLOCKER 1: `queryNotes` silently caps at LIMIT 100, which on a
+   * >100-note tag left the majority of notes unlinked — the exact
+   * silent-half-graph this feature exists to prevent). Ids are collected by
+   * a direct `note_tags` scan chunked under the IN-param cap, then hydrated
+   * in batches.
+   *
+   * Runs INSIDE the caller's tag-write transaction (round-4 review NIT 4 —
+   * NOT its own separate transaction), so a walk failure rolls the schema
+   * write back and the retry re-fires rather than leaving a persisted
+   * `reference` schema whose links never got built. `update-tag` is
+   * `vault:admin`-tier, so a bounded per-tag(+descendants) walk is an
+   * accepted cost.
+   */
+  private backfillReferenceFieldLinks(tag: string, referenceFieldNames: Set<string>): void {
+    if (referenceFieldNames.size === 0) return;
+    const hierarchy = this.getTagHierarchy();
+    const tagSet = Array.from(getTagDescendants(hierarchy, tag));
+    if (tagSet.length === 0) return;
+
+    // Unbounded id sweep: every note carrying `tag` or a descendant. Direct
+    // note_tags scan (deduped across tags), chunked under the IN-param cap —
+    // NO default LIMIT, unlike `queryNotes`.
+    const idSet = new Set<string>();
+    for (const chunk of chunkForInClause(tagSet)) {
+      const placeholders = chunk.map(() => "?").join(", ");
+      const rows = this.db.prepare(
+        `SELECT DISTINCT note_id FROM note_tags WHERE tag_name IN (${placeholders})`,
+      ).all(...chunk) as { note_id: string }[];
+      for (const r of rows) idSet.add(r.note_id);
+    }
+    if (idSet.size === 0) return;
+
+    const ids = Array.from(idSet);
+    const schemaConfig = this.getSchemaConfig();
+    const tagsById = noteOps.getNoteTagsForNotes(this.db, ids);
+    const notes = noteOps.getNotes(this.db, ids);
+
+    for (const note of notes) {
+      const tags = tagsById.get(note.id) ?? note.tags ?? [];
+      const resolution = resolveNoteSchemas(schemaConfig, { tags });
+      const metadata = note.metadata ?? {};
+      for (const fieldName of referenceFieldNames) {
+        const merged = resolution.mergedFields.get(fieldName);
+        // The field must actually be `reference` in THIS note's effective
+        // schema — a descendant tag can override it to a non-reference type
+        // (first-in-walk wins), in which case this note doesn't get a link.
+        if (!merged || merged.spec.type !== "reference") continue;
+        this.backfillOneReferenceField(note.id, fieldName, metadata[fieldName]);
+      }
+    }
+  }
+
+  /**
+   * Materialize the missing graph link(s) for ONE reference field's current
+   * value on one note (gap #3 backfill helper). Purely ADDITIVE and
+   * idempotent: for each element of the value (a scalar string is a
+   * one-element set; an array is deduped via {@link referenceValueToSet}),
+   * resolve-or-queue and, on a resolve, `createLink`. It NEVER deletes an
+   * edge — a backfill materializes links that were never built; reconciling
+   * divergent state (removing a stale edge when a value CHANGES) stays the
+   * write path's job (`syncReferenceFieldLinks` /
+   * {@link syncReferenceFieldArrayLinks}). Because `createLink` and the
+   * forward-ref queue are both `INSERT OR IGNORE`, a re-run — or an edge
+   * that already exists — is a no-op that preserves the existing row's
+   * `created_at` (so re-declaring a schema doesn't churn already-correct
+   * edges, and a scalar value that has since gone ambiguous doesn't silently
+   * lose its already-built edge — round-4 review NIT 5).
+   */
+  private backfillOneReferenceField(noteId: string, fieldName: string, value: unknown): void {
+    for (const element of referenceValueToSet(value)) {
+      const outcome = resolveOrQueueLink(this.db, noteId, element, fieldName);
+      if (outcome.status === "resolved") {
+        linkOps.createLink(this.db, noteId, outcome.note_id, fieldName);
+      }
+    }
+  }
+
   /**
    * Drop the tag-hierarchy cache if the mutated path is in the `_tags/*`
    * namespace. Called from create/update/delete — old path is passed
@@ -863,6 +1110,25 @@ export class BunSqliteStore implements Store {
     const priorIndexed = indexedSet(priorRecord?.fields);
     const nextIndexed = indexedSet(nextFields);
 
+    // Gap #3 backfill target set (vault typed-reference-field,
+    // docs/design/typed-reference-field.md) — the field names THIS call
+    // persists as `type: "reference"`. Fired for ANY reference field in the
+    // declared schema, NOT just a type-transition (round-4 review BLOCKER
+    // 2): keying on "transition to reference" made the documented
+    // "re-declare the field to heal existing notes" path a silent no-op (an
+    // already-reference field stays reference, so the transition never
+    // fires), stranding pre-fix vaults whose reference-many links were never
+    // built. The backfill itself is additive + idempotent, so re-firing on
+    // every declare is safe; `update-tag` is a rare admin op, so the bounded
+    // walk is an accepted cost. Empty when `fields` is untouched or cleared.
+    const referenceFieldNames = new Set<string>(
+      patch.fields !== undefined
+        ? Object.entries(nextFields ?? {})
+            .filter(([, spec]) => spec.type === "reference")
+            .map(([name]) => name)
+        : [],
+    );
+
     // PRE-VALIDATE every newly-indexed field BEFORE any persistence. A bad
     // field name (or unmappable type) must fail closed — the schema record
     // must NOT be written when the backing index can't be created. Pre-checking
@@ -910,50 +1176,73 @@ export class BunSqliteStore implements Store {
       }
     }
 
-    // Persist the record + reconcile the indexed-field lifecycle atomically.
-    // If declareField throws inside the transaction (e.g. a cross-tag type
-    // mismatch only detectable once the existing declarer set is consulted),
-    // the whole write rolls back — the schema never ends up claiming an index
-    // that doesn't exist. vault#478 transactional fix.
-    const result = this.transaction(() => {
-      const record = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
-
-      if (patch.fields !== undefined) {
-        for (const fieldName of nextIndexed) {
-          const spec = nextFields![fieldName]!;
-          // Type already validated above; non-null assertion is safe here.
-          const mapped = indexedFieldOps.mapFieldType(spec.type)!;
-          indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
-        }
-        for (const fieldName of priorIndexed) {
-          if (!nextIndexed.has(fieldName)) {
-            indexedFieldOps.releaseField(this.db, fieldName, tag);
+    // Persist the record + reconcile the indexed-field lifecycle AND the
+    // gap #3 reference-link backfill atomically, in ONE transaction (round-4
+    // review NIT 4). If declareField throws (e.g. a cross-tag type mismatch
+    // only detectable once the existing declarer set is consulted) OR the
+    // backfill walk throws, the whole write rolls back — the schema never
+    // ends up claiming an index that doesn't exist (vault#478), and never
+    // persists a `reference` declaration whose links silently failed to
+    // build (a partial-state 500 whose retry, post-BLOCKER-2, would re-fire
+    // and heal — but atomic avoids the partial state in the first place).
+    let result: tagSchemaOps.TagRecord;
+    try {
+      result = this.transaction(() => {
+        const record = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+
+        if (patch.fields !== undefined) {
+          for (const fieldName of nextIndexed) {
+            const spec = nextFields![fieldName]!;
+            // Type already validated above; non-null assertion is safe here.
+            const mapped = indexedFieldOps.mapFieldType(spec.type)!;
+            indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+          }
+          for (const fieldName of priorIndexed) {
+            if (!nextIndexed.has(fieldName)) {
+              indexedFieldOps.releaseField(this.db, fieldName, tag);
+            }
           }
         }
-      }
-      return record;
-    });
 
-    if (patch.parent_names !== undefined) {
-      // parent_names drives both query expansion (tag hierarchy) AND, post
-      // vault#270, schema inheritance — bust both caches.
-      this._tagHierarchy = null;
-      this._schemaConfig = null;
-    }
-    if (patch.fields !== undefined) {
-      this._schemaConfig = null;
-    }
-    // First-time creation of a tag row (e.g. an empty `_default` placeholder)
-    // changes the `_default` universal-parent gate even when no fields or
-    // parent_names are touched. Cheap to bust: caches rebuild on next read.
-    if (tag === "_default") {
-      this._tagHierarchy = null;
-      this._schemaConfig = null;
+        // Gap #3 backfill — INSIDE the transaction. Bust the in-memory
+        // caches FIRST (round-4 review NIT 6): the walk's
+        // `resolveNoteSchemas` must see the just-persisted reference
+        // declaration, and `getTagDescendants` must see the post-write
+        // hierarchy — including the `_default` universal-parent gate a
+        // first-time `_default` row flips (which used to be busted only
+        // AFTER the backfill call). Nulling a cache inside the txn is safe:
+        // it only forces a rebuild from the current in-txn DB state; the
+        // `finally` below re-nulls so a rollback can't strand the rebuild.
+        if (referenceFieldNames.size > 0) {
+          this._tagHierarchy = null;
+          this._schemaConfig = null;
+          this.backfillReferenceFieldLinks(tag, referenceFieldNames);
+        }
+        return record;
+      });
+    } finally {
+      // Invalidate whatever this write (or the backfill's mid-txn cache
+      // rebuild) may have touched — on BOTH the commit and the rollback
+      // path. `parent_names` drives query expansion + (vault#270) schema
+      // inheritance; `fields` drives schema validation; a first-time
+      // `_default` row flips the universal-parent gate; and the backfill
+      // above re-caches mid-transaction state a rollback must not keep.
+      if (
+        patch.parent_names !== undefined ||
+        patch.fields !== undefined ||
+        tag === "_default" ||
+        referenceFieldNames.size > 0
+      ) {
+        this._tagHierarchy = null;
+        this._schemaConfig = null;
+      }
     }
+
     // Tag-mutation event for the git-mirror and any other downstream
     // consumer. Fire "upserted" on every successful tag-record write —
     // schema/relationship/parent-name mutations all alter the sidecar
-    // contents the mirror persists.
+    // contents the mirror persists. (Success path only — a thrown/rolled-back
+    // write never reaches here.)
     this.hooks.dispatchTag("upserted", tag, this);
     return result;
   }

package/core/src/wikilinks.ts

@@ -807,6 +807,35 @@ export function clearQueuedLink(db: Database, sourceId: string, relationship: st
   }
 }
 
+/**
+ * Drop exactly ONE pending forward-ref — scoped by `targetPath` in addition
+ * to `sourceId`/`relationship` (the full `unresolved_wikilinks` primary
+ * key). Used by the `cardinality:"many"` reference-field array sync
+ * (core/src/store.ts's `syncReferenceFieldLinks`) when a SPECIFIC array
+ * element is removed from a field's value: unlike the scalar path (which
+ * owns the ENTIRE relationship namespace and can safely clear every queued
+ * row via {@link clearQueuedLink}), an array field can have MULTIPLE
+ * pending forward-refs under the same relationship at once (one per
+ * unresolved element) — blanket-clearing all of them on a single element's
+ * removal would silently drop the other still-pending elements' queue rows.
+ * Safe no-op when the table doesn't exist yet or nothing is queued for this
+ * exact (source, target, relationship) triple.
+ */
+export function clearQueuedLinkTarget(
+  db: Database,
+  sourceId: string,
+  relationship: string,
+  targetPath: string,
+): void {
+  try {
+    db.prepare(
+      "DELETE FROM unresolved_wikilinks WHERE source_id = ? AND relationship = ? AND target_path = ? COLLATE NOCASE",
+    ).run(sourceId, relationship, targetPath);
+  } catch {
+    // Table may not exist yet — nothing to clear.
+  }
+}
+
 /**
  * Resolve a structured link NOW, or queue it for lazy resolution when the
  * target doesn't exist yet — mirroring the wikilink forward-ref contract

package/package.json

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