@openparachute/vault 0.5.1 → 0.5.2-rc.2

package/core/src/mcp.ts

@@ -99,13 +99,31 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // Tool generation
 // ---------------------------------------------------------------------------
 
+/**
+ * Options for {@link generateMcpTools}.
+ *
+ * `expandVisibility` (vault security review) is an OPTIONAL per-note
+ * visibility predicate threaded into the wikilink-expansion context for
+ * `query-notes`. When provided, `expand_links` inlining leaves any wikilink
+ * whose target fails the predicate UNRESOLVED — so a tag-scoped MCP session
+ * can't inline out-of-scope note content during expansion (the filtering
+ * happens DURING expansion, not after). Core stays scope-unaware: it
+ * receives a plain `(note) => boolean` closure and never imports the
+ * server's tag-scope module. Omitted (every internal / unscoped caller) →
+ * expansion behaves exactly as before.
+ */
+export interface GenerateMcpToolsOpts {
+  expandVisibility?: (note: Note) => boolean;
+}
+
 /**
  * Generate the consolidated MCP tools for a vault. Surface (10):
  * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
  * delete-tag, find-path, vault-info, prune-schema (admin).
  */
-export function generateMcpTools(store: Store): McpToolDef[] {
+export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
   const db: Database = (store as any).db;
+  const expandVisibility = opts?.expandVisibility;
 
   return [
 
@@ -178,7 +196,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             type: "object",
             description: "Filter by metadata values. Each value is either a primitive (exact match, scans JSON) or an operator object: `{eq|ne|gt|gte|lt|lte|in|not_in|exists: value}`. Operator objects require the field to be declared `indexed: true` in a tag schema — they route through the backing B-tree index. Multiple operators on one field AND together (e.g. `{gt: 5, lt: 10}`). `in`/`not_in` take arrays; `exists` takes a boolean.",
           },
-          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
+          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. The special value `link_count` sorts by link DEGREE (both-directions raw row count) — no declaration needed — matching the `include_link_count` field for every note. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
           date_from: { type: "string", description: "Start date (ISO, inclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', from }`." },
           date_to: { type: "string", description: "End date (ISO, exclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', to }`." },
           date_filter: {
@@ -217,6 +235,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Control metadata in response: true (all, default), false (none), or array of field names to include",
           },
           include_links: { type: "boolean", description: "Include inbound + outbound links per note (default: false)" },
+          include_link_count: {
+            type: "boolean",
+            description:
+              "Include the note's link DEGREE as a `linkCount` field, without hauling the link objects (default: false). Degree is a raw row count: outbound (source) + inbound (target). A self-loop counts as 2. Cheap COUNT over indexes; batched once per request. For a tag-scoped token, `linkCount` is the raw degree and MAY include edges to notes the token can't see — only the number leaks, not the neighbor.",
+          },
+          link_count_direction: {
+            type: "string",
+            enum: ["both", "outbound", "inbound"],
+            description:
+              "Which edges `include_link_count` counts: both (default), outbound only (source_id), or inbound only (target_id). order_by=link_count always uses the both-directions degree.",
+          },
           include_attachments: { type: "boolean", description: "Include attachment records (default: false)" },
           expand_links: { type: "boolean", description: "Inline [[wikilinks]] in returned content (default: false). Has no effect if content is not included (e.g., default list mode with include_content=false); wikilinks inside fenced or inline code are not expanded." },
           expand_depth: { type: "number", description: "Recursion depth for link expansion (default 1, max 3). Only meaningful in 'full' mode — 'summary' mode does not recurse." },
@@ -235,7 +264,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           ),
         );
         const expandCtx: ExpandContext | null = expandLinks
-          ? { db, mode: expandMode, expanded: new Set() }
+          ? {
+              db,
+              mode: expandMode,
+              expanded: new Set(),
+              // Tag-scope confidentiality (security review): when a visibility
+              // predicate was injected, wikilinks to out-of-scope notes are
+              // left unresolved DURING inlining — never embedded. Unscoped
+              // callers pass no predicate and inlining is unchanged.
+              ...(expandVisibility ? { isVisible: expandVisibility } : {}),
+            }
           : null;
 
         // --- Single note by ID/path ---
@@ -256,10 +294,26 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           if (params.include_attachments) {
             result.attachments = await store.getAttachments(note.id);
           }
