@openparachute/vault 0.3.3 → 0.4.3

package/core/src/store.ts

@@ -7,6 +7,19 @@ import * as tagSchemaOps from "./tag-schemas.js";
 import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
 import { HookRegistry } from "./hooks.js";
+import {
+  loadTagHierarchy,
+  getTagDescendants,
+  TAG_CONFIG_PREFIX,
+  DEFAULT_TAG_NAME,
+  type TagHierarchy,
+} from "./tag-hierarchy.js";
+import {
+  loadSchemaConfig,
+  validateNote as runValidateNote,
+  type ResolvedSchemas,
+  type ValidationStatus,
+} from "./schema-defaults.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -16,11 +29,67 @@ import { HookRegistry } from "./hooks.js";
 export class BunSqliteStore implements Store {
   public readonly hooks: HookRegistry;
 
+  // Lazy-built caches over the post-v14 `tags` table — hierarchy via
+  // parent_names, schema validation via `fields`. Null means "not yet
+  // loaded or invalidated"; the next read rebuilds. We invalidate
+  // synchronously inside the writers that mutate the source rows so reads
+  // after writes always see the post-write state.
+  private _tagHierarchy: TagHierarchy | null = null;
+  private _schemaConfig: ResolvedSchemas | null = null;
+
   constructor(public readonly db: Database, opts?: { hooks?: HookRegistry }) {
     initSchema(db);
     this.hooks = opts?.hooks ?? new HookRegistry();
   }
 
+  /**
+   * Lazy accessor for the `_tags/*` config-note hierarchy. First call after
+   * boot or after an invalidation does the scan; subsequent calls hit the
+   * cache. Returns the same object until invalidated, so callers can rely
+   * on identity for memoizing per-tag descendant sets.
+   */
+  private getTagHierarchy(): TagHierarchy {
+    if (!this._tagHierarchy) this._tagHierarchy = loadTagHierarchy(this.db);
+    return this._tagHierarchy;
+  }
+
+  /**
+   * Lazy accessor for the per-tag `fields` resolution. Same lifecycle as
+   * the tag hierarchy cache.
+   */
+  private getSchemaConfig(): ResolvedSchemas {
+    if (!this._schemaConfig) this._schemaConfig = loadSchemaConfig(this.db);
+    return this._schemaConfig;
+  }
+
+  /**
+   * Run the resolved schemas against a note and return the resulting
+   * validation status, or null when no schema applies. Public so the MCP
+   * layer can surface `validation_status` on create/update responses
+   * without re-importing the config loader.
+   */
+  validateNoteAgainstSchemas(note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> }): ValidationStatus | null {
+    return runValidateNote(this.getSchemaConfig(), note);
+  }
+
+  /**
+   * Drop the tag-hierarchy cache if the mutated path is in the `_tags/*`
+   * namespace. Called from create/update/delete — old path is passed
+   * alongside new for rename cases (a note moved out of `_tags/` should
+   * still invalidate).
+   *
+   * Post-v17 the schema-config cache is purely tag-driven — its
+   * invalidation hook is on `upsertTagSchema` / `upsertTagRecord` /
+   * `deleteTagSchema` / `deleteTag` (mutations of `tags.fields`).
+   */
+  private invalidateConfigCachesForPath(path: string | null | undefined, oldPath?: string | null): void {
+    const isTagConfig = (p: string | null | undefined): boolean =>
+      typeof p === "string" && p.startsWith(TAG_CONFIG_PREFIX);
+    if (isTagConfig(path) || isTagConfig(oldPath)) {
+      this._tagHierarchy = null;
+    }
+  }
+
   // ---- Notes ----
 
   async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
@@ -34,6 +103,7 @@ export class BunSqliteStore implements Store {
       resolveUnresolvedWikilinks(this.db, note.path, note.id);
     }
 
+    this.invalidateConfigCachesForPath(note.path);
     this.hooks.dispatch("created", note, this);
 
     return note;
