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

package/core/src/migrate-tag-field.test.ts

@@ -0,0 +1,471 @@
+/**
+ * migrate-tag-field (vault#314) — evolve a tag-schema field across existing
+ * notes carrying a tag.
+ *
+ * Coverage (per the brief):
+ *   - dry-run reports the correct would-change set without mutating
+ *   - apply performs remap / set-default / retype correctly
+ *   - notes without the tag/field are untouched
+ *   - an unconvertible retype fails cleanly (clear error, no partial corruption)
+ *   - the migration writes through a strict-schema field (bypass) + the bypass
+ *     is logged/attributed
+ *   - idempotency (re-running apply is a no-op once conformant)
+ *   - the CLI transform-spec parser
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import {
+  migrateTagField,
+  applyTransform,
+  parseTransformSpec,
+  TransformError,
+  type ValidationWarning,
+} from "./migrate-tag-field.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+async function getMeta(id: string): Promise<Record<string, unknown>> {
+  const note = await store.getNote(id);
+  return (note?.metadata ?? {}) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Dry-run vs apply
+// ---------------------------------------------------------------------------
+
+describe("dry-run reports the would-change set without mutating", () => {
+  it("counts and samples changes but writes nothing", async () => {
+    const a = await store.createNote("a", { tags: ["kpi"], metadata: { unit: "wip" } });
+    const b = await store.createNote("b", { tags: ["kpi"], metadata: { unit: "wip" } });
+    const c = await store.createNote("c", { tags: ["kpi"], metadata: { unit: "done" } });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "unit",
+      transform: { kind: "remap", map: { wip: "in_progress" } },
+      // apply omitted → dry-run
+    });
+
+    expect(result.applied).toBe(false);
+    expect(result.scanned).toBe(3);
+    expect(result.changed).toBe(2);
+    expect(result.unchanged).toBe(1);
+    expect(result.errored).toBe(0);
+    expect(result.sample).toHaveLength(2);
+
+    // Nothing written.
+    expect((await getMeta(a.id)).unit).toBe("wip");
+    expect((await getMeta(b.id)).unit).toBe("wip");
+    expect((await getMeta(c.id)).unit).toBe("done");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// apply: remap / set-default / retype
+// ---------------------------------------------------------------------------
+
+describe("apply performs the transform correctly", () => {
+  it("remaps an enum value across matching notes only", async () => {
+    const a = await store.createNote("a", { tags: ["kpi"], metadata: { state: "wip", other: 1 } });
+    const b = await store.createNote("b", { tags: ["kpi"], metadata: { state: "shipped" } });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "in_progress" } },
+      apply: true,
+    });
+
+    expect(result.applied).toBe(true);
+    expect(result.changed).toBe(1);
+    expect((await getMeta(a.id)).state).toBe("in_progress");
+    expect((await getMeta(a.id)).other).toBe(1); // unrelated field preserved
+    expect((await getMeta(b.id)).state).toBe("shipped"); // value not in map — untouched
+  });
+
+  it("remap with a default fills missing/null AND remaps present values", async () => {
+    const missing = await store.createNote("missing", { tags: ["kpi"], metadata: {} });
+    const old = await store.createNote("old", { tags: ["kpi"], metadata: { state: "wip" } });
+    const kept = await store.createNote("kept", { tags: ["kpi"], metadata: { state: "shipped" } });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "in_progress" }, default: "unknown" },
+      apply: true,
+    });
+
+    expect(result.changed).toBe(2); // missing (filled) + old (remapped)
+    expect((await getMeta(missing.id)).state).toBe("unknown"); // default filled
+    expect((await getMeta(old.id)).state).toBe("in_progress"); // remapped
+    expect((await getMeta(kept.id)).state).toBe("shipped"); // not in map — kept
+  });
+
+  it("set_default onlyInvalid is a no-op when no schema declares the field", async () => {
+    // No upsertTagRecord here — nothing to validate against, so onlyInvalid
+    // must NOT clobber an existing value (the conservative reading).
+    const a = await store.createNote("a", { tags: ["freeform"], metadata: { x: "anything" } });
+    const result = await migrateTagField(store, {
+      tag: "freeform",
+      field: "x",
+      transform: { kind: "set_default", value: "default", onlyInvalid: true },
+      apply: true,
+    });
+    expect(result.changed).toBe(0);
+    expect((await getMeta(a.id)).x).toBe("anything");
+  });
+
+  it("sets a default on notes missing the field", async () => {
+    const a = await store.createNote("a", { tags: ["task"], metadata: { title: "t" } });
+    const b = await store.createNote("b", { tags: ["task"], metadata: { title: "u", priority: "high" } });
+
+    const result = await migrateTagField(store, {
+      tag: "task",
+      field: "priority",
+      transform: { kind: "set_default", value: "normal" },
+      apply: true,
+    });
+
+    expect(result.changed).toBe(1);
+    expect((await getMeta(a.id)).priority).toBe("normal"); // filled
+    expect((await getMeta(b.id)).priority).toBe("high"); // already present — untouched
+  });
+
+  it("retypes string → int and renames a key", async () => {
+    const a = await store.createNote("a", { tags: ["kpi"], metadata: { count: "5" } });
+
+    const retype = await migrateTagField(store, {
+      tag: "kpi",
+      field: "count",
+      transform: { kind: "to_int" },
+      apply: true,
+    });
+    expect(retype.changed).toBe(1);
+    expect((await getMeta(a.id)).count).toBe(5);
+
+    const rename = await migrateTagField(store, {
+      tag: "kpi",
+      field: "count",
+      transform: { kind: "rename", to: "total" },
+      apply: true,
+    });
+    expect(rename.changed).toBe(1);
+    const meta = await getMeta(a.id);
+    expect(meta.total).toBe(5);
+    expect("count" in meta).toBe(false); // old key dropped
+  });
+
+  it("preserves created attribution; migration is the last_updated actor", async () => {
+    const a = await store.createNote("a", {
+      tags: ["kpi"],
+      metadata: { state: "wip" },
+      actor: "alice",
+      via: "mcp",
+    });
+
+    await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "done" } },
+      apply: true,
+      actor: "migrate-bot",
+      via: "migrate",
+    });
+
+    const row = db.prepare("SELECT created_by, last_updated_by, last_updated_via FROM notes WHERE id = ?").get(a.id) as {
+      created_by: string | null;
+      last_updated_by: string | null;
+      last_updated_via: string | null;
+    };
+    expect(row.created_by).toBe("alice"); // set-once, untouched
+    expect(row.last_updated_by).toBe("migrate-bot");
+    expect(row.last_updated_via).toBe("migrate");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scope: notes without the tag/field are untouched
+// ---------------------------------------------------------------------------
+
+describe("notes without the tag/field are untouched", () => {
+  it("ignores notes carrying a different tag", async () => {
+    const tagged = await store.createNote("a", { tags: ["kpi"], metadata: { state: "wip" } });
+    const other = await store.createNote("b", { tags: ["note"], metadata: { state: "wip" } });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "done" } },
+      apply: true,
+    });
+
+    expect(result.scanned).toBe(1); // only the kpi note
+    expect((await getMeta(tagged.id)).state).toBe("done");
+    expect((await getMeta(other.id)).state).toBe("wip"); // other tag — never seen
+  });
+
+  it("leaves the metadata blob byte-identical when nothing matches", async () => {
+    const a = await store.createNote("a", { tags: ["kpi"], metadata: { state: "shipped", x: 1 } });
+    const before = JSON.stringify(await getMeta(a.id));
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "done" } }, // "shipped" not in map
+      apply: true,
+    });
+
+    expect(result.changed).toBe(0);
+    expect(JSON.stringify(await getMeta(a.id))).toBe(before);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Clean failure on unconvertible retype
+// ---------------------------------------------------------------------------
+
+describe("unconvertible retype fails cleanly with no partial corruption", () => {
+  it("atomically aborts the apply when any note can't convert", async () => {
+    const good = await store.createNote("good", { tags: ["kpi"], metadata: { count: "5" } });
+    const bad = await store.createNote("bad", { tags: ["kpi"], metadata: { count: "banana" } });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "count",
+      transform: { kind: "to_int" },
+      apply: true,
+    });
+
+    // Atomic: nothing written because one note errored.
+    expect(result.applied).toBe(false);
+    expect(result.errored).toBe(1);
+    expect(result.errors[0]!.error).toContain("banana");
+    expect((await getMeta(good.id)).count).toBe("5"); // NOT converted — atomic abort
+    expect((await getMeta(bad.id)).count).toBe("banana");
+  });
+
+  it("continue-on-error writes the convertible notes and reports the rest", async () => {
+    const good = await store.createNote("good", { tags: ["kpi"], metadata: { count: "5" } });
+    const bad = await store.createNote("bad", { tags: ["kpi"], metadata: { count: "banana" } });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "count",
+      transform: { kind: "to_int" },
+      apply: true,
+      continueOnError: true,
+    });
+
+    expect(result.applied).toBe(true);
+    expect(result.changed).toBe(1);
+    expect(result.errored).toBe(1);
+    expect((await getMeta(good.id)).count).toBe(5); // written
+    expect((await getMeta(bad.id)).count).toBe("banana"); // skipped, not corrupted
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Strict-schema bypass + logging
+// ---------------------------------------------------------------------------
+
+describe("migration writes through a strict-schema field (bypass) and logs it", () => {
+  beforeEach(async () => {
+    // Declare a strict enum AFTER the back-catalog exists, so the existing
+    // value is non-conforming — the exact migrate-bypass use case.
+    await store.upsertTagRecord("kpi", {
+      fields: {
+        state: { type: "string", enum: ["in_progress", "shipped"], strict: true },
+      },
+    });
+  });
+
+  it("remaps a non-conforming value through strict enforcement and logs the bypass", async () => {
+    const a = await store.createNote("a", { tags: ["kpi"], metadata: { state: "wip" } });
+
+    const bypassLogs: {
+      actor: string | null;
+      via: string | null;
+      violations: ValidationWarning[];
+    }[] = [];
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      // Map the illegal "wip" to a legal enum value — but the intermediate
+      // write still goes through a strict field, so the bypass path is exercised
+      // and the would-be violation (the original "wip") is what's being fixed.
+      transform: { kind: "remap", map: { wip: "in_progress" } },
+      apply: true,
+      actor: "migrate-bot",
+      via: "migrate",
+      onStrictBypass: (info) => bypassLogs.push(info),
+    });
+
+    expect(result.applied).toBe(true);
+    expect((await getMeta(a.id)).state).toBe("in_progress");
+    // The final value conforms, so no violation on the WRITTEN shape — the
+    // remap fixes the data. Confirm the written note passes strict validation.
+    const status = store.validateNoteAgainstSchemas({
+      tags: ["kpi"],
+      metadata: await getMeta(a.id),
+    });
+    expect(status!.warnings.filter((w) => w.strict)).toHaveLength(0);
+  });
+
+  it("logs + attributes the bypass when the written value still violates strict", async () => {
+    // set-default to a value NOT in the enum: the write itself stays
+    // non-conforming, so the bypass logger MUST fire (we waived enforcement).
+    const a = await store.createNote("a", { tags: ["kpi"], metadata: {} });
+
+    const bypassLogs: {
+      actor: string | null;
+      via: string | null;
+      path?: string | null;
+      violations: ValidationWarning[];
+    }[] = [];
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "set_default", value: "legacy" }, // not in enum
+      apply: true,
+      actor: "migrate-bot",
+      via: "migrate",
+      onStrictBypass: (info) => bypassLogs.push(info),
+    });
+
+    expect(result.applied).toBe(true);
+    expect((await getMeta(a.id)).state).toBe("legacy"); // written despite strict
+    expect(bypassLogs).toHaveLength(1);
+    expect(bypassLogs[0]!.actor).toBe("migrate-bot");
+    expect(bypassLogs[0]!.via).toBe("migrate");
+    expect(bypassLogs[0]!.violations.some((v) => v.field === "state" && v.reason === "enum_mismatch")).toBe(true);
+  });
+
+  it("set-default-invalid only overwrites values that fail the schema", async () => {
+    const legal = await store.createNote("legal", { tags: ["kpi"], metadata: { state: "shipped" } });
+    const illegal = await store.createNote("illegal", { tags: ["kpi"], metadata: { state: "wip" } });
+    const missing = await store.createNote("missing", { tags: ["kpi"], metadata: {} });
+
+    const result = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "set_default", value: "in_progress", onlyInvalid: true },
+      apply: true,
+      onStrictBypass: () => {},
+    });
+
+    expect(result.changed).toBe(2); // illegal + missing
+    expect((await getMeta(legal.id)).state).toBe("shipped"); // valid — kept
+    expect((await getMeta(illegal.id)).state).toBe("in_progress"); // invalid — fixed
+    expect((await getMeta(missing.id)).state).toBe("in_progress"); // missing — filled
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Idempotency
+// ---------------------------------------------------------------------------
+
+describe("idempotency — re-running apply is a no-op once conformant", () => {
+  it("second apply changes nothing", async () => {
+    await store.createNote("a", { tags: ["kpi"], metadata: { state: "wip" } });
+
+    const first = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "in_progress" } },
+      apply: true,
+    });
+    expect(first.changed).toBe(1);
+
+    const second = await migrateTagField(store, {
+      tag: "kpi",
+      field: "state",
+      transform: { kind: "remap", map: { wip: "in_progress" } },
+      apply: true,
+    });
+    expect(second.changed).toBe(0);
+    expect(second.scanned).toBe(1);
+  });
+
+  it("retype is idempotent — re-running on an already-int value is a no-op", async () => {
+    await store.createNote("a", { tags: ["kpi"], metadata: { count: "5" } });
+    const first = await migrateTagField(store, {
+      tag: "kpi", field: "count", transform: { kind: "to_int" }, apply: true,
+    });
+    expect(first.changed).toBe(1);
+    const second = await migrateTagField(store, {
+      tag: "kpi", field: "count", transform: { kind: "to_int" }, apply: true,
+    });
+    expect(second.changed).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Unit: applyTransform + coercion edge cases
+// ---------------------------------------------------------------------------
+
+describe("applyTransform unit", () => {
+  it("rename of an absent field is a no-op", () => {
+    expect(applyTransform("x", undefined, false, { kind: "rename", to: "y" })).toBeNull();
+  });
+  it("to_int rejects a fractional number", () => {
+    expect(() => applyTransform("x", 5.5, true, { kind: "to_int" })).toThrow(TransformError);
+  });
+  it("to_boolean parses yes/no strings", () => {
+    expect(applyTransform("x", "yes", true, { kind: "to_boolean" })!.value).toBe(true);
+    expect(applyTransform("x", "no", true, { kind: "to_boolean" })!.value).toBe(false);
+  });
+  it("to_string of an already-string value is a no-op (idempotent)", () => {
+    expect(applyTransform("x", "hi", true, { kind: "to_string" })).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Unit: parseTransformSpec
+// ---------------------------------------------------------------------------
+
+describe("parseTransformSpec", () => {
+  it("parses the retype keywords", () => {
+    expect(parseTransformSpec("to_string")).toEqual({ kind: "to_string" });
+    expect(parseTransformSpec("to_int")).toEqual({ kind: "to_int" });
+    expect(parseTransformSpec("to_number")).toEqual({ kind: "to_number" });
+    expect(parseTransformSpec("to_boolean")).toEqual({ kind: "to_boolean" });
+  });
+  it("parses rename", () => {
+    expect(parseTransformSpec("rename:metric")).toEqual({ kind: "rename", to: "metric" });
+  });
+  it("parses remap with multiple pairs and JSON scalars", () => {
+    expect(parseTransformSpec("remap:wip=in_progress,done=shipped")).toEqual({
+      kind: "remap",
+      map: { wip: "in_progress", done: "shipped" },
+    });
+    expect(parseTransformSpec("remap:a=1,b=true")).toEqual({
+      kind: "remap",
+      map: { a: 1, b: true },
+    });
+  });
+  it("parses set-default and set-default-invalid with scalar coercion", () => {
+    expect(parseTransformSpec("set-default:normal")).toEqual({ kind: "set_default", value: "normal" });
+    expect(parseTransformSpec("set-default:0")).toEqual({ kind: "set_default", value: 0 });
+    expect(parseTransformSpec("set-default-invalid:in_progress")).toEqual({
+      kind: "set_default",
+      value: "in_progress",
+      onlyInvalid: true,
+    });
+  });
+  it("throws on a malformed or unknown spec", () => {
+    expect(() => parseTransformSpec("bogus")).toThrow(TransformError);
+    expect(() => parseTransformSpec("rename:")).toThrow(TransformError);
+    expect(() => parseTransformSpec("remap:nopair")).toThrow(TransformError);
+    expect(() => parseTransformSpec("frobnicate:x")).toThrow(TransformError);
+  });
+});

package/core/src/migrate-tag-field.ts

@@ -0,0 +1,638 @@
+/**
+ * migrate-tag-field (vault#314) — evolve a tag-schema field's type / values
+ * across the existing notes that carry a tag, so a schema tightening (declare a
+ * `strict` enum, rename an enum value, retype a field, set a default for a
+ * now-required field) can bring the back-catalog into conformance in one
+ * operation instead of editing notes by hand.
+ *
+ * This is the companion to enforced writes (vault#299 / MW2): declare `strict`
+ * → find the non-conforming notes → migrate them. The migration is the EXACT
+ * use case the migrate-bypass scope (`vault:migrate`) exists for — it rewrites
+ * notes through `strict` enforcement and logs the bypass for audit.
+ *
+ * Design (issue #314):
+ *   - Walk every note carrying `tag` (descendants included — `store.queryNotes`
+ *     already expands the hierarchy), apply a `transform` to the named
+ *     metadata `field`, write back.
+ *   - **Dry-run by default.** The default returns a plan (count + sample of
+ *     would-change rows) WITHOUT mutating. `apply: true` is the explicit
+ *     opt-in that writes. A migration is destructive across many notes, so the
+ *     preview is first-class.
+ *   - **Bypass + attribution.** Each rewrite runs `enforceStrictWrite` with
+ *     `bypass: true` so a `strict:true` field that the back-catalog violates
+ *     doesn't block the migration, and every bypassed write is logged
+ *     (`onBypass`). Writes carry `actor`/`via` (MW1) — the migration is the
+ *     `last_updated_*` author; `created_*` is set-once and never touched.
+ *   - **Surgical.** Only the named `field` on matching notes is touched; all
+ *     other metadata is preserved verbatim. A `rename` transform moves the
+ *     value to the new key and drops the old.
+ *   - **Clean failure.** An unconvertible retype (`to_int` on `"banana"`)
+ *     fails that note cleanly — it's reported as `errored`, never partially
+ *     written. By default a single error aborts the whole apply BEFORE any
+ *     write (atomic preflight); `continueOnError: true` switches to
+ *     best-effort, writing the convertible notes and reporting the rest.
+ *   - **Idempotent.** Re-running an apply once the catalog conforms is a no-op
+ *     (no note is in the would-change set the second time).
+ */
+
+import type { Store, Note } from "./types.js";
+import type { ValidationWarning } from "./schema-defaults.js";
+import { enforceStrictWrite } from "./mcp.js";
+
+// Re-export for callers (tests, server layer) that work with the bypass
+// logger's violation list without importing schema-defaults directly.
+export type { ValidationWarning } from "./schema-defaults.js";
+
+// ---------------------------------------------------------------------------
+// Transforms
+// ---------------------------------------------------------------------------
+
+/**
+ * The transform set (issue #314 §Proposal — the built-in set; no expression
+ * language). Each names a concrete schema-evolution move:
+ *
+ *   - `rename`    — move the field's value to a NEW metadata key, dropping the
+ *                   old key. The schema-rename move (`kpi` → `metric`). `to` is
+ *                   the new field name. Notes missing the field are untouched.
+ *   - `remap`     — rewrite the field's VALUE per a value→value map. The enum
+ *                   value-rename move (`old` → `new`). Values not in the map are
+ *                   left as-is. Pass `default` to also fill missing/null values.
+ *   - `set_default` — set the field to `value` on notes where it's missing,
+ *                   null, or (when `onlyInvalid` + a validator) currently
+ *                   invalid. Notes that already carry a valid value are
+ *                   untouched. The "default for a now-required field" move.
+ *   - `to_string` / `to_int` / `to_number` / `to_boolean` — retype the field's
+ *                   value. Conversions are conservative (see `coerce*`); an
+ *                   unconvertible value is an error for that note, not a
+ *                   silent drop. The "changed a field's type" move.
+ */
+export type FieldTransform =
+  | { kind: "rename"; to: string }
+  | { kind: "remap"; map: Record<string, unknown>; default?: unknown }
+  | { kind: "set_default"; value: unknown; onlyInvalid?: boolean }
+  | { kind: "to_string" }
+  | { kind: "to_int" }
+  | { kind: "to_number" }
+  | { kind: "to_boolean" };
+
+/** A transform raised this when a value can't be converted (clean per-note failure). */
+export class TransformError extends Error {
+  code = "TRANSFORM_ERROR" as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "TransformError";
+  }
+}
+
+const PRESENT = Symbol("present"); // sentinel: field exists with this value
+const ABSENT = Symbol("absent"); // sentinel: field is missing entirely
+
+/**
+ * Outcome of applying a transform to one note's field. `change` describes the
+ * metadata edit:
+ *   - `null` → no change (note left untouched).
+ *   - `{ setField, value }` → set `setField` to `value`.
+ *   - `{ setField, value, dropField }` → set the new key, drop the old (rename).
+ */
+interface TransformResult {
+  /** Field name to write (the new key for rename, else the original field). */
+  setField: string;
+  /** Value to write. */
+  value: unknown;
+  /** Field name to remove (rename only — the original key). */
+  dropField?: string;
+}
+
+/**
+ * Apply a transform to the (possibly-absent) current value of `field`. Returns
+ * the metadata edit to make, or `null` for "no change." Throws `TransformError`
+ * on an unconvertible retype.
+ *
+ * `present` distinguishes "field is missing" from "field is present and null/
+ * undefined" — `set_default` fills both, but `rename`/`remap`/retype only act
+ * on a present field (you can't rename a key that isn't there).
+ */
+export function applyTransform(
+  field: string,
+  current: unknown,
+  present: boolean,
+  transform: FieldTransform,
+  isValid?: (v: unknown) => boolean,
+): TransformResult | null {
+  switch (transform.kind) {
+    case "rename": {
+      if (!present) return null; // nothing to move
+      if (transform.to === field) return null; // no-op rename
+      return { setField: transform.to, value: current, dropField: field };
+    }
+    case "remap": {
+      // Fill missing/null when a `default` is provided…
+      if (!present || current === null || current === undefined) {
+        if ("default" in transform) {
+          return changeIfDifferent(field, current, transform.default, present);
+        }
+        return null;
+      }
+      // …else remap the value if it's a key in the map (string-keyed lookup).
+      const key = typeof current === "string" ? current : String(current);
+      if (Object.prototype.hasOwnProperty.call(transform.map, key)) {
+        return changeIfDifferent(field, current, transform.map[key], present);
+      }
+      return null; // value not in the map — leave as-is
+    }
+    case "set_default": {
+      const missing = !present || current === null || current === undefined;
+      if (missing) {
+        return changeIfDifferent(field, current, transform.value, present);
+      }
+      // Present + non-null. Overwrite only when `onlyInvalid` and the value
+      // currently fails validation (e.g. an enum value that's no longer legal).
+      if (transform.onlyInvalid && isValid && !isValid(current)) {
+        return changeIfDifferent(field, current, transform.value, present);
+      }
+      return null;
+    }
+    case "to_string": {
+      if (!present || current === null || current === undefined) return null;
+      return changeIfDifferent(field, current, coerceString(current), present);
+    }
+    case "to_int": {
+      if (!present || current === null || current === undefined) return null;
+      return changeIfDifferent(field, current, coerceInt(field, current), present);
+    }
+    case "to_number": {
+      if (!present || current === null || current === undefined) return null;
+      return changeIfDifferent(field, current, coerceNumber(field, current), present);
+    }
+    case "to_boolean": {
+      if (!present || current === null || current === undefined) return null;
+      return changeIfDifferent(field, current, coerceBoolean(field, current), present);
+    }
+  }
+}
+
+/**
+ * Return a `TransformResult` only when the new value actually differs from the
+ * current one (idempotency at the value level — a remap to the same value, or a
+ * retype of an already-correctly-typed value, is a no-op). `present === false`
+ * always counts as a change when we're writing a value (the field is being
+ * added).
+ */
+function changeIfDifferent(
+  field: string,
+  current: unknown,
+  next: unknown,
+  present: boolean,
+): TransformResult | null {
+  if (present && Object.is(current, next)) return null;
+  // Deep-equal escape hatch for non-primitive equal values (rare; remap to an
+  // equal object/array). JSON compare is sufficient — metadata is JSON.
+  if (present && typeof current === typeof next && typeof current === "object") {
+    try {
+      if (JSON.stringify(current) === JSON.stringify(next)) return null;
+    } catch {
+      /* fall through — treat as a change */
+    }
+  }
+  return { setField: field, value: next };
+}
+
+function coerceString(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  // Objects/arrays → JSON, which is the least-surprising stringification for
+  // metadata and round-trips back through `to_*` cleanly.
+  return JSON.stringify(v);
+}
+
+function coerceInt(field: string, v: unknown): number {
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new TransformError(`'${field}': ${v} is not a finite number`);
+    if (!Number.isInteger(v)) {
+      throw new TransformError(`'${field}': ${v} has a fractional part — cannot convert to integer`);
+    }
+    return v;
+  }
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (typeof v === "string") {
+    const t = v.trim();
+    // Strict integer parse — reject "5px", "5.5", "" and other junk that
+    // Number() would silently coerce or NaN.
+    if (!/^[+-]?\d+$/.test(t)) {
+      throw new TransformError(`'${field}': "${v}" is not an integer`);
+    }
+    const n = Number(t);
+    if (!Number.isSafeInteger(n)) {
+      throw new TransformError(`'${field}': "${v}" is out of safe-integer range`);
+    }
+    return n;
+  }
+  throw new TransformError(`'${field}': cannot convert ${typeof v} to integer`);
+}
+
+function coerceNumber(field: string, v: unknown): number {
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new TransformError(`'${field}': ${v} is not a finite number`);
+    return v;
+  }
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (typeof v === "string") {
+    const t = v.trim();
+    if (t === "" || !Number.isFinite(Number(t))) {
+      throw new TransformError(`'${field}': "${v}" is not a number`);
+    }
+    return Number(t);
+  }
+  throw new TransformError(`'${field}': cannot convert ${typeof v} to number`);
+}
+
+function coerceBoolean(field: string, v: unknown): boolean {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") {
+    if (v === 1) return true;
+    if (v === 0) return false;
+    throw new TransformError(`'${field}': ${v} is not a boolean (expected 0 or 1)`);
+  }
+  if (typeof v === "string") {
+    const t = v.trim().toLowerCase();
+    if (t === "true" || t === "yes" || t === "1") return true;
+    if (t === "false" || t === "no" || t === "0") return false;
+    throw new TransformError(`'${field}': "${v}" is not a boolean (expected true/false/yes/no/1/0)`);
+  }
+  throw new TransformError(`'${field}': cannot convert ${typeof v} to boolean`);
+}
+
+// ---------------------------------------------------------------------------
+// Migration
+// ---------------------------------------------------------------------------
+
+export interface MigrateTagFieldOpts {
+  /** The tag whose notes carry the field. Hierarchy descendants are included. */
+  tag: string;
+  /** The metadata field to evolve. */
+  field: string;
+  /** The transform to apply. */
+  transform: FieldTransform;
+  /**
+   * Dry-run by default. `apply: true` is the explicit opt-in that writes —
+   * everything else returns a plan and mutates NOTHING.
+   */
+  apply?: boolean;
+  /**
+   * Write-attribution (MW1) for the rewrites. The migration is the
+   * `last_updated_*` author; `created_*` is never touched. Defaults to
+   * `{ actor: "migrate", via: "migrate" }` so a migration is always
+   * distinguishable in the attribution columns even when the caller omits it.
+   */
+  actor?: string | null;
+  via?: string | null;
+  /**
+   * How many would-change rows to include in `sample`. Default 10. The full
+   * count is always reported regardless.
+   */
+  sampleSize?: number;
+  /**
+   * Error policy on an unconvertible retype:
+   *   - default (`false`) — ATOMIC: any error aborts the whole apply BEFORE a
+   *     single write, so the migration is all-or-nothing. The plan lists every
+   *     errored note so the operator can fix the data first.
+   *   - `true` — best-effort: write every convertible note, report the rest.
+   */
+  continueOnError?: boolean;
+  /**
+   * Bypass-audit logger (MW2). Invoked once per write that bypassed a
+   * `strict:true` field constraint, with the would-be violations + attribution.
+   * The server layer passes `logStrictBypass`; core stays log-sink-agnostic.
+   * Omitted → bypassed writes still happen (the migration must), just unlogged.
+   */
+  onStrictBypass?: (info: {
+    actor: string | null;
+    via: string | null;
+    path?: string | null;
+    tags?: string[];
+    violations: ValidationWarning[];
+  }) => void;
+}
+
+/** A single planned/applied note change. */
+export interface MigrateChange {
+  id: string;
+  path: string | null;
+  /** The value of the field before the transform (the original key for rename). */
+  before: unknown;
+  /** The value written (under `field`, or under the new key for rename). */
+  after: unknown;
+  /** Set for rename: the new key the value moved to. */
+  renamedTo?: string;
+}
+
+/** A note that couldn't be transformed (unconvertible retype). */
+export interface MigrateErroredNote {
+  id: string;
+  path: string | null;
+  before: unknown;
+  error: string;
+}
+
+export interface MigrateTagFieldResult {
+  tag: string;
+  field: string;
+  transform: FieldTransform;
+  /** True when this run wrote to the vault; false for a dry-run. */
+  applied: boolean;
+  /** Notes carrying the tag that were scanned. */
+  scanned: number;
+  /** Notes that would change (dry-run) or did change (apply). */
+  changed: number;
+  /** Notes left untouched (already conformant / field absent / value not in map). */
+  unchanged: number;
+  /** Notes whose transform failed (unconvertible). */
+  errored: number;
+  /** A bounded preview of the changes (up to `sampleSize`). */
+  sample: MigrateChange[];
+  /** Every errored note (not bounded — the operator needs the full list to fix data). */
+  errors: MigrateErroredNote[];
+}
+
+/**
+ * Run a tag-field migration. Dry-run by default; `apply: true` writes.
+ *
+ * The flow is preflight-then-write:
+ *   1. Query every note carrying `tag`.
+ *   2. For each, compute the transform result. Collect changes + errors.
+ *   3. If NOT `apply` → return the plan (nothing written).
+ *   4. If `apply` and there are errors and NOT `continueOnError` → return the
+ *      plan WITHOUT writing (atomic abort — the operator fixes the data first).
+ *   5. Otherwise write each change via `store.updateNote`, running
+ *      `enforceStrictWrite(bypass:true)` first so a `strict` violation logs
+ *      rather than blocks.
+ */
+export async function migrateTagField(
+  store: Store,
+  opts: MigrateTagFieldOpts,
+): Promise<MigrateTagFieldResult> {
+  const { tag, field, transform } = opts;
+  const sampleSize = opts.sampleSize ?? 10;
+  const actor = opts.actor ?? "migrate";
+  const via = opts.via ?? "migrate";
+
+  // Validate the transform shape up front so a bad arg fails before any scan.
+  validateTransform(field, transform);
+
+  // A validator the `set_default { onlyInvalid }` path uses to decide whether
+  // a present value is "invalid" — driven by the tag's resolved schema for the
+  // field (enum / type), so `onlyInvalid` means "the current value violates the
+  // declared schema." Absent schema → never invalid (so onlyInvalid is a no-op,
+  // which is the safe reading: with nothing to validate against, don't clobber).
+  // Only built for the transform that uses it; other transforms never call it.
+  const isValid =
+    transform.kind === "set_default" && transform.onlyInvalid
+      ? makeFieldValidator(store, tag, field)
+      : undefined;
+
+  const notes = await collectTaggedNotes(store, tag);
+
+  const changes: MigrateChange[] = [];
+  const errors: MigrateErroredNote[] = [];
+  // Parallel list of (note, result) for the write phase — keeps the transform
+  // pass and the write pass from diverging on which notes change.
+  const pending: { note: Note; result: TransformResult }[] = [];
+
+  for (const note of notes) {
+    const meta = (note.metadata ?? {}) as Record<string, unknown>;
+    const present = Object.prototype.hasOwnProperty.call(meta, field);
+    const current = present ? meta[field] : undefined;
+    let result: TransformResult | null;
+    try {
+      result = applyTransform(field, current, present, transform, isValid);
+    } catch (err) {
+      errors.push({
+        id: note.id,
+        path: note.path ?? null,
+        before: current,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      continue;
+    }
+    if (result === null) continue; // unchanged
+    pending.push({ note, result });
+    if (changes.length < sampleSize) {
+      changes.push({
+        id: note.id,
+        path: note.path ?? null,
+        before: current,
+        after: result.value,
+        ...(result.dropField ? { renamedTo: result.setField } : {}),
+      });
+    }
+  }
+
+  const baseResult = {
+    tag,
+    field,
+    transform,
+    scanned: notes.length,
+    changed: pending.length,
+    unchanged: notes.length - pending.length - errors.length,
+    errored: errors.length,
+    sample: changes,
+    errors,
+  };
+
+  // Dry-run, or an atomic abort because the preflight found errors.
+  if (!opts.apply) {
+    return { ...baseResult, applied: false };
+  }
+  if (errors.length > 0 && !opts.continueOnError) {
+    // Atomic: refuse to write any note when some can't be converted, so the
+    // migration is all-or-nothing. The caller sees the full error list.
+    return { ...baseResult, applied: false };
+  }
+
+  // Write phase.
+  for (const { note, result } of pending) {
+    const nextMeta: Record<string, unknown> = { ...(note.metadata ?? {}) };
+    nextMeta[result.setField] = result.value;
+    if (result.dropField && result.dropField !== result.setField) {
+      delete nextMeta[result.dropField];
+    }
+
+    // Run strict enforcement with bypass ON (MW2) through the SAME gate the
+    // MCP/REST write transports use, so the migration can't drift from the
+    // canonical enforcement contract (e.g. when audit-log #300 lands and
+    // `onBypass` grows a DB write). The migration must write THROUGH a
+    // `strict:true` field the back-catalog violates — bypass skips the throw,
+    // and `onBypass` logs the waived violations with attribution for audit.
+    enforceStrictWrite(
+      store,
+      { path: note.path, tags: note.tags, metadata: nextMeta },
+      {
+        bypass: true,
+        onBypass: opts.onStrictBypass
+          ? (violations) =>
+              opts.onStrictBypass!({
+                actor,
+                via,
+                path: note.path ?? null,
+                tags: note.tags,
+                violations,
+              })
+          : undefined,
+      },
+    );
+
+    await store.updateNote(note.id, { metadata: nextMeta, actor, via });
+  }
+
+  return { ...baseResult, applied: true };
+}
+
+/**
+ * Make a predicate "does this value satisfy the tag's declared schema for
+ * `field`?" from the live schema config. Used by `set_default { onlyInvalid }`.
+ * When no schema declares the field, every value is "valid" (no constraint to
+ * fail), so `onlyInvalid` won't overwrite anything — the conservative choice.
+ */
+function makeFieldValidator(
+  store: Store,
+  tag: string,
+  field: string,
+): (v: unknown) => boolean {
+  return (v: unknown): boolean => {
+    // Build a synthetic single-field note and ask the resolver whether THIS
+    // field has a strict-or-advisory violation. Any violation on the field →
+    // invalid.
+    const status = store.validateNoteAgainstSchemas({
+      tags: [tag],
+      metadata: { [field]: v },
+    });
+    if (!status) return true;
+    return !status.warnings.some(
+      (w) => w.field === field && w.reason !== "schema_conflict" && w.reason !== "missing_required",
+    );
+  };
+}
+
+/** Pull every note carrying `tag` (hierarchy-expanded by the store). */
+async function collectTaggedNotes(store: Store, tag: string): Promise<Note[]> {
+  // The migration must see EVERY tagged note, not a default page. Use a large
+  // limit — the same approach `syncAllWikilinks` takes for a whole-vault sweep.
+  return store.queryNotes({ tags: [tag], limit: 1_000_000 });
+}
+
+// ---------------------------------------------------------------------------
+// CLI transform-spec parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a CLI `--transform <spec>` string into a `FieldTransform`. The built-in
+ * spec grammar (issue #314 — "just a built-in set", no expression language):
+ *
+ *   rename:<newkey>            → { kind: "rename", to }
+ *   remap:<old>=<new>[,...]    → { kind: "remap", map }
+ *   set-default:<value>        → { kind: "set_default", value }   (value JSON-parsed, else string)
+ *   set-default-invalid:<v>    → { kind: "set_default", value, onlyInvalid: true }
+ *   to_string|to_int|to_number|to_boolean → the matching retype
+ *
+ * `remap` values and `set-default` values are parsed as JSON when they parse
+ * (so `set-default:0`, `set-default:true`, `remap:a=1`), falling back to the
+ * literal string otherwise (so `set-default:draft`, `remap:wip=published`).
+ *
+ * Throws `TransformError` on an unrecognized or malformed spec.
+ */
+export function parseTransformSpec(spec: string): FieldTransform {
+  const trimmed = spec.trim();
+
+  if (trimmed === "to_string") return { kind: "to_string" };
+  if (trimmed === "to_int") return { kind: "to_int" };
+  if (trimmed === "to_number") return { kind: "to_number" };
+  if (trimmed === "to_boolean") return { kind: "to_boolean" };
+
+  const colon = trimmed.indexOf(":");
+  if (colon === -1) {
+    throw new TransformError(
+      `unrecognized transform "${spec}" (expected one of: rename:<key>, remap:<old>=<new>, set-default:<value>, set-default-invalid:<value>, to_string, to_int, to_number, to_boolean)`,
+    );
+  }
+  const head = trimmed.slice(0, colon);
+  const rest = trimmed.slice(colon + 1);
+
+  switch (head) {
+    case "rename": {
+      if (!rest) throw new TransformError("rename: missing new key — use rename:<newkey>");
+      return { kind: "rename", to: rest };
+    }
+    case "remap": {
+      if (!rest) throw new TransformError("remap: missing pairs — use remap:<old>=<new>[,<old>=<new>]");
+      const map: Record<string, unknown> = {};
+      for (const pair of rest.split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq === -1) {
+          throw new TransformError(`remap: "${pair}" is not an <old>=<new> pair`);
+        }
+        const oldVal = pair.slice(0, eq);
+        const newVal = pair.slice(eq + 1);
+        if (!oldVal) throw new TransformError(`remap: empty <old> in "${pair}"`);
+        map[oldVal] = parseScalar(newVal);
+      }
+      return { kind: "remap", map };
+    }
+    case "set-default": {
+      return { kind: "set_default", value: parseScalar(rest) };
+    }
+    case "set-default-invalid": {
+      return { kind: "set_default", value: parseScalar(rest), onlyInvalid: true };
+    }
+    default:
+      throw new TransformError(`unknown transform "${head}" in "${spec}"`);
+  }
+}
+
+/** Parse a CLI scalar: JSON when it parses to a scalar, else the literal string. */
+function parseScalar(raw: string): unknown {
+  if (raw === "") return "";
+  try {
+    const parsed = JSON.parse(raw);
+    // Only accept JSON scalars (string/number/boolean/null) — an unquoted word
+    // like `draft` throws and falls through to the literal-string branch.
+    if (
+      parsed === null ||
+      typeof parsed === "string" ||
+      typeof parsed === "number" ||
+      typeof parsed === "boolean"
+    ) {
+      return parsed;
+    }
+  } catch {
+    /* not JSON — treat as a literal string */
+  }
+  return raw;
+}
+
+/** Reject a structurally-invalid transform before any DB work. */
+function validateTransform(field: string, transform: FieldTransform): void {
+  switch (transform.kind) {
+    case "rename":
+      if (typeof transform.to !== "string" || transform.to.length === 0) {
+        throw new TransformError("rename: `to` (new field name) is required");
+      }
+      break;
+    case "remap":
+      if (!transform.map || typeof transform.map !== "object" || Array.isArray(transform.map)) {
+        throw new TransformError("remap: `map` (value→value object) is required");
+      }
+      break;
+    case "set_default":
+      if (!("value" in transform)) {
+        throw new TransformError("set_default: `value` is required");
+      }
+      break;
+    case "to_string":
+    case "to_int":
+    case "to_number":
+    case "to_boolean":
+      break;
+    default:
+      throw new TransformError(`unknown transform: ${(transform as { kind: string }).kind}`);
+  }
+}

package/package.json

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

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 ──────────────────────────────────────────────