@openparachute/vault 0.3.3 → 0.4.3

package/core/src/tag-schemas.ts

@@ -1,9 +1,18 @@
 /**
- * Tag schema CRUD — DB-backed storage for tag metadata schemas.
+ * Tag record CRUD — DB-backed storage for the per-tag identity row.
  *
- * Each tag can optionally have a schema that describes expected metadata
- * fields for notes with that tag. Schemas drive auto-population of defaults
- * and soft warnings on create/tag operations.
+ * Each tag row carries: human-readable description, indexed metadata field
+ * declarations (`fields`), typed-link relationship declarations
+ * (`relationships`), and the hierarchy parent list (`parent_names`).
+ * See parachute-patterns/patterns/tag-data-model.md.
+ *
+ * This module retains the historical `tag-schemas` filename and exports
+ * (`TagSchema`, `listTagSchemas`, `getTagSchema`, `upsertTagSchema`,
+ * `deleteTagSchema`, `getTagSchemaMap`) as a thin schema-only facade —
+ * callers that only care about `description + fields` keep working without
+ * change. New surface (`TagRecord`, `listTagRecords`, `getTagRecord`,
+ * `upsertTagRecord`) returns the full row including relationships and
+ * parent_names.
  */
 
 import { Database } from "bun:sqlite";
@@ -23,87 +32,278 @@ export interface TagFieldSchema {
   indexed?: boolean;
 }
 
+/**
+ * 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.
+ */
+export type TagRelCardinality = "one" | "optional" | "many" | "many-required";
+
+export const TAG_REL_CARDINALITIES: readonly TagRelCardinality[] = [
+  "one",
+  "optional",
+  "many",
+  "many-required",
+] as const;
+
+export interface TagRelationship {
+  target_tag: string;
+  cardinality: TagRelCardinality;
+  description?: string;
+}
+
+/**
+ * Schema-only view of a tag — the historical shape. Backwards-compatible
+ * with v13-and-earlier callers.
+ */
 export interface TagSchema {
   tag: string;
   description?: string;
   fields?: Record<string, TagFieldSchema>;
 }
 
