@telorun/analyzer 0.57.0 → 0.58.0

package/dist/migrations/yaml-edit.js

@@ -0,0 +1,245 @@
+/** Rendering a migration plan back into the author's YAML.
+ *
+ *  Edits are BYTE SPLICES computed from the parsed document's node ranges, not
+ *  `Document.toString()`. That is `cli/nodejs/src/commands/upgrade.ts`'s
+ *  precedent and it is load-bearing here for the same reason: re-serializing
+ *  re-folds block scalars, drops quote-style hints and reflows long strings, so
+ *  a one-key repair would arrive as a whole-file diff. Everything outside the
+ *  spliced ranges is byte-identical to the input.
+ *
+ *  The document is parsed with the same `defaultCustomTags()` every other
+ *  parse site uses, so a tagged scalar is a node here exactly as it is in the
+ *  loader's tree. */
+import { isMap, isPair, isScalar, isSeq } from "yaml";
+import { renderFixReplacement } from "../yaml-source-edit.js";
+export { applyTextEdits } from "../yaml-source-edit.js";
+function nodeAt(doc, path) {
+    if (path.length === 0)
+        return doc.contents;
+    return doc.getIn(path, true);
+}
+function rangeOf(node) {
+    const range = node?.range;
+    if (!Array.isArray(range) || typeof range[0] !== "number" || typeof range[1] !== "number") {
+        return undefined;
+    }
+    return [range[0], range[1]];
+}
+/** The Pair whose key is `key` inside the map at `parent`. */
+function pairAt(doc, parent, key) {
+    const map = nodeAt(doc, parent);
+    if (!isMap(map))
+        return undefined;
+    return map.items.find((item) => isPair(item) && isScalar(item.key) && String(item.key.value) === key);
+}
+/** Re-quote `value` in the style the author used at `original`.
+ *
+ *  A non-string is rendered as its YAML spelling and then handed to the shared
+ *  rule, so a migration and a quick fix quote the same value identically — the
+ *  rule itself is `renderFixReplacement` (`../yaml-source-edit.js`), which both
+ *  this and `@telorun/ide-support` read rather than restate. */
+function renderScalar(original, value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean" || typeof value === "number")
+        return String(value);
+    if (typeof value !== "string")
+        return undefined;
+    return renderFixReplacement(original, value);
+}
+/** Column of `offset` within its line, and the offset of that line's start. */
+function lineGeometry(text, offset) {
+    const lineStart = text.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+    return { lineStart, indent: offset - lineStart };
+}
+/** One YAML edit per effect, or `undefined` when the effect cannot be written
+ *  into this file — the same all-or-nothing rule the tree side has, so a
+ *  partially applied patch never reaches disk. */
+export function planTextEdits(doc, text, effects) {
+    if (effects.length === 0)
+        return [];
+    // **The document is never mutated.** A patch's later effects address the node
+    // by its POST-rename path, which the file does not have — so every effect is
+    // resolved at the one location the patch matched, read off the first effect.
+    // The tree applier and this one therefore agree without either replaying the
+    // other's state.
+    const first = effects[0];
+    const docPath = first.kind === "rename-key" ? [...first.parent, first.from] : first.path;
+    // A removal supersedes every other edit at the location: `planPatch` refuses
+    // anything after a `remove-entry`, and the line it deletes contains them.
+    const removal = effects.find((e) => e.kind === "remove-entry");
+    if (removal)
+        return removeEntryEdit(doc, text, docPath);
+    const edits = [];
+    let keyEdit;
+    // Value edits compose into ONE splice: a `set-tag` after a `set-value` must
+    // emit the tag in front of the NEW scalar, not re-read the old one.
+    let valueSpan;
+    let scalarText;
+    let tagText;
+    for (const effect of effects) {
+        switch (effect.kind) {
+            case "rename-key": {
+                const pair = pairAt(doc, docPath.slice(0, -1), String(docPath[docPath.length - 1]));
+                if (!isPair(pair) || !isScalar(pair.key))
+                    return undefined;
+                const range = rangeOf(pair.key);
+                if (!range)
+                    return undefined;
+                const rendered = renderScalar(text.slice(range[0], range[1]), effect.to);
+                if (rendered === undefined)
+                    return undefined;
+                keyEdit = { start: range[0], end: range[1], newText: rendered };
+                break;
+            }
+            case "set-value": {
+                const range = rangeOf(nodeAt(doc, docPath));
+                if (!range)
+                    return undefined;
+                const rendered = renderScalar(text.slice(range[0], range[1]), effect.value);
+                if (rendered === undefined)
+                    return undefined;
+                valueSpan ??= range;
+                scalarText = rendered;
+                break;
+            }
+            case "set-tag": {
+                const node = nodeAt(doc, docPath);
+                if (!isScalar(node))
+                    return undefined;
+                const range = rangeOf(node);
+                if (!range)
+                    return undefined;
+                // The tag sits outside the scalar's own span, so an existing one is
+                // replaced by rewriting from where it starts; a plain scalar just gains
+                // a prefix.
+                const existing = typeof node.tag === "string" ? node.tag : undefined;
+                const tagStart = existing ? text.lastIndexOf(existing, range[0]) : -1;
+                valueSpan = [tagStart >= 0 ? tagStart : range[0], range[1]];
+                scalarText ??= text.slice(range[0], range[1]);
+                tagText = `!${effect.tag}`;
+                break;
+            }
+            case "insert-item": {
+                const edit = insertItemEdit(doc, text, docPath, effect.index, effect.value);
+                if (!edit)
+                    return undefined;
+                edits.push(edit);
+                break;
+            }
+            case "remove-entry":
+                // Handled above.
+                break;
+        }
+    }
+    if (keyEdit)
+        edits.push(keyEdit);
+    if (valueSpan && scalarText !== undefined) {
+        edits.push({
+            start: valueSpan[0],
+            end: valueSpan[1],
+            newText: tagText ? `${tagText} ${scalarText}` : scalarText,
+        });
+    }
+    return edits;
+}
+function insertItemEdit(doc, text, path, index, value) {
+    const seq = nodeAt(doc, path);
+    // An empty sequence is written `[]` in flow style, which has no item line to
+    // extend — the one insert shape this cannot render.
+    if (!isSeq(seq) || seq.items.length === 0)
+        return undefined;
+    const rendered = renderScalar("", value);
+    if (rendered === undefined)
+        return undefined;
+    const anchorIndex = Math.min(index, seq.items.length - 1);
+    const anchor = rangeOf(seq.items[anchorIndex]);
+    if (!anchor)
+        return undefined;
+    const { lineStart, indent } = lineGeometry(text, anchor[0]);
+    // A block sequence's item starts two columns after its `- `; a flow sequence
+    // has no line of its own.
+    if (text.slice(lineStart, anchor[0]).trimStart() !== "- ")
+        return undefined;
+    const line = `${" ".repeat(Math.max(0, indent - 2))}- ${rendered}\n`;
+    if (index >= seq.items.length) {
+        const last = rangeOf(seq.items[seq.items.length - 1]);
+        if (!last)
+            return undefined;
+        const lineEnd = text.indexOf("\n", last[1]);
+        const at = lineEnd < 0 ? text.length : lineEnd + 1;
+        return { start: at, end: at, newText: line };
+    }
+    return { start: lineStart, end: lineStart, newText: line };
+}
+function removeEntryEdit(doc, text, path) {
+    const located = locateEntry(doc, path);
+    if (!located)
+        return undefined;
+    const { lineStart } = lineGeometry(text, located.start);
+    const prefix = text.slice(lineStart, located.start);
+    const opensSequenceItem = /^-\s+$/.test(prefix.trimStart());
+    // The entry OWNS its line — indentation for a mapping entry, indentation plus
+    // `- ` for a sequence item — so removing the line is exact.
+    if (located.item ? opensSequenceItem : prefix.trim() === "") {
+        const lineEnd = text.indexOf("\n", located.end);
+        return [{ start: lineStart, end: lineEnd < 0 ? text.length : lineEnd + 1, newText: "" }];
+    }
+    // A mapping entry that OPENS a sequence item shares its line with the `- `,
+    // and is the overwhelmingly common shape of the one thing a migration removes
+    // today: a legacy ref slot is almost always an `anyOf` branch, written
+    // `- type: string` with the annotation beneath it. Deleting the line would
+    // take the dash with it and fold the item into its predecessor — so the entry
+    // is spliced out up to the FOLLOWING sibling's key instead, which slides onto
+    // the dash at the column it already occupies. Refusing here would have made
+    // the diagnostic's own advice ("run `telo migrate`") dead for the case it is
+    // most often given in.
+    if (!located.item && opensSequenceItem) {
+        const next = nextSiblingKeyStart(doc, path);
+        // Nothing to promote onto the dash: the entry is the item's only one, and
+        // removing it would leave `- ` with no value.
+        if (next === undefined)
+            return undefined;
+        // Only whitespace may be swallowed. A comment or anything else between the
+        // two entries would be destroyed by the splice, so that stays a hand edit.
+        const between = text.slice(located.end, next);
+        if (!/^\s*$/.test(between) || !between.includes("\n"))
+            return undefined;
+        return [{ start: located.start, end: next, newText: "" }];
+    }
+    return undefined;
+}
+/** Offset of the key of the entry FOLLOWING `path` in its own mapping, or
+ *  `undefined` when `path` is the last entry (or anything is not a plain
+ *  key-scalar pair). */
+function nextSiblingKeyStart(doc, path) {
+    const map = nodeAt(doc, path.slice(0, -1));
+    if (!isMap(map))
+        return undefined;
+    const key = String(path[path.length - 1]);
+    const at = map.items.findIndex((item) => isPair(item) && isScalar(item.key) && String(item.key.value) === key);
+    if (at < 0)
+        return undefined;
+    const next = map.items[at + 1];
+    if (!isPair(next) || !isScalar(next.key))
+        return undefined;
+    return rangeOf(next.key)?.[0];
+}
+/** Span of a whole mapping entry (key through value) or sequence item. */
+function locateEntry(doc, path) {
+    const last = path[path.length - 1];
+    if (typeof last === "string") {
+        const pair = pairAt(doc, path.slice(0, -1), last);
+        if (!isPair(pair) || !isScalar(pair.key))
+            return undefined;
+        const keyRange = rangeOf(pair.key);
+        const valueRange = rangeOf(pair.value) ?? keyRange;
+        if (!keyRange || !valueRange)
+            return undefined;
+        return { start: keyRange[0], end: valueRange[1], item: false };
+    }
+    const range = rangeOf(nodeAt(doc, path));
+    if (!range)
+        return undefined;
+    return { start: range[0], end: range[1], item: true };
+}