+          // linkCount injected after filterMetadata on purpose — same as
+          // links/attachments above; filterMetadata only touches `metadata`.
+          if (params.include_link_count) {
+            const dir = normalizeLinkCountDirection(params.link_count_direction);
+            result.linkCount = linkOps.getLinkCounts(db, [note.id], dir).get(note.id) ?? 0;
+          }
           return result;
         }
 
         // --- Build near-scope (graph-filtered set of allowed IDs) ---
+        //
+        // Tag-scope policy for `near[]` (output-filter, not hop-guard): core
+        // is scope-unaware, so this BFS walks the FULL graph from the anchor —
+        // including out-of-scope intermediate hops. For a tag-scoped session
+        // the server's `applyTagScopeWrappers` (mcp-tools.ts) tag-filters the
+        // RESULT list AFTER execute, so out-of-scope notes never survive into
+        // the response — no content/ids leak. This is ASYMMETRIC with
+        // `find-path`, which guards every hop (it returns the path itself, so
+        // an out-of-scope intermediary would be a leak there). The asymmetry is
+        // deliberate; tracked at vault#439.
         let nearScope: Set<string> | null = null;
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
@@ -390,6 +444,19 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           output = output.map((n: any) => filterMetadata(n, includeMetadata));
         }
 
+        // --- Opt-in link degree (vault feedback #4) ---
+        // ONE batch count over all result ids (NOT per-note), so the field
+        // stays O(2 index scans) per request regardless of page size.
+        // Injected on the same objects the enrichment loop copies below.
+        // Ordering: runs AFTER the filterMetadata pass above on purpose —
+        // filterMetadata only touches the `metadata` key, so linkCount
+        // survives. Don't casually swap the order.
+        if (params.include_link_count) {
+          const dir = normalizeLinkCountDirection(params.link_count_direction);
+          const counts = linkOps.getLinkCounts(db, output.map((n: any) => n.id), dir);
+          for (const n of output) n.linkCount = counts.get(n.id) ?? 0;
+        }
+
         // --- Hydrate links/attachments per note if requested ---
         if (params.include_links || params.include_attachments) {
           const enrichedOut: any[] = [];
@@ -543,7 +610,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 - \`links: { add: [{ target, relationship }], remove: [{ target, relationship }] }\` — add/remove links
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - For batch: pass a \`notes\` array, each with an \`id\` field.
-- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
+- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
 - \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.`,
       inputSchema: {
@@ -567,7 +634,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
           created_at: { type: "string", description: "New created_at timestamp" },
           if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
-          force: { type: "boolean", description: "Override the required `if_updated_at` check and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe." },
+          force: { type: "boolean", description: "Waive the *requirement to supply* `if_updated_at` and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe. Note: this does not override an `if_updated_at` you actually pass — if you supply both, the precondition still applies and a mismatch returns a conflict error." },
           if_missing: { type: "string", enum: ["fail", "create"], description: "What to do when the note (by `id`/path) doesn't exist. `\"fail\"` (default) — error, current behavior. `\"create\"` — create the note from this same payload (content/path/tags/metadata become the create fields; the response carries `created: true`). Skips the `if_updated_at` precondition on the create branch (nothing to conflict with). Idempotent for sync loops that don't know ahead of time whether the note exists. See vault#309." },
           tags: {
             type: "object",
@@ -609,6 +676,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             type: "boolean",
             description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
           },
+          include_links: {
+            type: "boolean",
+            description: "Echo the note's hydrated inbound + outbound links on the response (vault feedback #8). Links are *also* echoed automatically whenever the update itself mutated links (`links.add`/`links.remove`), so you rarely need to set this — its purpose is to fetch the current link set on an update that didn't touch links. Default: `false` (and absent from the response unless mutated or requested). Mirrors `query-notes`'s `include_links`. This top-level flag applies to the single-note form only; for a batch, set `include_links` on each note object in `notes` (a top-level `include_links` is ignored when `notes` is present).",
+          },
           // Batch
           notes: {
             type: "array",
@@ -632,10 +703,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                 metadata: { type: "object" },
                 created_at: { type: "string" },
                 if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item or the item is `append`/`prepend`-only." },
-                force: { type: "boolean", description: "Override the required `if_updated_at` check for this item." },
+                force: { type: "boolean", description: "Waive the *requirement to supply* `if_updated_at` for this item. Does not override an `if_updated_at` you actually pass — a supplied precondition still applies and a mismatch conflicts." },
                 if_missing: { type: "string", enum: ["fail", "create"], description: "Per-item: see top-level `if_missing` docs. Each batch item carries its own setting." },
                 tags: { type: "object" },
                 links: { type: "object" },
+                include_links: { type: "boolean", description: "Per-item: echo hydrated links on this item's response (vault feedback #8). Also implied when this item mutates links." },
               },
               required: ["id"],
             },
@@ -657,6 +729,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // sync-loop caller (Gitcoin Brain et al) reads this to know which
         // path fired without doing a separate query. vault#309.
         const createdIds = new Set<string>();
+        // Track which note IDs should echo hydrated links on the response.
+        // A note qualifies when this request mutated its links
+        // (`links.add`/`links.remove`) OR the caller set `include_links`.
+        // vault feedback #8 — previously the update response omitted links
+        // entirely, forcing a re-query just to confirm a link the caller had
+        // just added/removed. Per-item on batch. Note IDs (not item indices)
+        // key this so the create-on-missing branch, which assigns the id
+        // late, can register correctly.
+        const echoLinkIds = new Set<string>();
         // Wrap multi-item batches in a SQLite transaction so any mid-batch
         // failure (precondition error, content_edit miss, ConflictError, …)
         // rolls back every prior mutation in the batch — see #236.
@@ -745,6 +826,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               const fresh = noteOps.getNote(db, created.id) ?? created;
               updated.push(fresh);
               createdIds.add(fresh.id);
+              // Echo links if this create-on-missing declared `links.add`
+              // (the only link op honored on create) or asked explicitly.
+              if (linksAdd !== undefined || item.include_links === true) {
+                echoLinkIds.add(fresh.id);
+              }
               continue;
             }
             // Fallthrough: not-found + no if_missing → existing error
