@telorun/analyzer 0.57.0 → 0.58.0

package/src/analyzer.ts

@@ -5,6 +5,7 @@ import {
   defaultRegistry,
   isRefSentinel,
   isTaggedSentinel,
+  plainChainOf,
   type CelSurface,
 } from "@telorun/templating";
 import type { DiagnosticFix } from "./types.js";
@@ -56,11 +57,17 @@ import {
   validateRefSlotDeclarations,
   type RefSlotIssue,
 } from "./validate-ref-slots.js";
+import {
+  validateValueTypeSlots,
+  type ValueTypeSlotIssue,
+} from "./validate-value-type-slots.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
   celTypeSatisfiesJsonSchema,
+  checkSchemaCompatibility,
+  navigateSchemaToExprPath,
   substituteCelFields,
   validateAgainstSchema,
   type SchemaIssue,
@@ -1201,6 +1208,18 @@ export class StaticAnalyzer {
     const refConstraintIssues: RefConstraintIssue[] = [];
     const refSlotIssues: RefSlotIssue[] = [];
     const zoneSlotIssues: ZoneSlotIssue[] = [];
+    // `x-telo-type` is checked on EVERY manifest, not only on definition docs: a
+    // schema fragment is written wherever a kind declares a schema-valued field,
+    // so an inline `inputType:` on an ordinary resource carries one just as a
+    // definition's `schema:` does. Same scoping as every other schema issue —
+    // the entry's own modules, since a dependency is not the consumer's to fix.
+    const valueTypeSlotIssues: ValueTypeSlotIssue[] = [];
+    for (const m of manifests) {
+      const declaringModule = (m.metadata as { module?: string } | undefined)?.module;
+      if (!declaringModule || rootModules.has(declaringModule)) {
+        valueTypeSlotIssues.push(...validateValueTypeSlots(m as unknown as ResourceManifest));
+      }
+    }
     for (const m of manifests) {
       if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
       const def = m as unknown as ResourceDefinition;
@@ -1340,6 +1359,26 @@ export class StaticAnalyzer {
       // accessor split; `readRefSlot` stays lenient so surfaces keep working
       // mid-migration, and this reports what leniency would silently absorb.
       for (const issue of refSlotIssues) diagnostics.push(refSlotIssueDiagnostic(issue));
+      // The same split for `x-telo-type`. Its reader returns a slot with no
+      // entry for a name it does not know, which is what an unrecognized brand
+      // used to do SILENTLY — the slot simply lost its identity.
+      for (const issue of valueTypeSlotIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+            ...(issue.fix ? { fix: issue.fix } : {}),
+          },
+        });
+      }
       // Same split for the two zone annotations. Unreadable ones fail in
       // OPPOSITE directions — a dropped requirement is silently unenforced, a
       // dropped provision invents failures — so neither can be left to
@@ -1625,6 +1664,11 @@ export class StaticAnalyzer {
       filePath?: string;
     })[] = [];
     const celTypeByPath = new Map<ResourceManifest, Map<string, string>>();
+    // The schema an expression RESOLVES TO, beside the CEL type it carries. Both
+    // are needed and neither replaces the other: the CEL type answers "does this
+    // fit the slot at all", the schema answers "do their type arguments agree",
+    // which cel-js cannot express because it types by constructor identity.
+    const celSourceSchemaByPath = new Map<ResourceManifest, Map<string, Record<string, any>>>();
     // Context-free typed environments, one per manifest. Reused across every
     // expression in it — see the build site for why a matched context opts out.
     const typedEnvByManifest = new Map<ResourceManifest, Environment>();