package/dist/parse-loaded-file.d.ts

@@ -1,11 +1,19 @@
 import type { Environment } from "@marcbachmann/cel-js";
 import type { LoadedFile } from "./loaded-types.js";
+import type { MigrationEntry } from "./migrations/types.js";
 export interface ParseOptions {
     /** When true, runs `precompileDoc` per document and stamps compiled CEL
      *  on the manifests — same flag `LoadOptions.compile` carries today. */
     compile?: boolean;
     /** CEL environment for precompile. Defaults to `buildCelEnvironment()`. */
     celEnv?: Environment;
+    /** When true, the migration phase runs over the parsed documents — legacy
+     *  spellings rewritten to the current ones before anything else reads the
+     *  tree. Off by default so a round-trip consumer (the editor) keeps the
+     *  author's vocabulary; see `LoadOptions.migrate`. */
+    migrate?: boolean;
+    /** Migration set. Defaults to the analyzer's own `CORE_MIGRATIONS`. */
+    migrations?: readonly MigrationEntry[];
 }
 /** Pure: text in, structured load result out. No I/O, no caches. */
 export declare function parseLoadedFile(source: string, requestedUrl: string, text: string, options?: ParseOptions): LoadedFile;

package/dist/parse-loaded-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAKhE,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CAiDZ"}
+{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;0DAGsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CA2DZ"}

package/dist/parse-loaded-file.js

@@ -1,6 +1,7 @@
 import { defaultCustomTags } from "@telorun/templating";
 import { parseAllDocuments } from "yaml";
 import { buildCelEnvironment } from "./cel-environment.js";
+import { migrateManifests, NO_MIGRATIONS } from "./migrations/driver.js";
 import { buildDocumentPositions } from "./position-metadata.js";
 import { precompileDoc } from "./precompile.js";
 import { documentToAst } from "./yaml-ast.js";
@@ -42,27 +43,34 @@ export function parseLoadedFile(source, requestedUrl, text, options) {
             });
         }
     });