-// DB row shape
-interface TagSchemaRow {
-  tag_name: string;
+/**
+ * Full tag record — schema + typed relationships + hierarchy parents.
+ */
+export interface TagRecord extends TagSchema {
+  relationships?: Record<string, TagRelationship>;
+  parent_names?: string[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+// DB row shape (post-v14 `tags` table).
+interface TagRow {
+  name: string;
   description: string | null;
   fields: string | null;
+  relationships: string | null;
+  parent_names: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// CRUD — full record
+// ---------------------------------------------------------------------------
+
+/** List all tag records, sorted by name. */
+export function listTagRecords(db: Database): TagRecord[] {
+  const rows = db.prepare(
+    "SELECT name, description, fields, relationships, parent_names, created_at, updated_at FROM tags ORDER BY name",
+  ).all() as TagRow[];
+  return rows.map(rowToRecord);
+}
+
+/** Get a single tag record, or null if the tag doesn't exist. */
+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;
+  return row ? rowToRecord(row) : null;
+}
+
+/**
+ * Upsert a tag record — partial update. Any field left `undefined` is
+ * preserved. Pass `null` explicitly to clear a column. Always touches
+ * `updated_at`; sets `created_at` on first insert.
+ */
+export function upsertTagRecord(
+  db: Database,
+  tag: string,
+  patch: {
+    description?: string | null;
+    fields?: Record<string, TagFieldSchema> | null;
+    relationships?: Record<string, TagRelationship> | null;
+    parent_names?: string[] | null;
+  },
+): TagRecord {
+  const now = new Date().toISOString();
+  db.prepare(
+    "INSERT OR IGNORE INTO tags (name, created_at, updated_at) VALUES (?, ?, ?)",
+  ).run(tag, now, now);
+
+  const existing = getTagRecord(db, tag);
+
+  const description =
+    patch.description === undefined ? (existing?.description ?? null) : patch.description;
+  const fields =
+    patch.fields === undefined
+      ? jsonOrNull(existing?.fields)
+      : jsonOrNull(patch.fields);
+  const relationships =
+    patch.relationships === undefined
+      ? jsonOrNull(existing?.relationships)
+      : jsonOrNull(patch.relationships);
+  const parent_names =
+    patch.parent_names === undefined
+      ? jsonOrNull(existing?.parent_names)
+      : jsonOrNull(patch.parent_names);
+
+  db.prepare(
+    `UPDATE tags
+       SET description = ?, fields = ?, relationships = ?, parent_names = ?, updated_at = ?
+     WHERE name = ?`,
+  ).run(description, fields, relationships, parent_names, now, tag);
+
+  return getTagRecord(db, tag)!;
 }
 
 // ---------------------------------------------------------------------------
-// CRUD
+// CRUD — schema-only facade (back-compat)
 // ---------------------------------------------------------------------------
 
-/** List all tag schemas. */
+/** List schema-only views for tags that have a description or fields set. */
 export function listTagSchemas(db: Database): TagSchema[] {
-  const rows = db.prepare("SELECT * FROM tag_schemas ORDER BY tag_name").all() as TagSchemaRow[];
-  return rows.map(rowToSchema);
+  const rows = db.prepare(
+    "SELECT name, description, fields FROM tags WHERE description IS NOT NULL OR fields IS NOT NULL ORDER BY name",
+  ).all() as { name: string; description: string | null; fields: string | null }[];
+  return rows.map((r) => ({
+    tag: r.name,
+    description: r.description ?? undefined,
+    fields: parseJson<Record<string, TagFieldSchema>>(r.fields),
+  }));
 }
 
-/** Get a single tag's schema, or null if none defined. */
+/**
+ * Schema-only view for a single tag. Returns null if the tag has neither
+ * a description nor fields (matches v13 behavior, where the absence of a
+ * `tag_schemas` row meant "no schema").
+ */
 export function getTagSchema(db: Database, tag: string): TagSchema | null {
-  const row = db.prepare("SELECT * FROM tag_schemas WHERE tag_name = ?").get(tag) as TagSchemaRow | undefined;
-  return row ? rowToSchema(row) : 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;
+  if (!row) return null;
+  if (row.description === null && row.fields === null) return null;
+  return {
+    tag: row.name,
+    description: row.description ?? undefined,
+    fields: parseJson<Record<string, TagFieldSchema>>(row.fields),
+  };
 }
 
 /** Get all schemas as a lookup map (tag → schema). Used by schema effects. */
-export function getTagSchemaMap(db: Database): Record<string, { description?: string; fields?: Record<string, TagFieldSchema> }> {
-  const schemas = listTagSchemas(db);
+export function getTagSchemaMap(
+  db: Database,
+): Record<string, { description?: string; fields?: Record<string, TagFieldSchema> }> {
   const map: Record<string, { description?: string; fields?: Record<string, TagFieldSchema> }> = {};
-  for (const s of schemas) {
+  for (const s of listTagSchemas(db)) {
     map[s.tag] = { description: s.description, fields: s.fields };
   }
   return map;
 }
 
 /**
- * Create or replace a tag schema (upsert).
- * Ensures the tag exists in the tags table first.
+ * Set or replace a tag's schema (description + fields). Other columns
+ * (`relationships`, `parent_names`) are left untouched. Idempotent.
  */
 export function upsertTagSchema(
   db: Database,
   tag: string,
   schema: { description?: string; fields?: Record<string, TagFieldSchema> },
 ): TagSchema {
-  // Ensure tag exists
-  db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)").run(tag);
-
-  const fieldsJson = schema.fields ? JSON.stringify(schema.fields) : null;
-  db.prepare(`
-    INSERT INTO tag_schemas (tag_name, description, fields)
-    VALUES (?, ?, ?)
-    ON CONFLICT(tag_name) DO UPDATE SET
-      description = excluded.description,
-      fields = excluded.fields
-  `).run(tag, schema.description ?? null, fieldsJson);
-
-  return getTagSchema(db, tag)!;
+  upsertTagRecord(db, tag, {
+    description: schema.description ?? null,
+    fields: schema.fields ?? null,
+  });
+  return getTagSchema(db, tag) ?? { tag, description: schema.description, fields: schema.fields };
 }
 
-/** Delete a tag's schema. Returns true if a schema was deleted. */
+/**
+ * Clear a tag's schema (description + fields). Returns true if anything
+ * was cleared. Other columns and the tag row itself are preserved — to
+ * delete the tag entirely, use `noteOps.deleteTag`.
+ */
 export function deleteTagSchema(db: Database, tag: string): boolean {
-  const result = db.prepare("DELETE FROM tag_schemas WHERE tag_name = ?").run(tag);
-  return result.changes > 0;
+  const before = getTagSchema(db, tag);
+  if (!before) return false;
+  db.prepare(
+    "UPDATE tags SET description = NULL, fields = NULL, updated_at = ? WHERE name = ?",
+  ).run(new Date().toISOString(), tag);
+  return true;
 }
 
 // ---------------------------------------------------------------------------
-// Helpers
+// Validation — typed relationships
 // ---------------------------------------------------------------------------
 
-function rowToSchema(row: TagSchemaRow): TagSchema {
-  let fields: Record<string, TagFieldSchema> | undefined;
-  if (row.fields) {
-    try { fields = JSON.parse(row.fields); } catch {}
+/**
+ * Validate a `relationships` payload before persisting. Returns the
+ * canonicalized object on success; throws Error with a user-readable
+ * message on the first violation. Rules:
+ *
+ *   - 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.
+ */
+export function validateRelationships(
+  raw: unknown,
+): Record<string, TagRelationship> {
+  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");
   }
+  const out: Record<string, TagRelationship> = {};
+  for (const [rel, decl] of Object.entries(raw as Record<string, unknown>)) {
+    if (!rel || typeof rel !== "string") {
+      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;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToRecord(row: TagRow): TagRecord {
   return {
-    tag: row.tag_name,
+    tag: row.name,
     description: row.description ?? undefined,
-    fields,
+    fields: parseJson<Record<string, TagFieldSchema>>(row.fields),
+    relationships: parseJson<Record<string, TagRelationship>>(row.relationships),
+    parent_names: parseJson<string[]>(row.parent_names),
+    created_at: row.created_at ?? undefined,
+    updated_at: row.updated_at ?? undefined,
   };
 }
+
+function parseJson<T>(raw: string | null): T | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  try { return JSON.parse(raw) as T; } catch { return undefined; }
+}
+
+function jsonOrNull(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    // Already-encoded payload (e.g. when copying from an existing row).
+    return value;
+  }
+  return JSON.stringify(value);
+}

package/core/src/types.ts

@@ -1,3 +1,9 @@
+import type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+
+// ---- Re-exports ----
+
+export type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+
 // ---- Note ----
 
 export interface Note {
@@ -41,6 +47,7 @@ export interface VaultStats {
   notesByMonth: { month: string; count: number }[];
   topTags: { tag: string; count: number }[];
   tagCount: number;
+  attachmentCount: number;
   linkCount: number;
 }
 
@@ -57,14 +64,35 @@ export interface QueryOpts {
   hasLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
+  // Restrict results to a specific set of note IDs. The MCP `near` query uses
+  // this to push graph-neighborhood scoping into the SQL WHERE clause so that
+  // LIMIT and ORDER BY apply to the filtered set, not the whole notes table.
+  // Empty array → no rows match (avoids `IN ()` syntax error).
+  ids?: string[];
   // Per-field metadata filter. Each value is either a primitive (exact
   // match, today's behavior) or an operator object — `{ eq, ne, gt, gte, lt,
   // lte, in, not_in, exists }` — which routes through the generated column
   // for the field. Operator queries require the field to be declared
   // `indexed: true` in a tag schema; undeclared fields error loudly.
   metadata?: Record<string, unknown>;
+  // Legacy shorthand: filters on `n.created_at` (vault ingestion time).
+  // Equivalent to `dateFilter: { field: "created_at", from, to }`. Kept
+  // as the common path; specifying both this and `dateFilter` rejects.
   dateFrom?: string;    // ISO date
   dateTo?: string;      // ISO date
+  // Generalized date range. `field` defaults to `created_at`; `updated_at`
+  // is also a recognized real column (the incremental-rebuild path —
+  // vault#285 1.5). Any other field must be declared `indexed: true` in a
+  // tag schema (so the SQL hits a real B-tree index, same contract as
+  // `metadata` operator queries and `orderBy`). Use this to filter on a
+  // *content* date — an email's received date, a meeting's scheduled
+  // date — rather than the ingestion timestamp, or on `updated_at` to ask
+  // "what changed since X."
+  dateFilter?: {
+    field?: string;
+    from?: string;
+    to?: string;
+  };
   sort?: "asc" | "desc";
   // Sort by an indexed metadata field instead of `created_at`. Must be
   // declared `indexed: true`; errors loudly otherwise. Direction is taken
@@ -114,7 +142,7 @@ export interface Store {
   getNote(id: string): Promise<Note | null>;
   getNoteByPath(path: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
   deleteNote(id: string): Promise<void>;
   queryNotes(opts: QueryOpts): Promise<Note[]>;
   searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Promise<Note[]>;
@@ -122,12 +150,31 @@ export interface Store {
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;
   untagNote(noteId: string, tags: string[]): Promise<void>;
+  /**
+   * Expand a set of tag names to the union of `{tag} ∪ descendants(tag)` for
+   * each input, using the `_tags/<name>` config-note hierarchy. Always
+   * includes each input tag in the result. Used by tag-scoped tokens to
+   * compute the effective allowlisted tag-set at auth time.
+   */
+  expandTagsWithDescendants(tags: string[]): Promise<Set<string>>;
   listTags(): Promise<{ name: string; count: number }[]>;
   deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }>;
   renameTag(
     oldName: string,
     newName: string,
-  ): Promise<{ renamed: number } | { error: "not_found" } | { error: "target_exists" }>;
+  ): Promise<
+    | {
+        renamed: number;
+        sub_tags_renamed: number;
+        parent_refs_updated: number;
+        tokens_updated: number;
+        indexed_field_declarers_updated: number;
+        notes_rewritten: number;
+        paths_renamed: number;
+      }
+    | { error: "not_found" }
+    | { error: "target_exists"; conflicting: string[] }
+  >;
   mergeTags(
     sources: string[],
     target: string,
@@ -151,12 +198,54 @@ export interface Store {
   traverseLinks(noteId: string, opts?: { max_depth?: number; relationship?: string }): Promise<{ noteId: string; depth: number; relationship: string; direction: "outbound" | "inbound" }[]>;
   findPath(sourceId: string, targetId: string, opts?: { max_depth?: number }): Promise<{ path: string[]; relationships: string[] } | null>;
 
-  // Tag schemas
-  listTagSchemas(): Promise<{ tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }[]>;
-  getTagSchema(tag: string): Promise<{ tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> } | null>;
-  upsertTagSchema(tag: string, schema: { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }): Promise<{ tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }>;
+  // Tag schemas — schema-only facade (description + fields). Back-compat
+  // surface for v13-and-earlier callers; reads/writes route through the
+  // post-v14 `tags` row directly.
+  listTagSchemas(): Promise<{ tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[]; indexed?: boolean }> }[]>;
+  getTagSchema(tag: string): Promise<{ tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[]; indexed?: boolean }> } | null>;
+  upsertTagSchema(tag: string, schema: { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[]; indexed?: boolean }> }): Promise<{ tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[]; indexed?: boolean }> }>;
   deleteTagSchema(tag: string): Promise<boolean>;
-  getTagSchemaMap(): Promise<Record<string, { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }>>;
+  getTagSchemaMap(): Promise<Record<string, { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[]; indexed?: boolean }> }>>;
+
+  // Tag records — full v14 identity row (description + fields + typed
+  // relationships + parent_names + timestamps). See
+  // parachute-patterns/patterns/tag-data-model.md.
+  listTagRecords(): Promise<TagRecord[]>;
+  getTagRecord(tag: string): Promise<TagRecord | null>;
+  /**
+   * Partial upsert. Any patch field left undefined is preserved; pass
+   * null to clear. Touching `parent_names` invalidates the tag-hierarchy
+   * cache. Returns the post-write row.
+   */
+  upsertTagRecord(
+    tag: string,
+    patch: {
+      description?: string | null;
+      fields?: Record<string, TagFieldSchema> | null;
+      relationships?: Record<string, TagRelationship> | null;
+      parent_names?: string[] | null;
+    },
+  ): Promise<TagRecord>;
+
+  // Schema validation (post-v17: backed by `tags.fields` only — the
+  // standalone note_schemas + schema_mappings subsystem retired in v17, see
+  // vault#267). Post vault#270 the resolver walks `parent_names` so a note's
+  // effective fields include all ancestors' declarations (first-in-walk wins
+  // on conflict, surfaced as `schema_conflict` warnings); a tag named
+  // `_default` is the implicit universal parent. Returns null when no
+  // ancestor declares any fields. The underlying resolver is in-memory after
+  // the first lazy load.
+  validateNoteAgainstSchemas(note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> }): {
+    schemas: string[];
+    warnings: {
+      field: string;
+      schema: string;
+      reason: "type_mismatch" | "enum_mismatch" | "schema_conflict";
+      message: string;
+      /** Set only on `schema_conflict` — the tag whose declaration was overridden. */
+      loser_schema?: string;
+    }[];
+  } | null;
 
   // Attachments
   addAttachment(noteId: string, path: string, mimeType: string, metadata?: Record<string, unknown>): Promise<Attachment>;