@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/core/src/tag-expand-axis.test.ts

@@ -0,0 +1,301 @@
+/**
+ * Tag-expansion axis (`expand`) tests — vault tag `expand` axis
+ * (design `design/2026-06-09-tag-expand-axis.md`).
+ *
+ * Covers the query engine (`store.queryNotes` → `expandQueryTags` →
+ * `_tagsExpanded`) and the mode-aware core helpers
+ * (`getTagExpansion`/`getTagNamespace`). REST + MCP + SSE parity are exercised
+ * in their own suites (`routes`/`mcp` here, `subscribe`/`live-match` in src/).
+ *
+ * The corpus deliberately separates the two axes so a mode that confuses them
+ * fails loudly:
+ *   - `entity` is the SUBTYPE parent of `person` (declared via parent_names).
+ *     `person` is NOT name-prefixed `entity/`.
+ *   - `entity/archived` is NAME-prefixed under `entity` but is NOT a declared
+ *     subtype (no parent_names link to `entity`).
+ *   - `entity/person` is BOTH a declared subtype-child of `entity` AND
+ *     name-prefixed `entity/` — the dedupe case.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import {
+  loadTagHierarchy,
+  getTagExpansion,
+  getTagNamespace,
+  getTagDescendants,
+} from "./tag-hierarchy.js";
+
+let store: SqliteStore;
+let db: Database;
+
+/**
+ * Seed the two-axis corpus and return the set of note ids by their kind so
+ * tests can assert membership without depending on insertion order.
+ */
+async function seedTwoAxisCorpus(s: SqliteStore) {
+  // SUBTYPE axis: person is-a entity (declared), but NOT filed under entity/.
+  await s.upsertTagRecord("entity", { description: "an entity" });
+  await s.upsertTagRecord("person", { parent_names: ["entity"] });
+  // NAMESPACE axis: entity/archived is filed under entity/ but declares no
+  // parent_names (pure filing, no is-a edge).
+  await s.upsertTagRecord("entity/archived", {});
+  // BOTH axes: entity/person is a declared subtype-child AND name-prefixed.
+  await s.upsertTagRecord("entity/person", { parent_names: ["entity"] });
+
+  const nEntity = await s.createNote("literal entity", { tags: ["entity"] });
+  const nPerson = await s.createNote("a person (subtype)", { tags: ["person"] });
+  const nArchived = await s.createNote("filed under entity/", { tags: ["entity/archived"] });
+  const nBoth = await s.createNote("subtype AND filed", { tags: ["entity/person"] });
+  const nUnrelated = await s.createNote("unrelated", { tags: ["work"] });
+
+  return {
+    entity: nEntity.id,
+    person: nPerson.id,
+    archived: nArchived.id,
+    both: nBoth.id,
+    unrelated: nUnrelated.id,
+  };
+}
+
+const idsOf = (notes: { id: string }[]) => new Set(notes.map((n) => n.id));
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("tag expand axis — core helpers", () => {
+  it("getTagNamespace returns the tag + lexically prefixed names, no parent_names subtypes", async () => {
+    await seedTwoAxisCorpus(store);
+    const h = loadTagHierarchy(db);
+    const ns = getTagNamespace(h, "entity");
+    // tag itself + name-prefixed entity/*
+    expect(ns).toContain("entity");
+    expect(ns).toContain("entity/archived");
+    expect(ns).toContain("entity/person");
+    // `person` is a subtype but NOT name-prefixed → must be absent.
+    expect(ns.has("person")).toBe(false);
+  });
+
+  it("getTagExpansion: subtypes = descendants, namespace = lexical, both = union, exact = literal", async () => {
+    await seedTwoAxisCorpus(store);
+    const h = loadTagHierarchy(db);
+
+    const subtypes = getTagExpansion(h, "entity", "subtypes");
+    // descendants via parent_names: entity, person, entity/person — NOT entity/archived
+    expect(subtypes).toEqual(getTagDescendants(h, "entity"));
+    expect(subtypes).toContain("person");
+    expect(subtypes).toContain("entity/person");
+    expect(subtypes.has("entity/archived")).toBe(false);
+
+    const ns = getTagExpansion(h, "entity", "namespace");
+    expect(ns).toContain("entity/archived");
+    expect(ns).toContain("entity/person");
+    expect(ns.has("person")).toBe(false);
+
+    const both = getTagExpansion(h, "entity", "both");
+    // union: subtype-only person + namespace-only entity/archived + shared
+    expect(both).toContain("person");
+    expect(both).toContain("entity/archived");
+    expect(both).toContain("entity/person");
+
+    const exact = getTagExpansion(h, "entity", "exact");
+    expect(exact).toEqual(new Set(["entity"]));
+  });
+
+  it("dedupe: entity/person (subtype AND name-prefixed) appears once under both", async () => {
+    await seedTwoAxisCorpus(store);
+    const h = loadTagHierarchy(db);
+    const both = getTagExpansion(h, "entity", "both");
+    const count = Array.from(both).filter((t) => t === "entity/person").length;
+    expect(count).toBe(1);
+  });
+
+  it("store.expandTags mirrors the helper modes and unions multi-tag input", async () => {
+    await seedTwoAxisCorpus(store);
+    expect(await store.expandTags(["entity"], "exact")).toEqual(new Set(["entity"]));
+    const ns = await store.expandTags(["entity"], "namespace");
+    expect(ns).toContain("entity/archived");
+    expect(ns.has("person")).toBe(false);
+    // default (no mode) === subtypes === expandTagsWithDescendants
+    const def = await store.expandTags(["entity"]);
+    expect(def).toEqual(await store.expandTagsWithDescendants(["entity"]));
+  });
+});
+
+describe("tag expand axis — query engine", () => {
+  it("subtypes (default / absent) is a pure regression: descendants only, no namespaced sibling", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+
+    const absent = await store.queryNotes({ tags: ["entity"] });
+    const explicit = await store.queryNotes({ tags: ["entity"], expand: "subtypes" });
+
+    // Absent ≡ explicit "subtypes" — byte-identical result set.
+    expect(idsOf(explicit)).toEqual(idsOf(absent));
+
+    // Returns the literal + declared subtypes…
+    expect(idsOf(absent)).toEqual(new Set([ids.entity, ids.person, ids.both]));
+    // …and NOT the namespace-only sibling entity/archived.
+    expect(idsOf(absent).has(ids.archived)).toBe(false);
+  });
+
+  it("namespace returns tag + tag/* lexical, NOT parent_names-only subtypes", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "namespace" });
+    // entity (literal) + entity/archived + entity/person (name-prefixed)
+    expect(idsOf(res)).toEqual(new Set([ids.entity, ids.archived, ids.both]));
+    // `person` is a subtype but not name-prefixed → excluded.
+    expect(idsOf(res).has(ids.person)).toBe(false);
+  });
+
+  it("both = union of subtypes and namespace", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "both" });
+    expect(idsOf(res)).toEqual(
+      new Set([ids.entity, ids.person, ids.archived, ids.both]),
+    );
+  });
+
+  it("exact = literal tag only, no descendants", async () => {
+    const ids = await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "exact" });
+    expect(idsOf(res)).toEqual(new Set([ids.entity]));
+  });
+
+  it("dedupe: a note tagged with a both-axis tag is returned once under both", async () => {
+    await seedTwoAxisCorpus(store);
+    const res = await store.queryNotes({ tags: ["entity"], expand: "both" });
+    const bothCount = res.filter((n) => n.content === "subtype AND filed").length;
+    expect(bothCount).toBe(1);
+  });
+
+  it("_default magic stays subtypes-only: namespace on _default does NOT collapse to all notes", async () => {
+    // _default declared → universal subtype parent. With a namespaced child.
+    await store.upsertTagRecord("_default", { description: "universal" });
+    await store.upsertTagRecord("_default/scoped", {});
+    const nA = await store.createNote("a", { tags: ["alpha"] });
+    const nScoped = await store.createNote("scoped", { tags: ["_default/scoped"] });
+
+    // subtypes: _default expands to ALL tags → every note matches.
+    const sub = await store.queryNotes({ tags: ["_default"], expand: "subtypes" });
+    expect(idsOf(sub).has(nA.id)).toBe(true);
+
+    // namespace: _default is treated literally → only _default + _default/* —
+    // does NOT collapse to "all notes" (nA, tagged only `alpha`, is excluded).
+    const ns = await store.queryNotes({ tags: ["_default"], expand: "namespace" });
+    expect(idsOf(ns).has(nA.id)).toBe(false);
+    expect(idsOf(ns).has(nScoped.id)).toBe(true);
+  });
+
+  it("both + _default collapses to all-notes via the subtypes axis", async () => {
+    // `both` includes the subtypes axis, so the `_default` universal-parent
+    // magic must still fire — the union with the namespace axis can only widen
+    // the set, and subtypes alone already means "every note." Untagged notes
+    // included (the _default collapse drops the tag filter entirely).
+    await store.upsertTagRecord("_default", { description: "universal" });
+    const nTagged = await store.createNote("tagged", { tags: ["alpha"] });
+    const nUntagged = await store.createNote("untagged", {});
+
+    const res = await store.queryNotes({ tags: ["_default"], expand: "both" });
+    const got = idsOf(res);
+    expect(got.has(nTagged.id)).toBe(true);
+    expect(got.has(nUntagged.id)).toBe(true);
+    // Equivalent to the no-filter corpus.
+    const all = await store.queryNotes({});
+    expect(got).toEqual(idsOf(all));
+  });
+});
+
+describe("tag expand axis — MCP query-notes schema + handler", () => {
+  it("query-notes schema advertises the four expand values", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    const tools = generateMcpTools(store);
+    const q = tools.find((t) => t.name === "query-notes")!;
+    const props = (q.inputSchema as any).properties;
+    expect(props.expand).toBeDefined();
+    expect(props.expand.enum).toEqual(["subtypes", "namespace", "both", "exact"]);
+  });
+
+  it("query-notes handler honors expand=namespace", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    const ids = await seedTwoAxisCorpus(store);
+    const tools = generateMcpTools(store);
+    const q = tools.find((t) => t.name === "query-notes")!;
+    // Non-cursor structured query returns a flat array of note-index entries.
+    const res: any = await q.execute({ tag: "entity", expand: "namespace" });
+    const got = new Set<string>(res.map((n: any) => n.id));
+    expect(got).toEqual(new Set([ids.entity, ids.archived, ids.both]));
+    expect(got.has(ids.person)).toBe(false);
+  });
+
+  it("query-notes handler rejects an unknown expand value with INVALID_QUERY", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    const tools = generateMcpTools(store);
+    const q = tools.find((t) => t.name === "query-notes")!;
+    let err: any;
+    try {
+      await q.execute({ tag: "entity", expand: "bogus" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeDefined();
+    expect(err.code).toBe("INVALID_QUERY");
+  });
+});
+
+describe("tag expand axis — MCP search path honors expand", () => {
+  // Corpus shares the FTS term "fox" so search(tag=entity) differs ONLY by the
+  // expand axis — proving the search branch threads it into store.searchNotes.
+  async function seedSearchCorpus(s: SqliteStore) {
+    await s.upsertTagRecord("entity", { description: "entity root" });
+    await s.upsertTagRecord("person", { parent_names: ["entity"] }); // subtype, not name-prefixed
+    await s.upsertTagRecord("entity/archived", {}); // name-prefixed, not subtype
+    await s.createNote("fox literal", { tags: ["entity"] });
+    await s.createNote("fox subtype", { tags: ["person"] });
+    await s.createNote("fox filed", { tags: ["entity/archived"] });
+    await s.createNote("dog unrelated", { tags: ["entity"] }); // no "fox" → FTS excludes
+  }
+
+  it("search + tag, absent expand ≡ subtypes (descendants, no namespaced sibling)", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await seedSearchCorpus(store);
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    const absent: any = await q.execute({ search: "fox", tag: "entity", include_content: true });
+    const sub: any = await q.execute({ search: "fox", tag: "entity", expand: "subtypes", include_content: true });
+    const absentSet = new Set(absent.map((n: any) => n.content));
+    expect(new Set(sub.map((n: any) => n.content))).toEqual(absentSet);
+    expect(absentSet).toEqual(new Set(["fox literal", "fox subtype"]));
+  });
+
+  it("search + tag + expand=namespace returns lexical tag/*, NOT subtype sibling", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await seedSearchCorpus(store);
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    const res: any = await q.execute({ search: "fox", tag: "entity", expand: "namespace", include_content: true });
+    expect(new Set(res.map((n: any) => n.content))).toEqual(new Set(["fox literal", "fox filed"]));
+  });
+
+  it("search + tag + expand=exact returns only the literal-tagged match", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await seedSearchCorpus(store);
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    const res: any = await q.execute({ search: "fox", tag: "entity", expand: "exact", include_content: true });
+    expect(res.map((n: any) => n.content)).toEqual(["fox literal"]);
+  });
+
+  it("search + expand=bogus is rejected with INVALID_QUERY before the search runs", async () => {
+    const { generateMcpTools } = await import("./mcp.js");
+    await store.createNote("fox here", { tags: ["entity"] });
+    const q = generateMcpTools(store).find((t) => t.name === "query-notes")!;
+    let err: any;
+    try {
+      await q.execute({ search: "fox", tag: "entity", expand: "bogus" });
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeDefined();
+    expect(err.code).toBe("INVALID_QUERY");
+  });
+});