-    const manifests = [];
-    let env;
-    for (const doc of documents) {
+    const manifests = documents.map((doc) => {
         const raw = doc.toJSON();
-        if (raw === null || raw === undefined) {
-            manifests.push(null);
-            continue;
-        }
-        if (options?.compile) {
+        return raw === null || raw === undefined ? null : raw;
+    });
+    // The migration phase, immediately after parse. It runs BEFORE precompile so
+    // matchers see the values the author wrote rather than `CompiledValue`
+    // wrappers, and — through the loader — before `desugarLoadedFile`, so a rule
+    // only ever matches author-written nodes: a synthetic Telo.Import manifest
+    // has no YAML document to edit, records a path the file never had, and
+    // carries its `variables` / `secrets` by reference from the module doc, so a
+    // match inside one would apply twice.
+    const migrations = options?.migrate
+        ? migrateManifests({ source, manifests, entries: options.migrations })
+        : NO_MIGRATIONS;
+    let env;
+    if (options?.compile) {
+        for (let i = 0; i < manifests.length; i++) {
+            const raw = manifests[i];
+            if (raw === null)
+                continue;
             env ??= options.celEnv ?? buildCelEnvironment();
             try {
-                const compiled = precompileDoc(raw, env);
-                manifests.push(compiled);
+                manifests[i] = precompileDoc(raw, env);
             }
             catch (error) {
                 throw new Error(`Failed to compile manifest in ${source}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        else {
-            manifests.push(raw);
-        }
     }
     return {
         source,
@@ -73,5 +81,6 @@ export function parseLoadedFile(source, requestedUrl, text, options) {
         manifests,
         positions,
         parseErrors,
+        migrations,
     };
 }

package/dist/resolve-schema-type-refs.d.ts

@@ -1,20 +1,37 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 /**
- * Rewrites import-scoped schema references in place. A `$ref` of the form
- * `telo://<authority>/<typeName>` names a `Type.JsonSchema` (or any `Telo.Type`)
- * reached through an import: `telo://Self/<type>` for the declaring module's own
- * type, `telo://<Alias>/<type>` for an imported module's. Each authority is
- * resolved to the owning module's name and the ref is rewritten to the canonical
- * `telo://<module>/<type>` the type registered its schema under.
+ * Rewrites schema references to their canonical, module-scoped form, in place.
  *
- * The version lives on the `imports:` entry, never the URI — only the pinned
- * version is loaded, so the canonical id is version-free.
+ * A named shape is written with the reference tag — `!ref File` for the declaring
+ * module's own, `!ref <Alias>.<File>` for one an imported library exports — which
+ * is Telo's ONE reference grammar, and `use: schema` has been in the `x-telo-ref`
+ * vocabulary for exactly this relation all along (*names a shape; no runtime
+ * instance, no edge*). Phase 2.5 has already turned the tag into `{kind, name,
+ * alias?}`; this pass turns that into `{ $ref: "telo:<module>/<type>" }`, the id
+ * the type registered its schema under.
  *
- * Already-canonical refs (authority is a real module name, not an alias) and
- * fragment-bearing built-ins (`telo://manifest#/$defs/ResourceRef`) are left
- * untouched: the former because the authority resolves to nothing, the latter
- * because they don't match the `authority/type` grammar.
+ * WHY NORMALIZE RATHER THAN RESOLVE. Substituting the shape itself would inline
+ * it, which changes schema identity — the compiled-validator cache is keyed on it
+ * — and would make a self-recursive shape inexpressible. Keeping a REFERENCE is
+ * what every validator wants, and it is not an AJV concern: a Rust validator
+ * wants a registered id just as much. So the tag is the authoring surface and the
+ * canonical `$ref` is the internal form, exactly as `resolveRefSentinels` and
+ * `resolveSchemaRefKinds` already split authoring sugar from canonical form.
+ *
+ * ALIAS SCOPE IS WHAT THE CANONICAL FORM CARRIES. The authority is resolved in
+ * the DECLARING module's scope, so the id names the owning module and two
+ * libraries declaring a shape of the same name stay distinct. A downstream
+ * resolver reads the module off the id instead of matching a bare name, which is
+ * how an alias used to get silently dropped.
+ *
+ * The legacy authoring spelling `$ref: "telo://<authority>/<type>"` is resolved
+ * the same way, since a published artifact carries it. The version lives on the
+ * `imports:` entry, never the URI — only the pinned version is loaded, so the
+ * canonical id is version-free. Already-canonical refs and fragment-bearing
+ * built-ins (`telo://manifest#/$defs/ResourceRef`) are left untouched: the former
+ * because the authority resolves to nothing, the latter because they do not match
+ * the `authority/type` grammar.
  */
 export declare function resolveSchemaTypeRefs(resources: ResourceManifest[], aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): void;
 //# sourceMappingURL=resolve-schema-type-refs.d.ts.map

package/dist/resolve-schema-type-refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-schema-type-refs.d.ts","sourceRoot":"","sources":["../src/resolve-schema-type-refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,IAAI,CAyBN"}
+{"version":3,"file":"resolve-schema-type-refs.d.ts","sourceRoot":"","sources":["../src/resolve-schema-type-refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,IAAI,CA6DN"}

package/dist/resolve-schema-type-refs.js

@@ -2,28 +2,51 @@ import { canonicalTypeSchemaId, parseTeloTypeRef } from "@telorun/sdk";
 /** Schema-bearing fields on a Telo.Definition / Telo.Type resource. */
 const SCHEMA_FIELDS = ["schema", "inputType", "outputType"];
 /**
- * Rewrites import-scoped schema references in place. A `$ref` of the form
- * `telo://<authority>/<typeName>` names a `Type.JsonSchema` (or any `Telo.Type`)
- * reached through an import: `telo://Self/<type>` for the declaring module's own
- * type, `telo://<Alias>/<type>` for an imported module's. Each authority is
- * resolved to the owning module's name and the ref is rewritten to the canonical
- * `telo://<module>/<type>` the type registered its schema under.
+ * Rewrites schema references to their canonical, module-scoped form, in place.
  *
- * The version lives on the `imports:` entry, never the URI — only the pinned
- * version is loaded, so the canonical id is version-free.
+ * A named shape is written with the reference tag — `!ref File` for the declaring
+ * module's own, `!ref <Alias>.<File>` for one an imported library exports — which
+ * is Telo's ONE reference grammar, and `use: schema` has been in the `x-telo-ref`
+ * vocabulary for exactly this relation all along (*names a shape; no runtime
+ * instance, no edge*). Phase 2.5 has already turned the tag into `{kind, name,
+ * alias?}`; this pass turns that into `{ $ref: "telo:<module>/<type>" }`, the id
+ * the type registered its schema under.
  *
- * Already-canonical refs (authority is a real module name, not an alias) and
- * fragment-bearing built-ins (`telo://manifest#/$defs/ResourceRef`) are left
- * untouched: the former because the authority resolves to nothing, the latter
- * because they don't match the `authority/type` grammar.
+ * WHY NORMALIZE RATHER THAN RESOLVE. Substituting the shape itself would inline
+ * it, which changes schema identity — the compiled-validator cache is keyed on it
+ * — and would make a self-recursive shape inexpressible. Keeping a REFERENCE is
+ * what every validator wants, and it is not an AJV concern: a Rust validator
+ * wants a registered id just as much. So the tag is the authoring surface and the
+ * canonical `$ref` is the internal form, exactly as `resolveRefSentinels` and
+ * `resolveSchemaRefKinds` already split authoring sugar from canonical form.
+ *
+ * ALIAS SCOPE IS WHAT THE CANONICAL FORM CARRIES. The authority is resolved in
+ * the DECLARING module's scope, so the id names the owning module and two
+ * libraries declaring a shape of the same name stay distinct. A downstream
+ * resolver reads the module off the id instead of matching a bare name, which is
+ * how an alias used to get silently dropped.
+ *
+ * The legacy authoring spelling `$ref: "telo://<authority>/<type>"` is resolved
+ * the same way, since a published artifact carries it. The version lives on the
+ * `imports:` entry, never the URI — only the pinned version is loaded, so the
+ * canonical id is version-free. Already-canonical refs and fragment-bearing
+ * built-ins (`telo://manifest#/$defs/ResourceRef`) are left untouched: the former
+ * because the authority resolves to nothing, the latter because they do not match
+ * the `authority/type` grammar.
  */
 export function resolveSchemaTypeRefs(resources, aliases, aliasesByModule) {
-    const walk = (value, resolveAuthority) => {
+    const walk = (value, resolveAuthority, ownModule, 
+    // The type field's OWN value is a declared reference slot (`x-telo-ref:
+    // Telo.Type`), with its own reference validation and its own editor picker.
+    // Only what sits INSIDE it is schema, and only schema is this pass's to
+    // canonicalize — rewriting the slot itself would hand the reference checker
+    // a shape it is right to reject.
+    isSlotRoot) => {
         if (value === null || typeof value !== "object")
             return;
         if (Array.isArray(value)) {
             for (const item of value)
-                walk(item, resolveAuthority);
+                walk(item, resolveAuthority, ownModule, false);
             return;
         }
         const obj = value;
@@ -33,15 +56,65 @@ export function resolveSchemaTypeRefs(resources, aliases, aliasesByModule) {
             if (module)
                 obj.$ref = canonicalTypeSchemaId(module, parsed.typeName);
         }
+        // A reference the tag left behind. Rewritten in place rather than replaced,
+        // so a node that carried siblings (a `title`, a `description`) keeps them —
+        // a `$ref` beside other keywords is ordinary JSON Schema.
+        const named = resolvedRefInSchema(obj);
+        if (named) {
+            const module = named.alias === undefined ? ownModule : resolveAuthority(named.alias);
+            // An unresolvable alias is left exactly as written: `validateReferences`
+            // is what reports a reference that names nothing, and guessing a module
+            // here would turn a typo into a `$ref` that resolves to the wrong shape.
+            if (module) {
+                const canonical = canonicalTypeSchemaId(module, named.name);
+                if (isSlotRoot) {
+                    // At the slot root the reference STAYS a reference — the canonical id
+                    // is stamped beside it. That is what makes the resolver alias-aware
+                    // here: it reads the module off the id instead of matching a bare
+                    // `metadata.name` across a flattened list, where two libraries
+                    // declaring a shape of the same name collide silently.
+                    obj.$ref = canonical;
+                }
+                else {
+                    delete obj.kind;
+                    delete obj.name;
+                    delete obj.alias;
+                    obj.$ref = canonical;
+                }
+            }
+        }
         for (const key of Object.keys(obj))
-            walk(obj[key], resolveAuthority);
+            walk(obj[key], resolveAuthority, ownModule, false);
     };
     for (const r of resources) {
         const ownModule = r.metadata?.module;
         const resolver = (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
         const resolveAuthority = (authority) => authority === "Self" ? ownModule : resolver?.moduleForAlias(authority);
         for (const field of SCHEMA_FIELDS) {
-            walk(r[field], resolveAuthority);
+            walk(r[field], resolveAuthority, ownModule, true);
         }
     }
 }
+/**
+ * A resolved `!ref` sitting where a schema belongs, or null.
+ *
+ * Recognised structurally: Phase 2.5 writes `{kind, name, alias?}` and nothing
+ * else, and a node carrying JSON Schema keywords is a schema that happens to be
+ * beside one rather than a reference. Being conservative here is the safe
+ * direction — a node this declines to rewrite stays a reference for
+ * `validateReferences` to judge, while one it rewrote wrongly would silently
+ * become a different shape.
+ */
+function resolvedRefInSchema(obj) {
+    if (typeof obj.kind !== "string" || typeof obj.name !== "string")
+        return null;
+    for (const key of Object.keys(obj)) {
+        // `$ref` is allowed so the pass is idempotent at a slot root, where the id
+        // is stamped BESIDE the reference rather than replacing it.
+        if (key !== "kind" && key !== "name" && key !== "alias" && key !== "$ref")
+            return null;
+    }
+    return typeof obj.alias === "string"
+        ? { name: obj.name, alias: obj.alias }
+        : { name: obj.name };
+}

package/dist/schema-compat.d.ts

@@ -12,10 +12,29 @@ export interface CompatibilityResult {
     compatible: boolean;
     issues: string[];
 }
-/** Conservative structural JSON Schema compatibility check.
- *  Only flags definite mismatches: missing required fields and primitive type conflicts.
- *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
-export declare function checkSchemaCompatibility(source: Record<string, any>, target: Record<string, any>): CompatibilityResult;
+/**
+ * Conservative structural JSON Schema compatibility check — is a value shaped
+ * like `source` acceptable where `target` is declared?
+ *
+ * COVARIANT, because the values this compares are consumed by reading: a
+ * narrower element satisfies a slot declaring a wider one. Only DEFINITE
+ * mismatches are flagged — a missing required field, a primitive type conflict,
+ * a disagreeing type argument. Anything ambiguous (`anyOf` / `oneOf` / `allOf`,
+ * an absent `type`, an undeclared argument) is treated as compatible, so an
+ * unmigrated producer and consumer keep checking exactly as they did.
+ *
+ * The traversal is written here rather than reused: the function this replaced
+ * compared only `type` for the names in `target.required` and descended only
+ * into objects, so a stream of arrays of strings and a stream of arrays of
+ * integers both read as `array` and passed — leaving argument checking inert on
+ * exactly the nested shapes it exists for. What survives from it is its posture.
+ *
+ * `resolveRef` sees through a named shape. Declaring a shape once and
+ * referencing it is the sanctioned way to reuse one, so without it two such
+ * arguments present as opaque nodes carrying no information — the same reason
+ * {@link withLiveValuesSkipped} takes one.
+ */
+export declare function checkSchemaCompatibility(source: Record<string, any>, target: Record<string, any>, resolveRef?: (ref: string) => Record<string, any> | undefined): CompatibilityResult;
 export declare function formatSingleError(err: any): string;
 export declare function formatAjvErrors(errors: any[] | null | undefined): string;
 /** A schema validation issue with a dotted-path pointer to the offending field. */
@@ -36,14 +55,21 @@ export declare function navigateJsonPointer(schema: unknown, pointer: string): u
  *  Returns `undefined` if any segment cannot be resolved. */
 export declare function navigateSchemaToExprPath(schema: Record<string, any>, path: string): Record<string, any> | undefined;
 /**
- * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * Every `json`-represented value type's CEL brand → the primitive it refines.
+ *
  * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
- * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
- * stay distinct for static wiring checks. Brands carry no runtime effect — the
- * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ * structurally-identical values (a `Telo.TcpPort` and a `Telo.UdpPort` are both
+ * integers) stay distinct for static wiring checks. Brands carry no runtime
+ * effect — the value flows as its base type.
+ *
+ * DERIVED from the value-type vocabulary, never hand-written: a new brand is a
+ * new entry file, and a table here would be a second place to edit that could
+ * silently disagree with the one the runtime reads.
  */
 export declare const VALUE_BRAND_BASE: Record<string, string>;
-/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+/** Read a `json`-represented value type's brand off a schema, or undefined.
+ *  An `instance` type is not a brand — it replaces the JSON layer rather than
+ *  refining it, so it carries its binding's CEL type instead. */
 export declare function brandOfSchema(schema: Record<string, any> | undefined): string | undefined;
 /** Map a JSON Schema type annotation to a CEL type string. */
 export declare function jsonSchemaToCelType(schema: Record<string, any> | undefined): string;

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAYA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAWpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAaD,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CA2B/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAkED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CA0C/E;AAqBD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAyDD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwBlF;AAED;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;AAChC;;;;;;;;6DAQ6D;AAC7D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EACrC,IAAI,SAAK,GACR,OAAO,CA2DT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"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"}