@telorun/analyzer 0.56.1 → 0.58.0

package/src/index.ts

@@ -65,7 +65,7 @@ export {
   PERMISSIVE_CONTRACT,
   resolveContract,
   resolveContractSchema,
-  withStreamPropertiesSkipped,
+  withLiveValuesSkipped,
 } from "./invocation-contract.js";
 export type { ContractOrigin, ContractScope, ResolvedContract } from "./invocation-contract.js";
 export {
@@ -97,7 +97,18 @@ export {
   transfersControl,
 } from "./ref-slot.js";
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
-export { binaryKeyword, isBinarySlot, X_TELO_BINARY } from "./binary-slot.js";
+export {
+  ANNOTATION_KEYWORDS,
+  registerTeloKeywords,
+  valueTypeKeyword,
+} from "./value-type-keyword.js";
+export {
+  applyTextEdits,
+  isPlainSafe,
+  quoteStyleOf,
+  renderFixReplacement,
+} from "./yaml-source-edit.js";
+export type { QuoteStyle, TextEdit } from "./yaml-source-edit.js";
 export {
   hasProvidesZone,
   hasRequiresZone,
@@ -123,6 +134,10 @@ export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
 export type { ZoneSlotIssue } from "./validate-zone-slots.js";
 export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validate-ref-slots.js";
 export type { RefSlotIssue } from "./validate-ref-slots.js";
+export { validateValueTypeSlots } from "./validate-value-type-slots.js";
+export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
+export { checkSchemaCompatibility } from "./schema-compat.js";
+export type { CompatibilityResult } from "./schema-compat.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
     CelSiteEvent,
@@ -139,6 +154,15 @@ export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
+export {
+  CORE_MIGRATIONS,
+  migrateFileText,
+  migrateManifests,
+  NO_MIGRATIONS,
+  parseMigrationEntry,
+  remapMigratedPaths,
+} from "./migrations/index.js";
+export type { FileMigrations, MigrationEntry, MigrationRewrite } from "./migrations/index.js";
 export { desugarLoadedFile, inlineImportManifests } from "./inline-imports.js";
 export type { SyntheticImport } from "./inline-imports.js";
 export {
@@ -207,6 +231,8 @@ export type {
   PlatformAxis,
   PlatformTarget,
 } from "./artifact-selector.js";
+export { collectModuleFileClaims } from "./module-file-claims.js";
+export type { ModuleFileClaim } from "./module-file-claims.js";
 export {
   LayerIndexError,
   matchControllerLayers,
@@ -224,10 +250,12 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
 export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export type { CelNode, CelSegment } from "./cel-ast.js";
-export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
+export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions,
+    DiagnosticData,
+    DiagnosticFix,
     LoaderInitOptions,
     LoadOptions,
     ManifestSource,

package/src/invocation-contract.ts

@@ -1,4 +1,4 @@
-import type { ResourceDefinition } from "@telorun/sdk";
+import { isLiveSlot, type ResourceDefinition } from "@telorun/sdk";
 import {
   type ContractDirection,
   contractDeclarer,
@@ -108,33 +108,41 @@ export function resolveContractSchema(
 }
 
 /**
- * A copy of `schema` with every `x-telo-stream`-marked property removed from
- * `properties` and `required`, for validating a runtime value against.
+ * A copy of `schema` with every `live`-typed node left unconstrained, for
+ * validating a runtime value against.
  *
- * Streams travel in BOTH directions — `Codec.Encoder` marks `input` on its
- * `inputType` and lists it in `required`, and `Record.Stream`, `Ai`, `Tar` and
- * `Console` do the same — so a one-directional skip would walk a live `Stream`
- * with AJV on the hottest path in the runtime. That is the same defect as
- * `stripCompiledValues` walking a live `ResourceInstance` in a ref slot: a live
- * object in a declared slot is not data to be traversed. The annotation already
- * marks exactly the properties to leave alone.
+ * Live values travel in BOTH directions — `Codec.Encoder` declares a stream on
+ * its `inputType` and lists it in `required`, and `Record.Stream`, `Ai`, `Tar`
+ * and `Console` do the same — so a one-directional skip would walk a live
+ * `Stream` with AJV on the hottest path in the runtime. That is the same defect
+ * as `stripCompiledValues` walking a live `ResourceInstance` in a ref slot: a
+ * live object in a declared slot is not data to be traversed.
+ *
+ * EXEMPTION IS A PROPERTY OF THE TYPE, not of a position. This used to neutralize
+ * only a key it found in a `properties` map, so an array-OF-streams element was
+ * reached and left constrained even though the walk descended into `items`.
+ * Reading the exemption off the declared value type makes an item, a union branch
+ * and a property the same case, and it is one rule instead of three.
+ *
+ * The exemption is from VALIDATION, never from TYPING: a live type's declared
+ * arguments still travel through every schema-typing walk the analyzer performs.
  *
  * Structural (returns a new object, never mutates), and shared so the analyzer
  * and the kernel exempt the same set.
  */
-export function withStreamPropertiesSkipped(
+export function withLiveValuesSkipped(
   schema: Record<string, any>,
   /** Resolves a `$ref` to the schema it names. Required to see through the
    *  reference form the runtime deliberately KEEPS intact for its validator: a
    *  contract written as `{ $ref: "telo:mod/Type" }` has none of its own
    *  properties, so a walk that cannot follow the reference exempts nothing and
-   *  the stream is traversed after all. */
+   *  the live value is traversed after all. */
   resolveRef?: (ref: string) => Record<string, any> | undefined,
 ): Record<string, any> {
-  return stripStreams(schema, [], resolveRef);
+  return stripLive(schema, [], resolveRef);
 }
 
-function stripStreams(
+function stripLive(
   node: unknown,
   // A PATH-scoped guard, not a global memo: a schema object reached twice from
   // different parents must be stripped twice (a global `seen` would hand the
@@ -145,7 +153,7 @@ function stripStreams(
   if (Array.isArray(node)) {
     let changed = false;
     const items = node.map((item) => {
-      const next = stripStreams(item, path, resolveRef);
+      const next = stripLive(item, path, resolveRef);
       if (next !== item) changed = true;
       return next;
     });
@@ -155,6 +163,14 @@ function stripStreams(
   let schema = node as Record<string, any>;
   if (path.includes(schema)) return schema;
 
+  // The one rule. An empty schema leaves the node DECLARED but unconstrained,
+  // rather than deleted: deleting a property would force `additionalProperties:
+  // false` open, and a closed contract would stop rejecting unknown keys the
+  // moment it grew a stream — trading one exemption for a hole across the whole
+  // shape. `required` is untouched for the same reason: a live value IS present,
+  // it is only not walked.
+  if (isLiveSlot(schema)) return {};
+
   // Follow a whole-document reference to SEE the annotations behind it, but
   // return the original node when nothing behind it was stripped. Substituting
   // the resolved target unconditionally would break schema identity — the
@@ -163,7 +179,7 @@ function stripStreams(
   if (resolveRef && typeof schema.$ref === "string") {
     const target = resolveRef(schema.$ref);
     if (target && !path.includes(target)) {
-      const stripped = stripStreams(target, [...path, schema], resolveRef);
+      const stripped = stripLive(target, [...path, schema], resolveRef);
       if (stripped === target) return node;
       const { $ref: _ref, ...siblings } = schema;
       return Object.keys(siblings).length > 0 ? { ...stripped, ...siblings } : stripped;
@@ -171,44 +187,23 @@ function stripStreams(
   }
   const here = [...path, schema];
 
-  let out: Record<string, any> = schema;
-  const properties = schema.properties as Record<string, any> | undefined;
-  if (properties) {
-    // A stream can be contributed by an `allOf` branch too (how type inheritance
-    // is expressed before the branches are merged), so the marked set is read
-    // from the folded view while the removal is applied here.
-    const streamed = Object.keys(properties).filter(
-      (key) => (properties[key] as Record<string, any> | undefined)?.["x-telo-stream"],
-    );
-    if (streamed.length > 0) {
-      const kept: Record<string, any> = {};
-      for (const [key, value] of Object.entries(properties)) {
-        if (!streamed.includes(key)) kept[key] = value;
-      }
-      // The key stays DECLARED but unconstrained, rather than being deleted.
-      // Deleting it would force `additionalProperties: false` open, and a closed
-      // contract would stop rejecting unknown keys the moment it grew a stream —
-      // trading one exemption for a hole across the whole shape.
-      for (const key of streamed) kept[key] = {};
-      out = { ...schema, properties: kept };
-    }
-  }
-
-  // Recurse: a stream one level down (an item, a branch, a nested object) is as
-  // live as one at the root, and walking it with AJV is the same defect.
+  // Recurse: a live value one level down (a property, an item, a branch, a
+  // nested object) is as live as one at the root, and walking it with AJV is the
+  // same defect. Each is neutralized by the single rule above when the walk
+  // reaches it.
   //
   // `properties` and `$defs` are MAPS of schemas, not schemas — descending into
   // them as if they were would visit nothing, since a map has none of the
   // keywords this walk looks for.
-  let changed = out !== schema;
-  const result: Record<string, any> = { ...out };
+  let changed = false;
+  const result: Record<string, any> = { ...schema };
   for (const key of ["properties", "$defs"] as const) {
-    const map = out[key] as Record<string, any> | undefined;
+    const map = schema[key] as Record<string, any> | undefined;
     if (!map || typeof map !== "object") continue;
     let mapChanged = false;
     const next: Record<string, any> = {};
     for (const [name, child] of Object.entries(map)) {
-      const stripped = stripStreams(child, here, resolveRef);
+      const stripped = stripLive(child, here, resolveRef);
       if (stripped !== child) mapChanged = true;
       next[name] = stripped;
     }
@@ -218,9 +213,9 @@ function stripStreams(
     }
   }
   for (const key of ["items", "allOf", "anyOf", "oneOf"] as const) {
-    const child = out[key];
+    const child = schema[key];
     if (child === undefined) continue;
-    const next = stripStreams(child, here, resolveRef);
+    const next = stripLive(child, here, resolveRef);
     if (next !== child) {
       result[key] = next;
       changed = true;
@@ -237,7 +232,7 @@ function stripStreams(
  *  schema's defaults rather than by the size of the payload. */
 export function defaultBearingPaths(
   schema: Record<string, any>,
-  /** See {@link withStreamPropertiesSkipped} — a contract kept in `$ref` form
+  /** See {@link withLiveValuesSkipped} — a contract kept in `$ref` form
    *  declares its defaults behind the reference, and a walk that cannot follow
    *  it would report none, leaving the caller's data shared where a fill lands. */
   resolveRef?: (ref: string) => Record<string, any> | undefined,

package/src/loaded-types.ts

@@ -1,5 +1,6 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import type { Document } from "yaml";
+import type { FileMigrations } from "./migrations/driver.js";
 import type { DocumentPosition } from "./position-metadata.js";
 import type { AnalysisDiagnostic, Range } from "./types.js";
 import type { AstDocument } from "./yaml-ast.js";
@@ -31,6 +32,12 @@ export interface LoadedFile {
   positions: DocumentPosition[];
   /** Document-level parse errors aggregated from `yaml.Document.errors`. */
   parseErrors: ParseError[];
+  /** What the migration phase rewrote in this file, and the diagnostics for it.
+   *  Empty unless the load opted into `migrate` AND a legacy spelling matched.
+   *  `manifests` above are the POST-migration tree; `documents` / `astDocuments`
+   *  / `positions` / `text` are always the author's file untouched, which is
+   *  what the recorded `legacyPath` resolves against. */
+  migrations: FileMigrations;
 }
 
 export interface ParseError {
@@ -93,6 +100,12 @@ export interface LoadedGraph {
    *  it independently re-resolves an import (the analyzer already sees repointed
    *  `importEdges`). Empty when no module identity appeared at two sources. */
   overrides: Map<string, string>;
+  /** Deprecation diagnostics from the loader's migration phase, scoped to the
+   *  ENTRY's own module (owner + its `include:` partials). A migration rewrites
+   *  always — the runtime must read artifacts published years ago — but reports
+   *  only here, because a published dependency is not the consumer's to fix.
+   *  Empty unless the load opted into `migrate`. */
+  migrationDiagnostics: AnalysisDiagnostic[];
   /** Diagnostics produced while reconciling module versions — one per import
    *  edge redirected to a different version (warning for a same-major hoist,
    *  error for a major mismatch). Surfaced alongside `analyze()` diagnostics by

package/src/manifest-loader.ts

@@ -9,6 +9,7 @@ import type {
   LoadedModule,
 } from "./loaded-types.js";
 import { desugarLoadedFile } from "./inline-imports.js";
+import type { MigrationEntry } from "./migrations/types.js";
 import { isModuleKind } from "./module-kinds.js";
 import { parseLoadedFile } from "./parse-loaded-file.js";
 import { reconcileModuleVersions } from "./reconcile-module-versions.js";
@@ -44,6 +45,18 @@ function collectParseDiagnostics(
   return diagnostics;
 }
 
+/** Rewrite always, report locally. Every file in the graph was migrated, but a
+ *  published dependency's manifest is not the consumer's to fix and its author
+ *  is the only person who can — so only the entry module's own files (owner +
+ *  its `include:` partials) report. Same rule `X_TELO_REF_UNRESOLVED` follows. */
+function collectMigrationDiagnostics(entry: LoadedModule): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+  for (const file of [entry.owner, ...entry.partials]) {
+    diagnostics.push(...file.migrations.diagnostics);
+  }
+  return diagnostics;
+}
+
 const SYSTEM_KINDS = new Set([
   "Telo.Application",
   "Telo.Library",
@@ -51,12 +64,19 @@ const SYSTEM_KINDS = new Set([
   "Telo.Definition",
 ]);
 
-/** File cache variant tags: compile (c/r) × desugarImports (d/n). A desugared
- *  and a raw load of the same file are distinct entries so neither sees the
- *  wrong manifest tree. */
-const CACHE_VARIANTS = ["rn", "rd", "cn", "cd"] as const;
+/** File cache variant tags: compile (c/r) × desugarImports (d/n) × migrate
+ *  (m/x). A desugared and a raw load of the same file are distinct entries so
+ *  neither sees the wrong manifest tree, and the migration axis is there for
+ *  the same reason — the editor's round-trip view and `telo migrate` must see
+ *  the author's spelling, everything else the current one. */
+const CACHE_VARIANTS = [
+  "rnx", "rdx", "cnx", "cdx",
+  "rnm", "rdm", "cnm", "cdm",
+] as const;
 function variantKey(options?: LoadOptions): string {
-  return `${options?.compile ? "c" : "r"}${options?.desugarImports ? "d" : "n"}`;
+  return `${options?.compile ? "c" : "r"}${options?.desugarImports ? "d" : "n"}${
+    options?.migrate ? "m" : "x"
+  }`;
 }
 
 export class Loader {
@@ -76,6 +96,7 @@ export class Loader {
 
   protected sources: ManifestSource[];
   private readonly celEnv: Environment;
+  private readonly migrations?: readonly MigrationEntry[];
 
   /** Sources are resolved in order — the first whose `supports(url)` matches
    *  wins. The caller (composition root) decides which concrete sources exist
@@ -85,6 +106,7 @@ export class Loader {
   constructor(sources: ManifestSource[] = [], options: LoaderInitOptions = {}) {
     this.sources = [...sources];
     this.celEnv = buildCelEnvironment(options.celHandlers);
+    this.migrations = options.migrations;
   }
 
   register(source: ManifestSource): this {
@@ -188,7 +210,13 @@ export class Loader {
    *  caller opted in. Desugaring lives here, not in the pure `parseLoadedFile`,
    *  so round-trip consumers (the editor) keep a raw manifest/AST/position
    *  triple they can pair by index; only resolved consumers that pass
-   *  `desugarImports` see synthetic Telo.Import manifests. */
+   *  `desugarImports` see synthetic Telo.Import manifests.
+ *
+ *  The migration phase runs inside `parseLoadedFile`, i.e. before desugaring —
+ *  a rule must only ever match author-written nodes, and the position is what
+ *  makes that structural rather than a convention. Nothing needs the later
+ *  position: the `imports:` map is read straight off the module manifest and is
+ *  equally available before desugaring. */
   private parseAndMaybeDesugar(
     source: string,
     requestedUrl: string,
@@ -198,6 +226,8 @@ export class Loader {
     const loaded = parseLoadedFile(source, requestedUrl, text, {
       compile: options?.compile,
       celEnv: this.celEnv,
+      migrate: options?.migrate,
+      migrations: this.migrations,
     });
     return options?.desugarImports ? desugarLoadedFile(loaded) : loaded;
   }
@@ -364,6 +394,7 @@ export class Loader {
       modules,
       importEdges,
       overrides,
+      migrationDiagnostics: collectMigrationDiagnostics(entry),
       versionDiagnostics: diagnostics,
       parseDiagnostics: collectParseDiagnostics(modules),
       errors,

package/src/manifest-visitor.ts

@@ -1,5 +1,10 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
+import {
+  isRefSentinel,
+  isTaggedSentinel,
+  walkCelExpressions,
+  type CelSurface,
+} from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -114,6 +119,9 @@ export interface CelSiteEvent {
   contextSchema?: Record<string, any>;
   /** Scope of the matched context (e.g. `$.routes[*].handler`), if matched. */
   matchedScope?: string;
+  /** Where `expr` sits in the scalar at `path`, and the delimiters to restore
+   *  around a corrected expression. See `CelSurface`. */
+  surface: CelSurface;
 }
 
 export interface ManifestVisitor {
@@ -352,7 +360,7 @@ export function visitManifest(
 
     if (wantsCel) {
       const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
-      walkCelExpressions(r, "", (expr, path, engineName) => {
+      walkCelExpressions(r, "", (expr, path, engineName, surface) => {
         let contextSchema: Record<string, any> | undefined;
         let matchedScope: string | undefined;
         for (const ctx of contexts) {
@@ -362,7 +370,7 @@ export function visitManifest(
             break;
           }
         }
-        visitor.onCel!({ source: r, path, expr, engineName, contextSchema, matchedScope });
+        visitor.onCel!({ source: r, path, expr, engineName, contextSchema, matchedScope, surface });
       });
     }
 

package/src/migrations/driver.ts

@@ -0,0 +1,262 @@
+/** The migration driver — one pass, one set of guarantees.
+ *
+ *  **Composition is the driver's guarantee, not each entry's proof
+ *  obligation.** The match set is frozen against the pre-migration tree, so no
+ *  rule can match a node another rule produced; rules within an entry apply in
+ *  order at each match; entries never see one another's output. That matters
+ *  once core and module entries are aggregated from different parties, where
+ *  "it happens to work" is not determinism. Idempotency then follows from the
+ *  driver rather than from every author getting it right: a rule matches only
+ *  the legacy spelling, and re-running finds nothing.
+ *
+ *  How a rewrite is REPORTED — the provenance record and the diagnostic — is
+ *  `report.ts`. Nothing there can change what a migration does, and nothing
+ *  here decides how it reads. */
+
+import type { ResourceManifest } from "@telorun/sdk";
+import type { Document } from "yaml";
+import {
+  applyEffectsToTree,
+  formatMigrationPath,
+  planPatch,
+  type MigrationEffect,
+} from "./patch.js";
+import { applyTextEdits, planTextEdits, type TextEdit } from "./yaml-edit.js";
+import { applicableRules, buildMatchIndex, selectMatches } from "./match.js";
+import { CORE_MIGRATIONS } from "./registry.js";
+import { toDiagnostic, toRewrite, type AppliedPatch } from "./report.js";
+import type {
+  MigrationEntry,
+  MigrationOperation,
+  MigrationPath,
+  MigrationRewrite,
+} from "./types.js";
+import type { AnalysisDiagnostic } from "../types.js";
+
+/** What one file's migration produced. */
+export interface FileMigrations {
+  /** One record per applied rewrite, in application order. Empty when the file
+   *  carried no legacy spelling — the overwhelmingly common case. */
+  readonly rewrites: readonly MigrationRewrite[];
+  /** One diagnostic per rewrite. Whether they are SURFACED is the graph's
+   *  decision: a migration rewrites always, because the runtime must read
+   *  artifacts published years ago, but reports only for the entry's own
+   *  modules, because a published dependency is not the consumer's to fix. */
+  readonly diagnostics: readonly AnalysisDiagnostic[];
+}
+
+export const NO_MIGRATIONS: FileMigrations = { rewrites: [], diagnostics: [] };
+
+/**
+ * Run `entries` over one file's parsed documents, mutating `manifests` in
+ * place. Returns the provenance records and their diagnostics.
+ *
+ * The manifests are the loader's own projection of the file, never the
+ * author's text — nothing here can reach disk.
+ */
+export function migrateManifests(args: {
+  source: string;
+  manifests: Array<ResourceManifest | null>;
+  entries?: readonly MigrationEntry[];
+}): FileMigrations {
+  const entries = args.entries ?? CORE_MIGRATIONS;
+  if (entries.length === 0) return NO_MIGRATIONS;
+
+  const applied = applyAll(args.manifests, entries);
+  if (applied.length === 0) return NO_MIGRATIONS;
+
+  const rewrites = applied.map((a) => toRewrite(a));
+  const diagnostics = applied.map((a, i) =>
+    toDiagnostic(a, rewrites[i]!, args.source, args.manifests),
+  );
+  return { rewrites, diagnostics };
+}
+
+/**
+ * Migrate the author's YAML instead of the loader's tree — the operation
+ * `telo migrate` is the reference application of.
+ *
+ * `manifests` must be the RAW (un-migrated) projection of `documents`, since
+ * the matchers select legacy spellings. Returns `null` when nothing matched, so
+ * a caller can leave an untouched file untouched rather than rewriting
+ * identical bytes.
+ *
+ * `unwritable` names every rewrite the tree accepted but the TEXT could not
+ * express. The two appliers can disagree only in this direction, and the
+ * disagreement has to be reported: the diagnostic that sent the author here
+ * says "run `telo migrate`", so a location this silently skipped would keep
+ * warning with no way to act on it.
+ */
+export function migrateFileText(args: {
+  source: string;
+  text: string;
+  documents: readonly Document[];
+  manifests: ReadonlyArray<ResourceManifest | null>;
+  entries?: readonly MigrationEntry[];
+}): {
+  text: string;
+  rewrites: MigrationRewrite[];
+  unwritable: MigrationRewrite[];
+} | null {
+  const entries = args.entries ?? CORE_MIGRATIONS;
+  if (entries.length === 0) return null;
+
+  // Planned against a copy: the tree walk is what decides which patches apply
+  // (and in what order they refuse), so the YAML side must ask exactly the same
+  // question of exactly the same state rather than re-deriving it.
+  const scratch = args.manifests.map((m) => (m ? (structuredClone(m) as ResourceManifest) : null));
+  const applied = applyAll(scratch, entries);
+  if (applied.length === 0) return null;
+
+  const edits: TextEdit[] = [];
+  const kept: AppliedPatch[] = [];
+  const skipped: AppliedPatch[] = [];
+  for (const patch of applied) {
+    const doc = args.documents[patch.documentIndex];
+    if (!doc) {
+      skipped.push(patch);
+      continue;
+    }
+    const planned = planTextEdits(doc, args.text, patch.plan.effects);
+    // A patch the tree accepted but the text cannot express (a block scalar
+    // span, a flow-style entry) leaves that node alone rather than half-written.
+    if (!planned) {
+      skipped.push(patch);
+      continue;
+    }
+    // Two patches whose spans overlap cannot both be spliced — the second would
+    // write into bytes the first replaced. The tree side has no equivalent,
+    // because an object write is idempotent where a splice is positional, so
+    // this is the one place the file applier is stricter: the later patch is
+    // dropped and its node stays as the author wrote it.
+    if (planned.some((edit) => edits.some((existing) => overlaps(edit, existing)))) {
+      skipped.push(patch);
+      continue;
+    }
+    edits.push(...planned);
+    kept.push(patch);
+  }
+  if (edits.length === 0 && skipped.length === 0) return null;
+
+  return {
+    text: edits.length > 0 ? applyTextEdits(args.text, edits) : args.text,
+    rewrites: kept.map(toRewrite),
+    unwritable: skipped.map(toRewrite),
+  };
+}
+
+/** Whether two splices contend for the same bytes. A pure insertion (an empty
+ *  span) collides only with a span that strictly contains its point. */
+function overlaps(a: TextEdit, b: TextEdit): boolean {
+  if (a.start === a.end) return b.start < a.start && a.start < b.end;
+  if (b.start === b.end) return a.start < b.start && b.start < a.end;
+  return a.start < b.end && b.start < a.end;
+}
+
+/** One pass: every match collected against the frozen pre-migration tree, then
+ *  applied in entry order. */
+function applyAll(
+  manifests: Array<ResourceManifest | null>,
+  entries: readonly MigrationEntry[],
+): AppliedPatch[] {
+  const candidates: Array<{
+    entry: MigrationEntry;
+    ops: readonly MigrationOperation[];
+    documentIndex: number;
+    path: MigrationPath;
+  }> = [];
+
+  // One index per DOCUMENT, shared by every rule that can reach it — the walk
+  // is the expensive part and does not depend on the rule. This runs 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 `inKind` gate and the `under` regions are both known BEFORE the walk,
+  // so they bound it rather than filtering its output: a document no rule
+  // targets is never walked, and a region no rule names is never descended
+  // into. `type:` alone occurs a couple of hundred times in a standard-library
+  // manifest, so indexing sites that cannot be selected is the whole cost.
+  const flatRules = entries.flatMap((entry) =>
+    entry.rules.map((rule) => ({ entry, ops: rule.patch, match: rule.match })),
+  );
+  for (let documentIndex = 0; documentIndex < manifests.length; documentIndex++) {
+    const manifest = manifests[documentIndex];
+    if (!manifest) continue;
+    const { rules, keys, roots } = applicableRules(flatRules, manifest.kind);
+    if (rules.length === 0) continue;
+    const index = buildMatchIndex(manifest, keys, roots);
+    for (const { entry, ops, match } of rules) {
+      for (const path of selectMatches(index, manifest, match)) {
+        candidates.push({ entry, ops, documentIndex, path });
+      }
+    }
+  }
+
+  // Arrays whose LENGTH an already-applied patch changed, as
+  // `<documentIndex>:<dotted path>`. A frozen match names a sequence element by
+  // INDEX, and an index is not an identity: once a sibling patch inserted or
+  // removed an item, the same index names a different element — including one
+  // another rule just produced, which is exactly what the frozen match set
+  // exists to prevent. A key-based path needs no such record, because a rename
+  // or removal makes the stale path resolve to nothing and `planPatch` refuses
+  // it on its own.
+  const shiftedArrays = new Set<string>();
+
+  const applied: AppliedPatch[] = [];
+  for (const candidate of candidates) {
+    const manifest = manifests[candidate.documentIndex];
+    if (!manifest) continue;
+    if (indexIsStale(candidate.documentIndex, candidate.path, shiftedArrays)) continue;
+    const result = planPatch(manifest, candidate.path, candidate.ops);
+    // Refusal is not an error: the node stays as the author wrote it and the
+    // ordinary validator reports it with an accurate message.
+    if (!result.ok) continue;
+    applyEffectsToTree(manifest, result.plan.effects);
+    for (const array of resizedArrays(candidate.documentIndex, result.plan.effects)) {
+      shiftedArrays.add(array);
+    }
+    applied.push({
+      entry: candidate.entry,
+      documentIndex: candidate.documentIndex,
+      matched: candidate.path,
+      plan: result.plan,
+      ops: candidate.ops,
+    });
+  }
+  return applied;
+}
+
+/** Arrays this patch resized, keyed for `shiftedArrays`. */
+function resizedArrays(
+  documentIndex: number,
+  effects: readonly MigrationEffect[],
+): string[] {
+  const out: string[] = [];
+  for (const effect of effects) {
+    if (effect.kind === "insert-item") {
+      out.push(`${documentIndex}:${formatMigrationPath(effect.path)}`);
+    } else if (
+      effect.kind === "remove-entry" &&
+      typeof effect.path[effect.path.length - 1] === "number"
+    ) {
+      out.push(`${documentIndex}:${formatMigrationPath(effect.path.slice(0, -1))}`);
+    }
+  }
+  return out;
+}
+
+/** Whether any index along `path` steps into an array a prior patch resized. */
+function indexIsStale(
+  documentIndex: number,
+  path: MigrationPath,
+  shiftedArrays: ReadonlySet<string>,
+): boolean {
+  if (shiftedArrays.size === 0) return false;
+  for (let i = 0; i < path.length; i++) {
+    if (typeof path[i] !== "number") continue;
+    if (shiftedArrays.has(`${documentIndex}:${formatMigrationPath(path.slice(0, i))}`)) {
+      return true;
+    }
+  }
+  return false;
+}