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

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.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/config.ts

@@ -215,6 +215,17 @@ export interface TriggerWhen {
   missing_metadata?: string[];
   /** Note.metadata must have ALL of these keys set (non-null). */
   has_metadata?: string[];
+  /**
+   * Value-matched metadata predicate (vault#299 Part B). A map of
+   * field → operator-object, evaluated against the note's live metadata with
+   * the SAME operators as `query-notes` (eq/ne/gt/gte/lt/lte/in/not_in/exists)
+   * via the shared `matchesOperator` engine. ALL entries must match (AND).
+   * Lets a trigger fire only on a specific transition — e.g.
+   * `metadata: { state: { eq: "published" } }` fires when a note reaches
+   * `published`, not on every edit. Combines with the presence/tag/content
+   * filters above (all must hold).
+   */
+  metadata?: Record<string, Record<string, unknown>>;
 }
 
 /**

package/src/mcp-http.ts

@@ -151,6 +151,11 @@ async function handleMcp(
         note_path?: string | null;
         current_updated_at?: string | null;
         expected_updated_at?: string;
+        field?: string;
+        expected_from?: unknown;
+        to?: unknown;
+        current?: unknown;
+        violations?: unknown;
       };
       if (e?.code === "CONFLICT") {
         throw new McpError(ErrorCode.InvalidRequest, message, {
@@ -161,6 +166,28 @@ async function handleMcp(
           note_id: e.note_id,
         });
       }
+      // State-transition compare-and-set conflict (vault#299 Part B) — a
+      // DISTINCT vocabulary from `conflict` (settled lead #3): the value
+      // didn't match, not the updated_at token.
+      if (e?.code === "TRANSITION_CONFLICT") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "transition_conflict",
+          note_id: e.note_id,
+          path: e.note_path ?? null,
+          field: e.field,
+          expected_from: e.expected_from,
+          to: e.to,
+          current: e.current ?? null,
+        });
+      }
+      // Strict-schema rejection (vault#299 Part A) — one error carrying ALL
+      // per-field violations (settled lead #1).
+      if (e?.code === "SCHEMA_VALIDATION") {
+        throw new McpError(ErrorCode.InvalidParams, message, {
+          error_type: "schema_validation",
+          violations: e.violations ?? [],
+        });
+      }
       if (e?.code === "PRECONDITION_REQUIRED") {
         throw new McpError(ErrorCode.InvalidParams, message, {
           error_type: "precondition_required",

package/src/mcp-tools.ts

@@ -6,7 +6,7 @@
  */
 
 import { generateMcpTools } from "../core/src/mcp.ts";
