@telorun/analyzer 0.56.1 → 0.58.0

package/src/migrations/match.ts

@@ -0,0 +1,382 @@
+/** The selector half of a migration: what a rule MATCHES, as data.
+ *
+ *  A patch addresses a known location; a migration has to find *every*
+ *  occurrence of a legacy spelling, so selection is the half a plain patch
+ *  format has none of. It is declarative for the same reason the operations
+ *  are: an entry travels to a Rust and a Go kernel, and a predicate expressed
+ *  in one language would mean one artifact is read two ways — invisibly, since
+ *  a migration that succeeds is silent.
+ *
+ *  **Containment is POSITIVE and required.** A rule states which document kinds
+ *  it may touch (`inKind`) and which region of those documents it may reach
+ *  into (`under`); nothing outside is reachable. The alternative — walk
+ *  everything and subtract — cannot be made sound, because the set to subtract
+ *  is unbounded: a `Run.Value` value, an `Assert.Equals` expected, any kind
+ *  whose config carries a user JSON blob can hold something shaped like the
+ *  node a rule looks for, and forgetting one corrupts a manifest with no
+ *  diagnostic. A denylist also cannot express the guarantee the module surface
+ *  is promised to carry — *a dependency can rename its own field and provably
+ *  nothing else* — which is a statement about what a rule may reach, so it has
+ *  to be said positively. `notUnder` remains for subtracting inside a region a
+ *  rule legitimately reaches, which is a narrowing, not the containment itself.
+ *
+ *  **`under` is ANCHORED at the document root**, not a set of key names to look
+ *  for anywhere on the path. Anchoring is what makes the containment claim
+ *  true: a `Telo.Definition`'s `resources:` template body carries other kinds'
+ *  configuration, and any of it may hold a key spelled `schema` over data that
+ *  merely looks like a schema — so "some segment of the path is `schema`" would
+ *  reach the very user JSON blob the positive form exists to keep out, and
+ *  would delete from it silently. Anchored, `under` names top-level document
+ *  keys and a region is a genuine subtree.
+ *
+ *  **`inSchema` is the one region a kind list cannot name.** An annotation
+ *  keyword occurs in author-written JSON Schema, and schema fragments are not
+ *  confined to kind documents: an inline `inputType:` / `outputType:` on ANY kind
+ *  that declares one, an API route's `request.schema.body`, a `Telo.JsonSchema`'s
+ *  `schema`. That set of kinds is open — any kind may declare a schema-valued
+ *  field — and enumerating the standard library's would put resource-kind
+ *  knowledge into the analyzer, against the topology-driven constraint. So a rule
+ *  may instead state that it reaches only inside a SCHEMA REGION, named by the
+ *  KERNEL's own schema-valued keys, which no kind owns.
+ *
+ *  With `inSchema`, and only with it, `inKind` / `under` may be `["*"]` — and
+ *  only for a rule keyed on a reserved `x-telo-*` annotation. That pairing IS the
+ *  containment: the region gate bounds where the walk may go, and the reserved-key
+ *  rule bounds what it may touch, since an `x-telo-*` key is Telo vocabulary
+ *  wherever it appears and cannot mean something else in someone's config. Both
+ *  halves are refused at entry-read time, so a module-shipped entry can no more
+ *  spell `"*"` than it can name another module's kind.
+ *
+ *  The residue is stated rather than claimed away: a manifest that asserts ABOUT
+ *  a schema — a schema literal under a key spelled `schema` inside an assertion's
+ *  expected value — is reachable, and would be rewritten into its own synonym.
+ *  That cannot be closed in a data-only matcher without naming kinds. It is
+ *  accepted because the sites the wildcards reach are exactly the ones no
+ *  enumeration covers, and the alternative leaves an author reading a deprecation
+ *  `telo migrate` refuses to act on.
+ *
+ *  The vocabulary is closed, which is what makes it a trust boundary once
+ *  module-shipped entries are aggregated beside core ones. An unrecognized key
+ *  is refused rather than ignored — a selector that silently matches wider than
+ *  it reads is the one failure this cannot tolerate. */
+
+import { isInSchemaRegion } from "../schema-region.js";
+import type { MigrationPath } from "./types.js";
+
+/** The wildcard `inKind` / `under` value. Legal only alongside `inSchema`, and
+ *  only for a rule keyed on an `x-telo-*` annotation. */
+export const MATCH_ANY = "*";
+
+export interface MigrationMatch {
+  /** The mapping key this rule rewrites. */
+  readonly key: string;
+  /** Document `kind:` values this rule may match in. Required and non-empty:
+   *  a rule that does not say which documents it touches cannot be reasoned
+   *  about, and is exactly the rule that reaches into a resource's config. */
+  readonly inKind: readonly string[];
+  /** The region of the document this rule may reach, named by TOP-LEVEL
+   *  document keys: the matched node must be AT or BELOW one of them. Required
+   *  and non-empty, for the same reason as `inKind`.
+   *
+   *  Anchored at the root rather than matched anywhere on the path — see the
+   *  file header; an unanchored `under` reaches into a nested resource's own
+   *  configuration and is not containment at all.
+   *
+   *  At-or-below rather than strictly-below so the vocabulary is complete — a
+   *  rule that rewrites a top-level key names that key, instead of the region
+   *  being unreachable and the grammar needing a second spelling for the
+   *  document root. */
+  readonly under: readonly string[];
+  /** The value must deep-equal this. Mutually exclusive with `valueOneOf`. */
+  readonly value?: unknown;
+  /** The value must be one of these. Matching against the KNOWN legacy values
+   *  rather than any value is what leaves an unrecognized one alone for the
+   *  ordinary validator to report, instead of silently rewriting it. */
+  readonly valueOneOf?: readonly unknown[];
+  /** A key that must be present in the same mapping. The matched key is often
+   *  stale only *because* of what sits beside it. */
+  readonly withSibling?: string;
+  /** Ancestor keys that disqualify a match inside the region `under` allows.
+   *  The data-bearing JSON Schema keywords (`const`, `default`, `enum`,
+   *  `examples`) hold values that may look like schemas. */
+  readonly notUnder?: readonly string[];
+  /** Narrow to a JSON Schema region: the match must be at or below a node
+   *  reached through one of {@link SCHEMA_REGION_KEYS}.
+   *
+   *  A second bound, never a replacement for `inKind` / `under` — it is what
+   *  makes their wildcard forms safe, and it narrows an enumerated region just as
+   *  usefully. See the file header for why an annotation rename needs it. */
+  readonly inSchema?: boolean;
+}
+
+export const MATCH_KEYS = [
+  "key",
+  "inKind",
+  "under",
+  "value",
+  "valueOneOf",
+  "withSibling",
+  "notUnder",
+  "inSchema",
+] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Structural equality over JSON values — what `value` / `valueOneOf` compare
+ *  with, so a match on `true` never also matches `"true"`.
+ *
+ *  Exported because the PATCHER asks the same question in the other direction:
+ *  "is the value already what this would write". Both answers have to come from
+ *  one rule, or a rule could match a spelling the patch then declares current. */
+export function deepEquals(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => deepEquals(item, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length) return false;
+    return aKeys.every((k) => Object.hasOwn(b, k) && deepEquals(a[k], b[k]));
+  }
+  return false;
+}
+
+function requireStringList(describe: string, raw: Record<string, unknown>, key: string): string[] {
+  const value = raw[key];
+  if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string")) {
+    throw new Error(`${describe}: 'match.${key}' must be a non-empty sequence of strings`);
+  }
+  return value as string[];
+}
+
+/** Read a rule's `match` block, refusing anything the vocabulary does not
+ *  define. `describe` names the entry and rule so a failure says which. */
+export function readMigrationMatch(describe: string, raw: unknown): MigrationMatch {
+  if (!isPlainObject(raw)) throw new Error(`${describe}: 'match' must be a mapping`);
+
+  for (const key of Object.keys(raw)) {
+    if (!(MATCH_KEYS as readonly string[]).includes(key)) {
+      throw new Error(
+        `${describe}: 'match' has no key '${key}'. Known keys: ${MATCH_KEYS.join(", ")}.`,
+      );
+    }
+  }
+  if (typeof raw.key !== "string" || raw.key.length === 0) {
+    throw new Error(`${describe}: 'match.key' must be a non-empty string`);
+  }
+  if (Object.hasOwn(raw, "value") && Object.hasOwn(raw, "valueOneOf")) {
+    throw new Error(`${describe}: 'match' takes at most one of 'value' or 'valueOneOf'`);
+  }
+  if (Object.hasOwn(raw, "valueOneOf") && !Array.isArray(raw.valueOneOf)) {
+    throw new Error(`${describe}: 'match.valueOneOf' must be a sequence`);
+  }
+  if (Object.hasOwn(raw, "withSibling") && typeof raw.withSibling !== "string") {
+    throw new Error(`${describe}: 'match.withSibling' must be a string`);
+  }
+  if (
+    Object.hasOwn(raw, "notUnder") &&
+    (!Array.isArray(raw.notUnder) || raw.notUnder.some((k) => typeof k !== "string"))
+  ) {
+    throw new Error(`${describe}: 'match.notUnder' must be a sequence of strings`);
+  }
+  if (Object.hasOwn(raw, "inSchema") && typeof raw.inSchema !== "boolean") {
+    throw new Error(`${describe}: 'match.inSchema' must be a boolean`);
+  }
+
+  // The two conditions that make a wildcard safe, refused here rather than
+  // narrowed later: a rule the reader accepts is a rule the driver will run, and
+  // a selector that matches wider than it reads is exactly what this vocabulary
+  // exists to prevent. A module-shipped entry therefore cannot spell `"*"` at
+  // all, because it cannot satisfy both halves for a keyword it does not own.
+  const wildcards = [
+    ...(Array.isArray(raw.inKind) ? (raw.inKind as unknown[]) : []),
+    ...(Array.isArray(raw.under) ? (raw.under as unknown[]) : []),
+  ].filter((value) => value === MATCH_ANY);
+  if (wildcards.length > 0) {
+    if (raw.inSchema !== true) {
+      throw new Error(
+        `${describe}: 'match.inKind' / 'match.under' may only be '${MATCH_ANY}' together with ` +
+          `'inSchema: true' — the schema region is what bounds a walk the wildcard unbounds`,
+      );
+    }
+    if (!(raw.key as string).startsWith("x-telo-")) {
+      throw new Error(
+        `${describe}: '${MATCH_ANY}' is legal only for a rule keyed on an 'x-telo-*' annotation, ` +
+          `which is Telo vocabulary wherever it appears — '${raw.key}' could mean something else ` +
+          `inside a resource's own configuration`,
+      );
+    }
+  }
+
+  const match: {
+    key: string;
+    inKind: readonly string[];
+    under: readonly string[];
+    value?: unknown;
+    valueOneOf?: readonly unknown[];
+    withSibling?: string;
+    notUnder?: readonly string[];
+    inSchema?: boolean;
+  } = {
+    key: raw.key,
+    inKind: requireStringList(describe, raw, "inKind"),
+    under: requireStringList(describe, raw, "under"),
+  };
+  if (Object.hasOwn(raw, "value")) match.value = raw.value;
+  if (Object.hasOwn(raw, "valueOneOf")) match.valueOneOf = raw.valueOneOf as unknown[];
+  if (Object.hasOwn(raw, "withSibling")) match.withSibling = raw.withSibling as string;
+  if (Object.hasOwn(raw, "notUnder")) match.notUnder = raw.notUnder as string[];
+  if (raw.inSchema === true) match.inSchema = true;
+  return match;
+}
+
+/** One candidate site: a mapping entry whose key some rule is interested in. */
+interface MatchSite {
+  readonly path: MigrationPath;
+  readonly value: unknown;
+  readonly parent: Record<string, unknown>;
+}
+
+/** Every candidate site in one document, keyed by mapping key.
+ *
+ *  Built ONCE per document and shared by every rule that can apply to it,
+ *  because the walk is the expensive part and it does not depend on the rule —
+ *  this is on the kernel's boot path for every file in the graph, so a walk per
+ *  rule would scale the cost of loading any manifest with the size of the
+ *  migration set.
+ *
+ *  The walk is bounded by the same containment the rules declare: `roots` is
+ *  the union of the applicable rules' `under`, so a region no rule can reach is
+ *  never descended into and a document no rule can match is never walked at
+ *  all. Only keys some rule asked for allocate a path array. */
+export type MatchIndex = ReadonlyMap<string, readonly MatchSite[]>;
+
+/**
+ * Index `document`'s candidate sites for `keys`, descending only into the
+ * top-level regions named by `roots`.
+ *
+ * The caller has already gated on `inKind` — see `selectMatches`, which repeats
+ * the check because it holds the individual rule.
+ */
+export function buildMatchIndex(
+  document: unknown,
+  keys: ReadonlySet<string>,
+  roots: ReadonlySet<string>,
+): MatchIndex {
+  const index = new Map<string, MatchSite[]>();
+  if (keys.size === 0 || roots.size === 0 || !isPlainObject(document)) return index;
+
+  // A mutable stack, materialized into an array only when a site is recorded.
+  const stack: (string | number)[] = [];
+
+  const record = (key: string, value: unknown, parent: Record<string, unknown>): void => {
+    const bucket = index.get(key) ?? [];
+    bucket.push({ path: [...stack], value, parent });
+    index.set(key, bucket);
+  };
+
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) {
+        stack.push(i);
+        walk(node[i]);
+        stack.pop();
+      }
+      return;
+    }
+    if (!isPlainObject(node)) return;
+
+    for (const [key, value] of Object.entries(node)) {
+      stack.push(key);
+      if (keys.has(key)) record(key, value, node);
+      walk(value);
+      stack.pop();
+    }
+  };
+
+  // Anchored containment, enforced by where the walk STARTS: everything the
+  // index holds is at or below a top-level key some rule named. A wildcard root
+  // starts everywhere instead — bounded not by where the walk begins but by the
+  // schema region and the reserved key its rule had to declare to earn it.
+  const everywhere = roots.has(MATCH_ANY);
+  for (const [key, value] of Object.entries(document)) {
+    if (!everywhere && !roots.has(key)) continue;
+    stack.push(key);
+    if (keys.has(key)) record(key, value, document);
+    walk(value);
+    stack.pop();
+  }
+  return index;
+}
+
+/** The rules in `entries` that may match a document of `kind`, with the key and
+ *  root sets their shared index needs. Empty rules mean the document is not
+ *  walked at all. */
+export function applicableRules<T extends { readonly match: MigrationMatch }>(
+  rules: Iterable<T>,
+  kind: unknown,
+): { rules: T[]; keys: Set<string>; roots: Set<string> } {
+  const applicable: T[] = [];
+  const keys = new Set<string>();
+  const roots = new Set<string>();
+  if (typeof kind !== "string") return { rules: applicable, keys, roots };
+  for (const rule of rules) {
+    if (!rule.match.inKind.includes(kind) && !rule.match.inKind.includes(MATCH_ANY)) continue;
+    applicable.push(rule);
+    keys.add(rule.match.key);
+    for (const root of rule.match.under) roots.add(root);
+  }
+  return { rules: applicable, keys, roots };
+}
+
+function valueMatches(match: MigrationMatch, value: unknown): boolean {
+  if (Object.hasOwn(match, "value")) return deepEquals(match.value, value);
+  if (match.valueOneOf) return match.valueOneOf.some((candidate) => deepEquals(candidate, value));
+  return true;
+}
+
+/** The sites in `index` this match selects, in document order. */
+export function selectMatches(
+  index: MatchIndex,
+  document: unknown,
+  match: MigrationMatch,
+): MigrationPath[] {
+  const kind = isPlainObject(document) ? document.kind : undefined;
+  if (typeof kind !== "string") return [];
+  if (!match.inKind.includes(kind) && !match.inKind.includes(MATCH_ANY)) return [];
+
+  const sites = index.get(match.key);
+  if (!sites) return [];
+
+  const anyRoot = match.under.includes(MATCH_ANY);
+  const out: MigrationPath[] = [];
+  for (const site of sites) {
+    // The index may be shared with rules naming other regions, so the anchor is
+    // re-checked per rule. A numeric first segment cannot occur — a document is
+    // a mapping — but the guard keeps the containment claim independent of that.
+    const anchor = site.path[0];
+    if (!anyRoot && (typeof anchor !== "string" || !match.under.includes(anchor))) continue;
+    // The schema region — the same ancestry rule every schema-bounded surface
+    // reads, so the migration and the validators cannot disagree about where a
+    // schema is.
+    if (match.inSchema && !isInSchemaRegion(site.path)) continue;
+    // `notUnder` subtracts within the region, so it reads the whole path. A
+    // numeric segment never equals a key name, so the raw path is enough.
+    if (match.notUnder?.some((segment) => site.path.includes(segment))) continue;
+    if (!valueMatches(match, site.value)) continue;
+    if (match.withSibling !== undefined && !Object.hasOwn(site.parent, match.withSibling)) continue;
+    out.push(site.path);
+  }
+  return out;
+}
+
+/** Convenience for a single match against a document — builds a one-rule index.
+ *  The driver uses `applicableRules` + `buildMatchIndex` + `selectMatches` so
+ *  one walk serves every rule that can reach the document. */
+export function findMatches(document: unknown, match: MigrationMatch): MigrationPath[] {
+  const index = buildMatchIndex(document, new Set([match.key]), new Set(match.under));
+  return selectMatches(index, document, match);
+}

