@telorun/kernel 0.70.0 → 0.73.0

package/src/kernel.ts

@@ -52,6 +52,7 @@ import { nodeCelHandlers } from "./cel-handlers.js";
 import { parseRef, seedInvokeSource } from "./invoke-dispatch.js";
 import { stripCompiledValues } from "./schema-compiled-values.js";
 import { injectAtPath } from "./dependency-injection.js";
+import { resolveIncludeSentinels, type IncludeCache } from "./resolve-include-sentinels.js";
 import {
   computeAnalysisSignature,
   readAnalysisStamp,
@@ -137,6 +138,10 @@ export class Kernel implements IKernel {
   private idleResolvers: Array<() => void> = [];
   private _exitCode = 0;
   private readonly sharedSchemaValidator = new SchemaValidator();
+  /** `!include-*` reads, keyed by resolved URI, so two resources embedding the
+   *  same asset read it once. Kernel-scoped: the values are retained by the
+   *  resources holding them anyway, so this deduplicates rather than retains. */
+  private readonly includeCache: IncludeCache = new Map();
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
   private _entryUrl?: string;
@@ -266,7 +271,7 @@ export class Kernel implements IKernel {
   }
 
   async loadManifests(url: string): Promise<ResourceManifest[]> {
-    const graph = await this.loader.loadGraph(url, { desugarImports: true });
+    const graph = await this.loader.loadGraph(url, { desugarImports: true, migrate: true });
     if (graph.errors.length > 0) throw graph.errors[0].error;
     return flattenForAnalyzer(graph);
   }
@@ -442,7 +447,7 @@ export class Kernel implements IKernel {
     // `desugarImports` expands each module's inline `imports:` map into synthetic
     // Telo.Import manifests before discovery walks the graph, so inline imports
     // resolve identically to authored Telo.Import docs.
-    const analysisGraph = await this.loader.loadGraph(sourceUrl, { desugarImports: true });
+    const analysisGraph = await this.loader.loadGraph(sourceUrl, { desugarImports: true, migrate: true });
     if (analysisGraph.errors.length > 0) {
       throw analysisGraph.errors[0].error;
     }
@@ -486,6 +491,20 @@ export class Kernel implements IKernel {
         this.logging.kernelLogger().warn(d.message, { "telo.diagnostic.code": d.code });
       }
     }
+    // A migration rewrites the entry module's own manifest silently otherwise:
+    // `telo check`, VS Code and the editor all report the deprecation, and
+    // `telo run` — the command an author actually uses — would be the only
+    // surface that does not. Already scoped to the entry's own files by the
+    // loader, so a published dependency's spelling never appears here.
+    for (const d of analysisGraph.migrationDiagnostics) {
+      const filePath = (d.data as { filePath?: string } | undefined)?.filePath;
+      this.logging
+        .kernelLogger()
+        .warn(
+          filePath ? `${filePath}: ${d.message}` : d.message,
+          d.code === undefined ? undefined : { "telo.diagnostic.code": d.code },
+        );
+    }
     const staticManifests = flattenForAnalyzer(analysisGraph);
     this.staticManifests = staticManifests;
 
@@ -618,7 +637,7 @@ export class Kernel implements IKernel {
     // routes them to the import-controller, which actually loads and runs them.
     // Without it (analysis-only desugar) inline imports would pass validation
     // and then never execute.
-    const lm = await this.loader.loadModule(sourceUrl, { compile: true, desugarImports: true });
+    const lm = await this.loader.loadModule(sourceUrl, { compile: true, desugarImports: true, migrate: true });
     const allManifests = flattenLoadedModule(lm);
 
     // Phase 2: normalize inline resources — extract inline values from x-telo-ref slots
@@ -1285,6 +1304,19 @@ export class Kernel implements IKernel {
     const compile = [...parentEval.compile, ...ownEval.compile];
     const runtime = [...parentEval.runtime, ...ownEval.runtime];
 
+    // Embedded files are read here, at the single instance-production site, and
+    // not at manifest load: `telo.yaml` is its own artifact layer so that reading
+    // a manifest cannot pull the payload, and an app loads every imported
+    // library's manifest. Before schema validation, so the schema sees the
+    // resolved value — bytes arrive at an `x-telo-binary` slot as the
+    // `Uint8Array` that annotation demands.
+    await resolveIncludeSentinels(
+      resource,
+      this.findModuleContext(evalContext).source,
+      this,
+      this.includeCache,
+    );
+
     // Schema validation runs before CEL evaluation so it sees the original manifest
     // shape. CompiledValue wrappers (from load-time precompilation) are stripped,
     // restoring the pre-CEL string view that the schema expects.

package/src/manifest-schemas.ts

@@ -2,7 +2,7 @@ import AjvModule from "ajv";
 import addFormats from "ajv-formats";
 // One definition of the `status:` block's shape, shared with `telo check` — the
 // `required:` restriction is reported by the analyzer, which can name the fix.
-import { binaryKeyword, OBSERVED_STATE_SCHEMA } from "@telorun/analyzer";
+import { OBSERVED_STATE_SCHEMA, registerTeloKeywords } from "@telorun/analyzer";
 const Ajv = AjvModule.default ?? AjvModule;
 
 // Re-export the shared ResourceRef fragment from the templating package
@@ -177,7 +177,7 @@ export const ResourceAbstractSchema = {
 };
 
 const ajv = new Ajv({ allErrors: true, strict: false });
-ajv.addKeyword(binaryKeyword());
+registerTeloKeywords(ajv);
 addFormats.default(ajv);
 
 // Lazy-compile validator: the AJV codegen cost (≈10–15 ms for these

package/src/module-file-resolution.ts

@@ -0,0 +1,64 @@
+import * as path from "path";
+import { pathToFileURL } from "url";
+import { RuntimeError } from "@telorun/sdk";
+import type { ModuleArtifact } from "./bundle/module-artifact.js";
+
+/** The slice of the kernel this module needs: a module's artifact, when it has
+ *  one. A module already on disk has none — that is normal, not an error. */
+export interface ModuleArtifactLookup {
+  getModuleArtifact(source: string | undefined): ModuleArtifact | undefined;
+}
+
+/**
+ * Resolve a module-relative reference against the declaring module's own
+ * directory, materializing the layers that could carry it on first use.
+ *
+ * A URI, not a filesystem path: the SDK is cross-runtime, and a path is only
+ * what *this* kernel happens to return for a module whose files are local. An
+ * already-absolute URI (one with a scheme) passes through untouched; a bare
+ * absolute filesystem path is returned as a `file://` URI rather than being
+ * rebased onto the module directory.
+ *
+ * Shared by `ctx.resolveModuleFile` and by `!include-*` resolution, so a file
+ * reached by a controller and a file embedded by a tag are located by one rule
+ * — including which layers get materialized on the way.
+ */
+export async function resolveModuleFileUri(
+  relative: string,
+  source: string,
+  lookup: ModuleArtifactLookup,
+): Promise<string> {
+  // An absolute URI names its own location; a bare absolute path is already
+  // resolved and must not be rebased onto the module directory.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(relative)) return relative;
+  if (path.isAbsolute(relative)) return pathToFileURL(relative).href;
+
+  const artifact = lookup.getModuleArtifact(source);
+  if (artifact) {
+    // Both the `assets` layer and `common` — the sink rule puts a file the
+    // author did not claim via `assets:` into `common`, and a module that ships
+    // static files with no bundled controller has no other route to its payload.
+    // Fetching only assets would leave such a module resolving into an empty
+    // directory.
+    await artifact.materializeModuleFiles();
+    return new URL(relative, pathToFileURL(path.join(artifact.directory, "/")).href).href;
+  }
+  // No artifact means no payload to fetch. That is normal for a module already
+  // on disk (development) or one that ships no files — but for a module reached
+  // over a non-local scheme it means the artifact carries no layer index, i.e. it
+  // predates layers. Raise the actionable error here rather than leaving each
+  // caller to invent its own message from a URI it cannot open.
+  if (!source.startsWith("file://") && !path.isAbsolute(source)) {
+    throw new RuntimeError(
+      "ERR_MODULE_FILES_UNAVAILABLE",
+      `Cannot resolve '${relative}' against module '${source}': the module's artifact ` +
+        `carries no layer index, so its files cannot be located. It was published by an ` +
+        `older Telo that wrote a single-blob artifact — republish the module, or import it ` +
+        `from a local path during development.`,
+    );
+  }
+  // Local module: resolve against the manifest URL, the same rule `include:`
+  // and sibling imports follow.
+  const base = source.startsWith("file://") ? source : pathToFileURL(source).href;
+  return new URL(relative, base).href;
+}

package/src/observed-state.ts

@@ -1,4 +1,4 @@
-import { binaryKeyword } from "@telorun/analyzer";
+import { registerTeloKeywords } from "@telorun/analyzer";
 import AjvModule from "ajv";
 import { detachSnapshotValue, OBSERVED_STATE_KEY, RuntimeError } from "@telorun/sdk";
 
@@ -58,7 +58,7 @@ function mark(target: Record<string, unknown>, info: ObservedStateInfo): void {
 }
 
 const ajv = new Ajv({ allErrors: true, strict: false });
-ajv.addKeyword(binaryKeyword());
+registerTeloKeywords(ajv);
 // Compiling a status schema costs ~ms and a resource may report repeatedly, so
 // keep the validator keyed on the schema object it came from. The kind's folded
 // `status:` is stamped once at registration, so this hits.

package/src/resolve-include-sentinels.ts

@@ -0,0 +1,219 @@
+import { readFile, stat } from "fs/promises";
+import { fileURLToPath } from "url";
+import { RuntimeError, type ResourceManifest } from "@telorun/sdk";
+import {
+  INCLUDE_BYTES_ENGINE,
+  isIncludeSentinel,
+  isTaggedSentinel,
+  normalizeIncludePath,
+  type TaggedSentinel,
+} from "@telorun/templating";
+import { resolveModuleFileUri, type ModuleArtifactLookup } from "./module-file-resolution.js";
+
+/**
+ * Ceiling on one embedded file.
+ *
+ * A resolved embed is an ordinary manifest value, retained for as long as the
+ * resource holding it, so there is no point at which a large one is released.
+ * Streaming a payload is a different primitive with a different lifetime, which
+ * is what the error points at.
+ */
+export const MAX_INCLUDE_BYTES = 32 * 1024 * 1024;
+
+/** Reads keyed by resolved URI. Two resources embedding the same font read it
+ *  once — the values are retained by those resources anyway, so the cache adds
+ *  deduplication rather than retention. */
+export type IncludeCache = Map<string, Uint8Array>;
+
+/** Manifest objects already walked. Keyed by identity and weakly held, so this
+ *  is a gate on repeated work rather than a lifetime extension. */
+const resolved = new WeakSet<object>();
+
+async function readIncluded(
+  uri: string,
+  displayPath: string,
+  cache: IncludeCache,
+): Promise<Uint8Array> {
+  const cached = cache.get(uri);
+  if (cached) return cached;
+
+  if (!uri.startsWith("file:")) {
+    throw new RuntimeError(
+      "ERR_INCLUDE_UNREADABLE",
+      `Cannot embed '${displayPath}': it resolved to '${uri}', which this runtime cannot read ` +
+        `as a file. An embedded file must ship inside the module's own artifact.`,
+    );
+  }
+  const filePath = fileURLToPath(uri);
+
+  // Size is checked before reading, so an oversized file is reported rather
+  // than loaded to discover it was too big.
+  let size: number;
+  try {
+    const info = await stat(filePath);
+    if (!info.isFile()) {
+      throw new RuntimeError(
+        "ERR_INCLUDE_UNREADABLE",
+        `Cannot embed '${displayPath}': '${filePath}' is not a file.`,
+      );
+    }
+    size = info.size;
+  } catch (error) {
+    if (error instanceof RuntimeError) throw error;
+    throw new RuntimeError(
+      "ERR_INCLUDE_FILE_NOT_FOUND",
+      `Cannot embed '${displayPath}': no such file at '${filePath}'. The path is relative to ` +
+        `the module root — the directory holding telo.yaml — not to the file the tag was ` +
+        `written in.`,
+    );
+  }
+  if (size > MAX_INCLUDE_BYTES) {
+    // Megabytes, not raw bytes: the limit is a round number chosen for a human,
+    // and this message is aimed at one.
+    const mb = (n: number) => `${Math.round((n / (1024 * 1024)) * 10) / 10} MB`;
+    throw new RuntimeError(
+      "ERR_INCLUDE_FILE_TOO_LARGE",
+      `Cannot embed '${displayPath}': it is ${mb(size)}, over the ${mb(MAX_INCLUDE_BYTES)} ` +
+        `limit for a file embedded into a manifest value. Read it at runtime with Fs.File ` +
+        `instead, which does not retain it for the life of the resource.`,
+    );
+  }
+
+  const bytes = new Uint8Array(await readFile(filePath));
+  cache.set(uri, bytes);
+  return bytes;
+}
+
+async function resolveSentinel(
+  sentinel: TaggedSentinel,
+  moduleSource: string,
+  lookup: ModuleArtifactLookup,
+  cache: IncludeCache,
+): Promise<string | Uint8Array> {
+  // Re-checked here rather than trusted from `telo check`: the kernel does not
+  // require that check to have run, and confinement is the one property whose
+  // absence is a security question rather than a broken build.
+  const { path: relative, diagnostic } = normalizeIncludePath(sentinel.source);
+  if (!relative) {
+    throw new RuntimeError(
+      "ERR_INCLUDE_PATH_INVALID",
+      `Invalid \`!${sentinel.engine}\` path: ${diagnostic?.message ?? "not a module-relative path."}`,
+    );
+  }
+
+  const uri = await resolveModuleFileUri(relative, moduleSource, lookup);
+  const bytes = await readIncluded(uri, relative, cache);
+  if (sentinel.engine === INCLUDE_BYTES_ENGINE) return bytes;
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+
+/**
+ * Replace every `!include-text` / `!include-bytes` sentinel in a resource's
+ * config with the file's contents, in place.
+ *
+ * Called at resource creation — the kernel's single instance-production site —
+ * and NOT during manifest load. The artifact spec gives `telo.yaml` a layer of
+ * its own precisely so that reading a manifest cannot pull the whole artifact;
+ * resolving at load would defeat that just as thoroughly, because loading an app
+ * loads every imported library's manifest and would fetch every library's assets
+ * layer whether or not anything used it. Resolving here bounds the cost to
+ * modules whose resources actually instantiate, and a `with:`-scoped resource
+ * pays only when its scope runs.
+ *
+ * It runs BEFORE the resource's schema validation, so a resolved value is what
+ * the schema sees: bytes reach an `x-telo-binary` slot as the `Uint8Array` that
+ * annotation demands, and an unresolved marker never reaches a controller.
+ *
+ * In place, like `resolveRefSentinels` — which also makes it idempotent, so a
+ * scoped resource created once per scope run reads its files once.
+ */
+export async function resolveIncludeSentinels(
+  resource: ResourceManifest,
+  moduleSource: string,
+  lookup: ModuleArtifactLookup,
+  cache: IncludeCache,
+): Promise<void> {
+  // A resource that defers across init passes reaches `create()` more than once,
+  // and a `with:`-scoped one is created per scope run — the walk is idempotent
+  // either way, so repeating it is pure cost on the init loop. One walk per
+  // manifest object is enough: resolution rewrites it in place.
+  if (resolved.has(resource)) return;
+
+  const pending: Array<Promise<void>> = [];
+
+  /** A nested resource DECLARATION — an inline `{ kind, … }`, whether it sits in
+   *  a `with:` scope or in a step's `invoke:`. Its embeds belong to it, not to
+   *  the resource that encloses it, and it reaches `create()` in its own right.
+   *  Phase-5 injection draws the same line for `!ref`s inside a scope. */
+  const isNestedDeclaration = (value: unknown): boolean =>
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof (value as { kind?: unknown }).kind === "string";
+
+  const take = (item: unknown, assign: (resolved: string | Uint8Array) => void): void => {
+    if (isIncludeSentinel(item)) {
+      pending.push(resolveSentinel(item, moduleSource, lookup, cache).then(assign));
+      return;
+    }
+    // Another engine's sentinel is opaque; a nested declaration is resolved when
+    // that resource is created, which is what keeps a scoped resource's files
+    // unread until its scope actually runs.
+    if (!isTaggedSentinel(item) && !isNestedDeclaration(item)) walk(item);
+  };
+
+  const walk = (value: unknown): void => {
+    if (value === null || typeof value !== "object") return;
+    // A compiled CEL node is opaque and carries no sentinels of its own.
+    if ((value as { __compiled?: unknown }).__compiled) return;
+    // Only PLAIN containers are descended into. A template kind expands
+    // `${{ self.connection }}` to a LIVE ResourceInstance, whose object graph
+    // reaches back into contexts and the kernel and contains cycles — walking it
+    // overflows the stack, and nothing in it could be a manifest value anyway.
+    // Same rule `compileWalker` and `precompileDoc` follow.
+    if (!Array.isArray(value)) {
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return;
+    }
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        const index = i;
+        take(value[index], (resolved) => {
+          value[index] = resolved;
+        });
+      }
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    for (const key of Object.keys(obj)) {
+      take(obj[key], (resolved) => {
+        obj[key] = resolved;
+      });
+    }
+  };
+
+  // The resource being created is itself a `{ kind, … }` declaration, so the walk
+  // starts INSIDE it rather than at it — only the ones nested below are deferred.
+  walk(resource as Record<string, unknown>);
+  // Reads run concurrently and every failure surfaces: one unreadable file must
+  // not be hidden by another failing first.
+  const settled = await Promise.allSettled(pending);
+  const failures = settled.flatMap((r) => (r.status === "rejected" ? [r.reason] : []));
+  resolved.add(resource);
+  if (failures.length === 0) return;
+  // The FIRST failure is rethrown, carrying its own code and its own cause.
+  // Wrapping several into one generic error made the reported code depend on how
+  // many files happened to fail — two missing files became ERR_INCLUDE_UNREADABLE
+  // rather than ERR_INCLUDE_FILE_NOT_FOUND — so a caller matching on the code was
+  // misled by an artefact of the batch, and the individual errors were flattened
+  // into a string nothing could branch on. The rest are attached as `causes`, and
+  // named in the message so none is hidden.
+  const [first, ...rest] = failures as Error[];
+  if (rest.length > 0 && first instanceof RuntimeError) {
+    (first as RuntimeError & { causes?: unknown[] }).causes = rest;
+    first.message += ` (${rest.length} more embed${rest.length === 1 ? "" : "s"} also failed: ${rest
+      .map((f) => f.message)
+      .join("; ")})`;
+  }
+  throw first;
+}

package/src/resource-context.ts

@@ -28,13 +28,14 @@ import {
   type TypeRule,
   type ZoneEntry,
 } from "@telorun/sdk";
-import { binaryKeyword } from "@telorun/analyzer";
+import { registerTeloKeywords } from "@telorun/analyzer";
 import { isRefSentinel } from "@telorun/templating";
 import { ZoneContext } from "./zone-context.js";
 import * as path from "path";
 import { pathToFileURL } from "url";
 import { withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import type { ModuleArtifact } from "./bundle/module-artifact.js";
+import { resolveModuleFileUri } from "./module-file-resolution.js";
 import { hostEnv } from "./host-env.js";
 import type { LoggingHost } from "./logging/logging-host.js";
 import type { ScopeConfig } from "./logging/scope-config.js";
@@ -316,10 +317,7 @@ export class ResourceContextImpl implements ResourceContext {
       removeAdditional: true,
     });
     addFormats.default(ajv);
-    for (const kw of ["x-telo-ref", "x-telo-scope", "x-telo-context", "x-telo-schema-from"]) {
-      ajv.addKeyword(kw);
-    }
-    ajv.addKeyword(binaryKeyword());
+    registerTeloKeywords(ajv);
     const validate = ajv.compile(
       "type" in schema && typeof schema.type === "string"
         ? schema
@@ -794,40 +792,7 @@ export class ResourceContextImpl implements ResourceContext {
    * rebased onto the module directory.
    */
   async resolveModuleFile(relative: string): Promise<string> {
-    // An absolute URI names its own location; a bare absolute path is already
-    // resolved and must not be rebased onto the module directory.
-    if (/^[a-z][a-z0-9+.-]*:/i.test(relative)) return relative;
-    if (path.isAbsolute(relative)) return pathToFileURL(relative).href;
-
-    const source = this.moduleContext.source;
-    const artifact = this.kernel.getModuleArtifact(source);
-    if (artifact) {
-      // Both the `assets` layer and `common` — the sink rule puts a file the
-      // author did not claim via `assets:` into `common`, and a module that ships
-      // static files with no bundled controller has no other route to its payload.
-      // Fetching only assets would leave such a module resolving into an empty
-      // directory.
-      await artifact.materializeModuleFiles();
-      return new URL(relative, pathToFileURL(path.join(artifact.directory, "/")).href).href;
-    }
-    // No artifact means no payload to fetch. That is normal for a module already
-    // on disk (development) or one that ships no files — but for a module reached
-    // over a non-local scheme it means the artifact carries no layer index, i.e. it
-    // predates layers. Raise the actionable error here rather than leaving each
-    // caller to invent its own message from a URI it cannot open.
-    if (!source.startsWith("file://") && !path.isAbsolute(source)) {
-      throw new RuntimeError(
-        "ERR_MODULE_FILES_UNAVAILABLE",
-        `Cannot resolve '${relative}' against module '${source}': the module's artifact ` +
-          `carries no layer index, so its files cannot be located. It was published by an ` +
-          `older Telo that wrote a single-blob artifact — republish the module, or import it ` +
-          `from a local path during development.`,
-      );
-    }
-    // Local module: resolve against the manifest URL, the same rule `include:`
-    // and sibling imports follow.
-    const base = source.startsWith("file://") ? source : pathToFileURL(source).href;
-    return new URL(relative, base).href;
+    return resolveModuleFileUri(relative, this.moduleContext.source, this.kernel);
   }
 
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {

package/src/runtime-seam.ts

@@ -2,8 +2,12 @@ import {
   Loader,
   StaticAnalyzer,
   collectZoneModuleDocuments,
+  diagnosticFix,
   flattenForAnalyzer,
+  remapMigratedPaths,
   type AnalysisDiagnostic,
+  type DiagnosticData,
+  type LoadedGraph,
   type ManifestSource,
   type ZoneModuleDocuments,
 } from "@telorun/analyzer";
@@ -116,6 +120,12 @@ const SEVERITY_NAMES: Record<number, CheckDiagnosticSeverity> = {
  *  read by kernels that speak no LSP. An unlabelled severity is an error: the
  *  analyzer's own default, and the safe reading for a caller gating on it. */
 function toCheckDiagnostic(diagnostic: AnalysisDiagnostic): CheckDiagnostic {
+  // The repair is read through the analyzer's accessor rather than by casting
+  // `data`, so the stamp's shape stays owned by one module. `resource` / `path`
+  // ride along because a repair replaces the value AT `path`; forwarding the
+  // fix without its anchor gives a consumer something it cannot apply.
+  const fix = diagnosticFix(diagnostic);
+  const stamp = diagnostic.data as DiagnosticData | undefined;
   return {
     code: String(diagnostic.code ?? ""),
     message: diagnostic.message,
@@ -123,6 +133,9 @@ function toCheckDiagnostic(diagnostic: AnalysisDiagnostic): CheckDiagnostic {
     source: diagnostic.source,
     line: diagnostic.range?.start?.line,
     column: diagnostic.range?.start?.character,
+    ...(stamp?.resource ? { resource: `${stamp.resource.kind}/${stamp.resource.name}` } : {}),
+    ...(stamp?.path ? { path: stamp.path } : {}),
+    ...(fix ? { fix: { replacement: fix.replacement } } : {}),
   };
 }
 
@@ -213,14 +226,26 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     // `analyze()`'s — carried out of the try so the checks below can see them.
     let parseDiagnostics: AnalysisDiagnostic[] = [];
     let versionDiagnostics: AnalysisDiagnostic[] = [];
+    let migrationDiagnostics: AnalysisDiagnostic[] = [];
     let moduleDocuments: ZoneModuleDocuments[] = [];
+    // Carried out of the try for the same reason the diagnostics are: analysis
+    // runs over the MIGRATED tree while every path a caller resolves points at
+    // the raw file, so the driver's provenance record has to be in hand below.
+    let loadedGraph: LoadedGraph | undefined;
     try {
+      // `migrate` unconditionally: this seam answers "does this manifest load
+      // and check", and the runtime it stands in for reads a legacy spelling
+      // through the same rewrite. A raw view is a round-trip editor's need, not
+      // a supervisor's.
       const graph = await loader.loadGraph(source, {
         desugarImports: options?.desugarImports ?? true,
+        migrate: true,
       });
       if (graph.errors.length > 0) throw graph.errors[0].error;
+      loadedGraph = graph;
       parseDiagnostics = graph.parseDiagnostics;
       versionDiagnostics = graph.versionDiagnostics;
+      migrationDiagnostics = graph.migrationDiagnostics;
       manifests = flattenForAnalyzer(graph);
       // The zone stage derives each imported library's export contracts from
       // its own full documents, which the flattened list drops.
@@ -243,17 +268,29 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     // treating a parse failure as fatal before analysis.
     if (parseDiagnostics.length > 0) {
       return {
-        diagnostics: [...parseDiagnostics, ...versionDiagnostics].map(toCheckDiagnostic),
+        diagnostics: [...parseDiagnostics, ...migrationDiagnostics, ...versionDiagnostics].map(
+          toCheckDiagnostic,
+        ),
       };
     }
 
     // `analyze()` never sees version skew, so without merging these a major
     // mismatch — which `load()` refuses to boot on — would check clean.
-    const diagnostics = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests, {
+    //
+    // The remap is the same call `assembleGraphDiagnostics` makes for the CLI
+    // and VS Code, and it is not optional here: a caller acts on `path` (a
+    // module's `Assert.Manifest` matches on it), so this seam reporting the
+    // MIGRATED spelling while every other surface reports the author's would
+    // make one manifest mean two things depending on who asked. A no-op when
+    // nothing was migrated.
+    const analysis = new StaticAnalyzer({ celHandlers: nodeCelHandlers }).analyze(manifests, {
       moduleDocuments,
     });
+    const diagnostics = remapMigratedPaths(loadedGraph, analysis);
     return {
-      diagnostics: [...versionDiagnostics, ...diagnostics].map(toCheckDiagnostic),
+      diagnostics: [...migrationDiagnostics, ...versionDiagnostics, ...diagnostics].map(
+        toCheckDiagnostic,
+      ),
     };
   }
 }

package/src/schema-validator.ts

@@ -7,7 +7,8 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
-import { binaryKeyword, X_TELO_BINARY } from "@telorun/analyzer";
+import { registerTeloKeywords } from "@telorun/analyzer";
+import { X_TELO_TYPE } from "@telorun/sdk";
 import { mergeFilledDefaults, withBigIntsAsNumbers } from "./bigint-schema-view.js";
 import { formatAjvErrors } from "./manifest-schemas.js";
 
@@ -25,7 +26,6 @@ import {
   EXACT_TEMPLATE_REGEX,
   isTaggedSentinel,
   ManifestRootSchema,
-  normalizeRefSlots,
 } from "@telorun/templating";
 
 const Ajv = AjvModule.default ?? AjvModule;
@@ -165,13 +165,19 @@ const NAME_KEYED_SCHEMA_KEYWORDS = new Set([
 const DATA_VALUE_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
 
 /** Annotations that DO emit validation code, and so must survive the strip and stay
- *  in the cache key. `x-telo-binary` is the first: bytes have no JSON Schema type,
+ *  in the cache key. `x-telo-type` is the only one: bytes have no JSON Schema type,
  *  so the keyword is the only thing standing between a byte slot and "accepts any
  *  object". Stripping it would silently reduce the slot to an empty schema — the
  *  precise regression the annotation was introduced to close — and, because the key
  *  is meant to describe the compiled validator, a keyword that changes the validator
- *  belongs in it. */
-const VALIDATING_ANNOTATIONS = new Set([X_TELO_BINARY]);
+ *  belongs in it.
+ *
+ *  Its names need no canonicalization to be safe in a key, unlike `x-telo-ref`'s:
+ *  the vocabulary is closed and `Telo.`-qualified, so an author writes the
+ *  canonical name or none, and a named SHAPE reaches the annotation as a `$ref`
+ *  the loader already resolved. There is nothing here that the analyzer's baked
+ *  view and the runtime could spell differently. */
+const VALIDATING_ANNOTATIONS = new Set([X_TELO_TYPE]);
 
 /** Deep-clone `schema` without its `x-telo-*` annotations — applied, like
  *  {@link collapseSentinelsToSource}, before both AJV compilation and cache
@@ -193,9 +199,7 @@ const VALIDATING_ANNOTATIONS = new Set([X_TELO_BINARY]);
  *
  *  Stripping is what makes the key describe the compiled validator and nothing
  *  else, so the two views converge without either side having to agree on an
- *  annotation's spelling. `normalizeRefSlots` runs FIRST and is unaffected: it
- *  reads `x-telo-ref` to drop a legacy scalar `type` at a ref slot, which does
- *  change validation, and it has already done so by the time this runs. */
+ *  annotation's spelling. */
 function stripTeloAnnotations(value: unknown, nameKeyed = false): unknown {
   // An array's items are schema nodes (`allOf`, tuple `items`), never names.
   if (Array.isArray(value)) return value.map((item) => stripTeloAnnotations(item));
@@ -258,27 +262,12 @@ export class SchemaValidator {
       code: { source: true },
     });
     addFormats.default(this.ajv);
-    for (const kw of [
-      "x-telo-ref",
-      "x-telo-eval",
-      "x-telo-scope",
-      "x-telo-context",
-      "x-telo-context-from",
-      "x-telo-context-ref-from",
-      "x-telo-schema-from",
-      "x-telo-topology-role",
-      "x-telo-step-context",
-      "x-telo-widget",
-      "x-telo-type",
-      "x-telo-inline",
-    ]) {
-      this.ajv.addKeyword(kw);
-    }
-    // Not a no-op like the rest: bytes have no JSON Schema type, so this keyword IS
-    // the check. Defined as codegen in the analyzer so it inlines into the
-    // standalone validators compiled and cached below, rather than needing the
-    // implementation present at load.
-    this.ajv.addKeyword(binaryKeyword());
+    // One registration site for every Telo keyword: the annotations as no-ops
+    // and `x-telo-type` as the one that actually checks. `x-telo-type` is defined
+    // as codegen in the analyzer so it inlines into the standalone validators
+    // compiled and cached below, rather than needing the implementation present
+    // at load.
+    registerTeloKeywords(this.ajv);
     // Register the shared manifest root so module schemas can
     // `$ref: "telo://manifest#/$defs/ResourceRef"` without each manifest
     // bundling its own copy. Mirrors the analyzer's createAjv().
@@ -361,12 +350,7 @@ export class SchemaValidator {
           }
         : normalized;
 
-    // Drop the legacy scalar `type` an older published module may still pin on
-    // its `x-telo-ref` slots. Schema validation runs in create() before Phase 5
-    // injection, so a ref slot holds the resolved `{kind, name, alias?}` object
-    // (or an unresolved sentinel) — both objects the stale `type: "string"`
-    // would otherwise reject.
-    const injected = normalizeRefSlots(withImplicit) as typeof withImplicit;
+    const injected = withImplicit;
 
     // Canonicalize CEL/template carriers (an inline `${{ }}` left in a
     // `description`, a `!cel` tag, …) to their bare source text so AJV can