-import type { McpToolDef } from "../core/src/mcp.ts";
+import type { McpToolDef, GenerateMcpToolsOpts } from "../core/src/mcp.ts";
 import { getNoteTags } from "../core/src/notes.ts";
 import type { Note } from "../core/src/types.ts";
 import {
@@ -16,7 +16,7 @@ import {
 } from "../core/src/vault-projection.ts";
 import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { hasScopeForVault, parseScopes, validateMintedScopes } from "./scopes.ts";
+import { hasScopeForVault, hasMigrateScopeForVault, parseScopes, validateMintedScopes, logStrictBypass } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
 import {
   expandTokenTagScope,
@@ -177,13 +177,25 @@ export function generateScopedMcpTools(
     ? { actor: auth.actor, via: auth.via === "operator" ? "operator" : "mcp" }
     : undefined;
 
+  // Migration-bypass (vault#299): a `vault:migrate`-scoped MCP session skips
+  // strict-schema enforcement and logs every bypassed write. Orthogonal to
+  // read/write/admin — an admin token does NOT bypass unless it also holds
+  // `migrate`. `onStrictBypass` writes the same structured log line the REST
+  // path uses (the audit-log table, #300, is deferred).
+  const strictBypass = auth ? hasMigrateScopeForVault(auth.scopes, vaultName) : false;
+  const onStrictBypass: GenerateMcpToolsOpts["onStrictBypass"] = strictBypass
+    ? (info) => logStrictBypass(info)
+    : undefined;
+
   const tools = generateMcpTools(
     store,
-    expandVisibility || nearTraversable || writeContext
+    expandVisibility || nearTraversable || writeContext || strictBypass
       ? {
           ...(expandVisibility ? { expandVisibility } : {}),
           ...(nearTraversable ? { nearTraversable } : {}),
           ...(writeContext ? { writeContext } : {}),
+          ...(strictBypass ? { strictBypass } : {}),
+          ...(onStrictBypass ? { onStrictBypass } : {}),
         }
       : undefined,
   );

package/src/routes.ts

@@ -21,7 +21,9 @@ import {
   contentRangeRequiresContent,
   type ContentRange,
 } from "../core/src/content-range.ts";
-import { attachValidationStatus } from "../core/src/mcp.ts";
+import { attachValidationStatus, enforceStrictWrite } from "../core/src/mcp.ts";
+import type { ValidationWarning } from "../core/src/schema-defaults.ts";
+import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import {
@@ -51,9 +53,45 @@ const NO_TAG_SCOPE: TagScopeCtx = { allowed: null, raw: null };
  * `store.createNote` / `store.updateNote`. Both null for paths without an auth
  * context (the no-op default). See `WriteContext` in core/src/notes.ts.
  */
-export type WriteCtx = { actor: string | null; via: string | null };
+export type WriteCtx = {
+  actor: string | null;
+  via: string | null;
+  /**
+   * Migration-bypass (vault#299). True when the caller holds `vault:migrate`
+   * — strict-schema enforcement is skipped and the bypass is logged. Defaults
+   * to false (full enforcement) for every normal write.
+   */
+  bypassStrict?: boolean;
+};
 
 const NO_WRITE_CTX: WriteCtx = { actor: null, via: null };
+
+/**
+ * Run the shared strict-schema gate for a REST write (vault#299). Mirrors the
+ * MCP path's `enforceStrict` closure: enforce unless the caller holds the
+ * migration-bypass scope, and log every bypassed write to the daemon's
+ * structured log (the audit-log table, #300, is deferred). Throws
+ * `SchemaValidationError` (caught by the route's catch → 422) when not bypassed.
+ */
+function gateStrictWrite(
+  store: Store,
+  writeCtx: WriteCtx,
+  shape: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+): void {
+  enforceStrictWrite(store, shape, {
+    bypass: writeCtx.bypassStrict === true,
+    onBypass: (violations: ValidationWarning[]) => {
+      logStrictBypass({
+        actor: writeCtx.actor,
+        via: writeCtx.via,
+        path: shape.path ?? null,
+        tags: shape.tags,
+        violations,
+      });
+    },
+  });
+}
+
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -1121,6 +1159,13 @@ async function handleNotesInner(
           const extension = item.extension !== undefined
             ? validateExtension(item.extension)
             : undefined;
+          // Strict-schema gate (vault#299) — reject before any write so a
+          // mid-batch violation rolls back via the outer BEGIN/ROLLBACK.
+          gateStrictWrite(store, writeCtx, {
+            path: item.path,
+            tags: item.tags,
+            metadata: item.metadata,
+          });
           const note = await store.createNote(item.content ?? "", {
             id: item.id,
             path: item.path,
@@ -1153,6 +1198,13 @@ async function handleNotesInner(
             409,
           );
         }
+        // Strict-schema rejection (vault#299 Part A) on create — 422.
+        if (e && e.code === "SCHEMA_VALIDATION") {
+          return json(
+            { error_type: "schema_validation", error: "schema_validation", violations: e.violations ?? [], message: e.message },
+            422,
+          );
+        }
         if (e && e.code === "INVALID_EXTENSION") {
           return json(
             { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
@@ -1410,6 +1462,12 @@ async function handleNotesInner(
             via: writeCtx.via,
           };
           const content = (body.content as string | undefined) ?? "";
+          // Strict-schema gate (vault#299) — if_missing:"create" is a create.
+          gateStrictWrite(store, writeCtx, {
+            path: createOpts.path ?? undefined,
+            tags: createOpts.tags,
+            metadata: createOpts.metadata,
+          });
           const created = await store.createNote(content, createOpts);
           if (tagsArr.length > 0) {
             await applySchemaDefaults(store, db, [created.id], tagsArr);
@@ -1499,7 +1557,19 @@ async function handleNotesInner(
         && body.createdAt === undefined
         && body.tags === undefined
         && body.links === undefined;
-      if (!isAppendOnly && body.if_updated_at === undefined && body.force !== true) {
+      // A state_transition is itself a compare-and-set precondition (vault#299
+      // Part B) — a transition-only PATCH needs no if_updated_at/force.
+      const isTransitionOnly = body.state_transition !== undefined
+        && !hasContent
+        && !hasAppendPrepend
+        && !hasContentEdit
+        && body.path === undefined
+        && body.metadata === undefined
+        && body.created_at === undefined
+        && body.createdAt === undefined
+        && body.tags === undefined
+        && body.links === undefined;
+      if (!isAppendOnly && !isTransitionOnly && body.if_updated_at === undefined && body.force !== true) {
         return json(
           {
             error_type: "precondition_required",
@@ -1591,6 +1661,33 @@ async function handleNotesInner(
       if (body.if_updated_at !== undefined) {
         updates.if_updated_at = body.if_updated_at;
       }
+      // Compare-and-set state transition (vault#299 Part B). Combinable with
+      // other field updates; folds into the same atomic UPDATE.
+      const stBody = body.state_transition as { field?: unknown; from?: unknown; to?: unknown } | undefined;
+      if (stBody !== undefined) {
+        if (typeof stBody.field !== "string" || stBody.field.length === 0) {
+          return json(
+            { error: "bad_request", message: "`state_transition.field` must be a non-empty string." },
+            400,
+          );
+        }
+        updates.state_transition = { field: stBody.field, from: stBody.from, to: stBody.to };
+      }
+
+      // --- Strict-schema gate (vault#299 Part A) ---
+      // Validate the PROSPECTIVE shape (final tags + merged metadata, incl. a
+      // state_transition's `to`) before the write so a rejection leaves the
+      // note untouched. Throws SchemaValidationError → 422 in the catch.
+      {
+        const removeSet = new Set<string>((body.tags?.remove as string[] | undefined) ?? []);
+        const projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
+        for (const t of (body.tags?.add as string[] | undefined) ?? []) projectedTags.add(t);
+        const baseMeta = updates.metadata ?? ((note.metadata as Record<string, unknown>) ?? {});
+        const projectedMeta = stBody !== undefined
+          ? { ...baseMeta, [stBody.field as string]: stBody.to }
+          : baseMeta;
+        gateStrictWrite(store, writeCtx, { path: note.path, tags: [...projectedTags], metadata: projectedMeta });
+      }
 
       if (Object.keys(updates).length > 0) {
         // Write-attribution (vault#298) — REST update. Stamp the most-recent-
@@ -1690,6 +1787,39 @@ async function handleNotesInner(
           409,
         );
       }
+      // State-transition compare-and-set conflict (vault#299 Part B). A
+      // DISTINCT error vocabulary from `conflict` (settled lead #3): the
+      // field VALUE didn't match `from`, not the updated_at token. 409.
+      if (e && e.code === "TRANSITION_CONFLICT") {
+        return json(
+          {
+            error_type: "transition_conflict",
+            error: "transition_conflict",
+            note_id: e.note_id,
+            path: e.note_path ?? null,
+            field: e.field,
+            expected_from: e.expected_from,
+            to: e.to,
+            current: e.current ?? null,
+            message: e.message,
+          },
+          409,
+        );
+      }
+      // Strict-schema rejection (vault#299 Part A). One error carrying ALL
+      // per-field violations (settled lead #1). 422 Unprocessable Entity —
+      // the note exists / request is well-formed but violates the contract.
+      if (e && e.code === "SCHEMA_VALIDATION") {
+        return json(
+          {
+            error_type: "schema_validation",
+            error: "schema_validation",
+            violations: e.violations ?? [],
+            message: e.message,
+          },
+          422,
+        );
+      }
       // Path-rename collision — schema's UNIQUE(path) tripped. Issue #126.
       if (e && e.code === "PATH_CONFLICT") {
         return json(

package/src/routing.ts

@@ -52,7 +52,7 @@ import {
   authenticateGlobalRequest,
   extractApiKey,
 } from "./auth.ts";
-import { hasScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
+import { hasScopeForVault, hasMigrateScopeForVault, SCOPE_ADMIN, SCOPE_READ, scopeForMethod, verbForMethod } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { handleScopedMcp } from "./mcp-http.ts";
 import {
@@ -818,7 +818,15 @@ export async function route(
   // `operator` for the env-var bearer). The REST surface IS the `api` channel,
   // so no refinement is needed here — the base via stands (the MCP handler is
   // the one that refines to `mcp`). Threaded only into the write handler.
-  const writeCtx: WriteCtx = { actor: auth.actor, via: auth.via };
+  // Migration-bypass (vault#299): a `vault:migrate`-scoped caller may write
+  // notes that violate `strict:true` field constraints (for backfill /
+  // migration). Every bypassed write is logged. Orthogonal to read/write/admin
+  // — an admin token does NOT bypass unless it also holds `migrate`.
+  const writeCtx: WriteCtx = {
+    actor: auth.actor,
+    via: auth.via,
+    bypassStrict: hasMigrateScopeForVault(auth.scopes, vaultName),
+  };
 
   if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope, writeCtx);
   // Live-query SSE subscription (design 2026-06-08). Snapshot + scoped live