@@ -907,6 +993,13 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             }
           }
 
+          // Echo links if this update mutated them (`links.add`/`links.remove`)
+          // or the caller asked explicitly. vault feedback #8.
+          const linkMutated = (item.links as any)?.add !== undefined || (item.links as any)?.remove !== undefined;
+          if (linkMutated || item.include_links === true) {
+            echoLinkIds.add(note.id);
+          }
+
           // Re-read for final state
           updated.push(noteOps.getNote(db, note.id) ?? result);
         }
@@ -929,11 +1022,23 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const final = updated.map((n) => {
           const validated = attachValidationStatus(store, db, n);
           const created = createdIds.has(n.id);
-          if (includeContent) return { ...validated, created } as Note & { created: boolean };
+          // Echo hydrated links when this note was flagged for it (mutated
+          // its links or `include_links` was set). Additive key, present only
+          // when triggered — mirrors the GET / query-notes shape exactly via
+          // the shared `linkOps.getLinksHydrated` call. vault feedback #8.
+          const echoLinks = echoLinkIds.has(n.id);
+          if (includeContent) {
+            const full: any = { ...validated, created };
+            if (echoLinks) full.links = linkOps.getLinksHydrated(db, n.id);
+            return full as Note & { created: boolean };
+          }
           const lean: any = noteOps.toNoteIndex(validated);
           const vs = (validated as any).validation_status;
           if (vs !== undefined) lean.validation_status = vs;
           lean.created = created;
+          // Carry the link echo across the lean conversion — `toNoteIndex`
+          // drops unknown fields.
+          if (echoLinks) lean.links = linkOps.getLinksHydrated(db, n.id);
           return lean;
         });
         return batch ? final : final[0];
