@telorun/analyzer 0.56.1 → 0.58.0

package/src/migrations/yaml-edit.ts

@@ -0,0 +1,260 @@
+/** 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, type Document, type Node } from "yaml";
+import { renderFixReplacement, type TextEdit } from "../yaml-source-edit.js";
+import type { MigrationEffect } from "./patch.js";
+import type { MigrationPath } from "./types.js";
+
+export { applyTextEdits, type TextEdit } from "../yaml-source-edit.js";
+
+function nodeAt(doc: Document, path: MigrationPath): unknown {
+  if (path.length === 0) return doc.contents;
+  return doc.getIn(path as (string | number)[], true);
+}
+
+function rangeOf(node: unknown): [number, number] | undefined {
+  const range = (node as { range?: unknown } | undefined)?.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: Document, parent: MigrationPath, key: string): unknown {
+  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: string, value: unknown): string | undefined {
+  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: string, offset: number): { lineStart: number; indent: number } {
+  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: Document,
+  text: string,
+  effects: readonly MigrationEffect[],
+): TextEdit[] | undefined {
+  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: MigrationPath =
+    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: TextEdit[] = [];
+  let keyEdit: TextEdit | undefined;
+  // 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: [number, number] | undefined;
+  let scalarText: string | undefined;
+  let tagText: string | undefined;
+
+  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: Document,
+  text: string,
+  path: MigrationPath,
+  index: number,
+  value: unknown,
+): TextEdit | undefined {
+  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] as Node);
+  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] as Node);
+    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: Document,
+  text: string,
+  path: MigrationPath,
+): TextEdit[] | undefined {
+  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: Document, path: MigrationPath): number | undefined {
+  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: Document,
+  path: MigrationPath,
+): { start: number; end: number; item: boolean } | undefined {
+  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/src/module-file-claims.ts

@@ -0,0 +1,168 @@
+import {
+  defaultCustomTags,
+  defaultRegistry,
+  walkCelExpressions,
+  type TemplatingEngineRegistry,
+} from "@telorun/templating";
+import { PackageURL } from "packageurl-js";
+import { parseAllDocuments } from "yaml";
+import { selectorFromQualifiers, selectorKey, type ArtifactSelector } from "./artifact-selector.js";
+
+/**
+ * One module-relative file a manifest names, and the artifact layer it belongs
+ * to.
+ *
+ * The single answer to "why is this file in the payload", replacing two
+ * derivations that happened to agree: publish used to re-parse the manifest with
+ * PURL knowledge hardcoded into the CLI, and any second vocabulary — a tag that
+ * embeds a file, say — would have had to be added there by hand. Here the
+ * knowledge sits with whoever owns the syntax: a controller candidate is read by
+ * this module, and a tagged value is read by the engine that owns its tag, via
+ * `TemplatingEngine.fileClaims`. Publish maps role to layer and recognises
+ * neither.
+ *
+ * Deliberately NOT hung off `analyze()`. That pass runs over a flattened,
+ * import-inclusive manifest set, so its claims would mix in imported libraries'
+ * files — whose paths are relative to *their* module and must never join this
+ * artifact — and it would make packaging, today derivable offline from manifest
+ * text, a product of resolving the whole import graph. This is per-module by
+ * construction and needs nothing but the text.
+ *
+ * Browser-safe, like the rest of the analyzer: parsing and string work only, no
+ * filesystem. Whether a claimed file EXISTS is a separate question, asked by the
+ * Node-side caller that has a directory to look in.
+ */
+interface ClaimBase {
+  /** Module-root-relative POSIX path — relative to the directory holding
+   *  `telo.yaml`, never to the file the claim was written in. Publish inlines
+   *  every `include:` partial into the published `telo.yaml`, so a
+   *  per-file-relative path would change meaning in the artifact. */
+  readonly path: string;
+  /** Where the claim came from, for diagnostics: the PURL, or `!<tag>` and the
+   *  path of the value that carried it. */
+  readonly origin: string;
+}
+
+/**
+ * A **discriminated union**, not one shape with optional fields: a controller
+ * layer is one per selector and carries sibling patterns, and an assets layer is
+ * neither. Optional fields on a single shape put the consumer one `!` away from
+ * a crash inside `selectorKey` with no useful message, and let a producer emit a
+ * controller claim with no selector that nothing would reject.
+ */
+export type ModuleFileClaim =
+  | (ClaimBase & {
+      readonly role: "controller";
+      readonly selector: ArtifactSelector;
+      /** Extra payload patterns that belong in the same layer as this claim —
+       *  `.gitignore`-style globs over the selected files, matched by the
+       *  caller, which is the side that knows what was selected. */
+      readonly siblings: readonly string[];
+    })
+  | (ClaimBase & { readonly role: "assets" });
+
+/** `pkg:telo/local/<format>?path=…` — the bundled-controller delivery mode.
+ *  Anything else (`pkg:npm`, `pkg:cargo`) fetches from its own ecosystem and
+ *  contributes no layer. */
+const BUNDLED_TYPE = "telo";
+const BUNDLED_NAMESPACE = "local";
+
+/** Qualifier naming extra files that belong in a controller's layer — what an
+ *  entry point loads but the manifest cannot otherwise see (a `.wasm` beside its
+ *  glue, a native library opened at runtime). */
+const SIBLINGS_QUALIFIER = "siblings";
+
+/** Normalize a `path=` / sibling value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value: string): string {
+  return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+
+/** Bundled-controller claims from one document's `controllers:` list. */
+function controllerClaims(json: unknown): ModuleFileClaim[] {
+  const candidates = (json as { controllers?: unknown } | null)?.controllers;
+  if (!Array.isArray(candidates)) return [];
+  const claims: ModuleFileClaim[] = [];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string") continue;
+    let parsed: PackageURL;
+    try {
+      parsed = PackageURL.fromString(candidate);
+    } catch {
+      // Not a parseable PURL — claim collection is not the place to reject it;
+      // the analyzer's own validation and the controller loader both report it
+      // with better context.
+      continue;
+    }
+    if (parsed.type !== BUNDLED_TYPE || parsed.namespace !== BUNDLED_NAMESPACE) continue;
+    const entry = parsed.qualifiers?.path;
+    if (typeof entry !== "string" || entry === "") continue;
+    claims.push({
+      role: "controller",
+      path: normalizeRelative(entry),
+      selector: selectorFromQualifiers(parsed.name, parsed.qualifiers, `controller "${candidate}"`),
+      siblings: String(parsed.qualifiers?.[SIBLINGS_QUALIFIER] ?? "")
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p !== ""),
+      origin: candidate,
+    });
+  }
+  return claims;
+}
+
+/** Claims contributed by tagged values, asked of the engine that owns each tag.
+ *  The walk reaches every tagged scalar in the document, so an engine that
+ *  embeds files is discovered wherever its tag was written.
+ *
+ *  The layer role is assigned HERE, not by the engine: an engine reports what it
+ *  embeds, and which layer that belongs in is this module's vocabulary. A file a
+ *  tag embeds is read only when the resource holding it is created, so `assets`
+ *  — the lazily-fetched layer — is what it is. */
+function taggedClaims(json: unknown, registry: TemplatingEngineRegistry): ModuleFileClaim[] {
+  const claims: ModuleFileClaim[] = [];
+  walkCelExpressions(json, "", (source, path, engineName) => {
+    const engine = registry.get(engineName);
+    for (const claim of engine?.fileClaims?.(source) ?? []) {
+      claims.push({ role: "assets", path: claim.path, origin: `!${engineName} at '${path}'` });
+    }
+  });
+  return claims;
+}
+
+/** Identity of a claim for de-duplication: the same file claimed twice by two
+ *  resources is one file in one layer. Role and selector are part of it because
+ *  a file two controller candidates both claim is genuinely copied into each of
+ *  their layers — dropping one would leave a platform's layer short a file it
+ *  declared it needs. */
+function claimKey(claim: ModuleFileClaim): string {
+  const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+  return `${claim.role}\0${selector}\0${claim.path}`;
+}
+
+/**
+ * Every module-relative file the manifest names, from every syntax that can name
+ * one.
+ *
+ * `manifestText` is one module's `telo.yaml`. Publish passes the text it is
+ * about to ship — i.e. after `include:` partials have been inlined — but the
+ * answer does not depend on that: claims are root-relative, so collecting them
+ * before or after inlining gives the same set.
+ */
+export function collectModuleFileClaims(
+  manifestText: string,
+  registry: TemplatingEngineRegistry = defaultRegistry(),
+): ModuleFileClaim[] {
+  const seen = new Set<string>();
+  const claims: ModuleFileClaim[] = [];
+  for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+    const json = doc.toJSON() as unknown;
+    for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+      const key = claimKey(claim);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      claims.push(claim);
+    }
+  }
+  return claims;
+}

