@openparachute/vault 0.6.4-rc.2 → 0.6.4-rc.4

package/core/src/notes.ts

@@ -208,6 +208,50 @@ export class ConflictError extends Error {
   }
 }
 
+/**
+ * Thrown by `updateNote` when a `state_transition` precondition fails: the
+ * named metadata field's current value does not equal `from` (a missing field
+ * counts as a mismatch). Distinct from `ConflictError` (vault#299 settled lead
+ * #3) — a state-transition conflict is about a VALUE not matching, not a
+ * stale `updated_at` token, so it carries its own `transition_conflict` code
+ * and the from/to/current triple rather than the if_updated_at vocabulary.
+ *
+ * The check + set is one atomic conditional UPDATE (`... WHERE
+ * json_extract(metadata,'$.field') IS ?`), so two racing transitioners can't
+ * both observe `from` and both commit — exactly one wins, the other gets this.
+ */
+export class TransitionConflictError extends Error {
+  code = "TRANSITION_CONFLICT" as const;
+  note_id: string;
+  note_path: string | null;
+  field: string;
+  expected_from: unknown;
+  to: unknown;
+  current: unknown;
+
+  constructor(
+    noteId: string,
+    notePath: string | null,
+    field: string,
+    from: unknown,
+    to: unknown,
+    current: unknown,
+  ) {
+    super(
+      `transition_conflict: note "${noteId}" field "${field}" is ${JSON.stringify(
+        current ?? null,
+      )}, expected ${JSON.stringify(from)} to transition to ${JSON.stringify(to)}`,
+    );
+    this.name = "TransitionConflictError";
+    this.note_id = noteId;
+    this.note_path = notePath;
+    this.field = field;
+    this.expected_from = from;
+    this.to = to;
+    this.current = current;
+  }
+}
+
 /**
  * Thrown by `createNote` / `updateNote` when the requested path is already
  * taken by another note. Surfaces as 409 at the HTTP layer so clients can
@@ -375,6 +419,18 @@ export function updateNote(
      * note still exists, a `ConflictError` is thrown.
      */
     if_updated_at?: string;
