@openparachute/vault 0.4.0 → 0.4.4-rc.11

package/core/src/schema-defaults.ts

@@ -1,73 +1,105 @@
 /**
- * Schema validation: resolves which schemas apply to a note (by path prefix
- * or tag), then validates the note's metadata against each. Writes are
- * never blocked — schemas are guidance. The MCP/REST layer surfaces a
- * `validation_status` block on create/update responses with any warnings
- * the agent can act on (missing required, type mismatch, enum mismatch).
+ * Schema validation: walk the tags carried by a note (plus their ancestors via
+ * `parent_names`), look up each ancestor's `fields` declaration, merge them
+ * (first-in-walk wins on conflict), and validate the note's metadata against
+ * the merged field map. Writes are never blocked — schemas are guidance. The
+ * MCP/REST layer surfaces a `validation_status` block on create/update
+ * responses with any warnings the agent can act on (type mismatch, enum
+ * mismatch, schema conflict).
  *
- * Storage (post-v15): schemas live in the `note_schemas` table; mapping
- * rules live in `schema_mappings`. Authoring is via `update-note-schema`
- * + `set-schema-mapping` (MCP/REST). The legacy `_schemas/<name>` and
- * `_schema_defaults` notes are retired but left in place — inert after
- * v15 (no resolver reads them).
+ * Storage: schemas live as `fields` columns on the `tags` table — same row
+ * that already carries description, relationships, and parent_names. Authoring
+ * is via `update-tag` (MCP) or PATCH /api/tags/:name (REST).
+ *
+ * This was a two-table subsystem (`note_schemas` + `schema_mappings`) prior
+ * to v17 — see vault#267. Removed in v17 because zero operator vaults used
+ * the path-prefix mapping kind, and tag-mapped schemas were fully redundant
+ * with `tags.fields`. The single-axis tag-driven validation lives here.
+ *
+ * Inheritance (vault#270, 2026-05-09):
+ * - A note's effective ancestor set = union of {tag ∪ ancestors(tag)} for each
+ *   tag on the note, walking `parent_names` recursively (cycle-safe).
+ * - `_default` is an implicit universal parent: if a tag named `_default`
+ *   exists in the tags table, it's appended to every note's effective ancestor
+ *   set (including untagged notes). The `tags.parent_names` column is never
+ *   auto-mutated — the magic lives at resolve time only.
+ * - Conflict resolution: first-in-walk wins. The walk visits each note tag
+ *   in order, then DFS through its `parent_names` array in declaration order,
+ *   so "first-in-`parent_names`-array wins" is the operator-controlled
+ *   precedence. Conflicts surface as advisory `schema_conflict` warnings; no
+ *   write blocking.
+ * - `_default` can technically carry its own `parent_names` and the resolver
+ *   handles it (cycle guard + visited Set), but the resulting interaction is
+ *   non-obvious — `_default` is usually appended last, so its ancestors
+ *   become low-precedence. Treat `_default` as a root tag in normal use.
  *
  * Resolution model:
  * - Lazy: rebuilt on first access, cached on the store.
- * - Invalidated when `note_schemas` or `schema_mappings` are mutated
- *   (table writes, not note writes).
- * - When no mappings exist and nothing else matches, validation is a
- *   no-op (status omitted).
+ * - Invalidated when `tags.fields` or `tags.parent_names` is mutated, when a
+ *   tag is deleted, renamed, or merged.
+ * - When no ancestor declares fields, validation is a no-op (status omitted).
  */
 
 import { Database } from "bun:sqlite";
 
