@openparachute/vault 0.5.1-rc.2 → 0.5.2-rc.1

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/portable-md.ts

@@ -2091,11 +2091,29 @@ export function parseFrontmatter(raw: string): {
   frontmatter: Record<string, unknown>;
   content: string;
 } {
-  if (!raw.startsWith("---")) return { frontmatter: {}, content: raw };
-  const endIdx = raw.indexOf("\n---", 3);
-  if (endIdx === -1) return { frontmatter: {}, content: raw };
-  const yamlBlock = raw.slice(4, endIdx); // skip opening "---\n"
-  const content = raw.slice(endIdx + 4).replace(/^\n/, "");
+  // 1. Strip a leading UTF-8 BOM (U+FEFF) if present. Without this an
+  //    Obsidian export saved with a BOM (`---\n…`) fails the open
+  //    test and the whole file — frontmatter included — falls into the
+  //    body, silently losing id/tags/timestamps (contract FX-FENCE-BOM).
+  const src = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+
+  // 2. Line-scan close-fence (CRLF-aware). The opening line must be
+  //    EXACTLY `---`; the closing fence is the FIRST subsequent line that
+  //    is EXACTLY `---` — not `----`, not `---text`, not `  ---`. An
+  //    unclosed block means the whole file is body (never swallow). This
+  //    replaces the old `indexOf("\n---")` which wrongly matched `\n----`
+  //    and `\n---more` (contract §1.1, FX-FENCE-FOURDASH-OPEN).
+  const lines = src.split(/\r?\n/);
+  if (lines[0] !== "---") return { frontmatter: {}, content: src };
+
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") { closeIdx = i; break; }
+  }
+  if (closeIdx === -1) return { frontmatter: {}, content: src };
+
+  const yamlBlock = lines.slice(1, closeIdx).join("\n");
+  const content = lines.slice(closeIdx + 1).join("\n");
   return { frontmatter: parseBlock(yamlBlock, 0).value, content };
 }
 