+    /**
+     * Compare-and-set state transition (vault#299 Part B). Atomically: if the
+     * named metadata field currently equals `from`, set it to `to` and commit;
+     * otherwise throw `TransitionConflictError` (a missing field is a
+     * conflict). The check rides the same conditional UPDATE — an additional
+     * `AND json_extract(metadata,'$.<field>') IS ?` clause — so two racing
+     * transitioners can't both pass. Combinable with `metadata` (other field
+     * updates merge alongside the transition) and `if_updated_at` (both
+     * preconditions must hold). `from`/`to` are JSON scalars (string / number /
+     * boolean / null).
+     */
+    state_transition?: { field: string; from: unknown; to: unknown };
   },
 ): Note {
   if (updates.content !== undefined && (updates.append !== undefined || updates.prepend !== undefined)) {
@@ -463,16 +519,37 @@ export function updateNote(
     sets.push("extension = ?");
     values.push(updates.extension);
   }
+  // State-transition (vault#299 Part B). The `to` value must land in the
+  // metadata field. Two sub-cases keep the metadata write consistent:
+  //   - caller ALSO passed `metadata` (the MCP/REST layer merges before
+  //     calling): fold `to` into that object so the single `metadata = ?`
+  //     SET carries it. The transition value wins over a merged value for
+  //     the same field — the transition is the authoritative state write.
+  //   - caller passed NO `metadata`: use SQL `json_set` so the field is
+  //     updated in place without a read-merge-write (keeps it atomic).
+  // The atomic GUARD (current value == from) is appended to the WHERE below.
+  const st = updates.state_transition;
+  if (st !== undefined && updates.metadata !== undefined) {
+    (updates.metadata as Record<string, unknown>)[st.field] = st.to;
+  }
   if (updates.metadata !== undefined) {
     sets.push("metadata = ?");
     values.push(JSON.stringify(updates.metadata));
+  } else if (st !== undefined) {
+    // No metadata payload — set the single field via json_set. The path is
+    // bound as a parameter (mirrors the json_extract pattern elsewhere); the
+    // value is bound as a JSON-typed argument via `json(?)` so booleans /
+    // numbers / null land as their JSON types, not stringified text.
+    sets.push(`metadata = json_set(COALESCE(metadata, '{}'), ?, json(?))`);
+    values.push(`$.${jsonPathKey(st.field)}`, JSON.stringify(st.to));
   }
   if (updates.created_at !== undefined) {
     sets.push("created_at = ?");
     values.push(updates.created_at);
   }
 
-  // No-op: no SET fields. If a caller still passed `if_updated_at`, we
+  // No-op: no SET fields. If a caller still passed `if_updated_at` (and no
+  // state_transition — that always pushes a metadata SET above), we
   // need to validate the precondition; a conditional UPDATE that sets
   // updated_at to itself does exactly that atomically — even a no-net-
   // change UPDATE takes the write lock in WAL mode, so it still serializes
@@ -497,10 +574,23 @@ export function updateNote(
     sql += " AND updated_at IS ?";
     values.push(updates.if_updated_at);
   }
+  // State-transition guard (vault#299 Part B): the atomic compare. The UPDATE
+  // only fires when the stored field currently equals `from`; otherwise zero
+  // rows match and we raise TransitionConflictError below. `IS` (not `=`) so
+  // a `from: null` correctly matches a stored JSON null / missing field, and
+  // a non-null `from` never matches a NULL/missing field (= conflict).
+  if (st !== undefined) {
+    sql += ` AND json_extract(metadata, ?) IS json_extract(json(?), '$')`;
+    values.push(`$.${jsonPathKey(st.field)}`, JSON.stringify(st.from));
+  }
 
+  // A value-conditional WHERE (if_updated_at OR state_transition) needs
+  // RETURNING to distinguish "matched + updated" from "no match" — `.changes`
+  // is unreliable inside transactions (vault#261).
+  const conditional = updates.if_updated_at !== undefined || st !== undefined;
   let matched: { id: string } | null = null;
   try {
-    if (updates.if_updated_at !== undefined) {
+    if (conditional) {
       matched = db.prepare(`${sql} RETURNING id`).get(...values) as
         | { id: string }
         | null;
@@ -520,13 +610,47 @@ export function updateNote(
     throw err;
   }
 
-  if (updates.if_updated_at !== undefined && matched === null) {
-    throwConflictOrMissing(db, id, updates.if_updated_at);
+  if (conditional && matched === null) {
+    // No row matched. Disambiguate the cause, checking the if_updated_at
+    // precondition first (it's the cheaper, pre-existing contract), then the
+    // state-transition value, then not-found.
+    const row = db.prepare("SELECT updated_at, path, metadata FROM notes WHERE id = ?").get(id) as
+      | { updated_at: string | null; path: string | null; metadata: string | null }
+      | null;
+    if (!row) throw new Error(`Note not found: "${id}"`);
+    if (updates.if_updated_at !== undefined && row.updated_at !== updates.if_updated_at) {
+      throw new ConflictError(id, row.path, row.updated_at, updates.if_updated_at);
+    }
+    if (st !== undefined) {
+      // if_updated_at (if any) matched, so the mismatch is the transition.
+      let current: unknown;
+      try {
+        const meta = row.metadata ? JSON.parse(row.metadata) : {};
+        current = (meta as Record<string, unknown>)[st.field];
+      } catch {
+        current = undefined;
+      }
+      throw new TransitionConflictError(id, row.path, st.field, st.from, st.to, current);
+    }
+    // if_updated_at-only path that fell through (timestamp matched but row
+    // vanished mid-flight): preserve the prior contract.
+    throwConflictOrMissing(db, id, updates.if_updated_at!);
   }
 
   return getNote(db, id)!;
 }
 
+/**
+ * Build the dotted JSON-path key fragment for a metadata field name. Field
+ * names that contain characters JSON-path treats specially (`.`, `[`, `"`,
+ * etc.) are double-quoted; simple identifiers pass through bare. Mirrors the
+ * SQLite JSON1 path grammar.
+ */
+function jsonPathKey(field: string): string {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) return field;
+  return `"${field.replace(/"/g, '\\"')}"`;
+}
+
 function throwConflictOrMissing(db: Database, id: string, expected: string): never {
   const row = db.prepare("SELECT updated_at, path FROM notes WHERE id = ?").get(id) as
     | { updated_at: string | null; path: string | null }

package/core/src/query-operators.ts

@@ -188,3 +188,120 @@ export function buildOperatorClause(
     params,
   };
 }
+
+// ---------------------------------------------------------------------------
+// In-memory operator evaluation (vault#299 — value-matched triggers)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate an operator object against a single in-memory value — the
+ * non-SQL twin of {@link buildOperatorClause}. The trigger engine fires on a
+ * live `note.metadata` object (not a DB row), so it can't route through the
+ * indexed generated columns; this gives it the SAME operator vocabulary +
+ * semantics without re-implementing them. An object with multiple operators
+ * is AND-composed (`{ gt: 5, lt: 10 }`), matching the SQL clause builder.
+ *
+ * `value` is the field's current value (`undefined` when the field is
+ * absent). Semantics mirror the SQL builder, including the NULL/missing
+ * handling: `ne`/`not_in` treat an absent/null value as "matches" (the SQL
+ * `(col IS NULL OR ...)` shape); `eq: null` matches an absent/null value.
+ *
+ * Throws `QueryError` on an unknown operator or a malformed operand — the
+ * trigger validator surfaces it as a 400 at registration time.
+ */
+export function matchesOperator(
+  field: string,
+  value: unknown,
+  opObj: Record<string, unknown>,
+): boolean {
+  validateOperatorObject(field, opObj);
+  const absent = value === undefined || value === null;
+
+  for (const [op, operand] of Object.entries(opObj)) {
+    switch (op as QueryOp) {
+      case "eq":
+        if (operand === null) {
+          if (!absent) return false;
+        } else if (absent || !looseEquals(value, operand)) {
+          return false;
+        }
+        break;
+      case "ne":
+        if (operand === null) {
+          if (absent) return false;
+        } else if (!absent && looseEquals(value, operand)) {
+          return false;
+        }
+        break;
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        if (absent) return false;
+        const cmp = compareScalar(value, operand);
+        if (cmp === null) return false;
+        if (op === "gt" && !(cmp > 0)) return false;
+        if (op === "gte" && !(cmp >= 0)) return false;
+        if (op === "lt" && !(cmp < 0)) return false;
+        if (op === "lte" && !(cmp <= 0)) return false;
+        break;
+      }
+      case "in":
+      case "not_in": {
+        if (!Array.isArray(operand)) {
+          throw new QueryError(
+            `operator "${op}" on metadata field "${field}" expects an array`,
+            "INVALID_OPERATOR_VALUE",
+          );
+        }
+        const present = !absent && operand.some((o) => looseEquals(value, o));
+        if (op === "in" && !present) return false;
+        // not_in: absent/null matches (mirrors SQL `col IS NULL OR ...`).
+        if (op === "not_in" && present) return false;
+        break;
+      }
+      case "exists":
+        if (typeof operand !== "boolean") {
+          throw new QueryError(
+            `operator "exists" on metadata field "${field}" expects a boolean`,
+            "INVALID_OPERATOR_VALUE",
+          );
+        }
+        if (operand === !absent) break;
+        return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Loose scalar equality used by in-memory `eq`/`ne`/`in`. Matches SQLite's
+ * affinity-tolerant comparison closely enough for trigger value-matching:
+ * exact for same-type scalars; cross-type number/string compares by string
+ * form (`5` matches `"5"`), since metadata round-trips through JSON and a
+ * note may carry either shape.
+ */
+function looseEquals(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (
+    (typeof a === "number" || typeof a === "string") &&
+    (typeof b === "number" || typeof b === "string")
+  ) {
+    return String(a) === String(b);
+  }
+  return false;
+}
+
+/**
+ * Three-way comparison for ordered operators (gt/gte/lt/lte). Returns a
+ * negative/zero/positive number, or `null` when the operands aren't
+ * order-comparable (so the caller treats it as "no match"). Numbers compare
+ * numerically; strings lexicographically; mixed types don't compare.
+ */
+function compareScalar(a: unknown, b: unknown): number | null {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  return null;
+}

package/core/src/schema-defaults.ts

@@ -60,6 +60,33 @@ export interface SchemaField {
   type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
   enum?: string[];
   description?: string;
+  /**
+   * Strict enforcement opt-in (vault#299, Part A). Default `false` — when
+   * unset/false, ALL constraints on this field are advisory: violations
+   * surface as `validation_status` warnings and the write succeeds (the
+   * historical byte-identical behavior). When `true`, ALL declared
+   * constraints on this field (type + enum + required + cardinality) flip
+   * to hard write rejections, all-or-nothing per field (the Gitcoin team's
+   * call — "enum + required together, not enum alone"). Free-form fields
+   * (`notes`/`description`) on an otherwise-strict tag stay advisory by
+   * simply leaving `strict` off — strictness is per-field, not per-tag.
+   */
+  strict?: boolean;
+  /**
+   * Whether the field MUST be present (and non-null) on a note carrying this
+   * tag. Advisory under `strict:false` (a `required` violation surfaces as a
+   * `missing_required` warning); a hard rejection only when `strict:true`.
+   */
+  required?: boolean;
+  /**
+   * Cardinality constraint for the field's value. `"one"` (the implicit
+   * default) means a single scalar — an array value is a `cardinality`
+   * violation. `"many"` means the value must be an array. Advisory under
+   * `strict:false`; a hard rejection when `strict:true`. Distinct from the
+   * relationship cardinality vocabulary (that governs typed links, not
+   * metadata fields).
+   */
+  cardinality?: "one" | "many";
 }
 
 /**
@@ -83,19 +110,35 @@ export interface ValidationWarning {
   /**
    * `type_mismatch` — value's type contradicts the declared `type`.
    * `enum_mismatch` — string value not in the declared `enum`.
+   * `missing_required` — a `required` field is absent or null (vault#299).
+   * `cardinality_mismatch` — value's shape (scalar vs array) contradicts the
+   *   declared `cardinality` (vault#299).
    * `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";
+  reason:
+    | "type_mismatch"
+    | "enum_mismatch"
+    | "missing_required"
+    | "cardinality_mismatch"
+    | "schema_conflict";
   message: string;
   /**
    * `schema_conflict` only — the tag whose declaration was overridden. Set
-   * when `reason === "schema_conflict"`; absent on type/enum mismatches.
+   * when `reason === "schema_conflict"`; absent on other reasons.
    * Surfaces structurally so agents don't have to regex `message` to find
    * the loser.
    */
   loser_schema?: string;
+  /**
+   * `true` when this violation comes from a `strict:true` field (vault#299).
+   * A strict violation is an ENFORCEMENT error — the write path rejects it.
+   * Absent/false for advisory warnings (the historical guidance behavior).
+   * Surfaced structurally so the write path can split "block" from "warn"
+   * without re-deriving the field's strict flag.
+   */
+  strict?: boolean;
 }
 
 export interface ValidationStatus {
@@ -126,6 +169,9 @@ function parseFieldsJson(raw: string | null): Record<string, SchemaField> {
     if (typeof f.type === "string") field.type = f.type as SchemaField["type"];
     if (Array.isArray(f.enum)) field.enum = f.enum.filter((x): x is string => typeof x === "string");
     if (typeof f.description === "string") field.description = f.description;
+    if (f.strict === true) field.strict = true;
+    if (f.required === true) field.required = true;
+    if (f.cardinality === "one" || f.cardinality === "many") field.cardinality = f.cardinality;
     fields[k] = field;
   }
   return fields;
@@ -301,15 +347,23 @@ function valueMatchesType(value: unknown, type: SchemaField["type"]): boolean {
  * 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.
+ * followed by per-field violations.
  *
  * Rules per merged field:
+ * - `required` declared and value absent/null → `missing_required`
  * - Present and `type` declared and value's type doesn't match → `type_mismatch`
  * - Present and `enum` declared and value not in enum → `enum_mismatch`
+ * - Present and `cardinality` declared and shape (scalar vs array) wrong
+ *   → `cardinality_mismatch`
+ *
+ * Every violation carries `strict: true` iff its field declared `strict:true`
+ * (vault#299). The list itself is the SAME whether or not a field is strict —
+ * the difference is only the per-warning `strict` flag, which the write path
+ * uses to decide block-vs-warn. Under `strict:false` this is byte-identical to
+ * the historical advisory behavior PLUS the new `required`/`cardinality`
+ * advisory reasons (which fire for any field declaring those, strict or not).
  *
- * 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.
+ * Fields not declared by any ancestor's schema are ignored entirely.
  */
 export function validateNote(
   resolved: ResolvedSchemas,
@@ -322,9 +376,25 @@ export function validateNote(
   const warnings: ValidationWarning[] = [...resolution.conflicts];
 
   for (const [fieldName, { spec, sourceTag }] of resolution.mergedFields) {
-    if (!(fieldName in m)) continue;
-    const value = m[fieldName];
-    if (value === undefined || value === null) continue;
+    const strictFlag = spec.strict === true ? { strict: true } : {};
+    const present = fieldName in m;
+    const value = present ? m[fieldName] : undefined;
+    const absent = !present || value === undefined || value === null;
+
+    if (spec.required === true && absent) {
+      warnings.push({
+        field: fieldName,
+        schema: sourceTag,
+        reason: "missing_required",
+        message: `'${fieldName}' is required (tag '${sourceTag}')`,
+        ...strictFlag,
+      });
+      // A required field that's absent has no value to type/enum/cardinality
+      // check — the missing_required violation stands alone.
+      continue;
+    }
+
+    if (absent) continue;
 
     if (spec.type && !valueMatchesType(value, spec.type)) {
       warnings.push({
@@ -332,6 +402,7 @@ export function validateNote(
         schema: sourceTag,
         reason: "type_mismatch",
         message: `'${fieldName}' should be ${spec.type} (tag '${sourceTag}')`,
+        ...strictFlag,
       });
     }
 
@@ -341,9 +412,91 @@ export function validateNote(
         schema: sourceTag,
         reason: "enum_mismatch",
         message: `'${fieldName}' must be one of [${spec.enum.join(", ")}] (tag '${sourceTag}')`,
+        ...strictFlag,
       });
     }
+
+    if (spec.cardinality) {
+      const isArray = Array.isArray(value);
+      const wantMany = spec.cardinality === "many";
+      if (wantMany !== isArray) {
+        warnings.push({
+          field: fieldName,
+          schema: sourceTag,
+          reason: "cardinality_mismatch",
+          message: wantMany
+            ? `'${fieldName}' must be an array (cardinality 'many', tag '${sourceTag}')`
+            : `'${fieldName}' must be a single value, not an array (cardinality 'one', tag '${sourceTag}')`,
+          ...strictFlag,
+        });
+      }
+    }
   }
 
   return { schemas: resolution.effectiveTags, warnings };
 }
+
+// ---------------------------------------------------------------------------
+// Strict enforcement (vault#299)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by the write path when a note violates one or more `strict:true`
+ * field constraints. Carries ALL per-field violations in a single error (the
+ * settled design lead — one `SchemaValidationError`, not per-axis errors), so
+ * an agent sees the whole contract it broke in one response and can fix every
+ * field before retrying.
+ *
+ * Each entry is a `ValidationWarning` with `strict: true`. `code` is stable
+ * (`SCHEMA_VALIDATION`) for transport mapping (MCP error / HTTP 422).
+ */
+export class SchemaValidationError extends Error {
+  code = "SCHEMA_VALIDATION" as const;
+  violations: ValidationWarning[];
+
+  constructor(violations: ValidationWarning[]) {
+    const summary = violations
+      .map((v) => `${v.field}: ${v.reason}`)
+      .join("; ");
+    super(`schema_validation: ${violations.length} strict field violation(s) — ${summary}`);
+    this.name = "SchemaValidationError";
+    this.violations = violations;
+  }
+}
+
+/**
+ * Extract the enforcement-level (strict) subset of a validation status —
+ * the violations the write path must reject. Conflict warnings are advisory
+ * by nature (they describe operator schema disagreements, not note data) and
+ * are never enforced even when a field is strict. Returns `[]` when nothing
+ * strict was violated (the common case — the caller then proceeds with the
+ * write).
+ */
+export function strictViolations(status: ValidationStatus | null): ValidationWarning[] {
+  if (!status) return [];
+  return status.warnings.filter((w) => w.strict === true && w.reason !== "schema_conflict");
+}
+
+/**
+ * Validate-and-enforce: run `validateNote`, and if any `strict:true` field is
+ * violated, throw a single `SchemaValidationError` carrying every violation.
+ * Returns the full advisory `ValidationStatus` (or null) on success so the
+ * caller can still surface advisory warnings on the response. `bypass: true`
+ * skips the throw entirely (migration-bypass scope) — the caller is
+ * responsible for logging the bypass.
+ *
+ * The write path calls this BEFORE persisting so a rejection leaves the note
+ * untouched.
+ */
+export function enforceStrictSchema(
+  resolved: ResolvedSchemas,
+  note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+  opts?: { bypass?: boolean },
+): { status: ValidationStatus | null; violations: ValidationWarning[] } {
+  const status = validateNote(resolved, note);
+  const violations = strictViolations(status);
+  if (violations.length > 0 && opts?.bypass !== true) {
+    throw new SchemaValidationError(violations);
+  }
+  return { status, violations };
+}

package/core/src/tag-schemas.ts

@@ -30,6 +30,18 @@ export interface TagFieldSchema {
   // across declarers — all tags declaring this field must agree on both
   // `type` and `indexed`. See core/src/indexed-fields.ts for lifecycle.
   indexed?: boolean;
+  // Strict-enforcement opt-in (vault#299). Default false (advisory). When
+  // true, ALL declared constraints on this field (type + enum + required +
+  // cardinality) flip from validation_status warnings to hard write
+  // rejections — all-or-nothing per field. Stored verbatim in the `fields`
+  // JSON column; the resolver (schema-defaults.ts) interprets it.
+  strict?: boolean;
+  // The field must be present + non-null on a note carrying this tag.
+  // Advisory unless `strict:true`. vault#299.
+  required?: boolean;
+  // "one" (scalar, default) or "many" (array). Advisory unless `strict:true`.
+  // Distinct from relationship cardinality. vault#299.
+  cardinality?: "one" | "many";
 }
 
 /**

package/core/src/triggers-store.ts

@@ -27,6 +27,12 @@ export interface StoredTriggerWhen {
   has_content?: boolean;
   missing_metadata?: string[];
   has_metadata?: string[];
+  /**
+   * Value-matched metadata predicate (vault#299 Part B). field →
+   * operator-object, evaluated with the shared query-operators engine. See
+   * src/config.ts:TriggerWhen.metadata.
+   */
+  metadata?: Record<string, Record<string, unknown>>;
 }
 
 /** Webhook auth — only the bearer-JWT path for now. */

package/core/src/types.ts

@@ -2,6 +2,7 @@ import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 import type { TagExpandMode } from "./tag-hierarchy.js";
+import type { ValidationStatus } from "./schema-defaults.js";
 
 // ---- Re-exports ----
 
@@ -420,17 +421,7 @@ export interface Store {
   // `_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;
+  validateNoteAgainstSchemas(note: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> }): ValidationStatus | null;
 
   // Attachments
   addAttachment(noteId: string, path: string, mimeType: string, metadata?: Record<string, unknown>): Promise<Attachment>;

package/core/src/vault-projection.ts

@@ -369,6 +369,25 @@ export function projectionToMarkdown(args: {
     lines.push(`- No indexed metadata fields.`);
   }
 
+  // Strict fields (vault#299): surface the enforced contract so an agent knows
+  // BEFORE writing which fields hard-reject on violation (not just warn).
+  // Derived from each schema tag's effective fields carrying `strict: true`.
+  const strictLines: string[] = [];
+  for (const t of projection.tags) {
+    const strictNames = Object.entries(t.effective_fields)
+      .filter(([, spec]) => (spec as { strict?: boolean }).strict === true)
+      .map(([name]) => name);
+    if (strictNames.length > 0) {
+      strictLines.push(`  - #${t.name}: ${strictNames.join(", ")}`);
+    }
+  }
+  if (strictLines.length > 0) {
+    lines.push(
+      `- Strict fields (writes that violate these are REJECTED, not just warned — enum/type/required/cardinality enforced):`,
+    );
+    lines.push(...strictLines);
+  }
+
   lines.push("");
   lines.push("## Querying");
   lines.push("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.4-rc.2",
+  "version": "0.6.4-rc.4",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",