package/src/parse-loaded-file.ts

@@ -4,6 +4,8 @@ import { defaultCustomTags } from "@telorun/templating";
 import { parseAllDocuments } from "yaml";
 import { buildCelEnvironment } from "./cel-environment.js";
 import type { LoadedFile, ParseError } from "./loaded-types.js";
+import { migrateManifests, NO_MIGRATIONS } from "./migrations/driver.js";
+import type { MigrationEntry } from "./migrations/types.js";
 import { buildDocumentPositions } from "./position-metadata.js";
 import { precompileDoc } from "./precompile.js";
 import { documentToAst } from "./yaml-ast.js";
@@ -14,6 +16,13 @@ export interface ParseOptions {
   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[];
 }
 
 /** Append an actionable hint to raw yaml-parser messages that are otherwise
@@ -64,26 +73,35 @@ export function parseLoadedFile(
     }
   });
 
-  const manifests: Array<ResourceManifest | null> = [];
-  let env: Environment | undefined;
-  for (const doc of documents) {
+  const manifests: Array<ResourceManifest | null> = 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 as ResourceManifest);
+  });
+
+  // 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: Environment | undefined;
+  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 as ResourceManifest);
+        manifests[i] = precompileDoc(raw, env) as ResourceManifest;
       } catch (error) {
         throw new Error(
           `Failed to compile manifest in ${source}: ${error instanceof Error ? error.message : String(error)}`,
         );
       }
-    } else {
-      manifests.push(raw as ResourceManifest);
     }
   }
 
@@ -96,5 +114,6 @@ export function parseLoadedFile(
     manifests,
     positions,
     parseErrors,
+    migrations,
   };
 }

package/src/resolve-schema-type-refs.ts

@@ -6,30 +6,57 @@ import type { AliasResolver } from "./alias-resolver.js";
 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: ResourceManifest[],
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
 ): void {
-  const walk = (value: unknown, resolveAuthority: (authority: string) => string | undefined): void => {
+  const walk = (
+    value: unknown,
+    resolveAuthority: (authority: string) => string | undefined,
+    ownModule: string | undefined,
+    // 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: boolean,
+  ): void => {
     if (value === null || typeof value !== "object") return;
     if (Array.isArray(value)) {
-      for (const item of value) walk(item, resolveAuthority);
+      for (const item of value) walk(item, resolveAuthority, ownModule, false);
       return;
     }
     const obj = value as Record<string, unknown>;
@@ -38,7 +65,33 @@ export function resolveSchemaTypeRefs(
       const module = resolveAuthority(parsed.authority);
       if (module) obj.$ref = canonicalTypeSchemaId(module, parsed.typeName);
     }
-    for (const key of Object.keys(obj)) walk(obj[key], resolveAuthority);
+    // 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, ownModule, false);
   };
 
   for (const r of resources) {
@@ -47,7 +100,31 @@ export function resolveSchemaTypeRefs(
     const resolveAuthority = (authority: string): string | undefined =>
       authority === "Self" ? ownModule : resolver?.moduleForAlias(authority);
     for (const field of SCHEMA_FIELDS) {
-      walk((r as Record<string, unknown>)[field], resolveAuthority);
+      walk((r as Record<string, unknown>)[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: Record<string, unknown>,
+): { name: string; alias?: string } | null {
+  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 };
+}