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

package/src/cli.ts

@@ -3345,11 +3345,17 @@ async function cmdExport(args: string[]) {
  */
 async function cmdSchema(args: string[] = []) {
   const sub = args[0];
+  if (sub === "migrate-field") {
+    await cmdSchemaMigrateField(args.slice(1));
+    return;
+  }
   if (sub !== "prune") {
-    console.error("Usage: parachute-vault schema prune [--vault <name>] [--dry-run|--apply|--yes]");
+    console.error("Usage: parachute-vault schema <prune|migrate-field> ...");
     console.error("\nSubcommands:");
-    console.error("  prune    Drop orphaned indexed-field columns whose declaring tags are gone.");
-    console.error("           Dry-run by default (--dry-run is an explicit alias); pass --apply (or --yes) to execute.");
+    console.error("  prune          Drop orphaned indexed-field columns whose declaring tags are gone.");
+    console.error("                 Dry-run by default (--dry-run is an explicit alias); pass --apply (or --yes) to execute.");
+    console.error("  migrate-field  Evolve a tag-schema field across existing notes (rename/remap/set-default/retype).");
+    console.error("                 Dry-run by default; pass --apply (or --yes) to write. See `schema migrate-field --help`.");
     process.exit(1);
   }
 
@@ -3416,6 +3422,154 @@ async function cmdSchema(args: string[] = []) {
   }
 }
 
+/**
+ * `parachute-vault schema migrate-field <tag> <field> --transform <spec>` —
+ * evolve a tag-schema field's type / values across the existing notes that
+ * carry the tag (vault#314). Dry-run by default — prints the count + a sample
+ * of what WOULD change and writes nothing; `--apply` (alias `--yes`) executes.
+ *
+ * Transform specs (the built-in set — issue #314):
+ *   rename:<newkey>          move the field's value to <newkey>, drop the old key
+ *   remap:<old>=<new>[,…]    rewrite enum-style values (repeatable / comma-sep)
+ *   set-default:<value>      fill the field where missing/null
+ *   set-default-invalid:<v>  set <v> where missing/null OR currently schema-invalid
+ *   to_string | to_int | to_number | to_boolean   retype the value
+ *
+ * The migration writes through `strict` enforcement (the migrate-bypass path,
+ * vault#299) so a freshly-declared strict field that the back-catalog violates
+ * doesn't block the rewrite, and every bypassed write is logged. Rewrites are
+ * attributed `migrate` (last_updated_*); created_* is preserved.
+ *
+ * Atomic by default: if any note's value can't be converted (e.g. `to_int` on
+ * "banana"), the apply aborts BEFORE writing anything and lists the offenders.
+ * Pass `--continue-on-error` for best-effort (write the convertible, skip the rest).
+ */
+async function cmdSchemaMigrateField(args: string[]) {
+  const usageLine =
+    "Usage: parachute-vault schema migrate-field <tag> <field> --transform <spec> [--vault <name>] [--apply|--yes] [--continue-on-error]";
+  if (args[0] === "--help" || args[0] === "-h") {
+    console.log(usageLine);
+    console.log("\nTransform specs:");
+    console.log("  rename:<newkey>          Move the field's value to <newkey>, drop the old key.");
+    console.log("  remap:<old>=<new>[,...]  Rewrite enum-style values (repeatable, comma-separated).");
+    console.log("  set-default:<value>      Set <value> on notes where the field is missing/null.");
+    console.log("  set-default-invalid:<v>  Set <v> where missing/null OR the current value is schema-invalid.");
+    console.log("  to_string | to_int | to_number | to_boolean   Retype the field's value.");
+    console.log("\nDry-run by default — prints the plan. Pass --apply (or --yes) to write.");
+    return;
+  }
+
+  let vaultName = "default";
+  let apply = false;
+  let continueOnError = false;
+  let transformSpec: string | undefined;
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--vault") {
+      const v = args[++i];
+      if (!v) { console.error("--vault requires a value."); process.exit(1); }
+      vaultName = v;
+    } else if (arg === "--transform") {
+      const v = args[++i];
+      if (!v) { console.error("--transform requires a value."); process.exit(1); }
+      transformSpec = v;
+    } else if (arg === "--apply" || arg === "--yes") {
+      apply = true;
+    } else if (arg === "--dry-run") {
+      // default; accept as an explicit affirmative
+    } else if (arg === "--continue-on-error") {
+      continueOnError = true;
+    } else if (arg.startsWith("--")) {
+      console.error(`Unknown flag for \`schema migrate-field\`: ${arg}`);
+      process.exit(1);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  const [tag, field] = positionals;
+  if (!tag || !field || !transformSpec) {
+    console.error(usageLine);
+    console.error("\n  <tag> <field> and --transform <spec> are all required.");
+    console.error("  Run `schema migrate-field --help` for the transform spec list.");
+    process.exit(1);
+  }
+
+  const { parseTransformSpec } = await import("../core/src/migrate-tag-field.ts");
+  let transform;
+  try {
+    transform = parseTransformSpec(transformSpec);
+  } catch (err) {
+    console.error(`Invalid --transform "${transformSpec}": ${(err as Error).message}`);
+    process.exit(1);
+  }
+
+  const config = readVaultConfig(vaultName);
+  if (!config) {
+    console.error(`Vault "${vaultName}" not found.`);
+    process.exit(1);
+  }
+
+  const { getVaultStore } = await import("./vault-store.ts");
+  const { migrateTagField } = await import("../core/src/migrate-tag-field.ts");
+  const { logStrictBypass } = await import("./scopes.ts");
+  const store = getVaultStore(vaultName);
+
+  const result = await migrateTagField(store, {
+    tag,
+    field,
+    transform: transform!,
+    apply,
+    continueOnError,
+    // The CLI is the operator path — it bypasses strict enforcement by nature
+    // (writes go through the store, not the scope-gated transport). Log every
+    // waived violation so the bypass is auditable, exactly as MW2 intends.
+    onStrictBypass: (info) => logStrictBypass(info),
+  });
+
+  const verb = result.applied ? "Migrated" : "Would migrate";
+  console.log(
+    `${verb} field "${result.field}" on #${result.tag} in vault "${vaultName}"${result.applied ? "" : " (dry-run)"}:`,
+  );
+  console.log(
+    `  scanned ${result.scanned} · ${result.applied ? "changed" : "would change"} ${result.changed} · unchanged ${result.unchanged} · errored ${result.errored}`,
+  );
+
+  if (result.sample.length > 0) {
+    console.log(`\n  ${result.applied ? "Changes" : "Sample of changes"} (${result.sample.length}${result.changed > result.sample.length ? ` of ${result.changed}` : ""}):`);
+    for (const c of result.sample) {
+      const ref = c.path ?? c.id;
+      if (c.renamedTo) {
+        console.log(`    ${ref}: ${field} → ${c.renamedTo} = ${JSON.stringify(c.after)}`);
+      } else {
+        console.log(`    ${ref}: ${JSON.stringify(c.before)} → ${JSON.stringify(c.after)}`);
+      }
+    }
+  }
+
+  if (result.errors.length > 0) {
+    console.log(`\n  Unconvertible (${result.errors.length}):`);
+    for (const e of result.errors) {
+      console.log(`    ${e.path ?? e.id}: ${e.error}`);
+    }
+    if (apply && !result.applied) {
+      console.log(
+        "\n  Aborted without writing — some notes can't be converted (atomic by default).",
+      );
+      console.log("  Fix the data, or re-run with --continue-on-error to migrate the rest.");
+      process.exit(1);
+    }
+  }
+
+  if (!apply && result.changed > 0) {
+    console.log("\n  Re-run with --apply (or --yes) to write these changes.");
+  }
+  if (result.changed === 0 && result.errored === 0) {
+    console.log("\n  Nothing to migrate — the back-catalog already conforms.");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Export-watch glue. The git-shell + commit-message logic lives in
 // `./export-watch.ts` for unit-testability; cli.ts just wires it in.
@@ -3961,6 +4115,13 @@ Schema maintenance:
   parachute-vault schema prune --apply                Execute the prune (alias: --yes). Co-declared
                                                        fields keep their column; a drop loses only
                                                        the index (data lives in notes.metadata).
+  parachute-vault schema migrate-field <tag> <field>  Evolve a tag-schema field across existing
+    --transform <spec>                                 notes (rename:<key>, remap:<old>=<new>,
+                                                       set-default:<v>, to_string/to_int/to_number/
+                                                       to_boolean). Dry-run by default — prints the
+                                                       plan; pass --apply (or --yes) to write.
+                                                       Writes through strict enforcement (migrate
+                                                       bypass). See \`schema migrate-field --help\`.
 
 ── Advanced / standalone ──────────────────────────────────────────────
 

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

package/src/scopes.test.ts

@@ -9,10 +9,12 @@ import {
   SCOPE_READ,
   SCOPE_WRITE,
   SCOPE_ADMIN,
+  SCOPE_MIGRATE,
   parseScopes,
   parseScopeFlags,
   hasScope,
   hasScopeForVault,
+  hasMigrateScopeForVault,
   findBroadVaultScopes,
   scopeForMethod,
   verbForMethod,
@@ -20,6 +22,28 @@ import {
   serializeScopes,
 } from "./scopes.ts";
 
+describe("hasMigrateScopeForVault — migration-bypass capability (vault#299)", () => {
+  test("broad vault:migrate satisfies any vault", () => {
+    expect(hasMigrateScopeForVault([SCOPE_MIGRATE], "default")).toBe(true);
+    expect(hasMigrateScopeForVault([SCOPE_MIGRATE], "anything")).toBe(true);
+  });
+
+  test("narrowed vault:<name>:migrate satisfies only that vault", () => {
+    expect(hasMigrateScopeForVault(["vault:gitcoin:migrate"], "gitcoin")).toBe(true);
+    expect(hasMigrateScopeForVault(["vault:gitcoin:migrate"], "default")).toBe(false);
+  });
+
+  test("admin does NOT imply migrate — orthogonal axis", () => {
+    expect(hasMigrateScopeForVault([SCOPE_ADMIN], "default")).toBe(false);
+    expect(hasMigrateScopeForVault(["vault:default:admin"], "default")).toBe(false);
+  });
+
+  test("no migrate scope → false", () => {
+    expect(hasMigrateScopeForVault([SCOPE_WRITE, SCOPE_READ], "default")).toBe(false);
+    expect(hasMigrateScopeForVault([], "default")).toBe(false);
+  });
+});
+
 describe("parseScopes", () => {
   test("returns [] for null or empty input", () => {
     expect(parseScopes(null)).toEqual([]);

package/src/scopes.ts

@@ -28,6 +28,19 @@ export const SCOPE_READ = "vault:read" as const;
 export const SCOPE_WRITE = "vault:write" as const;
 export const SCOPE_ADMIN = "vault:admin" as const;
 
+/**
+ * Migration-bypass scope (vault#299). A SEPARATE capability axis — NOT part
+ * of the read ⊇ write ⊇ admin inheritance chain. A token holding
+ * `vault:migrate` (broad) or `vault:<name>:migrate` (narrowed) may skip
+ * `strict:true` schema enforcement so existing non-conforming notes can be
+ * migrated/backfilled. It is deliberately orthogonal: an `admin` token does
+ * NOT auto-bypass strict validation — bypass must be an explicit, audited
+ * grant. A bypass write still needs `write` to actually mutate (migrate is an
+ * ADD-ON flag, not a write grant on its own). Every bypassed write is logged
+ * (see the write path) since #300 (the audit-log table) is deferred.
+ */
+export const SCOPE_MIGRATE = "vault:migrate" as const;
+
 /** All first-class vault scopes in inheritance order (lowest → highest). */
 export const VAULT_SCOPES = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN] as const;
 export type VaultScope = (typeof VAULT_SCOPES)[number];
@@ -137,6 +150,56 @@ export function hasScopeForVault(
   return false;
 }
 
+/**
+ * Migration-bypass check (vault#299): does `granted` hold the `migrate`
+ * capability for `vaultName`? Accepts broad `vault:migrate` (any vault) or
+ * narrowed `vault:<name>:migrate` (this vault only). Orthogonal to the
+ * read/write/admin verbs — a plain admin token returns `false` here, by
+ * design. The migrate scope does NOT live in `decomposeVaultScope` (it isn't a
+ * read/write/admin verb), so it's matched by exact shape here.
+ */
+export function hasMigrateScopeForVault(granted: string[], vaultName: string): boolean {
+  for (const s of granted) {
+    if (s === SCOPE_MIGRATE) return true; // broad — any vault
+    if (s === `vault:${vaultName}:migrate`) return true; // narrowed — this vault
+  }
+  return false;
+}
+
+/**
+ * Structured log line for a migration-bypassed write (vault#299 settled lead
+ * #2). Records WHO bypassed (actor/via from MW1 attribution), WHAT note, and
+ * WHICH strict violations were waived — enough to reconstruct the bypass for
+ * later audit without the #300 audit-log table (deferred). One JSON line so
+ * it's grep/jq-able in the daemon log. Lives here (next to the migrate-scope
+ * check) so both write transports — REST (routes.ts) and MCP (mcp-tools.ts) —
+ * emit the identical line without importing each other.
+ */
+export function logStrictBypass(info: {
+  actor: string | null;
+  via: string | null;
+  path?: string | null;
+  tags?: string[];
+  violations: { field: string; reason: string; schema: string }[];
+}): void {
+  console.warn(
+    "[schema-bypass] " +
+      JSON.stringify({
+        event: "strict_schema_bypass",
+        actor: info.actor,
+        via: info.via,
+        path: info.path ?? null,
+        tags: info.tags ?? [],
+        violations: info.violations.map((v) => ({
+          field: v.field,
+          reason: v.reason,
+          schema: v.schema,
+        })),
+        at: new Date().toISOString(),
+      }),
+  );
+}
+
 /**
  * Pick the required scope for a given API request.
  *   - GET/HEAD/OPTIONS → read

package/src/triggers-api.ts

@@ -30,6 +30,7 @@ import {
   type TriggerInput,
 } from "../core/src/triggers-store.ts";
 import { registerVaultTrigger } from "./triggers.ts";
+import { SUPPORTED_OPS } from "../core/src/query-operators.ts";
 import { hasScopeForVault, SCOPE_ADMIN } from "./scopes.ts";
 import type { AuthResult } from "./auth.ts";
 
@@ -135,6 +136,29 @@ function validateInput(body: unknown):
   if (typeof b.when !== "object" || b.when === null || Array.isArray(b.when)) {
     return { ok: false, message: "`when` is required and must be an object" };
   }
+  // Value-matched metadata predicate (vault#299 Part B): when present, each
+  // field must map to an operator-object whose keys are all supported
+  // operators. Fail at registration so a typo'd operator (`{ state: { equals:
+  // ... } }`) is a 400, not a silently-never-firing trigger.
+  const whenMeta = (b.when as Record<string, unknown>).metadata;
+  if (whenMeta !== undefined) {
+    if (typeof whenMeta !== "object" || whenMeta === null || Array.isArray(whenMeta)) {
+      return { ok: false, message: "`when.metadata` must be an object mapping field → operator-object" };
+    }
+    for (const [field, opObj] of Object.entries(whenMeta as Record<string, unknown>)) {
+      if (typeof opObj !== "object" || opObj === null || Array.isArray(opObj)) {
+        return { ok: false, message: `\`when.metadata.${field}\` must be an operator-object, e.g. { eq: "published" }` };
+      }
+      for (const op of Object.keys(opObj as Record<string, unknown>)) {
+        if (!SUPPORTED_OPS.includes(op as (typeof SUPPORTED_OPS)[number])) {
+          return {
+            ok: false,
+            message: `\`when.metadata.${field}\` has unknown operator "${op}". Supported: ${SUPPORTED_OPS.join(", ")}.`,
+          };
+        }
+      }
+    }
+  }
 
   if (typeof b.action !== "object" || b.action === null || Array.isArray(b.action)) {
     return { ok: false, message: "`action` is required and must be an object" };