@@ -55,6 +125,8 @@ export class BunSqliteStore implements Store {
     id: string,
     updates: {
       content?: string;
+      append?: string;
+      prepend?: string;
       path?: string;
       metadata?: Record<string, unknown>;
       created_at?: string;
@@ -70,8 +142,11 @@ export class BunSqliteStore implements Store {
 
     const note = noteOps.updateNote(this.db, id, updates);
 
-    if (updates.content !== undefined) {
-      syncWikilinks(this.db, id, updates.content);
+    // Wikilink sync runs against the *resulting* content. For append/prepend
+    // we don't have the new value pre-write — read it back off the returned
+    // note so a `[[Foo]]` introduced via append still creates the link.
+    if (updates.content !== undefined || updates.append !== undefined || updates.prepend !== undefined) {
+      syncWikilinks(this.db, id, note.content);
     }
 
     if (updates.path !== undefined && note.path) {
@@ -81,6 +156,12 @@ export class BunSqliteStore implements Store {
       resolveUnresolvedWikilinks(this.db, note.path, id);
     }
 
+    // Invalidate before the hook dispatch so any handler that re-queries
+    // the hierarchy from inside its own logic sees post-write state.
+    // `metadata` updates can change the `parents` field on a config note
+    // even when the path didn't change, so always invalidate when the
+    // current path is in a config namespace.
+    this.invalidateConfigCachesForPath(note.path, oldPath);
     this.hooks.dispatch("updated", note, this);
 
     return note;
@@ -122,14 +203,86 @@ export class BunSqliteStore implements Store {
   }
 
   async deleteNote(id: string): Promise<void> {
+    // Read before delete so we can invalidate config caches on the way out.
+    const existing = noteOps.getNote(this.db, id);
     noteOps.deleteNote(this.db, id);
+    if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
   }
 
   async queryNotes(opts: QueryOpts): Promise<Note[]> {
-    return noteOps.queryNotes(this.db, opts);
+    return noteOps.queryNotes(this.db, this.expandQueryTags(opts));
+  }
+
+  /**
+   * If `tags` are present, attach a parallel `_tagsExpanded` array where
+   * each input tag is replaced with `{tag} ∪ descendants(tag)`. The SQL
+   * builder uses this to widen the tag join from `name = ?` to
+   * `name IN (...)`, so a query for `#manual` matches notes tagged with
+   * any descendant declared via `tags.parent_names`.
+   *
+   * `_default` magic (vault#270): when a `_default` tag row exists in the
+   * vault, it's the implicit parent of every note (tagged or not). A query
+   * filter that names `_default` is therefore equivalent to "no tag filter
+   * at all" — but the precise treatment depends on `tagMatch`:
+   *
+   * - `all` (default, AND-semantics): `_default` is universally satisfied,
+   *   so it can be dropped from the tag list. Other tags' AND-semantics
+   *   still apply. If `_default` was the only entry, drop the filter
+   *   entirely so untagged notes match.
+   * - `any` (OR-semantics): `_default` matches every note, so the disjunction
+   *   collapses to "every note." Drop the filter entirely regardless of
+   *   what else was in the list (otherwise we'd narrow to the union of
+   *   the other tags' notes — wrong).
+   *
+   * Other filters (path, metadata, dates) still apply in both cases.
+   */
+  private expandQueryTags(opts: QueryOpts): QueryOpts {
+    if (!opts.tags || opts.tags.length === 0) return opts;
+    const hierarchy = this.getTagHierarchy();
+
+    let tags = opts.tags;
+    if (hierarchy.allTags.has(DEFAULT_TAG_NAME) && tags.includes(DEFAULT_TAG_NAME)) {
+      const match = opts.tagMatch ?? "all";
+      if (match === "any") {
+        const { tags: _drop, ..._rest } = opts;
+        return _rest as QueryOpts;
+      }
+      tags = tags.filter((t) => t !== DEFAULT_TAG_NAME);
+      if (tags.length === 0) {
+        const { tags: _drop, ..._rest } = opts;
+        return _rest as QueryOpts;
+      }
+      opts = { ...opts, tags };
+    }
+
+    if (hierarchy.childrenOf.size === 0) return opts;
+    const expanded = tags.map((t) => Array.from(getTagDescendants(hierarchy, t)));
+    return { ...opts, _tagsExpanded: expanded } as QueryOpts;
   }
 
   async searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Promise<Note[]> {
+    // Same hierarchy-expansion treatment as queryNotes — searching `#manual`
+    // should match notes tagged with any descendant tag. The underlying
+    // FTS path already uses `IN (...)` for tags, so we flatten the
+    // per-input expansions into a single union (search semantics are
+    // "any tag matches"). When `_default` is among the requested tags
+    // (and a `_default` row exists), the OR collapses to "every note" —
+    // drop the tag filter entirely so the search hits the full corpus
+    // and untagged notes are reachable.
+    if (opts?.tags && opts.tags.length > 0) {
+      const hierarchy = this.getTagHierarchy();
+      if (hierarchy.allTags.has(DEFAULT_TAG_NAME) && opts.tags.includes(DEFAULT_TAG_NAME)) {
+        const { tags: _drop, ..._rest } = opts;
+        return noteOps.searchNotes(this.db, query, _rest);
+      }
+      if (hierarchy.childrenOf.size > 0) {
+        const expanded = new Set<string>();
+        for (const t of opts.tags) {
+          for (const x of getTagDescendants(hierarchy, t)) expanded.add(x);
+        }
+        return noteOps.searchNotes(this.db, query, { ...opts, tags: Array.from(expanded) });
+      }
+    }
     return noteOps.searchNotes(this.db, query, opts);
   }
 
@@ -143,23 +296,52 @@ export class BunSqliteStore implements Store {
     noteOps.untagNote(this.db, noteId, tags);
   }
 
+  async expandTagsWithDescendants(tags: string[]): Promise<Set<string>> {
+    const expanded = new Set<string>();
+    if (tags.length === 0) return expanded;
+    const hierarchy = this.getTagHierarchy();
+    for (const t of tags) {
+      for (const x of getTagDescendants(hierarchy, t)) expanded.add(x);
+    }
+    return expanded;
+  }
+
   async listTags(): Promise<{ name: string; count: number }[]> {
     return noteOps.listTags(this.db);
   }
 
   async deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }> {
-    return noteOps.deleteTag(this.db, name);
+    const result = noteOps.deleteTag(this.db, name);
+    // The deleted tag may have been a parent or child in the hierarchy
+    // and may have declared `fields` powering schema validation.
+    this._tagHierarchy = null;
+    this._schemaConfig = null;
+    return result;
   }
 
   async renameTag(oldName: string, newName: string): Promise<noteOps.RenameTagResult> {
-    return noteOps.renameTag(this.db, oldName, newName);
+    const result = noteOps.renameTag(this.db, oldName, newName);
+    // Vault#240: the cascade rewrites parent_names in OTHER tag rows as
+    // part of the same transaction, plus tokens.scoped_tags and
+    // indexed_fields.declarer_tags. Both caches are tag-keyed, so they
+    // must be rebuilt regardless — the hierarchy by tag-set identity,
+    // the schema-config by parent_names + fields content.
+    this._tagHierarchy = null;
+    this._schemaConfig = null;
+    return result;
   }
 
   async mergeTags(
     sources: string[],
     target: string,
   ): Promise<{ merged: Record<string, number>; target: string }> {
-    return noteOps.mergeTags(this.db, sources, target);
+    const result = noteOps.mergeTags(this.db, sources, target);
+    // Source tags drop out of the hierarchy; downstream callers asking
+    // for descendants of target should pick up any merged children. Also
+    // bust the schema cache — `fields` declarations follow tag identity.
+    this._tagHierarchy = null;
+    this._schemaConfig = null;
+    return result;
   }
 
   // ---- Vault Stats ----
@@ -191,6 +373,11 @@ export class BunSqliteStore implements Store {
   async createNotes(inputs: noteOps.BulkNoteInput[]): Promise<Note[]> {
     const notes = noteOps.createNotes(this.db, inputs);
     for (const note of notes) {
+      // Bulk path needs the same config-cache invalidation as singleton
+      // createNote — without it, a batch that includes `_tags/*` notes
+      // would leave the hierarchy cache stale until the next singleton
+      // write happened to bust it.
+      this.invalidateConfigCachesForPath(note.path);
       this.hooks.dispatch("created", note, this);
     }
     return notes;
@@ -225,27 +412,94 @@ export class BunSqliteStore implements Store {
   }
 
   async upsertTagSchema(tag: string, schema: { description?: string; fields?: Record<string, tagSchemaOps.TagFieldSchema> }) {
-    return tagSchemaOps.upsertTagSchema(this.db, tag, schema);
+    const result = tagSchemaOps.upsertTagSchema(this.db, tag, schema);
+    // `fields` drives validation — bust the schema cache so the next
+    // create/update sees the new declarations.
+    this._schemaConfig = null;
+    return result;
   }
 
   async deleteTagSchema(tag: string) {
-    return tagSchemaOps.deleteTagSchema(this.db, tag);
+    const result = tagSchemaOps.deleteTagSchema(this.db, tag);
+    if (result) this._schemaConfig = null;
+    return result;
   }
 
   async getTagSchemaMap() {
     return tagSchemaOps.getTagSchemaMap(this.db);
   }
 
+  // ---- Tag Records (post-v14: full identity row) ----
+
+  async listTagRecords() {
+    return tagSchemaOps.listTagRecords(this.db);
+  }
+
+  async getTagRecord(tag: string) {
+    return tagSchemaOps.getTagRecord(this.db, tag);
+  }
+
+  /**
+   * Partial upsert of the full tag record. Any patch field left undefined
+   * is preserved; pass null to clear. Invalidates the tag-hierarchy cache
+   * when `parent_names` is touched.
+   */
+  async upsertTagRecord(
+    tag: string,
+    patch: {
+      description?: string | null;
+      fields?: Record<string, tagSchemaOps.TagFieldSchema> | null;
+      relationships?: Record<string, tagSchemaOps.TagRelationship> | null;
+      parent_names?: string[] | null;
+    },
+  ) {
+    const result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+    if (patch.parent_names !== undefined) {
+      // parent_names drives both query expansion (tag hierarchy) AND, post
+      // vault#270, schema inheritance — bust both caches.
+      this._tagHierarchy = null;
+      this._schemaConfig = null;
+    }
+    if (patch.fields !== undefined) {
+      this._schemaConfig = null;
+    }
+    // First-time creation of a tag row (e.g. an empty `_default` placeholder)
+    // changes the `_default` universal-parent gate even when no fields or
+    // parent_names are touched. Cheap to bust: caches rebuild on next read.
+    if (tag === "_default") {
+      this._tagHierarchy = null;
+      this._schemaConfig = null;
+    }
+    return result;
+  }
+
   // ---- Batch Wikilink Sync ----
 
   /**
    * Create a note without triggering wikilink sync.
    * Use this during bulk imports, then call syncAllWikilinks() after.
+   *
+   * Does **not** invalidate the `_tags/*` config cache — importers writing
+   * tag-hierarchy notes through this path must call `rebuildConfigCaches()`
+   * once the import is done. (Default importers follow `createNoteRaw` with
+   * `syncAllWikilinks`, so adding the cache rebuild there is the natural
+   * place.)
    */
   async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
     return noteOps.createNote(this.db, content, opts);
   }
 
+  /**
+   * Drop the config caches unconditionally. Used by bulk-import paths that
+   * skip per-note invalidation for throughput, and by importers that
+   * directly mutate `tags` / `tags.fields` outside the singleton write
+   * methods.
+   */
+  rebuildConfigCaches(): void {
+    this._tagHierarchy = null;
+    this._schemaConfig = null;
+  }
+
   /**
    * Sync wikilinks for all notes in the vault.
    * Efficient for bulk imports — call once after importing all notes.

package/core/src/tag-hierarchy.ts

@@ -0,0 +1,171 @@
+/**
+ * Tag hierarchy resolution from the `tags.parent_names` column.
+ *
+ * A `tags` row named `voice` with `parent_names = ["manual", "note"]`
+ * registers `voice` as a child of `manual` and `note`. Queries that ask for
+ * `tags: ["manual"]` then transparently match notes tagged `#voice` (or any
+ * other transitive descendant of `#manual`).
+ *
+ * History: pre-v14 vaults stored hierarchy in notes-as-config at
+ * `_tags/<name>`. The v14 migration (see core/src/schema.ts:migrateToV14)
+ * lifts those parent declarations onto the tags row and the resolver here
+ * was swapped accordingly. See parachute-patterns/patterns/tag-data-model.md.
+ *
+ * Resolution model:
+ * - Lazy: built on first access, cached on the store.
+ * - Invalidated synchronously when a tag's parent_names changes (see
+ *   `BunSqliteStore.invalidateTagCaches`).
+ * - Tags without parent_names are treated as root-level (no parents, no
+ *   children). They still match queries by their own name.
+ *
+ * Cycle handling:
+ * - Cycles in declared parents are tolerated at load — we don't reject the
+ *   config (we don't have a "fail loud" signal at boot from inside a query).
+ *   Descendant traversal uses a visited-set so a cycle can't loop forever;
+ *   the resolved descendant set is well-defined regardless.
+ */
+
+import { Database } from "bun:sqlite";
+
+export interface TagHierarchy {
+  /** tag → set of immediate child tags (those that declared `tag` as a parent). */
+  childrenOf: Map<string, Set<string>>;
+  /** Memoization cache: tag → set including the tag itself plus all transitive descendants. */
+  descendantsCache: Map<string, Set<string>>;
+  /**
+   * Every known tag name in the vault. Loaded once at hierarchy build so the
+   * `_default` universal-parent magic in `getTagDescendants` can answer
+   * "expand `_default` → every tag" without a second DB scan.
+   */
+  allTags: Set<string>;
+}
+
+/**
+ * Reserved tag name treated as the implicit universal parent of every other
+ * tag (vault#270). When a row named `_default` exists in the `tags` table,
+ * its schema applies to all notes — tagged or not — and tag-hierarchy queries
+ * for `_default` expand to the full tag list. The `tags.parent_names` column
+ * is never auto-mutated; the universal-parent property lives at resolve time.
+ */
+export const DEFAULT_TAG_NAME = "_default";
+
+/**
+ * Pre-v14 path prefix that marked a note as a tag-hierarchy declaration.
+ * Retained as an exported constant so call-sites that still need to know
+ * about historical `_tags/*` notes (cache-invalidation, importers) can
+ * reference a single source of truth.
+ */
+export const TAG_CONFIG_PREFIX = "_tags/";
+
+/**
+ * Decode a JSON-encoded `parent_names` column value, defending against
+ * malformed input. Non-string entries are dropped silently — the column
+ * is expected to be well-formed (we control all writers) but a single bad
+ * row shouldn't break the whole hierarchy resolution.
+ */
+function readParentNames(raw: string | null): string[] {
+  if (!raw) return [];
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((x): x is string => typeof x === "string" && x.length > 0);
+}
+
+/**
+ * Scan the `tags` table and build the parent→children adjacency map.
+ * Each row's `parent_names` JSON array contributes one edge per parent.
+ * Also collects every known tag name in `allTags` so the `_default`
+ * universal-parent leg in `getTagDescendants` can return the full tag list
+ * without a second scan.
+ */
+export function loadTagHierarchy(db: Database): TagHierarchy {
+  const rows = db.prepare(
+    `SELECT name, parent_names FROM tags`,
+  ).all() as { name: string; parent_names: string | null }[];
+
+  const childrenOf = new Map<string, Set<string>>();
+  const allTags = new Set<string>();
+
+  for (const row of rows) {
+    if (!row.name) continue;
+    allTags.add(row.name);
+    const parents = readParentNames(row.parent_names);
+    for (const parent of parents) {
+      let children = childrenOf.get(parent);
+      if (!children) {
+        children = new Set();
+        childrenOf.set(parent, children);
+      }
+      children.add(row.name);
+    }
+  }
+
+  return { childrenOf, descendantsCache: new Map(), allTags };
+}
+
+/**
+ * Return the tag plus all transitive descendants. Always includes the tag
+ * itself, so callers can use the result as a drop-in replacement for the
+ * input tag when expanding queries.
+ *
+ * Special case: `_default` is treated as the implicit parent of every tag
+ * (vault#270). When a row named `_default` exists in the `tags` table, this
+ * function returns the full set of known tag names — symmetric with the
+ * schema-inheritance model where `_default`'s fields apply to every note.
+ * When `_default` is *not* declared as a tag row, the call falls through to
+ * normal descendant traversal (which yields just `{_default}` since nothing
+ * lists it as a parent).
+ */
+export function getTagDescendants(h: TagHierarchy, tag: string): Set<string> {
+  const cached = h.descendantsCache.get(tag);
+  if (cached) return cached;
+
+  if (tag === DEFAULT_TAG_NAME && h.allTags.has(DEFAULT_TAG_NAME)) {
+    const universal = new Set<string>(h.allTags);
+    h.descendantsCache.set(tag, universal);
+    return universal;
+  }
+
+  const result = new Set<string>([tag]);
+  const stack = [tag];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    const children = h.childrenOf.get(current);
+    if (!children) continue;
+    for (const child of children) {
+      if (result.has(child)) continue;
+      result.add(child);
+      stack.push(child);
+    }
+  }
+
+  h.descendantsCache.set(tag, result);
+  return result;
+}
+
+/**
+ * Detect cycles in the declared hierarchy. Returns the list of tags
+ * reachable from themselves via parent declarations. Used by
+ * `update-tag` write paths to surface a warning to the caller without
+ * blocking the write — cycles are tolerated at runtime (descendant
+ * traversal uses a visited set), but they're almost always a config bug.
+ */
+export function findHierarchyCycles(h: TagHierarchy): string[] {
+  const cycles: string[] = [];
+  for (const tag of h.childrenOf.keys()) {
+    const descendants = getTagDescendants(h, tag);
+    if (descendants.has(tag) && descendants.size > 1) {
+      // tag reaches itself through a non-trivial path
+      const ownChildren = h.childrenOf.get(tag);
+      if (ownChildren) {
+        for (const child of ownChildren) {
+          if (getTagDescendants(h, child).has(tag)) {
+            cycles.push(tag);
+            break;
+          }
+        }
+      }
+    }
+  }
+  return cycles;
+}