package/src/migrations/patch.ts

@@ -0,0 +1,265 @@
+/** Planning and applying a migration patch.
+ *
+ *  Planning is separate from applying because a patch is ALL-OR-NOTHING at each
+ *  match: a rule whose second operation cannot apply must not leave the first
+ *  one's edit behind. `planPatch` resolves every operation against the tree
+ *  first and returns either a concrete effect list or one refusal; only then
+ *  does an applier run. The same plan drives both appliers — the JSON tree the
+ *  loader hands the analyzer, and the YAML document `telo migrate` writes — so
+ *  the in-memory rewrite and the on-disk repair cannot disagree about what an
+ *  operation means. */
+
+import { makeTaggedSentinel } from "@telorun/templating";
+import { deepEquals } from "./match.js";
+import type {
+  MigrationOperation,
+  MigrationPath,
+  MigrationRefusal,
+} from "./types.js";
+
+/** A resolved, unconditionally applicable edit. */
+export type MigrationEffect =
+  | { readonly kind: "rename-key"; readonly parent: MigrationPath; readonly from: string; readonly to: string }
+  | { readonly kind: "set-value"; readonly path: MigrationPath; readonly value: unknown }
+  | { readonly kind: "set-tag"; readonly path: MigrationPath; readonly tag: string; readonly source: string }
+  | { readonly kind: "insert-item"; readonly path: MigrationPath; readonly index: number; readonly value: unknown }
+  | { readonly kind: "remove-entry"; readonly path: MigrationPath };
+
+export interface PatchPlan {
+  readonly effects: readonly MigrationEffect[];
+  /** Where the matched node lives after the patch. Differs from the matched
+   *  path only when a `rename-key` moved it. */
+  readonly finalPath: MigrationPath;
+  /** The value at the match before anything was applied — the "before" half of
+   *  the generated diagnostic sentence. */
+  readonly before: unknown;
+  /** The value at the match after the patch, or `undefined` for a removal. */
+  readonly after: unknown;
+}
+
+export type PatchPlanResult =
+  | { readonly ok: true; readonly plan: PatchPlan }
+  | { readonly ok: false; readonly refusal: MigrationRefusal };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The container a path's last segment indexes into, or `undefined` when any
+ *  hop is missing. An empty path has no container — the document root is not a
+ *  mapping entry and no operation targets it. */
+function containerOf(
+  root: unknown,
+  path: MigrationPath,
+): { container: unknown; key: string | number } | undefined {
+  if (path.length === 0) return undefined;
+  let current: unknown = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (typeof segment === "number") {
+      if (!Array.isArray(current)) return undefined;
+      current = current[segment];
+    } else {
+      if (!isPlainObject(current)) return undefined;
+      current = current[segment];
+    }
+  }
+  return { container: current, key: path[path.length - 1]! };
+}
+
+function readAt(root: unknown, path: MigrationPath): { found: boolean; value: unknown } {
+  const located = containerOf(root, path);
+  if (!located) return { found: false, value: undefined };
+  const { container, key } = located;
+  if (typeof key === "number") {
+    if (!Array.isArray(container) || key < 0 || key >= container.length) {
+      return { found: false, value: undefined };
+    }
+    return { found: true, value: container[key] };
+  }
+  if (!isPlainObject(container) || !Object.hasOwn(container, key)) {
+    return { found: false, value: undefined };
+  }
+  return { found: true, value: container[key] };
+}
+
+/** A scalar YAML can carry behind a tag, and the only thing `set-tag` and
+ *  `qualify` can operate on. */
+function scalarSource(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return undefined;
+}
+
+/**
+ * Resolve `ops` at `path` against `root`, or refuse.
+ *
+ * Refusing is the design's safety valve: the node is left exactly as the author
+ * wrote it and the ordinary validator reports it with an accurate message,
+ * rather than the migration guessing or dropping a value.
+ */
+export function planPatch(
+  root: unknown,
+  path: MigrationPath,
+  ops: readonly MigrationOperation[],
+): PatchPlanResult {
+  const initial = readAt(root, path);
+  if (!initial.found) return { ok: false, refusal: "path-not-found" };
+
+  const effects: MigrationEffect[] = [];
+  let currentPath: MigrationPath = path;
+  let currentValue = initial.value;
+  let removed = false;
+
+  for (const op of ops) {
+    if (removed) return { ok: false, refusal: "path-not-found" };
+
+    switch (op.op) {
+      case "rename-key": {
+        const located = containerOf(root, currentPath);
+        const key = located?.key;
+        if (!located || typeof key !== "string" || !isPlainObject(located.container)) {
+          return { ok: false, refusal: "not-a-mapping-entry" };
+        }
+        if (op.to !== key && Object.hasOwn(located.container, op.to)) {
+          // Refuse rather than replace: the occupied destination holds a value
+          // the author wrote.
+          return { ok: false, refusal: "destination-occupied" };
+        }
+        const parent = currentPath.slice(0, -1);
+        effects.push({ kind: "rename-key", parent, from: key, to: op.to });
+        currentPath = [...parent, op.to];
+        break;
+      }
+      case "set-value": {
+        let next: unknown;
+        if (op.qualify !== undefined) {
+          if (typeof currentValue !== "string") {
+            return { ok: false, refusal: "malformed-value" };
+          }
+          if (currentValue.startsWith(op.qualify)) {
+            return { ok: false, refusal: "nothing-to-rewrite" };
+          }
+          next = `${op.qualify}${currentValue}`;
+        } else {
+          // Same refusal as `qualify`'s, and for the same reason: a rule should
+          // match only the legacy spelling, so a write of the value already
+          // there means the matcher was too wide. Reporting it would be a
+          // deprecation reading `type: string is now written type: string`.
+          if (deepEquals(op.value, currentValue)) {
+            return { ok: false, refusal: "nothing-to-rewrite" };
+          }
+          next = op.value;
+        }
+        effects.push({ kind: "set-value", path: currentPath, value: next });
+        currentValue = next;
+        break;
+      }
+      case "set-tag": {
+        const source = scalarSource(currentValue);
+        if (source === undefined) return { ok: false, refusal: "not-a-scalar" };
+        effects.push({ kind: "set-tag", path: currentPath, tag: op.tag, source });
+        currentValue = makeTaggedSentinel(op.tag, source);
+        break;
+      }
+      case "insert-item": {
+        if (!Array.isArray(currentValue)) return { ok: false, refusal: "not-a-sequence" };
+        const index =
+          op.at === undefined
+            ? currentValue.length
+            : Math.max(0, Math.min(op.at, currentValue.length));
+        effects.push({ kind: "insert-item", path: currentPath, index, value: op.value });
+        currentValue = [
+          ...currentValue.slice(0, index),
+          op.value,
+          ...currentValue.slice(index),
+        ];
+        break;
+      }
+      case "remove-entry": {
+        effects.push({ kind: "remove-entry", path: currentPath });
+        currentValue = undefined;
+        removed = true;
+        break;
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    plan: {
+      effects,
+      finalPath: currentPath,
+      before: initial.value,
+      after: removed ? undefined : currentValue,
+    },
+  };
+}
+
+/** Apply a plan to the in-memory manifest tree. Mutates in place — the tree is
+ *  the loader's own projection of the document, never the author's file. */
+export function applyEffectsToTree(root: unknown, effects: readonly MigrationEffect[]): void {
+  for (const effect of effects) {
+    switch (effect.kind) {
+      case "rename-key": {
+        const parent =
+          effect.parent.length === 0 ? root : readAt(root, effect.parent).value;
+        if (!isPlainObject(parent)) continue;
+        // Rebuilt in place so the renamed key keeps its position. Key order is
+        // what a round-trip consumer and a rendered diff both read.
+        const entries = Object.entries(parent);
+        for (const [key] of entries) delete parent[key];
+        for (const [key, value] of entries) {
+          parent[key === effect.from ? effect.to : key] = value;
+        }
+        break;
+      }
+      case "set-value":
+      case "set-tag": {
+        const located = containerOf(root, effect.path);
+        if (!located) continue;
+        const next =
+          effect.kind === "set-value"
+            ? effect.value
+            : makeTaggedSentinel(effect.tag, effect.source);
+        writeAt(located.container, located.key, next);
+        break;
+      }
+      case "insert-item": {
+        const target = readAt(root, effect.path).value;
+        if (!Array.isArray(target)) continue;
+        target.splice(effect.index, 0, effect.value);
+        break;
+      }
+      case "remove-entry": {
+        const located = containerOf(root, effect.path);
+        if (!located) continue;
+        if (typeof located.key === "number") {
+          if (Array.isArray(located.container)) located.container.splice(located.key, 1);
+        } else if (isPlainObject(located.container)) {
+          delete located.container[located.key];
+        }
+        break;
+      }
+    }
+  }
+}
+
+function writeAt(container: unknown, key: string | number, value: unknown): void {
+  if (typeof key === "number") {
+    if (Array.isArray(container)) container[key] = value;
+    return;
+  }
+  if (isPlainObject(container)) container[key] = value;
+}
+
+/** Dotted rendering of a path, in the form the position index and every
+ *  diagnostic's `data.path` use: `routes[0].handler`. */
+export function formatMigrationPath(path: MigrationPath): string {
+  let out = "";
+  for (const segment of path) {
+    if (typeof segment === "number") out += `[${segment}]`;
+    else out += out.length === 0 ? segment : `.${segment}`;
+  }
+  return out;
+}