@telorun/analyzer 0.51.0 → 0.53.0

package/src/cel-bindings.ts

@@ -0,0 +1,222 @@
+import { isCompiledValue } from "@telorun/sdk";
+import { buildCelEnvironment, extractAccessChains } from "@telorun/templating";
+import { extractContextsFromSchema } from "./validate-cel-context.js";
+
+/** Annotation on an `x-telo-context` node naming the resource field that holds
+ *  the kind's named CEL bindings. The field is read from the RESOURCE ROOT, not
+ *  the per-scope manifest item: a bindings map belongs to the resource, while the
+ *  contexts that see it may be anchored anywhere (a decision table annotates both
+ *  `choices` and `default`). */
+export const BINDINGS_ANNOTATION = "x-telo-bindings-from";
+
+export interface BindingSites {
+  /** Resource field holding the bindings map. */
+  field: string;
+  /** Every field named by an annotation on this kind. More than one is a
+   *  kind-authoring mistake: which of them holds the bindings would be decided
+   *  by schema walk order. */
+  fields: string[];
+  /** Variable names the annotated contexts declare — a binding may not shadow one. */
+  scopeNames: Set<string>;
+}
+
+/**
+ * CEL keywords. A binding named after one is unreachable — `true` lexes as a
+ * literal, `in` as an operator — so it is reserved alongside the scope names,
+ * which turns silence into a diagnostic.
+ */
+export const CEL_RESERVED_WORDS: readonly string[] = [
+  "as",
+  "break",
+  "const",
+  "continue",
+  "else",
+  "false",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "let",
+  "loop",
+  "namespace",
+  "null",
+  "package",
+  "return",
+  "true",
+  "var",
+  "void",
+  "while",
+];
+
+/** Locate a kind's bindings field and the scope names its annotated contexts
+ *  declare. Returns undefined for a kind that declares no bindings region. */
+export function findBindingSites(
+  definitionSchema: Record<string, any> | undefined,
+): BindingSites | undefined {
+  if (!definitionSchema) return undefined;
+  const fields: string[] = [];
+  const scopeNames = new Set<string>();
+  for (const { schema } of extractContextsFromSchema(definitionSchema)) {
+    const declared = schema?.[BINDINGS_ANNOTATION];
+    if (typeof declared !== "string" || declared.length === 0) continue;
+    if (!fields.includes(declared)) fields.push(declared);
+    for (const name of Object.keys(schema.properties ?? {})) scopeNames.add(name);
+  }
+  return fields.length > 0 ? { field: fields[0]!, fields, scopeNames } : undefined;
+}
+
+const TEMPLATE_RE = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+const EXACT_TEMPLATE_RE = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+
+/** Parser for expressions that reach here uncompiled. Built once; the base
+ *  environment is stateless and shared with the runtime's own. */
+let parseEnv: ReturnType<typeof buildCelEnvironment> | undefined;
+
+/**
+ * Root identifiers an expression source reads — the first element of every
+ * member-access chain, which is what a dependency edge is made of.
+ *
+ * Parsed, never lexed: `inputs.total` reads `inputs`, not `total`, and a name
+ * inside a string literal reads nothing. A token scan would make two bindings
+ * named after each other's *fields* look mutually recursive and reject a correct
+ * manifest — the worst outcome a static check has. An expression that does not
+ * parse contributes no edges; its syntax error is the engine pass's to report.
+ */
+function addRootIdentifiers(source: string, out: Set<string>): void {
+  try {
+    parseEnv ??= buildCelEnvironment();
+    for (const chain of extractAccessChains(parseEnv.parse(source).ast)) {
+      if (chain.length > 0) out.add(chain[0]!);
+    }
+  } catch {
+    // Unparseable — see above.
+  }
+}
+
+/** Root identifiers a binding's value reads. Walks the whole value so a
+ *  structured binding (a map with `!cel` leaves) is covered, and reads both a
+ *  compiled expression and a still-raw `${{ }}` string — the editor's
+ *  round-trip view never compiles. An untagged plain string is a literal, not
+ *  an expression, and contributes nothing. */
+function collectRefs(value: unknown, out: Set<string>): void {
+  if (isCompiledValue(value)) {
+    const refs = (value as { refs?: readonly string[] }).refs;
+    if (refs) for (const ref of refs) out.add(ref);
+    else addRootIdentifiers((value as { source?: string }).source ?? "", out);
+    return;
+  }
+  if (typeof value === "string") {
+    for (const match of value.matchAll(TEMPLATE_RE)) addRootIdentifiers(match[1]!, out);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) collectRefs(entry, out);
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    for (const entry of Object.values(value)) collectRefs(entry, out);
+  }
+}
+
+/** Each binding's dependencies, restricted to its siblings — an identifier that
+ *  names something else in scope (`inputs`, `item`) is not an edge. */
+export function bindingDependencies(
+  bindings: Record<string, unknown>,
+): Map<string, Set<string>> {
+  const names = new Set(Object.keys(bindings));
+  const deps = new Map<string, Set<string>>();
+  for (const [name, value] of Object.entries(bindings)) {
+    const refs = new Set<string>();
+    collectRefs(value, refs);
+    const own = new Set<string>();
+    for (const ref of refs) if (names.has(ref)) own.add(ref);
+    deps.set(name, own);
+  }
+  return deps;
+}
+
+/** Member-access chain for a binding whose value is one bare dotted identifier
+ *  expression (`inputs.user.name`). Null for anything else — a literal, a call,
+ *  a comprehension, a structured value — none of which reduces to a typed path. */
+export function bindingPathChain(value: unknown): string[] | null {
+  let source: string | undefined;
+  if (isCompiledValue(value)) source = (value as { source?: string }).source;
+  else if (typeof value === "string") source = value.match(EXACT_TEMPLATE_RE)?.[1];
+  if (source === undefined) return null;
+  const expr = source.trim();
+  if (!/^[A-Za-z_]\w*(\.[A-Za-z_]\w*)*$/.test(expr)) return null;
+  return expr.split(".");
+}
+
+/**
+ * The context properties a bindings map contributes: each name typed from its
+ * expression where that expression is a chain into an already-typed scope
+ * variable, and left open otherwise.
+ *
+ * Gradual by design — the same stance `x-telo-context-element-from` takes. An
+ * open schema costs a missed `CEL_UNKNOWN_FIELD` under that name; inventing a
+ * type would cost a false one.
+ */
+export function bindingContextProperties(
+  bindings: Record<string, unknown>,
+  contextSchema: Record<string, any>,
+): Record<string, any> {
+  const props: Record<string, any> = {};
+  for (const [name, value] of Object.entries(bindings)) {
+    props[name] = schemaAtChain(bindingPathChain(value), contextSchema) ?? {};
+  }
+  return props;
+}
+
+/** Walk a member-access chain through a schema's `properties`, returning the
+ *  terminal node or undefined once the path leaves typed schema. */
+export function schemaAtChain(
+  chain: string[] | null,
+  root: Record<string, any>,
+): Record<string, any> | undefined {
+  if (!chain) return undefined;
+  let current: Record<string, any> | undefined = root;
+  for (const key of chain) {
+    const props = current?.properties as Record<string, any> | undefined;
+    if (!props || !(key in props)) return undefined;
+    current = props[key] as Record<string, any>;
+  }
+  return current && typeof current === "object" ? current : undefined;
+}
+
+/**
+ * Evaluation order derived from the reference graph, plus any cycles found.
+ *
+ * Order is what the editor and diagnostics show; the runtime does not need it,
+ * since lazy evaluation reaches a binding's dependencies by construction. A
+ * cycle is reported as the path that closes it (`a → b → a`).
+ */
+export function resolveBindingOrder(bindings: Record<string, unknown>): {
+  order: string[];
+  cycles: string[][];
+} {
+  const deps = bindingDependencies(bindings);
+  const order: string[] = [];
+  const cycles: string[][] = [];
+  const state = new Map<string, "visiting" | "done">();
+  const path: string[] = [];
+
+  const visit = (name: string): void => {
+    const seen = state.get(name);
+    if (seen === "done") return;
+    if (seen === "visiting") {
+      cycles.push([...path.slice(path.indexOf(name)), name]);
+      return;
+    }
+    state.set(name, "visiting");
+    path.push(name);
+    for (const dep of deps.get(name) ?? []) visit(dep);
+    path.pop();
+    state.set(name, "done");
+    order.push(name);
+  };
+
+  for (const name of Object.keys(bindings)) visit(name);
+  return { order, cycles };
+}