@@ -2119,11 +2137,16 @@ function parseBlock(text: string, baseIndent: number): ParseResult {
   while (i < lines.length) {
     const line = lines[i]!;
     if (line.trim() === "") { i++; continue; }
+    // Skip `#`-comment lines (contract C3 / §1.2). A comment at the
+    // block's base level is not a key line; the parser must step over it.
+    if (line.trimStart().startsWith("#")) { i++; continue; }
     const indent = countLeadingSpaces(line);
     if (indent < baseIndent) break;
     if (indent > baseIndent) { i++; continue; } // shouldn't happen at this level
 
-    const kv = line.slice(baseIndent).match(/^([\w][\w-]*):\s*(.*)$/);
+    // Key regex (contract C2 / §1.2): dots allowed in keys, optional
+    // whitespace before the colon (`created.at:` / `key :` both parse).
+    const kv = line.slice(baseIndent).match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
     if (!kv) { i++; continue; }
     const key = kv[1]!;
     const valueText = kv[2]!.trim();
@@ -2199,7 +2222,8 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
     // First content after `- `.
     const after = line.slice(indent + 2).trim();
     // Is this a scalar item (`- foo`) or an object item (`- key: value`)?
-    const objMatch = after.match(/^([\w][\w-]*):\s*(.*)$/);
+    // Key regex matches parseBlock's (contract C2): dots + optional space.
+    const objMatch = after.match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
     if (!objMatch) {
       result.push(parseScalarOrInline(after));
       i++;
@@ -2251,7 +2275,7 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
       const sibIndent = countLeadingSpaces(sib);
       if (sibIndent !== itemIndent) break;
       if (sib.slice(sibIndent).startsWith("- ")) break;
-      const sibKv = sib.slice(sibIndent).match(/^([\w][\w-]*):\s*(.*)$/);
+      const sibKv = sib.slice(sibIndent).match(/^([\w][\w.-]*)\s*:\s*(.*)$/);
       if (!sibKv) break;
       const sibKey = sibKv[1]!;
       const sibValue = sibKv[2]!.trim();
@@ -2287,6 +2311,36 @@ function parseArrayBlock(lines: string[], start: number, arrayIndent: number): {
   return { value: result, consumed: i - start };
 }
 
+/**
+ * Quote-aware split of an inline-array body on top-level commas
+ * (contract C4 / §1.2). A comma inside a single- or double-quoted string
+ * does not separate items, so `"a, b", c` → `['"a, b"', 'c']`. Quote
+ * chars are preserved in the parts; `parseScalarOrInline` strips them via
+ * `unquote`. Mirrors the web parser's `splitInlineArray`.
+ */
+function splitInlineArray(inner: string): string[] {
+  const parts: string[] = [];
+  let buf = "";
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i]!;
+    if (quote) {
+      buf += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      buf += ch;
+    } else if (ch === ",") {
+      parts.push(buf);
+      buf = "";
+    } else {
+      buf += ch;
+    }
+  }
+  parts.push(buf);
+  return parts;
+}
+
 /**
  * Parse a scalar or inline form (`[a, b]`, `{ k: v }`). Used for the
  * value portion of `key: value` lines.
@@ -2295,7 +2349,10 @@ function parseScalarOrInline(s: string): unknown {
   if (s.startsWith("[") && s.endsWith("]")) {
     const inner = s.slice(1, -1).trim();
     if (inner === "") return [];
-    return inner.split(",").map((part) => parseScalarOrInline(part.trim()));
+    // Quote-aware split (contract C4 / §1.2): a comma inside a quoted
+    // string is NOT an item separator, so `["a, b", c]` → 2 items, not 3.
+    // Matches the web parser's `splitInlineArray`.
+    return splitInlineArray(inner).map((part) => parseScalarOrInline(part.trim()));
   }
   if (s.startsWith("{") && s.endsWith("}")) {
     const inner = s.slice(1, -1).trim();
@@ -2376,18 +2433,59 @@ function unquote(s: string): unknown {
 // Directory walking — shared with obsidian.ts
 // ---------------------------------------------------------------------------
 
-/** Recursively list all .md files in a directory, excluding hidden dirs
- *  (including `.parachute/` and `.obsidian/`). */
+/**
+ * Markdown-file classification (contract §1.7). Case-insensitive `.md`
+ * OR `.markdown`. `.mdx`, `.txt`, etc. are NOT markdown for the importer.
+ * Identical to the web parser's classifier.
+ */
+export function isMarkdownExtension(path: string): boolean {
+  return /\.(md|markdown)$/i.test(path);
+}
+
+/**
+ * Named intake-excluded directory/entry segments (contract §1.9). The
+ * generic `startsWith(".")` rule below subsumes the dot-prefixed ones;
+ * the named set is kept explicit for readability + to cover
+ * `__MACOSX`/`node_modules` (which do not start with ".").
+ */
+const EXCLUDED_SEGMENTS = new Set([
+  ".obsidian",
+  ".trash",
+  ".git",
+  ".parachute",
+  "__MACOSX",
+  "node_modules",
+]);
+
+/**
+ * Intake (file-selection) exclusion (contract §1.9). Excludes a source
+ * path if ANY `/`-segment is a named-excluded entry OR starts with "."
+ * (generic dotfile/dotdir). Applied identically by both parsers before
+ * parsing. The generic dot rule means legit dot-prefixed user files
+ * (`.daily-note.md`) ARE excluded — the chosen, consistent behavior.
+ */
+export function isExcludedPath(sourcePath: string): boolean {
+  for (const segment of sourcePath.split("/")) {
+    if (segment === "") continue;
+    if (EXCLUDED_SEGMENTS.has(segment)) return true;
+    if (segment.startsWith(".")) return true;
+  }
+  return false;
+}
+
+/** Recursively list all .md / .markdown files in a directory, excluding
+ *  hidden + named-internal dirs per the canonical `isExcludedPath` rule
+ *  (`.parachute/`, `.obsidian/`, `node_modules`, …). Legacy import path. */
 export function walkMarkdownFiles(dir: string): string[] {
   const results: string[] = [];
   function walk(current: string) {
     for (const entry of readdirSync(current)) {
-      if (entry.startsWith(".")) continue;
-      if (entry === "node_modules") continue;
+      // Per-segment exclusion: the named set + generic dotfile rule.
+      if (EXCLUDED_SEGMENTS.has(entry) || entry.startsWith(".")) continue;
       const full = join(current, entry);
       const stat = statSync(full);
       if (stat.isDirectory()) walk(full);
-      else if (stat.isFile() && extname(entry).toLowerCase() === ".md") results.push(full);
+      else if (stat.isFile() && isMarkdownExtension(entry)) results.push(full);
     }
   }
   walk(dir);
@@ -2417,15 +2515,43 @@ export function walkContentFiles(dir: string): string[] {
   return results.sort();
 }
 
+/**
+ * Canonical inline-tag regex (contract §1.3). `#` at line-start or after
+ * whitespace; body chars `[A-Za-z0-9_/-]` (slash for hierarchy); the tag
+ * MUST contain ≥1 non-numeric char (the middle `[A-Za-z_/-]`), so `#2024`
+ * is NOT a tag but `#v2`, `#2024-plan`, `#area/sub` are. Identical to the
+ * web parser's `INLINE_HASHTAG`.
+ */
+const INLINE_TAG_REGEX = /(?:^|\s)#([A-Za-z0-9_/-]*[A-Za-z_/-][A-Za-z0-9_/-]*)/g;
+
+/**
+ * Normalize + slug-validate a tag value (contract §1.4). Shared by inline
+ * tag extraction and frontmatter tag extraction (obsidian.ts re-exports
+ * this) so both surfaces validate identically. Returns null when the
+ * value is unusable (non-string non-scalar, empty, or fails slug rules).
+ */
+export function normalizeTagValue(v: unknown): string | null {
+  if (typeof v === "number" || typeof v === "boolean") {
+    return String(v).toLowerCase();
+  }
+  if (typeof v !== "string") return null;
+  const stripped = v.trim().replace(/^#/, "").toLowerCase();
+  if (stripped === "") return null;
+  // Slug-validate: lowercase alnum, underscore, hyphen, slash (hierarchy).
+  if (!/^[a-z0-9_/-]+$/.test(stripped)) return null;
+  return stripped;
+}
+
 /** Extract inline #tags from markdown content. Excludes tags in code blocks. */
 export function extractInlineTags(content: string): string[] {
   let stripped = content.replace(/```[\s\S]*?```/g, "");
   stripped = stripped.replace(/`[^`\n]+`/g, "");
   const tags = new Set<string>();
-  const regex = /(?:^|\s)#([\w][\w/-]*[\w]|[\w])/gm;
+  const regex = new RegExp(INLINE_TAG_REGEX.source, INLINE_TAG_REGEX.flags);
   let match: RegExpExecArray | null;
   while ((match = regex.exec(stripped)) !== null) {
-    tags.add(match[1]!.toLowerCase());
+    const tag = normalizeTagValue(match[1]!);
+    if (tag) tags.add(tag);
   }
   return [...tags];
 }

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,

package/core/src/types.ts

@@ -1,9 +1,9 @@
-import type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 
 // ---- Re-exports ----
 
-export type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+export type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 export type { PrunedField } from "./indexed-fields.js";
 
 // ---- Note ----
@@ -25,6 +25,14 @@ export interface Note {
   updatedAt?: string;
   tags?: string[];
   links?: Link[];
+  /**
+   * Opt-in link degree (raw row count, both directions by default). Present
+   * only when the caller requests it via `include_link_count` (REST/MCP).
+   * Surfaced the same way `links`/`attachments` are — an extra key injected
+   * onto the response after the base shape. See `getLinkCounts` in links.ts
+   * for the exact degree semantics (self-loop = 2 under `both`).
+   */
+  linkCount?: number;
 }
 
 // ---- Link ----
@@ -59,6 +67,16 @@ export interface VaultStats {
   tagCount: number;
   attachmentCount: number;
   linkCount: number;
+  /**
+   * Total bytes of all note content, computed as the sum of the UTF-8 byte
+   * length of every note's `content`. The SQL uses `LENGTH(CAST(content AS
+   * BLOB))` deliberately: SQLite's bare `LENGTH(text)` returns the number of
+   * *characters*, not bytes, so a note full of multibyte UTF-8 (emoji, CJK,
+   * accents) would undercount its true on-disk/on-wire footprint. Casting to
+   * BLOB forces `LENGTH` to count raw bytes. This is the logical content size,
+   * not the physical DB-file size (see `usage.ts:dbBytes` for the latter).
+   */
+  contentBytes: number;
 }
 
 // ---- Query Options ----
@@ -115,6 +133,12 @@ export interface QueryOpts {
   // declared `indexed: true`; errors loudly otherwise. Direction is taken
   // from `sort` (default "asc") and `created_at` is appended as a stable
   // tiebreaker.
+  //
+  // The pseudo-field `link_count` is special-cased (no indexed-field
+  // declaration needed): it sorts by link DEGREE — the both-directions
+  // raw row count — using the same directional-sum definition as the
+  // `linkCount` response field, so the sort key equals the field value for
+  // every note (self-loops included). See `queryNotes`/`getLinkCounts`.
   orderBy?: string;
   limit?: number;
   offset?: number;
@@ -153,6 +177,8 @@ export interface NoteSummary {
   createdAt: string;
   updatedAt?: string;
   tags?: string[];
+  /** Opt-in link degree (see `Note.linkCount`). */
+  linkCount?: number;
 }
 
 /**
@@ -169,6 +195,8 @@ export interface NoteIndex {
   metadata?: Record<string, unknown>;
   byteSize: number;
   preview: string;
+  /** Opt-in link degree (see `Note.linkCount`). */
+  linkCount?: number;
 }
 
 /** Link with hydrated note summaries. */
@@ -313,7 +341,7 @@ export interface Store {
     patch: {
       description?: string | null;
       fields?: Record<string, TagFieldSchema> | null;
-      relationships?: Record<string, TagRelationship> | null;
+      relationships?: TagRelationshipMap | null;
       parent_names?: string[] | null;
     },
   ): Promise<TagRecord>;

package/package.json

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

package/src/auth.test.ts

@@ -26,7 +26,8 @@ import {
   hashKey,
 } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
-import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
+import { authenticateVaultRequest, authenticateGlobalRequest, warnLegacyGlobalApiKeys } from "./auth.ts";
+import type { StoredKey } from "./config.ts";
 
 let tmpHome: string;
 let prevHome: string | undefined;
@@ -442,3 +443,38 @@ describe("auth — VAULT_AUTH_TOKEN server-wide operator bearer", () => {
     expect("error" in result).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Legacy GLOBAL api_keys boot warning (security review — multi-user
+// hardening). Cross-vault credentials in config.yaml must be surfaced loudly
+// at boot, but never altered. Pure-function unit tests (no server boot).
+// ---------------------------------------------------------------------------
+describe("warnLegacyGlobalApiKeys (legacy cross-vault key boot warning)", () => {
+  function key(id: string): StoredKey {
+    return {
+      id,
+      label: id,
+      key_hash: `sha256:${id}`,
+      scope: "full",
+      created_at: new Date().toISOString(),
+    };
+  }
+
+  test("warns when global api_keys are present", () => {
+    const msgs: string[] = [];
+    const count = warnLegacyGlobalApiKeys([key("a"), key("b")], (m) => msgs.push(m));
+    expect(count).toBe(2);
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]).toContain("legacy GLOBAL api_key");
+    expect(msgs[0]).toContain("CROSS-VAULT");
+    // Heads-up only — must signal it does NOT alter the keys.
+    expect(msgs[0]).toContain("remain active");
+  });
+
+  test("silent when there are no global api_keys", () => {
+    const msgs: string[] = [];
+    expect(warnLegacyGlobalApiKeys([], (m) => msgs.push(m))).toBe(0);
+    expect(warnLegacyGlobalApiKeys(undefined, (m) => msgs.push(m))).toBe(0);
+    expect(msgs).toHaveLength(0);
+  });
+});

package/src/auth.ts

@@ -171,6 +171,35 @@ export function warnLegacyOnce(cacheKey: string, context: string): void {
   );
 }
 
+/**
+ * Boot-time warning for legacy GLOBAL `api_keys` in `config.yaml` (security
+ * review — multi-user hardening). Those keys are CROSS-VAULT credentials: a
+ * single key authenticates against EVERY vault on this server (see the global
+ * `api_keys` branch in `authenticate` ~L283). That predates per-vault keys +
+ * tag-scoped hub JWTs and is a confidentiality hazard once a server hosts
+ * multiple users' vaults — one user's global key reads another's vault.
+ *
+ * WARNING ONLY — never touches the keys (the operator owns them). The
+ * verification flagged 6 such keys on the live box; this surfaces them at
+ * boot so they're rotated/removed before multi-user sharing. Returns the
+ * count it warned about (0 = silent) so callers / tests can assert.
+ */
+export function warnLegacyGlobalApiKeys(
+  globalApiKeys: StoredKey[] | undefined,
+  warn: (msg: string) => void = console.warn,
+): number {
+  const count = globalApiKeys?.length ?? 0;
+  if (count === 0) return 0;
+  warn(
+    `[auth] WARNING: ${count} legacy GLOBAL api_key(s) found in config.yaml. ` +
+      "These are CROSS-VAULT credentials (each grants access to every vault on this server) " +
+      "and predate per-vault keys + tag-scoped hub JWTs. Before multi-user sharing, ROTATE or " +
+      "REMOVE them — a global key leaks one user's vault to another. They remain active (the " +
+      "operator owns them); this is a heads-up, not an automatic change.",
+  );
+  return count;
+}
+
 /** Read-only tools (the only tools allowed for "read" permission). */
 const READ_TOOLS = new Set([
   "query-notes",