@@ -1029,7 +1134,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     {
       name: "update-tag",
       requiredVerb: "write",
-      description: "Create or update a tag's identity row: description, indexed-field schemas, typed-link relationships, 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-patterns/patterns/tag-data-model.md.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1051,16 +1156,8 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           },
           relationships: {
             type: "object",
-            description: 'Typed-link declarations. Each value declares { target_tag, cardinality, description? }. Cardinality is one of: one | optional | many | many-required. Phase 1: informational, not enforced at write time. E.g., { "lives_in": { "target_tag": "place", "cardinality": "one" } }',
-            additionalProperties: {
-              type: "object",
-              properties: {
-                target_tag: { type: "string", description: "Tag the relationship points at" },
-                cardinality: { type: "string", enum: ["one", "optional", "many", "many-required"], description: "How many targets this relationship may have" },
-                description: { type: "string", description: "Why this relationship exists; surfaced to AI clients" },
-              },
-              required: ["target_tag", "cardinality"],
-            },
+            description: 'Opaque relationship-vocabulary map: keys are relationship names, values are arbitrary JSON the declaring app interprets. Vault stores and returns the values verbatim and does NOT enforce any inner shape — only that this is a JSON object (a map), not an array or primitive. Replaces any prior map wholesale when provided; pass null to clear. The historical typed shape { "lives_in": { "target_tag": "place", "cardinality": "one" } } is still a valid value, as is any app-defined shape e.g. { "works-on": { "from": "person", "to": "project" } }.',
+            additionalProperties: true,
           },
           parent_names: {
             type: "array",
@@ -1124,10 +1221,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
-        // ---- relationships: replace wholesale when provided. Validate
-        // shape + cardinality vocabulary before persisting so a malformed
-        // payload can't leave the row in an inconsistent state.
-        let relationshipsPatch: Record<string, tagSchemaOps.TagRelationship> | null | undefined;
+        // ---- relationships: replace wholesale when provided. `relationships`
+        // is an opaque vocabulary map (relationship-name → arbitrary JSON the
+        // app interprets). Validate only that it's a JSON object (a map), then
+        // persist verbatim — no inner-shape enforcement.
+        let relationshipsPatch: tagSchemaOps.TagRelationshipMap | null | undefined;
         if (params.relationships === null) {
           relationshipsPatch = null;
         } else if (params.relationships !== undefined) {
@@ -1382,6 +1480,16 @@ function normalizeTags(tag: unknown): string[] | undefined {
   return [tag as string];
 }
 
+/**
+ * Coerce the `link_count_direction` MCP param to a known value, defaulting
+ * to "both" (matches the REST `parseLinkCountDirection` fallback). A typo
+ * silently degrades to the documented default rather than erroring.
+ */
+function normalizeLinkCountDirection(v: unknown): "both" | "outbound" | "inbound" {
+  if (v === "outbound" || v === "inbound") return v;
+  return "both";
+}
+
 // Re-exported for backward compat; defined in notes.ts alongside the
 // conditional-UPDATE implementation that raises it. AmbiguousPathError
 // joins the set (vault#331 N2) so external callers can `instanceof`

package/core/src/notes.ts

@@ -736,6 +736,32 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     // be at the mercy of SQLite's row order and the next page could
     // miss or duplicate one.
     orderBy = "n.updated_at ASC, n.id ASC";
+  } else if (opts.orderBy === "link_count") {
+    // `link_count` is a pseudo-field — like `created_at`/`updated_at` in the
+    // dateFilter block above, it bypasses `requireIndexedField` (it's not a
+    // metadata column). Sort by link DEGREE using the SAME directional-sum
+    // definition as the `linkCount` response field (see `getLinkCounts` in
+    // links.ts): two correlated COUNT subqueries summed. This MUST stay a
+    // sum of two directional counts — a single
+    // `COUNT(*) ... WHERE source_id=n.id OR target_id=n.id` would count a
+    // self-loop ONCE (degree 1) and DIVERGE from the field's degree-2. Both
+    // subqueries ride the existing `idx_links_source` / `idx_links_target`
+    // B-trees. `created_at` stays the stable tiebreaker.
+    //
+    // Always the both-directions degree — inbound-only ordering is a future
+    // extension and is not built here.
+    //
+    // Perf caveat: these are correlated subqueries, evaluated once per
+    // candidate row. At small-to-moderate vault sizes (tens of thousands of
+    // notes) that's fine — each subquery is an O(log n) index probe. At very
+    // large vault sizes the per-row scan cost grows; the upgrade path is a
+    // maintained `link_count` counter column on `notes`, incremented in
+    // `createLink` and decremented in `deleteLink`, then ordered directly.
+    // NOT built now — flagged so a future contributor sees the lever.
+    orderBy =
+      `((SELECT COUNT(*) FROM links WHERE source_id = n.id) ` +
+      `+ (SELECT COUNT(*) FROM links WHERE target_id = n.id)) ${direction}, ` +
+      `n.created_at ${direction}`;
   } else if (opts.orderBy) {
     requireIndexedField(db, opts.orderBy);
     // `orderBy` came from indexed_fields (validated on declaration), so
@@ -1553,6 +1579,15 @@ export function getVaultStats(
   const linkCountRow = db.prepare("SELECT COUNT(*) as c FROM links").get() as { c: number };
   const linkCount = linkCountRow.c;
 
+  // Total content bytes. CAST(content AS BLOB) forces SQLite's LENGTH() to
+  // count UTF-8 BYTES rather than characters (bare LENGTH on TEXT returns a
+  // char count, which undercounts multibyte content). COALESCE because SUM
+  // over zero rows is NULL. See VaultStats.contentBytes for the rationale.
+  const contentBytesRow = db
+    .prepare("SELECT COALESCE(SUM(LENGTH(CAST(content AS BLOB))), 0) as b FROM notes")
+    .get() as { b: number };
+  const contentBytes = contentBytesRow.b;
+
   return {
     totalNotes,
     earliestNote: earliestRow
@@ -1566,6 +1601,7 @@ export function getVaultStats(
     tagCount,
     attachmentCount,
     linkCount,
+    contentBytes,
   };
 }
 

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

@@ -794,6 +794,37 @@ describe("importPortableVault", async () => {
     expect(typed!.metadata).toEqual({ source: "git://x" });
   });
 
+  it("preserves an opaque relationship-vocabulary map across export → import → re-export (vault#428)", async () => {
+    const vocab = {
+      "works-on": { from: "person", to: "project" },
+      "member-of": { from: "person", to: "organization" },
+      "partner-of": { from: "person", to: "person" },
+      "based-at": { from: "project", to: "place", note: "freeform" },
+    };
+    await store.upsertTagRecord("person", {
+      description: "a human",
+      relationships: vocab,
+    });
+    const outDir = join(tmpBase, "out");
+    await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir: outDir });
+    expect(stats.schemas_restored).toBe(1);
+
+    // Imported value matches the original verbatim.
+    const restored = await target.getTagRecord("person");
+    expect(restored?.relationships).toEqual(vocab);
+
+    // Re-export from the restored store and confirm the schema file is
+    // byte-identical to the first export (deep round-trip stability).
+    const outDir2 = join(tmpBase, "out2");
+    await exportVaultToDir(target, { outDir: outDir2, exportedAt: "2026-05-13T00:00:00.000Z" });
+    const schemaA = readFileSync(join(outDir, SIDECAR_DIR, "schemas", "person.yaml"), "utf-8");
+    const schemaB = readFileSync(join(outDir2, SIDECAR_DIR, "schemas", "person.yaml"), "utf-8");
+    expect(schemaB).toBe(schemaA);
+  });
+
   it("skips typed links whose target is missing from the import set", async () => {
     // Source note has a typed link to a target we don't include in
     // the export (synthetic — write the .md file by hand).
@@ -862,6 +893,15 @@ describe("portable-md round-trip — byte-equivalent re-export after blow-away i
       description: "A long-running effort",
       fields: { status: { type: "string", enum: ["active", "done"] } },
     });
+    // Opaque relationship-vocabulary map (vault#428) — exercises that the
+    // round-trip preserves an arbitrary app-defined relationships shape,
+    // not just the historical { target_tag, cardinality } one.
+    await store.upsertTagRecord("project", {
+      relationships: {
+        "works-on": { from: "person", to: "project" },
+        "based-at": { from: "project", to: "place", note: "freeform" },
+      },
+    });
     const n1 = await store.createNote("alpha body", {
       id: "01HX001",
       path: "Inbox/alpha",

package/core/src/schema.ts

@@ -30,10 +30,13 @@ CREATE TABLE IF NOT EXISTS notes (
 -- description    — human-readable blurb (markdown).
 -- fields         — JSON: indexed metadata field declarations per
 --                  query-operators.md. Replaces v6-era tag_schemas.fields.
--- relationships  — JSON: typed-link declarations
---                  ({ "rel": { target_tag, cardinality, description? } }).
---                  Cardinality vocabulary: one | optional | many | many-required.
---                  Phase 1 informational — declared but not enforced at write.
+-- relationships  — JSON: opaque relationship-vocabulary map. Keys are
+--                  relationship names; values are arbitrary JSON the declaring
+--                  app interprets (e.g. the Weaver's { "works-on": { from, to } }).
+--                  Stored + returned verbatim; only the top level is validated
+--                  (must be a JSON object/map). The historical typed shape
+--                  { "rel": { target_tag, cardinality, description? } } remains a
+--                  valid value. Not enforced at write time. See vault#428.
 -- parent_names   — JSON array of parent tag names. Replaces the v6-era
 --                  _tags/NAME config-note hierarchy.
 CREATE TABLE IF NOT EXISTS tags (

package/core/src/store.ts

@@ -572,7 +572,7 @@ export class BunSqliteStore implements Store {
     patch: {
       description?: string | null;
       fields?: Record<string, tagSchemaOps.TagFieldSchema> | null;
-      relationships?: Record<string, tagSchemaOps.TagRelationship> | null;
+      relationships?: tagSchemaOps.TagRelationshipMap | null;
       parent_names?: string[] | null;
     },
   ) {

package/core/src/tag-schemas.ts

@@ -33,10 +33,13 @@ export interface TagFieldSchema {
 }
 
 /**
- * Cardinality vocabulary for typed relationships. Names rather than
- * algebra so AI clients reading `list-tags` can reason about intent
- * directly. Phase 1 is informational — declarations are not enforced
- * at write time. See patterns/tag-data-model.md §Typed relationships.
+ * Cardinality vocabulary for the historical typed-relationship shape.
+ * Names rather than algebra so AI clients reading `list-tags` can reason
+ * about intent directly. Retained for callers that still want the typed
+ * `{ target_tag, cardinality }` declaration — but `relationships` is now an
+ * opaque vocabulary map (see `TagRelationshipMap` / `validateRelationships`),
+ * so this is one valid value shape among many, not a required one.
+ * See patterns/tag-data-model.md §Relationships.
  */
 export type TagRelCardinality = "one" | "optional" | "many" | "many-required";
 
@@ -47,12 +50,24 @@ export const TAG_REL_CARDINALITIES: readonly TagRelCardinality[] = [
   "many-required",
 ] as const;
 
+/**
+ * The historical typed-relationship declaration. Still a valid opaque-map
+ * value — vault no longer enforces it. New apps (the Weaver / structural-link
+ * picker) declare their own freeform vocabulary instead.
+ */
 export interface TagRelationship {
   target_tag: string;
   cardinality: TagRelCardinality;
   description?: string;
 }
 
+/**
+ * `relationships` is an opaque vocabulary map: relationship-name → arbitrary
+ * JSON value the declaring app interprets. Vault stores and returns the values
+ * verbatim and enforces only that the top-level value is a JSON object (a map).
+ */
+export type TagRelationshipMap = Record<string, unknown>;
+
 /**
  * Schema-only view of a tag — the historical shape. Backwards-compatible
  * with v13-and-earlier callers.
@@ -67,7 +82,7 @@ export interface TagSchema {
  * Full tag record — schema + typed relationships + hierarchy parents.
  */
 export interface TagRecord extends TagSchema {
-  relationships?: Record<string, TagRelationship>;
+  relationships?: TagRelationshipMap;
   parent_names?: string[];
   created_at?: string;
   updated_at?: string;
@@ -115,7 +130,7 @@ export function upsertTagRecord(
   patch: {
     description?: string | null;
     fields?: Record<string, TagFieldSchema> | null;
-    relationships?: Record<string, TagRelationship> | null;
+    relationships?: TagRelationshipMap | null;
     parent_names?: string[] | null;
   },
 ): TagRecord {
@@ -226,56 +241,56 @@ export function deleteTagSchema(db: Database, tag: string): boolean {
 }
 
 // ---------------------------------------------------------------------------
-// Validation — typed relationships
+// Validation — relationships (opaque vocabulary map)
 // ---------------------------------------------------------------------------
 
 /**
- * Validate a `relationships` payload before persisting. Returns the
- * canonicalized object on success; throws Error with a user-readable
- * message on the first violation. Rules:
+ * Validate a `relationships` payload before persisting. `relationships` is
+ * an **opaque vocabulary map**: a JSON object whose keys are relationship
+ * names and whose values are arbitrary JSON the declaring app interprets
+ * (e.g. the Weaver / structural-link picker's `{ "works-on": { from, to } }`
+ * shape). Vault does not enforce any inner structure — it stores and returns
+ * the values verbatim.
+ *
+ * Rules (the only ones):
+ *   - The top-level value must be a plain JSON object (a map). A top-level
+ *     array or primitive is rejected — relationships is a map, not a list.
+ *   - The payload must be JSON-serializable (no circular refs / functions /
+ *     bigints), since it's persisted as a JSON column.
  *
- *   - Each value must declare `target_tag` (non-empty string) and
- *     `cardinality` from the named vocabulary.
- *   - `description` is optional, must be a string when present.
- *   - Relationship keys must be non-empty strings.
+ * Returns the value verbatim (round-trips through JSON.parse(JSON.stringify)
+ * to both prove serializability and strip anything non-serializable). The
+ * historical typed shape `{ target_tag, cardinality }` is a valid opaque map,
+ * so this is a backwards-compatible superset — existing typed declarations
+ * and callers keep working unchanged.
+ *
+ * Phase 1 was already informational ("declarations are not enforced at write
+ * time"); dropping the inner-shape gate is consistent with that intent.
  */
-export function validateRelationships(
-  raw: unknown,
-): Record<string, TagRelationship> {
+export function validateRelationships(raw: unknown): Record<string, unknown> {
   if (raw === null || raw === undefined) {
     throw new Error("relationships: expected an object, got null/undefined");
   }
   if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error("relationships: expected an object mapping rel name → declaration");
+    throw new Error(
+      "relationships: expected an object mapping relationship name → value (got an array or primitive)",
+    );
   }
-  const out: Record<string, TagRelationship> = {};
-  for (const [rel, decl] of Object.entries(raw as Record<string, unknown>)) {
-    if (!rel || typeof rel !== "string") {
+  for (const rel of Object.keys(raw as Record<string, unknown>)) {
+    if (!rel) {
       throw new Error("relationships: keys must be non-empty strings");
     }
-    if (!decl || typeof decl !== "object" || Array.isArray(decl)) {
-      throw new Error(`relationships["${rel}"]: declaration must be an object`);
-    }
-    const d = decl as Record<string, unknown>;
-    if (typeof d.target_tag !== "string" || d.target_tag.length === 0) {
-      throw new Error(`relationships["${rel}"]: target_tag must be a non-empty string`);
-    }
-    const card = d.cardinality;
-    if (typeof card !== "string" || !TAG_REL_CARDINALITIES.includes(card as TagRelCardinality)) {
-      throw new Error(
-        `relationships["${rel}"]: cardinality must be one of ${TAG_REL_CARDINALITIES.join(" | ")}; got ${JSON.stringify(card)}`,
-      );
-    }
-    if (d.description !== undefined && typeof d.description !== "string") {
-      throw new Error(`relationships["${rel}"]: description must be a string when set`);
-    }
-    out[rel] = {
-      target_tag: d.target_tag,
-      cardinality: card as TagRelCardinality,
-      ...(d.description !== undefined ? { description: d.description as string } : {}),
-    };
   }
-  return out;
+  // Round-trip through JSON to (a) confirm the payload is serializable —
+  // the column is stored as JSON — and (b) return a clean, owned copy with
+  // no non-JSON values lingering. Throws on circular refs / bigint / etc.
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(raw);
+  } catch (err) {
+    throw new Error(`relationships: value must be JSON-serializable (${(err as Error).message})`);
+  }
+  return JSON.parse(serialized) as Record<string, unknown>;
 }
 
 // ---------------------------------------------------------------------------
@@ -287,7 +302,7 @@ function rowToRecord(row: TagRow): TagRecord {
     tag: row.name,
     description: row.description ?? undefined,
     fields: parseJson<Record<string, TagFieldSchema>>(row.fields),
-    relationships: parseJson<Record<string, TagRelationship>>(row.relationships),
+    relationships: parseJson<TagRelationshipMap>(row.relationships),
     parent_names: parseJson<string[]>(row.parent_names),
     created_at: row.created_at ?? undefined,
     updated_at: row.updated_at ?? undefined,