package/src/index.ts

@@ -24,6 +24,14 @@ export {
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  BINDINGS_ANNOTATION,
+  bindingContextProperties,
+  bindingDependencies,
+  findBindingSites,
+  resolveBindingOrder,
+} from "./cel-bindings.js";
+export type { BindingSites } from "./cel-bindings.js";
 export {
   applyObservedStateNode,
   buildObservedStateIndex,
@@ -111,6 +119,7 @@ export { defaultSources } from "./sources/default-sources.js";
 export {
   splitIntegrity,
   foldIntegrity,
+  isCanonicalIntegrity,
   verifyIntegrity,
   verifiedFetch,
   sha256Base64Url,
@@ -158,6 +167,10 @@ export {
 } from "./artifact-layer-index.js";
 export type { ArtifactLayer } from "./artifact-layer-index.js";
 export { validateModuleArtifact } from "./validate-module-artifact.js";
+// Warnings everywhere, fatal at `telo publish` — descriptive metadata has no
+// runtime failure mode, so it must not stop a manifest running, but it is the
+// module's public face the moment it is published.
+export { PUBLISH_BLOCKING_CODES } from "./validate-module-metadata.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";

package/src/sources/integrity.ts

@@ -11,6 +11,13 @@
  *  only algorithm accepted today; the prefix leaves room to migrate. */
 const INTEGRITY_FRAGMENT = /#(sha256-[A-Za-z0-9_+/=-]+)$/;
 
+/** The canonical written form: SHA-256 as unpadded base64url, exactly what
+ *  {@link sha256Base64Url} emits and what the `layers[].integrity` schema
+ *  accepts. Stricter than {@link INTEGRITY_FRAGMENT}, which also tolerates the
+ *  padded / standard-base64 spellings {@link verifyIntegrity} normalizes on the
+ *  way in — reading is forgiving, writing is not. */
+const CANONICAL_INTEGRITY = /^sha256-[A-Za-z0-9_-]{43}$/;
+
 /** A failed integrity/tamper check — always terminal, never best-effort. A
  *  distinct type so a caller doing best-effort network handling (e.g. the
  *  bundle extractor warning-and-skipping on a fetch blip) can still let a
@@ -41,6 +48,19 @@ export function foldIntegrity(source: string, integrity: unknown): string {
     : source;
 }
 
+/** True for a value safe to WRITE into a manifest as an integrity pin.
+ *
+ *  A pin arriving from outside the file — the hub's version index, a registry
+ *  response — is untrusted text before it is untrusted *content*: a value
+ *  carrying a quote, a `#`, or a newline corrupts the YAML it is spliced into,
+ *  which no later install-time verification can catch because the manifest no
+ *  longer parses. A wrong-but-well-formed hash is the case install *does*
+ *  catch; this is the case it cannot. Callers writing a pin they did not
+ *  compute check here first and fall back to writing none. */
+export function isCanonicalIntegrity(value: unknown): value is string {
+  return typeof value === "string" && CANONICAL_INTEGRITY.test(value);
+}
+
 function toBase64Url(bytes: Uint8Array): string {
   let binary = "";
   for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);

package/src/validate-cel-context.ts

@@ -325,11 +325,16 @@ export function resolveContextAnnotations(
       : [fromRefKindRaw];
   if (fromRoot || fromRefKinds.length > 0) {
     if (fromRoot) {
-      const resolved = navigatePath(manifestRoot, fromRoot.split("/")) as
+      const navigated = navigatePath(manifestRoot, fromRoot.split("/")) as
         | Record<string, any>
         | undefined;
-      if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
-        return resolved;
+      if (navigated && typeof navigated === "object" && !Array.isArray(navigated)) {
+        // A `telo#Type` slot resolves to the schema it names — the inline
+        // `{ kind, schema }` wrapper, a `!ref` to a named type, or a bare name —
+        // so the variable is typed by the CONTRACT rather than by the wrapper
+        // around it. A raw JSON Schema resolves to itself, and a plain property
+        // map (a transport scope) resolves to nothing and is used verbatim.
+        return resolveTypeFieldToSchema(navigated, allManifests ?? []) ?? navigated;
       }
     }
     if (defs) {

package/src/validate-module-metadata.ts

@@ -0,0 +1,335 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { distance } from "./levenshtein.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Static validation of the `metadata:` block on module docs (`Telo.Application` /
+ * `Telo.Library`) and of `metadata.deprecated` wherever it appears.
+ *
+ * These fields are descriptive — nothing in the kernel branches on them — but they
+ * are the module's public face: a hub indexes them, and a consumer reads them
+ * before deciding to import. That is exactly why they need checking. A field the
+ * runtime ignores has no failure mode that would ever surface it, so a mistyped
+ * `licence:` or `deprecatd:` is invisible forever, and the module ships claiming
+ * nothing while its author believes otherwise.
+ *
+ * The vocabulary stays **open** — `metadata` accepts any key, because a publisher
+ * may carry their own — so an unknown key is only reported when it is a near-miss
+ * of a known one. That catches the typo without closing the set.
+ *
+ * **Everything here is a WARNING, and fatal only at `telo publish`** (see
+ * {@link PUBLISH_BLOCKING_CODES}). Refusing to *run* a manifest over a field no
+ * runtime reads gets the cost backwards: `version: 1.0` is a YAML float rather
+ * than a string, which is a real mistake worth reporting, but stopping the app
+ * from starting over it is worse than the mistake. Publication is the moment
+ * these fields become consequential — they are projected onto the artifact's
+ * annotations and indexed by the hub — so that is where they block.
+ */
+
+/**
+ * Codes that must not block running a manifest but MUST block publishing one.
+ *
+ * Kept as a set rather than a severity because the two audiences differ: a
+ * developer running a manifest wants to know, a publisher must be stopped. If a
+ * later check earns the same treatment, add its code here rather than inventing
+ * a third severity level.
+ */
+export const PUBLISH_BLOCKING_CODES: ReadonlySet<string> = new Set([
+  "METADATA_INVALID_TYPE",
+  "METADATA_UNKNOWN_FIELD",
+  "INVALID_DEPRECATION",
+  "DEPRECATION_REPLACEMENT_UNRESOLVED",
+]);
+
+type FieldType = "string" | "string[]" | "object";
+
+/** Conventional module-doc metadata, and the type each carries. Descriptive only;
+ *  `name` is the sole field anything resolves against. */
+const MODULE_METADATA_TYPES: Record<string, FieldType> = {
+  name: "string",
+  module: "string",
+  version: "string",
+  description: "string",
+  repository: "string",
+  homepage: "string",
+  documentation: "string",
+  license: "string",
+  namespace: "string",
+  categories: "string[]",
+  deprecated: "object",
+};
+
+/** What a kind doc's `metadata:` may carry.
+ *
+ *  Deliberately narrower than a module's: `version`, `license` and the rest
+ *  belong to the module, and a kind restating them means nothing. `categories`
+ *  is legal and *replaces* the module's for that kind; `description` is hub
+ *  search text. Both have exactly the failure mode this file exists for — a
+ *  `descriptoin:` on a kind doc is read by nothing and reported by nothing, so
+ *  it ships silently — which is why kind docs are checked rather than exempt. */
+const KIND_METADATA_TYPES: Record<string, FieldType> = {
+  name: "string",
+  module: "string",
+  description: "string",
+  categories: "string[]",
+  deprecated: "object",
+};
+
+/** Alias-qualified kind — `Self.Migrations`, `Cache.Store`, `Telo.JsonSchema`. */
+const ALIAS_KIND_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
+
+/** The built-in namespace, resolvable without an import — mirrors `validate-extends`. */
+const TELO_BUILTIN_ALIAS = "Telo";
+
+function typeOf(value: unknown): "string" | "string[]" | "object" | "other" {
+  if (typeof value === "string") return "string";
+  if (Array.isArray(value)) return value.every((v) => typeof v === "string") ? "string[]" : "other";
+  if (value !== null && typeof value === "object") return "object";
+  return "other";
+}
+
+export function validateModuleMetadata(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  // Docs forwarded from imported libraries carry `metadata.module` set to that
+  // library's name. Their `replacedBy` aliases — `Self`, or any alias private to
+  // that library — belong to the library's OWN scope, which the consumer's
+  // resolver knows nothing about, so re-checking them here reports a false
+  // DEPRECATION_REPLACEMENT_UNRESOLVED against a manifest the consumer does not
+  // own. They are validated when that library is analyzed as a root, which is
+  // its author's concern. Same rule, and the same reason, as `validate-extends`.
+  const importedModules = new Set<string>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const resolved = (m.metadata as { resolvedModuleName?: string } | undefined)
+      ?.resolvedModuleName;
+    if (resolved) importedModules.add(resolved);
+  }
+
+  for (const manifest of manifests) {
+    const isModuleDoc = manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library";
+    const isKindDoc = manifest.kind === "Telo.Definition" || manifest.kind === "Telo.Abstract";
+    if (!isModuleDoc && !isKindDoc) continue;
+
+    const metadata = manifest.metadata as Record<string, unknown> | undefined;
+    if (!metadata) continue;
+
+    const ownModule = (metadata as { module?: string }).module;
+    if (ownModule && importedModules.has(ownModule)) continue;
+
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const filePath = typeof metadata.source === "string" ? metadata.source : undefined;
+    const ctx = {
+      label: `${manifest.kind}/${name ?? "(unnamed)"}`,
+      resource: { kind: manifest.kind, name },
+      filePath,
+    };
+
+    validateFieldTypes(
+      metadata,
+      isModuleDoc ? MODULE_METADATA_TYPES : KIND_METADATA_TYPES,
+      ctx,
+      out,
+    );
+    validateDeprecation(metadata, isModuleDoc, ctx, registry, aliases, out);
+  }
+  return out;
+}
+
+interface DocContext {
+  label: string;
+  resource: { kind: string; name: string | undefined };
+  filePath: string | undefined;
+}
+
+/** How far a key may be from a known one and still be called a typo.
+ *
+ *  Scaled, not absolute: at a flat 2, `date:` (a perfectly ordinary key an
+ *  author might carry) is two edits from `name` and gets told it is a
+ *  misspelling of it. The vocabulary is open, so a false accusation on a short
+ *  key is worse than missing a typo on one. */
+function typoThreshold(key: string, known: string): number {
+  return Math.max(1, Math.floor(Math.min(key.length, known.length) / 3));
+}
+
+function validateFieldTypes(
+  metadata: Record<string, unknown>,
+  allowed: Record<string, FieldType>,
+  ctx: DocContext,
+  out: AnalysisDiagnostic[],
+): void {
+  const known = Object.keys(allowed);
+  for (const [key, value] of Object.entries(metadata)) {
+    // Stamped by the loader, not authored — never a typo to report on.
+    if (key === "source") continue;
+
+    // Listed as known so a typo still gets suggested against it, but its shape
+    // belongs to `validateDeprecation`, which can say what is actually wrong.
+    // Type-checking it here too would report one mistake twice.
+    if (key === "deprecated") continue;
+
+    const expected = allowed[key];
+    if (expected === undefined) {
+      const near = known.find((k) => distance(key, k) <= typoThreshold(key, k));
+      if (near) {
+        out.push({
+          severity: DiagnosticSeverity.Warning,
+          code: "METADATA_UNKNOWN_FIELD",
+          source: SOURCE,
+          message:
+            `${ctx.label}: 'metadata.${key}' is not a known field — did you mean '${near}'? ` +
+            `Nothing reads an unrecognized key, so this declares nothing.`,
+          data: { resource: ctx.resource, filePath: ctx.filePath, path: `metadata.${key}` },
+        });
+      }
+      continue;
+    }
+
+    if (typeOf(value) !== expected) {
+      out.push({
+        severity: DiagnosticSeverity.Warning,
+        code: "METADATA_INVALID_TYPE",
+        source: SOURCE,
+        message: `${ctx.label}: 'metadata.${key}' must be ${describeType(expected)}.`,
+        data: { resource: ctx.resource, filePath: ctx.filePath, path: `metadata.${key}` },
+      });
+    }
+  }
+}
+
+function describeType(t: "string" | "string[]" | "object"): string {
+  if (t === "string[]") return "an array of strings";
+  if (t === "object") return "an object";
+  return "a string";
+}
+
+/**
+ * `metadata.deprecated: { reason, replacedBy? }`.
+ *
+ * `replacedBy` is deliberately resolvable rather than free text, and its form
+ * follows the level: a module doc names another **module ref** (the `imports:`
+ * source grammar), a kind doc names an **alias-qualified kind** resolved through
+ * this file's own imports — the same grammar `kind:` / `extends:` use, so the
+ * replacement is a link a consumer can follow rather than a sentence they have to
+ * interpret.
+ *
+ * A kind whose replacement lives in a module this one does not import cannot be
+ * named; that case deprecates at module level with a module ref instead. Accepted
+ * over inventing a second grammar for it.
+ */
+function validateDeprecation(
+  metadata: Record<string, unknown>,
+  isModuleDoc: boolean,
+  ctx: DocContext,
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  out: AnalysisDiagnostic[],
+): void {
+  const deprecated = metadata.deprecated;
+  if (deprecated === undefined) return;
+
+  const at = "metadata.deprecated";
+  const push = (
+    code: string,
+    message: string,
+    path = at,
+    severity = DiagnosticSeverity.Warning,
+  ): void => {
+    out.push({
+      severity,
+      code,
+      source: SOURCE,
+      message: `${ctx.label}: ${message}`,
+      data: { resource: ctx.resource, filePath: ctx.filePath, path },
+    });
+  };
+
+  if (typeOf(deprecated) !== "object") {
+    push(
+      "INVALID_DEPRECATION",
+      `'${at}' must be an object with a 'reason' (and an optional 'replacedBy'). ` +
+        `A bare 'true' says a thing is deprecated without saying what to do instead.`,
+    );
+    return;
+  }
+
+  const block = deprecated as Record<string, unknown>;
+  const allowed = new Set(["reason", "replacedBy"]);
+  for (const key of Object.keys(block)) {
+    if (!allowed.has(key)) {
+      push("INVALID_DEPRECATION", `'${at}.${key}' is not a recognized key (reason, replacedBy).`, `${at}.${key}`);
+    }
+  }
+
+  if (typeof block.reason !== "string" || block.reason.trim() === "") {
+    push(
+      "INVALID_DEPRECATION",
+      `'${at}.reason' is required and must be a non-empty string — it is what a consumer reads to know what to do instead.`,
+      `${at}.reason`,
+    );
+  }
+
+  const replacedBy = block.replacedBy;
+  if (replacedBy === undefined) return;
+  const path = `${at}.replacedBy`;
+  if (typeof replacedBy !== "string" || replacedBy.trim() === "") {
+    push("INVALID_DEPRECATION", `'${path}' must be a non-empty string.`, path);
+    return;
+  }
+
+  if (isModuleDoc) {
+    // A module is replaced by another module, addressed the way an import is.
+    // Catching alias form here is worth a dedicated message: it is the natural
+    // mistake, and it would otherwise be stored as an unresolvable ref.
+    if (ALIAS_KIND_RE.test(replacedBy)) {
+      push(
+        "INVALID_DEPRECATION",
+        `'${path}: ${replacedBy}' looks like a kind reference, but a module doc's replacement is a ` +
+          `module ref (e.g. 'oci://ghcr.io/acme/thing'). Deprecate the kind itself to point at another kind.`,
+        path,
+      );
+    }
+    return;
+  }
+
+  // Kind level: resolve through this file's imports, exactly as `extends` does.
+  if (!ALIAS_KIND_RE.test(replacedBy)) {
+    push(
+      "INVALID_DEPRECATION",
+      `'${path}: ${replacedBy}' must be an alias-qualified kind ("<Alias>.<Kind>", ` +
+        `e.g. 'Self.Migrations'), resolved via this file's imports.`,
+      path,
+    );
+    return;
+  }
+
+  const prefix = replacedBy.slice(0, replacedBy.indexOf("."));
+  if (prefix !== TELO_BUILTIN_ALIAS && !aliases.hasAlias(prefix)) {
+    push(
+      "DEPRECATION_REPLACEMENT_UNRESOLVED",
+      `'${path}: ${replacedBy}' — alias '${prefix}' is not an import in this file's scope. ` +
+        `Declare the import or correct the alias.`,
+      path,
+    );
+    return;
+  }
+
+  const canonical = aliases.resolveKind(replacedBy);
+  if (!canonical || !registry.resolve(canonical)) {
+    push(
+      "DEPRECATION_REPLACEMENT_UNRESOLVED",
+      `'${path}: ${replacedBy}' does not resolve to a known kind. A replacement a consumer ` +
+        `cannot follow is no better than none.`,
+      path,
+    );
+  }
+}