@openparachute/vault 0.3.3 → 0.4.0

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,
+  type TagHierarchy,
+} from "./tag-hierarchy.js";
+import {
+  loadSchemaConfig,
+  validateNote as runValidateNote,
+  type ResolvedSchemas,
+  type ValidationStatus,
+} from "./schema-defaults.js";
+import * as noteSchemaOps from "./note-schemas.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -16,11 +29,68 @@ 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) and the post-v15 `note_schemas` + `schema_mappings`
+  // tables (validation). Null means "not yet loaded or invalidated"; the
+  // next read rebuilds. We invalidate synchronously inside the writers
+  // that mutate the source tables 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 `note_schemas` + `schema_mappings` 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-v15 the schema-config cache is no longer note-driven — its
+   * invalidation hook is on `upsertNoteSchema` / `setSchemaMapping` /
+   * `deleteNoteSchema` / `deleteSchemaMapping` instead.
+   */
+  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 +104,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 +126,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 +143,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 +157,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 +204,50 @@ 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/*` config notes.
+   *
+   * No-op when no `_tags/*` notes exist (empty hierarchy → each tag
+   * expands to just itself, identical to the pre-expansion behavior).
+   */
+  private expandQueryTags(opts: QueryOpts): QueryOpts {
+    if (!opts.tags || opts.tags.length === 0) return opts;
+    const hierarchy = this.getTagHierarchy();
+    if (hierarchy.childrenOf.size === 0) return opts;
+    const expanded = opts.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").
+    if (opts?.tags && opts.tags.length > 0) {
+      const hierarchy = this.getTagHierarchy();
+      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 +261,45 @@ 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.
+    this._tagHierarchy = 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);
+    // Other tags' parent_names may reference oldName — though we don't
+    // rewrite those, the hierarchy cache should be rebuilt to pick up the
+    // new row identity.
+    this._tagHierarchy = 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.
+    this._tagHierarchy = null;
+    return result;
   }
 
   // ---- Vault Stats ----
@@ -191,6 +331,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/*` or
+      // `_schemas/*` notes would leave the cache stale until the next
+      // singleton write happened to bust it.
+      this.invalidateConfigCachesForPath(note.path);
       this.hooks.dispatch("created", note, this);
     }
     return notes;
@@ -236,16 +381,113 @@ export class BunSqliteStore implements Store {
     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) {
+      this._tagHierarchy = 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 populate `note_schemas` / `schema_mappings`.
+   */
+  rebuildConfigCaches(): void {
+    this._tagHierarchy = null;
+    this._schemaConfig = null;
+  }
+
+  // ---- Note schemas (post-v15: validation by path-prefix or tag) ----
+
+  async listNoteSchemas() {
+    return noteSchemaOps.listNoteSchemas(this.db);
+  }
+
+  async getNoteSchema(name: string) {
+    return noteSchemaOps.getNoteSchema(this.db, name);
+  }
+
+  /**
+   * Partial-upsert a note schema. Auto-creates the row if missing. Any
+   * patch field left undefined is preserved; pass null to clear. Empty
+   * `required: []` collapses to null. Invalidates the schema-config cache.
+   */
+  async upsertNoteSchema(name: string, patch: noteSchemaOps.NoteSchemaPatch) {
+    const result = noteSchemaOps.upsertNoteSchema(this.db, name, patch);
+    this._schemaConfig = null;
+    return result;
+  }
+
+  async deleteNoteSchema(name: string) {
+    const removed = noteSchemaOps.deleteNoteSchema(this.db, name);
+    if (removed) this._schemaConfig = null;
+    return removed;
+  }
+
+  async listSchemaMappings(opts?: noteSchemaOps.ListMappingsOpts) {
+    return noteSchemaOps.listSchemaMappings(this.db, opts ?? {});
+  }
+
+  async setSchemaMapping(
+    schema_name: string,
+    match_kind: noteSchemaOps.SchemaMappingKind,
+    match_value: string,
+  ) {
+    noteSchemaOps.setSchemaMapping(this.db, schema_name, match_kind, match_value);
+    this._schemaConfig = null;
+  }
+
+  async deleteSchemaMapping(
+    schema_name: string,
+    match_kind: noteSchemaOps.SchemaMappingKind,
+    match_value: string,
+  ) {
+    const removed = noteSchemaOps.deleteSchemaMapping(this.db, schema_name, match_kind, match_value);
+    if (removed) this._schemaConfig = null;
+    return removed;
+  }
+
   /**
    * 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,137 @@
+/**
+ * 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>>;
+}
+
+/**
+ * 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.
+ */
+export function loadTagHierarchy(db: Database): TagHierarchy {
+  const rows = db.prepare(
+    `SELECT name, parent_names FROM tags WHERE parent_names IS NOT NULL`,
+  ).all() as { name: string; parent_names: string | null }[];
+
+  const childrenOf = new Map<string, Set<string>>();
+
+  for (const row of rows) {
+    if (!row.name) continue;
+    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() };
+}
+
+/**
+ * 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.
+ */
+export function getTagDescendants(h: TagHierarchy, tag: string): Set<string> {
+  const cached = h.descendantsCache.get(tag);
+  if (cached) return cached;
+
+  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;
+}