@telorun/analyzer 0.71.0 → 0.73.0

package/src/validate-ref-slots.ts

@@ -38,7 +38,9 @@ export interface RefSlotIssue {
     | "X_TELO_REF_MISSING_USE"
     | "X_TELO_REF_MISSING_KIND"
     | "X_TELO_REF_USE_CONFLICT"
-    | "X_TELO_REF_DYNAMIC_SELECTOR";
+    | "X_TELO_REF_DYNAMIC_SELECTOR"
+    | "X_TELO_REF_UNKNOWN_KEY"
+    | "X_TELO_REF_INVALID_THROWS_THROUGH";
   /** The definition (schema issues) or resource (selector issues) at fault. */
   manifest: ResourceManifest;
   /** Schema path of the slot (schema issues) or concrete value path of the
@@ -140,9 +142,47 @@ function checkAnnotation(
     }
   }
 
+  // `throwsThrough` is read as `=== true`, so anything else is silently absent —
+  // and absent means the declaring resource's catch scope stops enclosing what
+  // it holds, so every route under it starts reporting UNCOVERED_THROW_CODE with
+  // nothing naming the cause. The same failure `X_TELO_REF_INVALID_USE` exists
+  // to prevent, one key over.
+  if (obj.throwsThrough !== undefined && typeof obj.throwsThrough !== "boolean") {
+    issues.push({
+      code: "X_TELO_REF_INVALID_THROWS_THROUGH",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares 'throwsThrough: ${JSON.stringify(obj.throwsThrough)}', ` +
+        `which is not a boolean. Only 'true' declares that throws from this slot's target ` +
+        `surface through the declaring resource; anything else reads as absent, which ` +
+        `silently stops its catch list from enclosing what it holds.`,
+    });
+  }
+
+  // Closed, for the reason the token sets are: a misspelled key is indexed by
+  // nothing and read by nothing, so it validates, ships, and does exactly what
+  // omitting it would.
+  for (const key of Object.keys(obj)) {
+    if (REF_ANNOTATION_KEYS.has(key)) continue;
+    issues.push({
+      code: "X_TELO_REF_UNKNOWN_KEY",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares unrecognized key '${key}'. Known keys: ` +
+        `${[...REF_ANNOTATION_KEYS].sort().join(", ")}. An unrecognized key is read by nothing, ` +
+        `so it has exactly the effect of leaving it out.`,
+    });
+  }
+
   return declaredUses(use);
 }
 
+/** Every key the structured `x-telo-ref` form accepts — the write side of
+ *  `readRefSlot`'s read side. Adding one belongs in both. */
+const REF_ANNOTATION_KEYS = new Set(["kind", "use", "inputs", "throwsThrough"]);
+
 /** True when a node is a reference slot: it carries `x-telo-ref` directly or on
  *  an `anyOf`/`oneOf` branch. */
 function carriesRefAnnotation(obj: Record<string, unknown>): boolean {

package/src/validate-references.ts

@@ -15,10 +15,141 @@ import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisContext } fro
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { moduleAliasScope } from "./module-alias-scope.js";
+import { isModuleKind } from "./module-kinds.js";
 import { isInjectedDeclaration } from "./resource-input.js";
 
 const SOURCE = "telo-analyzer";
 
+/** What a name IS on one side of a collision. The three shapes share the
+ *  kernel's one namespace but read as different things to an author — an alias
+ *  is not a resource, and a module's own name is not a declaration inside it —
+ *  so calling all three "resource name" describes two of them wrongly. */
+function describeNamed(m: ResourceManifest, name: string): string {
+  if (m.kind === "Telo.Import") return `import alias '${name}'`;
+  if (isModuleKind(m.kind)) return `this module's own name (${m.kind} '${name}')`;
+  return `resource ${m.kind}/${name}`;
+}
+
+/**
+ * WHAT SHARES A NAME AT THE KERNEL.
+ *
+ * `registerManifest` keys on `metadata.name` alone, per module context, for
+ * EVERY kind — so an import alias, a kind definition and an ordinary resource
+ * are one namespace. This check used to model a narrower one: `Telo.Import` was
+ * excluded outright, on the stated grounds that an alias "lives in a separate
+ * namespace from resources", and `Telo.Definition` / `Telo.Abstract` fell out
+ * through the ref-validation skip set, which answers a different question. All
+ * three passed `telo check` and then died at boot with `ERR_DUPLICATE_RESOURCE`
+ * — an application named after one of its own imports (`metadata.name: Schedule`
+ * beside `Schedule: oci://…/scheduler`) being the shape that reaches an author,
+ * since nothing about the two lines looks like one name written twice.
+ *
+ * Grouped per DECLARING MODULE, which is what makes including imports sound: a
+ * library's own `Telo.Import` / `Telo.Definition` docs are forwarded into a
+ * consumer's flat set, and two modules sharing an alias (`Console` in an app and
+ * again in a library it imports) is ordinary rather than a collision. A module
+ * doc carries no `metadata.module` and IS its own scope — that is what puts an
+ * application's own name in the same group as its imports.
+ *
+ * Kept apart from the resolution lookup it used to share a map with: that one
+ * must hold resolution targets alone, so the two disagree about membership by
+ * design and merging them re-keyed every bare-name reference.
+ */
+function duplicateNameDiagnostics(
+  resources: ResourceManifest[],
+  isForeign: (r: ResourceManifest) => boolean,
+  moduleOf: (r: ResourceManifest) => string | undefined,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  const moduleDocNames = new Set<string>();
+  for (const r of resources) {
+    if (isModuleKind(r.kind) && typeof r.metadata?.name === "string") {
+      moduleDocNames.add(r.metadata.name);
+    }
+  }
+  // A module doc belongs in the scope its OWN resources are in. Flattened, they
+  // carry `metadata.module` equal to its name, so it scopes to itself — which is
+  // what puts an application's name beside its imports. Unflattened (a hand-built
+  // fixture, a single-file editor analysis) nothing is stamped, so its resources
+  // sit in the unnamed scope and the doc has to join them there or a collision
+  // with one of them splits across two groups and goes unreported.
+  const stampedModules = new Set<string>();
+  for (const r of resources) {
+    const m = moduleOf(r);
+    if (m) stampedModules.add(m);
+  }
+
+  // scope → name → declarations, so no separator has to be safe against a name.
+  const byScope = new Map<string, Map<string, ResourceManifest[]>>();
+  const seen = new Set<string>();
+  for (const r of resources) {
+    if (!r.metadata?.name || isForeign(r)) continue;
+    const name = r.metadata.name as string;
+    const scope = isModuleKind(r.kind)
+      ? (stampedModules.has(name) ? name : "")
+      : (moduleOf(r) ?? "");
+    // A scope with no module doc in this set is an imported library's, whose
+    // doc `selectModuleManifestsForAnalysis` drops — its internals are its own
+    // author's to fix, and its own `telo check` reports them.
+    if (scope !== "" && moduleDocNames.size > 0 && !moduleDocNames.has(scope)) continue;
+    // Dedup pipeline echoes — the same physical document emitted twice through
+    // an analyzer host's pipeline (telo studio walks a file reachable as both an
+    // entry module and an `include:` partial). Keyed on (kind, name, source,
+    // sourceLine), so two textually-distinct docs in one file keep separate
+    // fingerprints and still trip the diagnostic.
+    const meta = r.metadata as unknown as { source?: string; sourceLine?: number };
+    const fingerprint = `${r.kind} ${name} ${meta.source} ${meta.sourceLine}`;
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    let names = byScope.get(scope);
+    if (!names) byScope.set(scope, (names = new Map()));
+    const existing = names.get(name);
+    if (existing) existing.push(r);
+    else names.set(name, [r]);
+  }
+
+  for (const names of byScope.values()) {
+    for (const [name, list] of names) {
+      if (list.length <= 1) continue;
+      const [first, ...rest] = list;
+      for (const dup of rest) {
+        // Two imports sharing an alias is ONE defect with its own diagnostic
+        // (`DUPLICATE_IMPORT_ALIAS`), which says what to do about it; reporting
+        // it again here would describe one mistake as two.
+        if (dup.kind === "Telo.Import" && first.kind === "Telo.Import") continue;
+        const dupMeta = dup.metadata as { source?: string; sourceLine?: number } | undefined;
+        // The precomputed range matters because editor hosts resolve positions
+        // via a `${file}::${kind}::${name}` lookup, which collides on duplicates.
+        const range =
+          typeof dupMeta?.sourceLine === "number"
+            ? {
+                start: { line: dupMeta.sourceLine, character: 0 },
+                end: { line: dupMeta.sourceLine, character: Number.MAX_SAFE_INTEGER },
+              }
+            : undefined;
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "DUPLICATE_RESOURCE_NAME",
+          source: SOURCE,
+          message:
+            `${dup.kind}/${name}: ${describeNamed(dup, name)} collides with ` +
+            `${describeNamed(first, name)} declared earlier — the kernel registers both ` +
+            `under '${name}' in one namespace, so boot fails with ERR_DUPLICATE_RESOURCE. ` +
+            `Rename one of them.`,
+          ...(range ? { range } : {}),
+          data: {
+            resource: { kind: dup.kind, name },
+            filePath: dupMeta?.source,
+            path: "metadata.name",
+          },
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+
 /**
  * Liskov substitutability at a kind constraint: is `resolved` (a canonical
  * `<module>.<Kind>`) accepted where `targetKind` is required?
@@ -162,40 +293,16 @@ export function validateReferences(
   const aliasesByModule = context.aliasesByModule;
   if (!aliases || !registry) return diagnostics;
 
-  // Build outer resource lookup by name for resolution check, collecting
-  // every entry per name so we can surface name collisions as diagnostics
-  // (the kernel's resource registry shares one namespace across all
-  // non-system kinds — e.g. `Telo.Application HelloApi` and `Http.Api
-  // HelloApi` collide at boot with `ERR_DUPLICATE_RESOURCE`. Catching it
-  // statically removes a class of "everything analyzes clean, then the
-  // kernel refuses to start" surprises.)
-  //
-  // Telo.Import is excluded from the duplicate check on top of the
-  // SYSTEM_KINDS skip: its `metadata.name` is an alias, not a resource
-  // identity (aliases live in a separate namespace from resources, and
-  // colliding aliases vs. resource names is benign — the alias is only
-  // ever read as a kind prefix).
-  // Group manifests by name to detect collisions. Two subtleties:
+  // Build the outer resource lookup by name, for the resolution checks below.
+  // WHICH NAMES COLLIDE is a different question over a different namespace and
+  // is answered by `duplicateNameDiagnostics`; this map answers only "what does
+  // a bare `!ref <name>` resolve to", so it holds resolution TARGETS alone — an
+  // import alias and a kind definition are neither, and admitting them here
+  // would resolve a reference to something no ref slot can accept.
   //
-  //   1. Some analyzer hosts emit the SAME physical document twice through
-  //      their pipeline — e.g. telo studio's `toAnalysisManifests` walks
-  //      each workspace module's documents independently, and a file
-  //      reachable from two angles (entry module + `include:` partial)
-  //      shows up twice. The fingerprint includes `sourceLine` so identical
-  //      docs (same kind, name, source, AND source line) collapse to one,
-  //      while two textually-separate documents in the same file (different
-  //      source lines) keep separate fingerprints and trip the diagnostic.
-  //   2. The diagnostic carries a precomputed `range` pointing at the
-  //      duplicate's source line — editor hosts that resolve diagnostic
-  //      positions via a `${file}::${kind}::${name}` lookup would otherwise
-  //      collide on duplicates (Map.set overwrites) and place the squiggle
-  //      ambiguously. The explicit `range` short-circuits that lookup.
-  // Dedup pipeline echoes — the same physical document emitted twice
-  // through an analyzer host's pipeline. Keyed on (kind, name, source,
-  // sourceLine), so two textually-distinct docs in the same file (same
-  // source, different sourceLine) keep separate fingerprints and still
-  // trip the diagnostic. `analyze()` enforces that every non-system
-  // manifest carries both positional fields — no defensive guard needed.
+  // The list per name survives because resolution falls back to the FIRST
+  // occurrence when a collision exists, which keeps the rest of the pass
+  // behaving as it did before duplicates were reported at all.
   // Forwarded foreign exports (an imported library's exported instances, carrying a
   // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
   // duplicate detection and local name resolution, and never walked as ref sources.
@@ -246,33 +353,7 @@ export function validateReferences(
     if (existing) existing.push(r);
     else byNameAll.set(name, [r]);
   }
-  for (const [name, list] of byNameAll) {
-    if (list.length <= 1) continue;
-    const [first, ...rest] = list;
-    const firstLabel = `${first.kind}/${name}`;
-    for (const dup of rest) {
-      const dupMeta = dup.metadata as { source?: string; sourceLine?: number } | undefined;
-      const range =
-        typeof dupMeta?.sourceLine === "number"
-          ? {
-              start: { line: dupMeta.sourceLine, character: 0 },
-              end: { line: dupMeta.sourceLine, character: Number.MAX_SAFE_INTEGER },
-            }
-          : undefined;
-      diagnostics.push({
-        severity: DiagnosticSeverity.Error,
-        code: "DUPLICATE_RESOURCE_NAME",
-        source: SOURCE,
-        message: `${dup.kind}/${name}: resource name collides with ${firstLabel} declared earlier (kernel runtime would fail with ERR_DUPLICATE_RESOURCE)`,
-        ...(range ? { range } : {}),
-        data: {
-          resource: { kind: dup.kind, name },
-          filePath: dupMeta?.source,
-          path: "metadata.name",
-        },
-      });
-    }
-  }
+  diagnostics.push(...duplicateNameDiagnostics(resources, isForeign, moduleOf));
   // The dot rule that used to live here is now the strictest special case of
   // the identifier grammar in `validate-identifier-names.ts` — a dot is one of
   // several characters that make a name unreferenceable, and checking one of
@@ -562,14 +643,44 @@ export function validateReferences(
 
           for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
             if (fieldValue == null) continue;
-            const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
+            // CEL leaves become schema-shaped placeholders first, exactly as the
+            // sibling-ref branch below does and for the same reason: a slot
+            // anchored at a shared value-shape is overwhelmingly written as
+            // expressions, so validating it raw reports every one of them as a
+            // type error and the check fires only on the literal case nobody
+            // writes. Omitting it here made one annotation mean two different
+            // things depending on which branch resolved it — a `when:` typed
+            // `boolean` accepted a `!cel` at a route's inline slot and rejected
+            // the identical expression at a slot anchored on the carrier that
+            // declares that very shape.
+            const substituted = substituteCelFields(
+              fieldValue,
+              subSchema as Record<string, any>,
+            );
+            // Anchored at the offending node INSIDE the value, not at the slot:
+            // a `returns:` list is an array of entries, and reporting every one
+            // of its issues on the `returns:` line puts three diagnostics on one
+            // line and none on the entry that is wrong.
+            const issues = registry.validateResourceConfig(
+              substituted,
+              subSchema as Record<string, any>,
+            );
             for (const issue of issues) {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
                 code: "DEPENDENT_SCHEMA_MISMATCH",
                 source: SOURCE,
-                message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-                data: { resource: resourceData, filePath, path: concretePath },
+                message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue.message}`,
+                data: {
+                  resource: resourceData,
+                  filePath,
+                  // An index-first sub-path (`[0].content`) joins with no dot.
+                  path: !issue.path
+                    ? concretePath
+                    : issue.path.startsWith("[")
+                      ? `${concretePath}${issue.path}`
+                      : `${concretePath}.${issue.path}`,
+                },
               });
             }
           }

package/src/validate-template-body.ts

@@ -0,0 +1,274 @@
+import { nearestName } from "./nearest-name.js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import type { AliasResolver, ModuleScopes } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { refSentinelTarget } from "./ref-sentinel-target.js";
+import { isRefEntry, resolveFieldEntries, satisfiesValueBranch } from "./reference-field-map.js";
+import { templateBodies } from "./template-body.js";
+import { DiagnosticSeverity, DiagnosticTag, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** The four slots a `Telo.Definition` names its dispatch target in.
+ *
+ *  WHAT THE TARGET'S CAPABILITY IS IS DELIBERATELY NOT CHECKED. The kernel tests
+ *  METHOD PRESENCE at dispatch (`entry.instance?.invoke`), so a declared
+ *  capability says nothing about whether a dispatch works — the same structural
+ *  -versus-nominal split that keeps `use` uncross-constrained against a slot's
+ *  target. A check here read `Run.Sequence`'s `capability: Telo.Runnable` and
+ *  rejected `Ai.Buffered`, a shipping module whose sequence implements `invoke()`
+ *  over an inputs/outputs contract and dispatches correctly. Trimming the refused
+ *  set would only move that: any controller may expose a method its capability
+ *  does not name, and a template body is exactly where that is done on purpose. */
+const DISPATCH_SLOTS = ["invoke", "run", "provide", "mount"] as const;
+
+/**
+ * A TEMPLATE BODY IS WRITTEN LIKE EVERY OTHER MANIFEST, AND CHECKED LIKE ONE.
+ *
+ * A `Telo.Definition` is in both reference skip sets — its body holds
+ * declarations of OTHER kinds, and its dispatch slots carry no `x-telo-ref` — so
+ * no reference pass reached it, and each rule about it was added per construct:
+ * `provide:` and `mount:` had a target check for the `{ kind, name }` object
+ * form, `!ref` had one that switched itself off for any definition with a
+ * CEL-named entry, and `invoke:` / `run:` had none. What was tagged was caught
+ * and what was a plain name was resolved by the kernel alone. This pass is the
+ * one reader of a body's reference surface, and it rests on one spelling:
+ *
+ *  - every `resources:` entry is named by a LITERAL (`TEMPLATE_ENTRY_NAME_DYNAMIC`).
+ *    Each instance of a template owns its children in a child context of its
+ *    own, so a per-instance suffix (`self.name + '-query'`) buys nothing — and a
+ *    `!ref` is looked up verbatim, so a CEL-named sibling is one nothing can name;
+ *  - a dispatch slot is `!ref <entry>` naming an entry
+ *    (`TEMPLATE_DISPATCH_UNKNOWN`); the legacy spellings are deprecated rather
+ *    than refused, since published artifacts carry them. What the target's
+ *    CAPABILITY is stays unchecked — see `DISPATCH_SLOTS`;
+ *  - a reference slot INSIDE an entry follows the rule every other slot does —
+ *    `!ref` or an inline declaration, never `{ kind, name }` or a bare string
+ *    (`INVALID_REFERENCE_FORM`) — and a bare `!ref` names a sibling or a
+ *    resource of the defining module (`TEMPLATE_REF_UNKNOWN`). Slots are found
+ *    through the nested kind's own field map, resolved in the DEFINING module's
+ *    alias scope, since that is where the body's kinds are written.
+ *
+ * Entry-module-scoped, like every other declaration check: a published
+ * dependency's template body is not the consumer's to fix. Browser-safe.
+ */
+export function validateTemplateBody(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver>,
+  rootModules: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  const scopes: ModuleScopes = { aliasesByModule, rootModules };
+
+  // A definition forwarded from an imported library is that library's to fix;
+  // the imports name them (the `validate-extends` rule).
+  const importedModules = new Set<string>();
+  // Every named instance, by declaring module — what a body's bare `!ref` may
+  // reach beside its siblings. A manifest with no stamp belongs to the entry.
+  const instancesByModule = new Map<string | undefined, Set<string>>();
+  for (const m of manifests) {
+    const name = m.metadata?.name;
+    if (typeof name !== "string") continue;
+    if (m.kind === "Telo.Import") {
+      const resolved = (m.metadata as { resolvedModuleName?: string }).resolvedModuleName;
+      if (resolved) importedModules.add(resolved);
+      continue;
+    }
+    if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") continue;
+    if (m.kind === "Telo.Library" || m.kind === "Telo.Application") continue;
+    const mod = (m.metadata as { module?: string } | undefined)?.module;
+    let set = instancesByModule.get(mod);
+    if (!set) instancesByModule.set(mod, (set = new Set()));
+    set.add(name);
+  }
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const meta = m.metadata as { name?: string; module?: string; source?: string } | undefined;
+    const name = meta?.name;
+    if (!name) continue;
+    if (meta?.module && importedModules.has(meta.module)) continue;
+
+    const bodies = (m as Record<string, unknown>).resources;
+    const resourceRef = { kind: m.kind, name };
+    const filePath = meta?.source;
+    const label = `${m.kind}/${name}`;
+    const report = (code: string, path: string, message: string, fix?: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        data: {
+          resource: resourceRef,
+          filePath,
+          path,
+          ...(fix ? { fix: { replacement: fix } } : {}),
+        },
+      });
+
+    /** A spelling the kernel still READS. Warning-grade because refusing it
+     *  would break every app pinning a version that carries it, and tagged so an
+     *  editor strikes it through rather than merely colouring it — the
+     *  `DEPRECATED_KIND` shape, for the same reason. */
+    const deprecate = (code: string, path: string, message: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Warning,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        tags: [DiagnosticTag.Deprecated],
+        data: { resource: resourceRef, filePath, path },
+      });
+
+    const entries = Array.isArray(bodies) ? bodies : [];
+    const siblings: string[] = [];
+    let anyDynamic = false;
+    entries.forEach((entry, i) => {
+      const entryName = (entry as { metadata?: { name?: unknown } } | undefined)?.metadata?.name;
+      if (typeof entryName === "string" && !entryName.includes("${{")) {
+        siblings.push(entryName);
+        return;
+      }
+      if (entryName === undefined) return;
+      anyDynamic = true;
+      deprecate(
+        "DEPRECATED_TEMPLATE_ENTRY_NAME",
+        `resources[${i}].metadata.name`,
+        `a 'resources:' entry named by ${describeDynamic(entryName)} is deprecated — name it ` +
+          `with a literal and dispatch to it with '!ref'. Each instance of a template owns its ` +
+          `children in a child context of its own, so a per-instance suffix buys nothing, and a ` +
+          `'!ref' is looked up verbatim, so nothing can name a computed entry. While one is ` +
+          `present the target checks below are switched off for this kind.`,
+      );
+    });
+
+    // Siblings PLUS the declaring module's own resources, because that is what
+    // the runtime resolves at a reference slot: a body's `!ref` is stamped
+    // `{kind, name}` with an empty kind for a non-sibling, and Phase-5 injection
+    // dispatches by NAME and recovers the kind from the instance it finds — so
+    // `client: !ref moduleClient` in a body reaches the module-level client and
+    // works. (A step's `invoke:` is a different path that does NOT: see the
+    // `resources` note in `validate-template-body`'s own tests.)
+    const reachable = new Set([
+      ...siblings,
+      ...(instancesByModule.get(meta?.module) ?? []),
+    ]);
+
+    // --- dispatch slots ---
+    for (const slot of DISPATCH_SLOTS) {
+      const value = (m as Record<string, unknown>)[slot];
+      if (value == null) continue;
+      if (!isRefSentinel(value)) {
+        deprecate(
+          "DEPRECATED_TEMPLATE_DISPATCH_FORM",
+          slot,
+          `'${slot}:' written as ${describeDispatchValue(value)} is deprecated — ` +
+            `write '!ref <entry>', the spelling every other reference uses. ` +
+            `Available: ${siblings.join(", ") || "(none)"}.`,
+        );
+        continue;
+      }
+      const source = value.source;
+      const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
+      if (siblings.includes(target)) continue;
+      // A dynamic sibling has already been reported, and might be the one
+      // meant — a second diagnostic about the same line would be noise.
+      if (anyDynamic) continue;
+      const suggestion = nearestName(target, siblings);
+      report(
+        "TEMPLATE_DISPATCH_UNKNOWN",
+        slot,
+        `'${slot}: !ref ${source}' names no entry in 'resources:'. ` +
+          `Available: ${siblings.join(", ") || "(none)"}.` +
+          (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+        suggestion,
+      );
+    }
+
+    // --- reference slots inside each entry ---
+    for (const body of templateBodies(m, registry, aliases, scopes)) {
+      const kind = body.manifest.kind;
+      const fieldMap = registry.expandedFieldMapForResource(
+        { ...body.manifest, metadata: { ...(body.manifest.metadata ?? {}), module: meta?.module } },
+        aliases,
+        aliasesByModule,
+      );
+      if (!fieldMap) continue;
+      for (const [fieldPath, entry] of fieldMap) {
+        if (!isRefEntry(entry)) continue;
+        for (const site of resolveFieldEntries(body.manifest, fieldPath)) {
+          const value = site.value;
+          if (value == null) continue;
+          const path = `${body.prefix}.${site.path}`;
+          if (isTaggedSentinel(value)) {
+            const target = refSentinelTarget(value);
+            if (!target) continue;
+            const { alias, name: refName } = target;
+            if (alias && alias !== "Self") continue;
+            if (reachable.has(refName)) continue;
+            const suggestion = nearestName(refName, [...reachable]);
+            report(
+              "TEMPLATE_REF_UNKNOWN",
+              path,
+              `'${site.path}: !ref ${value.source}' on the ${kind} entry names no sibling ` +
+                `'resources:' entry and no resource of this module. ` +
+                `Siblings: ${siblings.filter((s) => s !== body.manifest.metadata?.name).join(", ") || "(none)"}.` +
+                (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+              suggestion,
+            );
+            continue;
+          }
+          const hasValueBranch = (entry.valueBranches?.length ?? 0) > 0;
+          if (hasValueBranch && typeof value !== "object") continue;
+          if (satisfiesValueBranch(value, entry.valueBranches, registry)) continue;
+          if (typeof value === "string") {
+            if (value.includes("${{")) continue;
+            report(
+              "INVALID_REFERENCE_FORM",
+              path,
+              `string reference at '${site.path}' on the ${kind} entry → '${value}' is not ` +
+                `supported; write it as '!ref ${value}'`,
+            );
+            continue;
+          }
+          if (value && typeof value === "object" && !Array.isArray(value)) {
+            const obj = value as Record<string, unknown>;
+            if (typeof obj.kind === "string" && obj.name !== undefined) {
+              report(
+                "INVALID_REFERENCE_FORM",
+                path,
+                `object reference '{ kind, name }' at '${site.path}' on the ${kind} entry is ` +
+                  `not supported; write it as '!ref ${describeRefName(obj.name)}'`,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+function describeDynamic(name: unknown): string {
+  if (isTaggedSentinel(name)) return `the expression '${name.source}'`;
+  if (typeof name === "string") return `the template '${name}'`;
+  return `a ${typeof name}`;
+}
+
+function describeDispatchValue(value: unknown): string {
+  if (isTaggedSentinel(value)) return `a '!${value.engine}' expression`;
+  if (typeof value === "string") return `the string '${value}'`;
+  if (value && typeof value === "object" && "name" in value) return "the '{ kind, name }' object form";
+  return `a ${typeof value}`;
+}
+
+function describeRefName(name: unknown): string {
+  if (typeof name === "string") return name;
+  if (isTaggedSentinel(name)) return "<entry>";
+  return String(name);
+}