-// ---------------------------------------------------------------------------
-// Legacy path prefixes — kept exported for any historical caller that still
-// references them. No resolver code reads notes-as-config post-v15.
-// ---------------------------------------------------------------------------
-
-export const SCHEMA_CONFIG_PREFIX = "_schemas/";
-export const SCHEMA_DEFAULTS_PATH = "_schema_defaults";
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export interface SchemaField {
-  type?: "string" | "number" | "boolean" | "array" | "object";
+  /**
+   * Declared type for the field's metadata value. `"integer"` is distinct
+   * from `"number"` only at validation time — JSON has no separate integer
+   * type, so a JSON number with zero fractional part (`5`, `5.0`,
+   * `Number.isInteger(n) === true`) is accepted as integer and a non-zero
+   * fractional value (`5.5`) is rejected. This matches the indexed-fields
+   * `"integer"` storage type (TYPE_MAP) and removes the false-positive
+   * `type_mismatch` warning that previously fired on every integer-shaped
+   * field because the validator had no `"integer"` case. See vault#310.
+   */
+  type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
   enum?: string[];
   description?: string;
 }
 
-export interface SchemaDefinition {
-  name: string;
-  description?: string;
-  fields: Record<string, SchemaField>;
-  required: string[];
-}
-
-export interface SchemaDefaults {
-  /** Path prefix → schema name. Longest prefix wins on tie. */
-  pathPrefixes: Array<{ prefix: string; schema: string }>;
-  /** Tag → schema name. */
-  tagToSchema: Map<string, string>;
-}
-
+/**
+ * Tag-record snapshot used by the resolver. Loaded from the `tags` table once
+ * and cached on the store. `allTags` carries every known name (so `_default`
+ * existence checks and query expansion can be answered without a re-read).
+ */
 export interface ResolvedSchemas {
-  defaults: SchemaDefaults;
-  definitions: Map<string, SchemaDefinition>;
+  /** Set of all known tag names (for `_default` magic + presence checks). */
+  allTags: Set<string>;
+  /** Per-tag own fields (only entries with at least one declaration). */
+  tagToFields: Map<string, Record<string, SchemaField>>;
+  /** Per-tag `parent_names` (only entries with at least one parent declared). */
+  tagToParents: Map<string, string[]>;
 }
 
 export interface ValidationWarning {
   field: string;
+  /** Tag whose schema declared the violated field (or won the conflict). */
   schema: string;
-  /** "missing_required" | "type_mismatch" | "enum_mismatch" */
-  reason: "missing_required" | "type_mismatch" | "enum_mismatch";
+  /**
+   * `type_mismatch` — value's type contradicts the declared `type`.
+   * `enum_mismatch` — string value not in the declared `enum`.
+   * `schema_conflict` — two ancestors declared the same field with
+   * different specs; first-in-walk wins, the loser surfaces here so the
+   * operator can resolve the disagreement.
+   */
+  reason: "type_mismatch" | "enum_mismatch" | "schema_conflict";
   message: string;
+  /**
+   * `schema_conflict` only — the tag whose declaration was overridden. Set
+   * when `reason === "schema_conflict"`; absent on type/enum mismatches.
+   * Surfaces structurally so agents don't have to regex `message` to find
+   * the loser.
+   */
+  loser_schema?: string;
 }
 
 export interface ValidationStatus {
-  /** Schema names that matched the note (for transparency). */
+  /** Tag names whose schemas contributed at least one field to the merged map. */
   schemas: string[];
   /** Empty when all checks pass. */
   warnings: ValidationWarning[];
@@ -99,55 +131,34 @@ function parseFieldsJson(raw: string | null): Record<string, SchemaField> {
   return fields;
 }
 
-function parseRequiredJson(raw: string | null): string[] {
+function parseParentsJson(raw: string | null): string[] {
   if (!raw) return [];
-  try {
-    const parsed = JSON.parse(raw);
-    if (!Array.isArray(parsed)) return [];
-    return parsed.filter((x): x is string => typeof x === "string");
-  } catch {
-    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);
 }
 
 /**
- * Build the full resolution map from the `note_schemas` and `schema_mappings`
- * tables. Always returns a well-formed `ResolvedSchemas` even when the
- * tables are empty (empty maps).
+ * Build a resolution map from the `tags` table. Returns a well-formed
+ * `ResolvedSchemas` even when no tag declares fields (empty `tagToFields`).
  */
 export function loadSchemaConfig(db: Database): ResolvedSchemas {
-  const definitions = new Map<string, SchemaDefinition>();
-  const defRows = db.prepare(
-    `SELECT name, description, fields, required FROM note_schemas`,
-  ).all() as { name: string; description: string | null; fields: string | null; required: string | null }[];
-  for (const row of defRows) {
+  const allTags = new Set<string>();
+  const tagToFields = new Map<string, Record<string, SchemaField>>();
+  const tagToParents = new Map<string, string[]>();
+  const rows = db.prepare(
+    `SELECT name, fields, parent_names FROM tags`,
+  ).all() as { name: string; fields: string | null; parent_names: string | null }[];
+  for (const row of rows) {
     if (!row.name) continue;
-    definitions.set(row.name, {
-      name: row.name,
-      description: row.description ?? undefined,
-      fields: parseFieldsJson(row.fields),
-      required: parseRequiredJson(row.required),
-    });
-  }
-
-  const defaults: SchemaDefaults = {
-    pathPrefixes: [],
-    tagToSchema: new Map(),
-  };
-  const mappingRows = db.prepare(
-    `SELECT schema_name, match_kind, match_value FROM schema_mappings`,
-  ).all() as { schema_name: string; match_kind: string; match_value: string }[];
-  for (const row of mappingRows) {
-    if (row.match_kind === "path_prefix") {
-      defaults.pathPrefixes.push({ prefix: row.match_value, schema: row.schema_name });
-    } else if (row.match_kind === "tag") {
-      defaults.tagToSchema.set(row.match_value, row.schema_name);
-    }
+    allTags.add(row.name);
+    const fields = parseFieldsJson(row.fields);
+    if (Object.keys(fields).length > 0) tagToFields.set(row.name, fields);
+    const parents = parseParentsJson(row.parent_names);
+    if (parents.length > 0) tagToParents.set(row.name, parents);
   }
-  // Longest prefix wins — sort once at load so resolve is O(n) without re-sorts.
-  defaults.pathPrefixes.sort((a, b) => b.prefix.length - a.prefix.length);
-
-  return { defaults, definitions };
+  return { allTags, tagToFields, tagToParents };
 }
 
 // ---------------------------------------------------------------------------
@@ -155,41 +166,111 @@ export function loadSchemaConfig(db: Database): ResolvedSchemas {
 // ---------------------------------------------------------------------------
 
 /**
- * Find the schemas that apply to a note based on its path and tags. Returns
- * schema *names* in the order they were resolved (path-prefix first, then
- * each matching tag in declaration order). Names that don't have a row in
- * `note_schemas` are dropped.
+ * Walk-order accumulator for a single note's effective ancestor set. DFS
+ * through `parent_names` in declaration order, cycle-protected via a visited
+ * Set. The output array preserves first-encounter order so the field-merge
+ * pass can apply first-wins precedence.
+ *
+ * Exported so other consumers (vault projection, future hierarchy
+ * inspectors) can reuse the exact walk semantics rather than carrying
+ * their own copy. Mutating walks (push to `out`, add to `visited`) keep
+ * the implementation cheap; callers pass fresh accumulators.
  */
-export function resolveApplicableSchemas(
+export function walkAncestors(
+  startTag: string,
   resolved: ResolvedSchemas,
-  note: { path?: string | null; tags?: string[] },
-): string[] {
-  const names: string[] = [];
-  const seen = new Set<string>();
+  visited: Set<string>,
+  out: string[],
+): void {
+  if (visited.has(startTag)) return;
+  visited.add(startTag);
+  out.push(startTag);
+  const parents = resolved.tagToParents.get(startTag);
+  if (!parents) return;
+  for (const p of parents) {
+    walkAncestors(p, resolved, visited, out);
+  }
+}
 
-  if (note.path) {
-    for (const { prefix, schema } of resolved.defaults.pathPrefixes) {
-      if (note.path.startsWith(prefix)) {
-        if (!seen.has(schema) && resolved.definitions.has(schema)) {
-          names.push(schema);
-          seen.add(schema);
-        }
-        break; // longest match wins (sorted at load)
-      }
-    }
+interface MergedField {
+  spec: SchemaField;
+  sourceTag: string;
+}
+
+interface NoteResolution {
+  /** Walk-order tag list whose `fields` contributed at least one entry. */
+  effectiveTags: string[];
+  /** Field name → winning spec + source tag. First-in-walk wins. */
+  mergedFields: Map<string, MergedField>;
+  /** Conflict warnings — same field declared by ≥2 ancestors with diverging specs. */
+  conflicts: ValidationWarning[];
+}
+
+/**
+ * Resolve the effective schema for a note. Walks each note tag through its
+ * `parent_names` chain (cycle-safe), implicitly appends `_default` when the
+ * tag exists, and merges all encountered `fields` declarations with
+ * first-in-walk precedence. A note with no tags still picks up `_default`'s
+ * schema when one is declared.
+ *
+ * Internal — exported for tests. The public entry point is `validateNote`.
+ */
+export function resolveNoteSchemas(
+  resolved: ResolvedSchemas,
+  note: { tags?: string[] },
+): NoteResolution {
+  const visited = new Set<string>();
+  const order: string[] = [];
+
+  for (const tag of note.tags ?? []) {
+    walkAncestors(tag, resolved, visited, order);
+  }
+  if (resolved.allTags.has("_default")) {
+    walkAncestors("_default", resolved, visited, order);
   }
 
-  if (note.tags) {
-    for (const tag of note.tags) {
-      const schema = resolved.defaults.tagToSchema.get(tag);
-      if (schema && !seen.has(schema) && resolved.definitions.has(schema)) {
-        names.push(schema);
-        seen.add(schema);
+  const mergedFields = new Map<string, MergedField>();
+  const conflicts: ValidationWarning[] = [];
+
+  for (const tagName of order) {
+    const fields = resolved.tagToFields.get(tagName);
+    if (!fields) continue;
+    for (const [fieldName, spec] of Object.entries(fields)) {
+      const existing = mergedFields.get(fieldName);
+      if (!existing) {
+        mergedFields.set(fieldName, { spec, sourceTag: tagName });
+        continue;
       }
+      if (fieldSpecsEqual(existing.spec, spec)) continue;
+      conflicts.push({
+        field: fieldName,
+        schema: existing.sourceTag,
+        loser_schema: tagName,
+        reason: "schema_conflict",
+        message: `field '${fieldName}' has conflicting specs in ancestor tags '${existing.sourceTag}' (kept) and '${tagName}' (ignored)`,
+      });
     }
   }
 
-  return names;
+  const contributing = new Set<string>();
+  for (const { sourceTag } of mergedFields.values()) contributing.add(sourceTag);
+  const effectiveTags = order.filter((t) => contributing.has(t));
+
+  return { effectiveTags, mergedFields, conflicts };
+}
+
+function fieldSpecsEqual(a: SchemaField, b: SchemaField): boolean {
+  if (a.type !== b.type) return false;
+  if (!stringArraysEqual(a.enum, b.enum)) return false;
+  return true;
+}
+
+function stringArraysEqual(a: string[] | undefined, b: string[] | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
 }
 
 function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
@@ -199,6 +280,14 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
       return typeof value === "string";
     case "number":
       return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      // JSON has no separate integer type — `5.0` and `5` decode to the
+      // same JS Number. Accept any finite Number whose fractional part is
+      // zero; reject `5.5`, `NaN`, `Infinity`, and non-Number types.
+      // vault#310 (Gitcoin Brain drift detector emits JSON for diffs;
+      // without this case, every integer-typed field warned
+      // `type_mismatch` and buried the real warnings).
+      return typeof value === "number" && Number.isInteger(value);
     case "boolean":
       return typeof value === "boolean";
     case "array":
@@ -209,79 +298,52 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
 }
 
 /**
- * Validate a note's metadata against each applicable schema and collect
- * warnings. Validation is non-blocking — the caller decides what to do with
- * the warnings (currently: surface them on the create/update response).
+ * Validate a note's metadata against the merged schema. Returns null when no
+ * ancestor declares any fields (so the caller can omit `validation_status`
+ * entirely). Otherwise returns the status with conflict warnings prepended,
+ * followed by per-field type/enum mismatches.
  *
- * Rules per field:
- * - In `required` and absent → `missing_required`
+ * Rules per merged field:
  * - Present and `type` declared and value's type doesn't match → `type_mismatch`
  * - Present and `enum` declared and value not in enum → `enum_mismatch`
  *
- * Fields not declared in the schema are ignored entirely (this isn't a
- * "strict" validator — it's a guide).
+ * Fields not declared by any ancestor's schema are ignored entirely (this
+ * isn't a "strict" validator — it's a guide). There is no `required` concept
+ * (post-v17); declarations are advisory only.
  */
-export function validateMetadata(
+export function validateNote(
   resolved: ResolvedSchemas,
-  schemaNames: string[],
-  metadata: Record<string, unknown> | undefined,
-): ValidationStatus {
-  const warnings: ValidationWarning[] = [];
-  const m = metadata ?? {};
-
-  for (const name of schemaNames) {
-    const def = resolved.definitions.get(name);
-    if (!def) continue;
+  note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+): ValidationStatus | null {
+  const resolution = resolveNoteSchemas(resolved, note);
+  if (resolution.mergedFields.size === 0) return null;
 
-    for (const requiredField of def.required) {
-      if (!(requiredField in m) || m[requiredField] === undefined || m[requiredField] === null) {
-        warnings.push({
-          field: requiredField,
-          schema: name,
-          reason: "missing_required",
-          message: `'${requiredField}' is required by schema '${name}'`,
-        });
-      }
-    }
+  const m = note.metadata ?? {};
+  const warnings: ValidationWarning[] = [...resolution.conflicts];
 
-    for (const [fieldName, field] of Object.entries(def.fields)) {
-      if (!(fieldName in m)) continue;
-      const value = m[fieldName];
-      if (value === undefined || value === null) continue;
+  for (const [fieldName, { spec, sourceTag }] of resolution.mergedFields) {
+    if (!(fieldName in m)) continue;
+    const value = m[fieldName];
+    if (value === undefined || value === null) continue;
 
-      if (field.type && !valueMatchesType(value, field.type)) {
-        warnings.push({
-          field: fieldName,
-          schema: name,
-          reason: "type_mismatch",
-          message: `'${fieldName}' should be ${field.type} (schema '${name}')`,
-        });
-      }
+    if (spec.type && !valueMatchesType(value, spec.type)) {
+      warnings.push({
+        field: fieldName,
+        schema: sourceTag,
+        reason: "type_mismatch",
+        message: `'${fieldName}' should be ${spec.type} (tag '${sourceTag}')`,
+      });
+    }
 
-      if (field.enum && field.enum.length > 0 && typeof value === "string" && !field.enum.includes(value)) {
-        warnings.push({
-          field: fieldName,
-          schema: name,
-          reason: "enum_mismatch",
-          message: `'${fieldName}' must be one of [${field.enum.join(", ")}] (schema '${name}')`,
-        });
-      }
+    if (spec.enum && spec.enum.length > 0 && typeof value === "string" && !spec.enum.includes(value)) {
+      warnings.push({
+        field: fieldName,
+        schema: sourceTag,
+        reason: "enum_mismatch",
+        message: `'${fieldName}' must be one of [${spec.enum.join(", ")}] (tag '${sourceTag}')`,
+      });
     }
   }
 
-  return { schemas: schemaNames, warnings };
-}
-
-/**
- * Convenience: combine resolve + validate for a note. Returns null when no
- * schemas apply (so the caller can decide whether to omit the field on the
- * response or surface an empty status).
- */
-export function validateNote(
-  resolved: ResolvedSchemas,
-  note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
-): ValidationStatus | null {
-  const names = resolveApplicableSchemas(resolved, note);
-  if (names.length === 0) return null;
-  return validateMetadata(resolved, names, note.metadata);
+  return { schemas: resolution.effectiveTags, warnings };
 }