package/core/src/tag-hierarchy.ts

@@ -143,6 +143,86 @@ export function getTagDescendants(h: TagHierarchy, tag: string): Set<string> {
   return result;
 }
 
+/**
+ * Tag-expansion axis (vault tag `expand` axis — design
+ * `design/2026-06-09-tag-expand-axis.md`). A tag relates to others along two
+ * orthogonal axes; this selects which one (or both, or neither) a query expands
+ * along:
+ *
+ * - `"subtypes"` (DEFAULT): tag ∪ `parent_names` descendants. The semantic
+ *   is-a axis — today's always-on behavior, unchanged. `_default` universal
+ *   parent magic fires here.
+ * - `"namespace"`: tag ∪ {names lexically prefixed `tag/`}. The organizational
+ *   filing axis — purely lexical over the known tag set, no `parent_names`, no
+ *   `_default` magic.
+ * - `"both"`: union of subtypes and namespace.
+ * - `"exact"`: the literal tag only, no expansion.
+ */
+export type TagExpandMode = "subtypes" | "namespace" | "both" | "exact";
+
+export const TAG_EXPAND_MODES: readonly TagExpandMode[] = [
+  "subtypes",
+  "namespace",
+  "both",
+  "exact",
+] as const;
+
+export const DEFAULT_TAG_EXPAND_MODE: TagExpandMode = "subtypes";
+
+/**
+ * Lexical namespace expansion for a single tag: the tag itself plus every
+ * known tag name filed under it (`name === tag` OR `name` starts with
+ * `tag + "/"`). Purely a string-prefix match over `h.allTags` — namespacing is
+ * free-form (the slash in the tag *name*), declared nowhere, which is the whole
+ * point: subtyping is declared via `parent_names`, filing is not. No `_default`
+ * magic here — that's a subtypes-axis concept.
+ */
+export function getTagNamespace(h: TagHierarchy, tag: string): Set<string> {
+  // Pre-seeded with `tag` itself, so the loop only needs the strict `tag/*`
+  // prefix test (the `name === tag` case is already covered by the seed).
+  const result = new Set<string>([tag]);
+  const prefix = tag + "/";
+  for (const name of h.allTags) {
+    if (name.startsWith(prefix)) result.add(name);
+  }
+  return result;
+}
+
+/**
+ * Mode-aware single-tag expansion (vault tag `expand` axis). Returns the set of
+ * tag names a query for `tag` should match under `mode`. Always includes `tag`
+ * itself. Set semantics: a tag that is BOTH a declared subtype-child AND
+ * name-prefixed appears once.
+ *
+ * - `"subtypes"` → `getTagDescendants` (parent_names + `_default` magic).
+ * - `"namespace"` → `getTagNamespace` (lexical `tag/*`).
+ * - `"both"` → union of the two.
+ * - `"exact"` → `{tag}`.
+ */
+export function getTagExpansion(
+  h: TagHierarchy,
+  tag: string,
+  mode: TagExpandMode,
+): Set<string> {
+  switch (mode) {
+    case "exact":
+      return new Set<string>([tag]);
+    case "namespace":
+      return getTagNamespace(h, tag);
+    case "both": {
+      const union = new Set<string>(getTagDescendants(h, tag));
+      for (const name of getTagNamespace(h, tag)) union.add(name);
+      return union;
+    }
+    case "subtypes":
+    default:
+      // `default` is a defensive fallback — `TagExpandMode` already constrains
+      // the value to the four cases above; it can only be reached if an
+      // untyped caller passes a bad string.
+      return getTagDescendants(h, tag);
+  }
+}
+
 /**
  * Detect cycles in the declared hierarchy. Returns the list of tags
  * reachable from themselves via parent declarations. Used by

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;
@@ -100,7 +115,7 @@ export function listTagRecords(db: Database): TagRecord[] {
 export function getTagRecord(db: Database, tag: string): TagRecord | null {
   const row = db.prepare(
     "SELECT name, description, fields, relationships, parent_names, created_at, updated_at FROM tags WHERE name = ?",
-  ).get(tag) as TagRow | undefined;
+  ).get(tag) as TagRow | null;
   return row ? rowToRecord(row) : null;
 }
 
@@ -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 {
@@ -174,7 +189,7 @@ export function listTagSchemas(db: Database): TagSchema[] {
 export function getTagSchema(db: Database, tag: string): TagSchema | null {
   const row = db.prepare(
     "SELECT name, description, fields FROM tags WHERE name = ?",
-  ).get(tag) as { name: string; description: string | null; fields: string | null } | undefined;
+  ).get(tag) as { name: string; description: string | null; fields: string | null } | null;
   if (!row) return null;
   if (row.description === null && row.fields === null) return null;
   return {
@@ -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/triggers-store.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Unit tests for the persisted-triggers store (core/src/triggers-store.ts) —
+ * JSON encode/decode round-trip + upsert/list/get/delete semantics over an
+ * in-memory SQLite DB (schema v21).
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import {
+  upsertTrigger,
+  listTriggers,
+  getTrigger,
+  deleteTrigger,
+  loadAllTriggers,
+} from "./triggers-store.js";
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+
+function sample(name: string) {
+  return {
+    name,
+    events: ["created", "updated"] as Array<"created" | "updated">,
+    when: { tags: ["channel-message"], has_content: true },
+    action: {
+      webhook: "https://example.test/hook",
+      send: "json" as const,
+      timeout: 30000,
+      auth: { bearer: "jwt-token" },
+    },
+  };
+}
+
+describe("triggers-store", () => {
+  test("the triggers table exists after initSchema (v21)", () => {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='triggers'")
+      .get();
+    expect(row).toBeTruthy();
+  });
+
+  test("upsert → get round-trips the structured JSON columns", () => {
+    upsertTrigger(db, sample("inbound"));
+    const got = getTrigger(db, "inbound");
+    expect(got).not.toBeNull();
+    expect(got!.when).toEqual({ tags: ["channel-message"], has_content: true });
+    expect(got!.action.webhook).toBe("https://example.test/hook");
+    expect(got!.action.auth).toEqual({ bearer: "jwt-token" });
+    expect(got!.events).toEqual(["created", "updated"]);
+    expect(got!.created_at).toBeTruthy();
+    expect(got!.updated_at).toBeTruthy();
+  });
+
+  test("upsert by name replaces + preserves created_at, bumps updated_at", async () => {
+    const first = upsertTrigger(db, sample("inbound"));
+    // Ensure clock advances so updated_at differs.
+    await new Promise((r) => setTimeout(r, 5));
+    const second = upsertTrigger(db, {
+      ...sample("inbound"),
+      action: { webhook: "https://example.test/v2" },
+    });
+
+    expect(listTriggers(db)).toHaveLength(1);
+    expect(second.created_at).toBe(first.created_at);
+    expect(second.updated_at >= first.updated_at).toBe(true);
+    expect(getTrigger(db, "inbound")!.action.webhook).toBe("https://example.test/v2");
+  });
+
+  test("events defaults to [created, updated] when omitted", () => {
+    upsertTrigger(db, {
+      name: "no-events",
+      when: { tags: ["x"] },
+      action: { webhook: "https://example.test/hook" },
+    });
+    expect(getTrigger(db, "no-events")!.events).toEqual(["created", "updated"]);
+  });
+
+  test("list / loadAllTriggers return all rows ordered by name", () => {
+    upsertTrigger(db, sample("zebra"));
+    upsertTrigger(db, sample("alpha"));
+    expect(listTriggers(db).map((t) => t.name)).toEqual(["alpha", "zebra"]);
+    expect(loadAllTriggers(db).map((t) => t.name)).toEqual(["alpha", "zebra"]);
+  });
+
+  test("delete removes the row; returns false on a missing name", () => {
+    upsertTrigger(db, sample("inbound"));
+    expect(deleteTrigger(db, "inbound")).toBe(true);
+    expect(getTrigger(db, "inbound")).toBeNull();
+    expect(deleteTrigger(db, "inbound")).toBe(false);
+  });
+
+  test("getTrigger returns null for an unknown name", () => {
+    expect(getTrigger(db, "nope")).toBeNull();
+  });
+});