@telorun/analyzer 0.57.0 → 0.58.0

package/dist/loaded-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loaded-types.d.ts","sourceRoot":"","sources":["../src/loaded-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;4EAI4E;AAC5E,MAAM,WAAW,UAAU;IACzB;+DAC2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf;gEAC4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;+EAE2E;IAC3E,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB;+EAC2E;IAC3E,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,SAAS,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;mCACmC;AACnC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB;oEACgE;IAChE,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;;;;sCAKsC;AACtC,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB;;;kEAG8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;6EACyE;IACzE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;kDAE8C;IAC9C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;0BAC0B;AAC1B,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB;;wBAEoB;IACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC;;;;2BAIuB;IACvB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAClD;;;iFAG6E;IAC7E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;iDAG6C;IAC7C,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IACzC;;;8EAG0E;IAC1E,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC;yCACqC;IACrC,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B;8BAC0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ;;qEAEiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;gFAE4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;CACd"}
+{"version":3,"file":"loaded-types.d.ts","sourceRoot":"","sources":["../src/loaded-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;4EAI4E;AAC5E,MAAM,WAAW,UAAU;IACzB;+DAC2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf;gEAC4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;+EAE2E;IAC3E,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB;+EAC2E;IAC3E,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,SAAS,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B;;;;2DAIuD;IACvD,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;mCACmC;AACnC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB;oEACgE;IAChE,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;;;;sCAKsC;AACtC,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB;;;kEAG8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;6EACyE;IACzE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;kDAE8C;IAC9C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;0BAC0B;AAC1B,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB;;wBAEoB;IACpB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC;;;;2BAIuB;IACvB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAClD;;;iFAG6E;IAC7E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;sDAIkD;IAClD,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;IAC3C;;;iDAG6C;IAC7C,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IACzC;;;8EAG0E;IAC1E,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC;yCACqC;IACrC,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B;8BAC0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ;;qEAEiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;gFAE4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;CACd"}

package/dist/manifest-loader.d.ts

@@ -15,6 +15,7 @@ export declare class Loader {
     private readonly urlToSource;
     protected sources: ManifestSource[];
     private readonly celEnv;
+    private readonly migrations?;
     /** Sources are resolved in order — the first whose `supports(url)` matches
      *  wins. The caller (composition root) decides which concrete sources exist
      *  and supplies them; `defaultSources()` bundles the browser-safe built-ins
@@ -50,7 +51,13 @@ export declare 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;
     /** Raw text of any already-cached variant for `source`, so a cache miss on
      *  one (compile, desugar) variant reparses without a second source read. */

package/dist/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAwCpB,qBAAa,MAAM;IACjB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;;;;8BAK0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;mBAIe;gBACH,OAAO,GAAE,cAAc,EAAO,EAAE,OAAO,GAAE,iBAAsB;IAK3E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUrD;;;;2CAIuC;IACvC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;;;gFAS4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAYzB;;;+BAG2B;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAyCvE;;;;gEAI4D;IAC5D,OAAO,CAAC,oBAAoB;IAa5B;gFAC4E;IAC5E,OAAO,CAAC,cAAc;IAQtB;;wEAEoE;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAsB3E;;;qCAGiC;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAiI9E;;;;;;;;sBAQkB;IAClB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAOlE,OAAO,CAAC,6BAA6B;IAarC,OAAO,CAAC,mCAAmC;IAc3C,OAAO,CAAC,2BAA2B;YAkCrB,eAAe;IAmB7B;;;0CAGsC;IAChC,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA0B5D"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AA2DpB,qBAAa,MAAM;IACjB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;;;;8BAK0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA4B;IAExD;;;;mBAIe;gBACH,OAAO,GAAE,cAAc,EAAO,EAAE,OAAO,GAAE,iBAAsB;IAM3E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUrD;;;;2CAIuC;IACvC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;;;gFAS4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAYzB;;;+BAG2B;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAyCvE;;;;;;;;;;6CAUyC;IACzC,OAAO,CAAC,oBAAoB;IAe5B;gFAC4E;IAC5E,OAAO,CAAC,cAAc;IAQtB;;wEAEoE;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAsB3E;;;qCAGiC;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAkI9E;;;;;;;;sBAQkB;IAClB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAOlE,OAAO,CAAC,6BAA6B;IAarC,OAAO,CAAC,mCAAmC;IAc3C,OAAO,CAAC,2BAA2B;YAkCrB,eAAe;IAmB7B;;;0CAGsC;IAChC,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA0B5D"}

package/dist/manifest-loader.js

@@ -24,18 +24,34 @@ function collectParseDiagnostics(modules) {
     }
     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) {
+    const diagnostics = [];
+    for (const file of [entry.owner, ...entry.partials]) {
+        diagnostics.push(...file.migrations.diagnostics);
+    }
+    return diagnostics;
+}
 const SYSTEM_KINDS = new Set([
     "Telo.Application",
     "Telo.Library",
     "Telo.Import",
     "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"];
+/** 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",
+];
 function variantKey(options) {
-    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 {
     /** LoadedFile cache keyed by `${compile ? "compiled" : "raw"}:${source}`.
@@ -52,6 +68,7 @@ export class Loader {
     urlToSource = new Map();
     sources;
     celEnv;
+    migrations;
     /** Sources are resolved in order — the first whose `supports(url)` matches
      *  wins. The caller (composition root) decides which concrete sources exist
      *  and supplies them; `defaultSources()` bundles the browser-safe built-ins
@@ -60,6 +77,7 @@ export class Loader {
     constructor(sources = [], options = {}) {
         this.sources = [...sources];
         this.celEnv = buildCelEnvironment(options.celHandlers);
+        this.migrations = options.migrations;
     }
     register(source) {
         this.sources.unshift(source);
@@ -157,11 +175,19 @@ 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. */
     parseAndMaybeDesugar(source, requestedUrl, text, options) {
         const loaded = parseLoadedFile(source, requestedUrl, text, {
             compile: options?.compile,
             celEnv: this.celEnv,
+            migrate: options?.migrate,
+            migrations: this.migrations,
         });
         return options?.desugarImports ? desugarLoadedFile(loaded) : loaded;
     }
@@ -318,6 +344,7 @@ export class Loader {
             modules,
             importEdges,
             overrides,
+            migrationDiagnostics: collectMigrationDiagnostics(entry),
             versionDiagnostics: diagnostics,
             parseDiagnostics: collectParseDiagnostics(modules),
             errors,

package/dist/migrations/driver.d.ts

@@ -0,0 +1,69 @@
+/** 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 type { MigrationEntry, 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 declare const NO_MIGRATIONS: FileMigrations;
+/**
+ * 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 declare function migrateManifests(args: {
+    source: string;
+    manifests: Array<ResourceManifest | null>;
+    entries?: readonly MigrationEntry[];
+}): FileMigrations;
+/**
+ * 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 declare function migrateFileText(args: {
+    source: string;
+    text: string;
+    documents: readonly Document[];
+    manifests: ReadonlyArray<ResourceManifest | null>;
+    entries?: readonly MigrationEntry[];
+}): {
+    text: string;
+    rewrites: MigrationRewrite[];
+    unwritable: MigrationRewrite[];
+} | null;
+//# sourceMappingURL=driver.d.ts.map

package/dist/migrations/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/migrations/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;iCAaiC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAWrC,OAAO,KAAK,EACV,cAAc,EAGd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B;uEACmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C;;;gFAG4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrD;AAED,eAAO,MAAM,aAAa,EAAE,cAAkD,CAAC;AAE/E;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC,GAAG,cAAc,CAYjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,SAAS,EAAE,aAAa,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAClD,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC,GAAG;IACF,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC,GAAG,IAAI,CA8CP"}

package/dist/migrations/driver.js

@@ -0,0 +1,200 @@
+/** 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 { applyEffectsToTree, formatMigrationPath, planPatch, } from "./patch.js";
+import { applyTextEdits, planTextEdits } from "./yaml-edit.js";
+import { applicableRules, buildMatchIndex, selectMatches } from "./match.js";
+import { CORE_MIGRATIONS } from "./registry.js";
+import { toDiagnostic, toRewrite } from "./report.js";
+export const NO_MIGRATIONS = { 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) {
+    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) {
+    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) : null));
+    const applied = applyAll(scratch, entries);
+    if (applied.length === 0)
+        return null;
+    const edits = [];
+    const kept = [];
+    const skipped = [];
+    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, b) {
+    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, entries) {
+    const candidates = [];
+    // 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();
+    const applied = [];
+    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, effects) {
+    const out = [];
+    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, path, shiftedArrays) {
+    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;
+}

package/dist/migrations/entries/index.d.ts

@@ -0,0 +1,3 @@
+/** Every entry file, in the order the driver applies them. */
+export declare const MIGRATION_ENTRY_FILES: ReadonlyArray<readonly [file: string, data: unknown]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/entries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/entries/index.ts"],"names":[],"mappings":"AAKA,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAGvF,CAAC"}

package/dist/migrations/entries/index.js

@@ -0,0 +1,9 @@
+// GENERATED by scripts/copy-migration-entries.mjs — do not edit, and do not commit.
+// Source: analyzer/migrations/*.json (lexically ordered).
+import e0 from "./normalize-value-types.json" with { type: "json" };
+import e1 from "./ref-slot-scalar-type.json" with { type: "json" };
+/** Every entry file, in the order the driver applies them. */
+export const MIGRATION_ENTRY_FILES = [
+    ["normalize-value-types.json", e0],
+    ["ref-slot-scalar-type.json", e1],
+];

package/dist/migrations/entries/normalize-value-types.json

@@ -0,0 +1,48 @@
+{
+    "$comment": "Three keywords answered one question — what is the value at this slot, beyond what JSON Schema's `type` can say — and each answered it differently. `inSchema` with the wildcard `inKind` / `under` is what makes this reachable at all: these annotations occur in author-written schema fragments inside ORDINARY resource documents (an inline `inputType:` on any kind that declares one, a route's `request.schema.body`), and that set of kinds is open, so enumerating it would be both incomplete and a violation of the topology-driven constraint. The wildcards are earned by the pairing the reader enforces: a schema region bounds where the walk may go, and an `x-telo-*` key — Telo vocabulary wherever it appears — bounds what it may touch. Each rule sets the value BEFORE renaming the key, so both match the frozen pre-migration tree; a rename first would leave the second rule looking for a node that no longer exists. `notUnder` keeps all three out of the data-bearing keywords, where a value may merely look like a schema.",
+    "id": "normalize-value-types",
+    "code": "X_TELO_TYPE_DEPRECATED",
+    "severity": "warning",
+    "reason": "The three value-type annotations were unified into one `x-telo-type`, whose names are `Telo.`-qualified like every other kernel-owned name. `x-telo-binary` and `x-telo-stream` said what a value IS just as `x-telo-type` did, differing only in posture toward the JSON Schema layer — so a fourth kind of value meant a fourth keyword and edits across four packages.",
+    "rules": [
+        {
+            "match": {
+                "key": "x-telo-stream",
+                "inKind": ["*"],
+                "under": ["*"],
+                "inSchema": true,
+                "value": true,
+                "notUnder": ["const", "default", "enum", "examples"]
+            },
+            "patch": [
+                { "op": "set-value", "value": "Telo.Stream" },
+                { "op": "rename-key", "to": "x-telo-type" }
+            ]
+        },
+        {
+            "match": {
+                "key": "x-telo-binary",
+                "inKind": ["*"],
+                "under": ["*"],
+                "inSchema": true,
+                "value": true,
+                "notUnder": ["const", "default", "enum", "examples"]
+            },
+            "patch": [
+                { "op": "set-value", "value": "Telo.Bytes" },
+                { "op": "rename-key", "to": "x-telo-type" }
+            ]
+        },
+        {
+            "match": {
+                "key": "x-telo-type",
+                "inKind": ["*"],
+                "under": ["*"],
+                "inSchema": true,
+                "valueOneOf": ["TcpPort", "UdpPort"],
+                "notUnder": ["const", "default", "enum", "examples"]
+            },
+            "patch": [{ "op": "set-value", "qualify": "Telo." }]
+        }
+    ]
+}

package/dist/migrations/entries/ref-slot-scalar-type.json

@@ -0,0 +1,20 @@
+{
+    "$comment": "See README.md in this directory. `inKind` + `under` are the positive containment: `under` names TOP-LEVEL keys, so this rule can reach nothing but the schema blocks of a kind document — never the `resources:` template body, whose nested config may hold a key spelled `schema` over data. `withSibling` is what makes it precise — a scalar `type:` is stale only because an `x-telo-ref` sits beside it. `notUnder` then narrows within that region, keeping the rule out of the data-bearing keywords where a value may merely look like a schema.",
+    "id": "ref-slot-scalar-type",
+    "code": "X_TELO_REF_SCALAR_TYPE",
+    "severity": "warning",
+    "reason": "A reference is written with the `!ref` tag and resolves to an object, so a reference slot no longer carries the scalar `type:` that plain-string references were pinned to. Leaving it in place makes the slot reject the very value it is declared to accept, and every schema reader has had to know to ignore it.",
+    "rules": [
+        {
+            "match": {
+                "key": "type",
+                "inKind": ["Telo.Definition", "Telo.Abstract"],
+                "under": ["schema", "status", "inputType", "outputType"],
+                "valueOneOf": ["string", "number", "integer", "boolean"],
+                "withSibling": "x-telo-ref",
+                "notUnder": ["const", "default", "enum", "examples"]
+            },
+            "patch": [{ "op": "remove-entry" }]
+        }
+    ]
+}

package/dist/migrations/entry-data.d.ts

@@ -0,0 +1,25 @@
+/** The on-disk shape of a migration entry, and its reader.
+ *
+ *  An entry is DATA: one file per entry under `analyzer/migrations/`, consumed
+ *  as one lexically ordered set. That is what makes adding a migration one file
+ *  and retiring one deleting it, what ships the set in the published package,
+ *  and what lets the Rust crate embed the identical files at build time rather
+ *  than reimplementing each rewrite.
+ *
+ *  **An entry contains no code.** Both halves — what a rule matches and what it
+ *  patches — are data, so one file is read identically by every kernel. A
+ *  predicate expressed in one language would mean one artifact is read two
+ *  ways, invisibly, since a migration that succeeds is silent.
+ *
+ *  Reading is STRICT. A malformed entry is an authoring mistake, and the
+ *  alternative to throwing is a migration that silently does not run — the one
+ *  failure mode a rewrite-on-load design cannot afford, because a migration
+ *  that succeeds and one that never fires look identical. */
+import type { MigrationEntry } from "./types.js";
+/**
+ * Read one entry file's parsed data into a `MigrationEntry`.
+ *
+ * `file` names the entry file, so a failure says which one.
+ */
+export declare function parseMigrationEntry(file: string, data: unknown): MigrationEntry;
+//# sourceMappingURL=entry-data.d.ts.map

package/dist/migrations/entry-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-data.d.ts","sourceRoot":"","sources":["../../src/migrations/entry-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;6DAgB6D;AAI7D,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,YAAY,CAAC;AAgJpB;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,cAAc,CAiC/E"}