@@ -1962,12 +2006,15 @@ export class StaticAnalyzer {
               defs,
               aliases,
               { aliasesByModule, rootModules },
+              celStepContextSchema,
             )) {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: "CONTRACT_INPUTS_MISMATCH",
+                code: issue.code ?? "CONTRACT_INPUTS_MISMATCH",
                 source: SOURCE,
-                message: `${m.kind}/${stepName}: inputs at '${issue.path}' do not satisfy ${issue.targetLabel}'s declared inputType: ${issue.message}`,
+                message: issue.code
+                  ? `${m.kind}/${stepName}: inputs at '${issue.path}' flow into ${issue.targetLabel} with disagreeing type arguments: ${issue.message}`
+                  : `${m.kind}/${stepName}: inputs at '${issue.path}' do not satisfy ${issue.targetLabel}'s declared inputType: ${issue.message}`,
                 data: {
                   resource: { kind: m.kind, name: stepName ?? "" },
                   filePath: stepFile,
@@ -2260,6 +2307,30 @@ export class StaticAnalyzer {
             byPath.set(path, result.type);
           }
 
+          // The producer half of the type-argument check. A CEL type is a bare
+          // name — cel-js types by constructor identity, so a byte stream and a
+          // string stream are one CEL type and always will be — so the argument
+          // comparison is a parallel pass over the SCHEMAS the analyzer already
+          // walks. This is where the producer's schema is in hand: navigating
+          // the expression's chain into its context schema is exactly "the
+          // producer's outputType at the expression's tail".
+          //
+          // Only a PLAIN CHAIN is navigated — `steps.encode.result.output`, the
+          // shape a wiring site actually takes. An expression that computes
+          // rather than names has no schema to read off the context, so it
+          // records nothing and no argument check fires: silence where the
+          // analyzer knows least is the conservative direction, and the same one
+          // `x-telo-step-context`'s pure-`value` typing takes.
+          const chain = effectiveContext ? plainChainOf(`\${{${expr}}}`) : undefined;
+          if (chain) {
+            const produced = navigateSchemaToExprPath(effectiveContext!, chain);
+            if (produced) {
+              let byPath = celSourceSchemaByPath.get(m);
+              if (!byPath) celSourceSchemaByPath.set(m, (byPath = new Map()));
+              byPath.set(path, produced);
+            }
+          }
+
           // A non-deterministic call in a compile-eval field is baked once at
           // load: `nowIso()` there freezes at boot. Sometimes that is the
           // intent (a boot timestamp, a run id), so it warns rather than
@@ -2331,13 +2402,35 @@ export class StaticAnalyzer {
     for (const slot of celReturnSlots) {
       const type = celTypeByPath.get(slot.manifest)?.get(slot.path);
       if (type === undefined) continue;
-      if (celTypeSatisfiesJsonSchema(type.split("<")[0]!, slot.schema)) continue;
-      const expected = slot.schema["x-telo-type"] ?? slot.schema.type ?? "unknown";
+      if (!celTypeSatisfiesJsonSchema(type.split("<")[0]!, slot.schema)) {
+        const expected = slot.schema["x-telo-type"] ?? slot.schema.type ?? "unknown";
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "CEL_TYPE_ERROR",
+          source: SOURCE,
+          message: `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' returns '${type}' but the field expects '${expected}'.`,
+          data: { resource: slot.resource, filePath: slot.filePath, path: slot.path },
+        });
+        continue;
+      }
+      // The type fits; do its ARGUMENTS agree? Covariant and gradual — an
+      // omitted argument is *any* in both directions, so an unmigrated producer
+      // or consumer is never reported, and only a definite conflict is.
+      const produced = celSourceSchemaByPath.get(slot.manifest)?.get(slot.path);
+      if (!produced) continue;
+      const { compatible, issues } = checkSchemaCompatibility(
+        produced,
+        slot.schema,
+        (ref: string) => defs.schemaForId(ref),
+      );
+      if (compatible) continue;
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
-        code: "CEL_TYPE_ERROR",
+        code: "CEL_TYPE_ARGUMENT_MISMATCH",
         source: SOURCE,
-        message: `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' returns '${type}' but the field expects '${expected}'.`,
+        message:
+          `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' produces a value ` +
+          `whose type arguments disagree with the field's: ${issues.join("; ")}.`,
         data: { resource: slot.resource, filePath: slot.filePath, path: slot.path },
       });
     }

package/src/cel-environment.ts

@@ -3,10 +3,13 @@ import type { ResourceManifest } from "@telorun/sdk";
 import { jsonSchemaToCelType, VALUE_BRAND_BASE } from "./schema-compat.js";
 
 /** Transport protocol on a `ports` entry → the nominal CEL brand its resolved
- *  value carries. Mirrors the `protocol` enum in the Application schema. */
+ *  value carries. Mirrors the `protocol` enum in the Application schema, and
+ *  names the value types by their canonical `Telo.`-qualified names — the same
+ *  spelling an author writes at `x-telo-type`, so a branded port and a branded
+ *  field are comparable by name with nothing in between to translate. */
 const PORT_PROTOCOL_BRAND: Record<string, string> = {
-  tcp: "TcpPort",
-  udp: "UdpPort",
+  tcp: "Telo.TcpPort",
+  udp: "Telo.UdpPort",
 };
 
 export { buildCelEnvironment } from "@telorun/templating";

package/src/definition-registry.ts

@@ -127,6 +127,16 @@ export class DefinitionRegistry {
     return this.registeredSchemaIds.has(id) || this.ajv.getSchema(id) !== undefined;
   }
 
+  /** The schema registered under `id`, for a structural comparison that must see
+   *  THROUGH a named shape. Declaring a shape once and referencing it is the
+   *  sanctioned way to reuse one, so a comparator that cannot follow the
+   *  reference judges two opaque nodes and learns nothing. */
+  schemaForId(id: string): Record<string, any> | undefined {
+    const compiled = this.ajv.getSchema(id);
+    const schema = compiled?.schema;
+    return schema && typeof schema === "object" ? (schema as Record<string, any>) : undefined;
+  }
+
   /** Validates data against a schema using this registry's AJV instance, which has all
    *  registered definition schemas loaded — enabling cross-module $ref resolution.
    *  A compile failure returns `[]` here; it is surfaced loudly (once, on the

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 {

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,