@telorun/analyzer 0.65.0 → 0.67.0

package/src/validate-resource-inputs.ts

@@ -0,0 +1,367 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { findDynamicLeaf } from "./resource-rule.js";
+import { readResourceInputs, readSuppliedResources } from "./resource-input.js";
+import { type AnalysisDiagnostic, DiagnosticSeverity } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** A target library's declared `resources:` block, canonicalized in that
+ *  library's own alias scope and stamped onto the `Telo.Import` by
+ *  `stampRequiredResources`: entry name → canonical kind. */
+type RequiredResources = Record<string, string>;
+
+/**
+ * The strict half of {@link readResourceInputs} — the `validate-ref-slots.ts`
+ * split applied to the resource-input boundary, and not optional for the same
+ * reason: the two sides fail in OPPOSITE directions. An unreadable DECLARATION
+ * leaves the library referencing a name nothing stands behind; an unchecked
+ * INJECTION hands a library an instance of a kind it never asked for, which
+ * surfaces as a method-missing failure inside someone else's module.
+ *
+ * Two surfaces, scoped the same way every other declaration check is — to the
+ * entry's own modules, since a published dependency's block is not the
+ * consumer's to fix:
+ *
+ *  - **The library's own declaration.** Each entry's alias-qualified `kind:` must
+ *    resolve in the DECLARING module's scope (`RESOURCE_INPUT_KIND_UNRESOLVED`).
+ *    A constraint that resolves to nothing accepts anything, which is the same
+ *    hole `X_TELO_REF_UNRESOLVED` exists to close one level down.
+ *  - **The injection site.** Every declared entry must be supplied
+ *    (`RESOURCE_INPUT_MISSING` — the same failure as a missing required
+ *    variable), nothing beyond them may be (`RESOURCE_INPUT_UNKNOWN`), the value
+ *    must name a resource that exists (`RESOURCE_INPUT_UNRESOLVED`), and its
+ *    kind must satisfy the declared constraint transitively
+ *    (`RESOURCE_INPUT_KIND_MISMATCH`).
+ *
+ * Browser-safe.
+ */
+export function validateResourceInputs(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  rootModules: Set<string>,
+  /** Kind acceptance, transitively — the `checkKind` rule `validate-references`
+   *  applies at an ordinary ref slot, passed in rather than re-derived so the
+   *  two cannot disagree about what satisfies a constraint. */
+  acceptsKind: (suppliedKind: string, requiredKind: string) => boolean,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  const isOwn = (module: string | undefined): boolean => !module || rootModules.has(module);
+
+  // --- the library's own declaration -------------------------------------
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Library") continue;
+    const moduleName = m.metadata?.name as string | undefined;
+    // Only the entry's own modules, so the declaring scope is always the root
+    // alias table — a library analyzed here IS a root module.
+    if (!isOwn(moduleName)) continue;
+    const scope = aliases;
+    const exported = new Set(
+      (((m as Record<string, any>).exports?.resources ?? []) as unknown[]).filter(
+        (e): e is string => typeof e === "string",
+      ),
+    );
+    for (const input of readResourceInputs(m)) {
+      // An input is the IMPORTER's instance, borrowed. Exporting it back out
+      // would forward a kind-only stand-in into the consumer's flattened set as
+      // a resource this library declares — a phantom the consumer can `!ref`
+      // and whose kind constraint is all there is behind it. Handing an
+      // instance straight back to whoever supplied it is also a relation
+      // nothing needs; if it ever does, it should be a decision rather than a
+      // name collision nobody noticed.
+      if (exported.has(input.name)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_EXPORTED",
+          source: SOURCE,
+          message:
+            `Resource input '${input.name}' is also listed in 'exports.resources'. An input is ` +
+            `an instance the importer supplies, not one this library declares, so there is ` +
+            `nothing to export — remove it from 'exports.resources', or rename the input.`,
+          data: {
+            resource: { kind: m.kind, name: moduleName as string },
+            filePath: (m.metadata as { source?: string } | undefined)?.source,
+            path: `resources.${input.name}`,
+          },
+        });
+      }
+      if (registry.resolve(input.kind) ?? registry.resolve(scope.resolveKind(input.kind) ?? "")) {
+        continue;
+      }
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "RESOURCE_INPUT_KIND_UNRESOLVED",
+        source: SOURCE,
+        message:
+          `Resource input '${input.name}' is constrained to kind '${input.kind}', which does not ` +
+          `resolve in this library's scope. Write it alias-qualified — '<Alias>.<Kind>' for an ` +
+          `import declared in this file, 'Self.<Kind>' for a kind this library owns, or ` +
+          `'Telo.<Kind>' for a built-in. An unresolvable constraint accepts anything.`,
+        data: {
+          resource: { kind: m.kind, name: moduleName as string },
+          filePath: (m.metadata as { source?: string } | undefined)?.source,
+          path: `resources.${input.name}.kind`,
+        },
+      });
+    }
+  }
+
+  // --- the injection site --------------------------------------------------
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const meta = m.metadata as
+      | {
+          name?: string;
+          module?: string;
+          source?: string;
+          resolvedModuleName?: string;
+          requiredResources?: RequiredResources;
+          sharedLibrary?: boolean;
+          resolvedSource?: string;
+        }
+      | undefined;
+    const alias = meta?.name;
+    if (!alias || !isOwn(meta?.module)) continue;
+    // An import whose target identity was never established registers nothing —
+    // reporting a missing input against it would blame the author for a
+    // dependency the loader has already said it could not obtain.
+    if (!meta?.resolvedModuleName) continue;
+
+    // A singleton has no room for a per-import override: `logging:` scopes a
+    // subtree that is no longer this import's subtree, and `runtime:` selects a
+    // controller backend for a library that is instantiated once. Whichever
+    // import happened to be created first would decide, so the field is
+    // rejected rather than silently applied to everyone or silently dropped.
+    if (meta.sharedLibrary === true) {
+      for (const field of ["logging", "runtime"] as const) {
+        if ((m as Record<string, unknown>)[field] === undefined) continue;
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "SHARED_LIBRARY_OVERRIDE",
+          source: SOURCE,
+          message:
+            `Import '${alias}' declares '${field}:', but module ` +
+            `'${meta.resolvedModuleName}' is 'lifecycle: shared' — one instantiation for the ` +
+            `whole application, so a per-import override cannot apply to it. Remove it, or ` +
+            `make the library 'lifecycle: isolated'.`,
+          data: {
+            resource: { kind: m.kind, name: alias },
+            filePath: meta.source,
+            path: field,
+          },
+        });
+      }
+    }
+
+    const required = Object.entries(meta.requiredResources ?? {});
+    const supplied = readSuppliedResources(m);
+    const declared = new Map(required);
+    const resource = { kind: m.kind, name: alias };
+    const filePath = meta.source;
+
+    for (const [entryName, entryKind] of required) {
+      if (entryName in supplied) continue;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "RESOURCE_INPUT_MISSING",
+        source: SOURCE,
+        message:
+          `Import '${alias}' does not supply the resource input '${entryName}', which module ` +
+          `'${meta.resolvedModuleName}' requires (kind '${entryKind}'). Add ` +
+          `\`resources: { ${entryName}: !ref <name> }\` to the import.`,
+        data: { resource, filePath, path: "resources" },
+      });
+    }
+
+    for (const [name, value] of Object.entries(supplied)) {
+      const path = `resources.${name}`;
+      const entry = declared.get(name);
+      if (!entry) {
+        const known = required.map(([n]) => n).join(", ") || "(none)";
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_UNKNOWN",
+          source: SOURCE,
+          message:
+            `Import '${alias}' supplies a resource input '${name}', which module ` +
+            `'${meta.resolvedModuleName}' does not declare. Declared inputs: ${known}.`,
+          data: { resource, filePath, path },
+        });
+        continue;
+      }
+      // Phase 2.5 rewrote a resolvable `!ref` to `{kind, name}`; a sentinel that
+      // survived names nothing the importer can reach.
+      if (isRefSentinel(value)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_UNRESOLVED",
+          source: SOURCE,
+          message: `Import '${alias}': resource input '${name}' → resource '${value.source}' not found`,
+          data: { resource, filePath, path },
+        });
+        continue;
+      }
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "RESOURCE_INPUT_UNRESOLVED",
+          source: SOURCE,
+          message:
+            `Import '${alias}': resource input '${name}' must be a '!ref' to a resource this ` +
+            `module declares.`,
+          data: { resource, filePath, path },
+        });
+        continue;
+      }
+      const suppliedKind = (value as { kind?: unknown }).kind;
+      if (typeof suppliedKind !== "string") continue;
+      const canonical = aliases.resolveKind(suppliedKind) ?? suppliedKind;
+      if (acceptsKind(canonical, entry)) continue;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "RESOURCE_INPUT_KIND_MISMATCH",
+        source: SOURCE,
+        message:
+          `Import '${alias}': resource input '${name}' is '${suppliedKind}' (resolved: ` +
+          `'${canonical}'), which does not satisfy the declared constraint '${entry}'.`,
+        data: { resource, filePath, path },
+      });
+    }
+  }
+
+  out.push(...sharedLibraryConflicts(manifests, isOwn));
+
+  return out;
+}
+
+/** One import's supplied configuration, as the conflict check compares it. */
+interface SuppliedConfig {
+  readonly alias: string;
+  readonly module: string | undefined;
+  readonly filePath: string | undefined;
+  readonly blocks: ReadonlyMap<string, Record<string, unknown>>;
+}
+
+const SUPPLIED_BLOCKS = ["variables", "secrets", "resources"] as const;
+
+/**
+ * Two imports of ONE `lifecycle: shared` library supplying different values.
+ *
+ * The runtime half (`ERR_SHARED_LIBRARY_CONFLICT`) is authoritative — it holds
+ * resolved values and live instances, and a library reached through a
+ * programmatic load never passed `telo check`. But the overwhelmingly common
+ * shape is two literal scalars in one flattened manifest set, which is decidable
+ * here, and a conflict is a hard BOOT failure: finding it at `telo check` is the
+ * difference between a squiggle and a deployment that will not start.
+ *
+ * Only what is DECIDABLE is compared, and the two ways it is not are skipped
+ * rather than guessed:
+ *
+ *  - A value holding a `!cel` (at any depth) is known only at load. Two
+ *    different expressions may evaluate equal, and identical text in two
+ *    different modules may not.
+ *  - A `resources:` entry names a resource by name, which means the same
+ *    instance only when both imports were DECLARED in the same module — so a
+ *    cross-module pair is left to the runtime.
+ *
+ * Grouped by the target's RESOLVED SOURCE, the identity the kernel keys its
+ * singleton registry on; `resolvedModuleName` would collapse two versions of one
+ * module, which are two libraries.
+ */
+function sharedLibraryConflicts(
+  manifests: ResourceManifest[],
+  isOwn: (module: string | undefined) => boolean,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  const byTarget = new Map<string, SuppliedConfig[]>();
+
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Import") continue;
+    const meta = m.metadata as
+      | { name?: string; module?: string; source?: string; sharedLibrary?: boolean; resolvedSource?: string }
+      | undefined;
+    if (meta?.sharedLibrary !== true || !meta.name || !meta.resolvedSource) continue;
+    const blocks = new Map<string, Record<string, unknown>>();
+    for (const block of SUPPLIED_BLOCKS) {
+      const value = (m as Record<string, unknown>)[block];
+      blocks.set(
+        block,
+        value && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : {},
+      );
+    }
+    const bucket = byTarget.get(meta.resolvedSource);
+    const entry: SuppliedConfig = {
+      alias: meta.name,
+      module: meta.module,
+      filePath: meta.source,
+      blocks,
+    };
+    if (bucket) bucket.push(entry);
+    else byTarget.set(meta.resolvedSource, [entry]);
+  }
+
+  for (const group of byTarget.values()) {
+    if (group.length < 2) continue;
+    const [first, ...rest] = group;
+    for (const later of rest) {
+      for (const block of SUPPLIED_BLOCKS) {
+        // A reference means the same instance only within one module's scope.
+        if (block === "resources" && first!.module !== later.module) continue;
+        const a = first!.blocks.get(block)!;
+        const b = later.blocks.get(block)!;
+        for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+          if (findDynamicLeaf(a[key]) || findDynamicLeaf(b[key])) continue;
+          if (sameSuppliedValue(a[key], b[key])) continue;
+          out.push({
+            severity: DiagnosticSeverity.Error,
+            code: "SHARED_LIBRARY_CONFLICT",
+            source: SOURCE,
+            message:
+              `Import '${later.alias}' and import '${first!.alias}' both reach a ` +
+              `'lifecycle: shared' library — one instantiation for the whole application — but ` +
+              `they supply different values for ${block}.${key}. Make the two imports agree, or ` +
+              `make the library 'lifecycle: isolated'.`,
+            data: isOwn(later.module)
+              ? {
+                  resource: { kind: "Telo.Import", name: later.alias },
+                  filePath: later.filePath,
+                  path: `${block}.${key}`,
+                }
+              : {
+                  resource: { kind: "Telo.Import", name: first!.alias },
+                  filePath: first!.filePath,
+                  path: `${block}.${key}`,
+                },
+          });
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Structural equality, key-order insensitive — the analyzer's half of the rule
+ *  the kernel applies to resolved values. A secret's VALUE is compared but never
+ *  printed: the key is what the author has to look at. */
+function sameSuppliedValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => sameSuppliedValue(item, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const left = a as Record<string, unknown>;
+    const right = b as Record<string, unknown>;
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    return [...keys].every((key) => sameSuppliedValue(left[key], right[key]));
+  }
+  return false;
+}

package/src/validate-resource-rules.ts

@@ -22,11 +22,18 @@
  * Browser-safe: no Node built-ins.
  */
 import type { ResourceManifest } from "@telorun/sdk";
-import { RULE_BUDGET_MS, compileRuleCondition, conditionRefusals } from "./rule-condition.js";
+import {
+  RULE_BUDGET_MS,
+  UNTAGGED_CONDITION,
+  compileRuleCondition,
+  conditionRefusals,
+} from "./rule-condition.js";
 import {
   RESOURCE_RULES_ANNOTATION,
   celSourceOf,
   findDynamicLeaf,
+  type DynamicLeaf,
+  isTaggedCondition,
   pointerSegments,
   readRawResourceRules,
   readResourceRules,
@@ -54,7 +61,7 @@ export type ResourceRuleFinding =
       path: string;
       message: string;
     }
-  | { kind: "skipped"; rule: ResourceRule; path: string; dynamicAt: string }
+  | { kind: "skipped"; rule: ResourceRule; path: string; dynamic: DynamicLeaf }
   | { kind: "failed"; rule: ResourceRule; path: string; reason: string }
   | { kind: "over-budget"; rule: ResourceRule; path: string; elapsedMs: number };
 
@@ -63,8 +70,11 @@ function isObject(value: unknown): value is Record<string, unknown> {
 }
 
 /** Navigate a kind's own schema to the node describing what a pointer names, so
- *  an `in:` naming a field the kind does not declare is caught at the kind. */
-function schemaAtPointer(schema: unknown, pointer: string): unknown {
+ *  an `in:` naming a field the kind does not declare is caught at the kind.
+ *  Exported because the peer-rule strict half asks the same question of the
+ *  REFERRER's schema, and two navigators would eventually disagree about what a
+ *  pointer names. */
+export function schemaAtPointer(schema: unknown, pointer: string): unknown {
   const segments = pointerSegments(pointer);
   if (!segments) return undefined;
   let node: unknown = schema;
@@ -83,7 +93,7 @@ function schemaAtPointer(schema: unknown, pointer: string): unknown {
 
 /** True when a schema node describes something a rule can iterate. Unknown or
  *  absent `type` passes: an open schema is not evidence of a defect. */
-function isIterableSchema(node: unknown): boolean {
+export function isIterableSchema(node: unknown): boolean {
   if (!isObject(node)) return true;
   const type = node.type;
   if (type === undefined) return true;
@@ -198,6 +208,10 @@ export function validateResourceRuleDeclarations(
       }
     }
 
+    if (condition !== undefined && condition.length > 0 && !isTaggedCondition(entry.condition)) {
+      issue(`${at}.condition`, UNTAGGED_CONDITION);
+    }
+
     if (condition) {
       for (const refusal of conditionRefusals(condition)) issue(`${at}.condition`, refusal);
     }
@@ -243,13 +257,13 @@ export function evaluateResourceRules(
       // Only the nodes this condition READS decide whether it can run — see
       // `readNodes`. Scanning the whole subject would disable every
       // resource-wide rule on any manifest containing one unrelated expression.
-      let dynamicAt: string | undefined;
+      let dynamic: DynamicLeaf | undefined;
       for (const node of readNodes(chains, { self, this: subject.value })) {
-        dynamicAt = findDynamicLeaf(node);
-        if (dynamicAt !== undefined) break;
+        dynamic = findDynamicLeaf(node);
+        if (dynamic !== undefined) break;
       }
-      if (dynamicAt !== undefined) {
-        findings.push({ kind: "skipped", rule, path: subject.path, dynamicAt });
+      if (dynamic !== undefined) {
+        findings.push({ kind: "skipped", rule, path: subject.path, dynamic });
         continue;
       }
       let held: unknown;
@@ -347,8 +361,8 @@ export function reportResourceRules(
         severity: "information",
         message:
           `${manifest.kind}/${name}: rule '${finding.rule.code}' did not run` +
-          `${at ? ` at '${at}'` : ""} — the value holds a CEL expression at ` +
-          `'${finding.dynamicAt}', which is not known until the resource is created. ` +
+          `${at ? ` at '${at}'` : ""} — the value holds ${finding.dynamic.what} at ` +
+          `'${finding.dynamic.path}', which is not known until the resource is created. ` +
           "Reported rather than dropped: a check whose coverage varies invisibly reads as passing.",
         manifest,
         path: at,

package/src/validate-schema-projection.ts

@@ -26,6 +26,7 @@ import {
   projectionKeyMap,
   rawSchemaProjection,
   readSchemaProjection,
+  schemaMapBranch,
   schemaProjectionIsMisplaced,
 } from "./schema-projection.js";
 
@@ -118,6 +119,48 @@ export function validateSchemaProjection(manifest: ResourceManifest): SchemaProj
     ];
   }
 
+  const reference = raw.reference;
+  if (reference !== undefined) {
+    if (!isObject(reference)) {
+      issues.push(
+        issue(
+          "SCHEMA_PROJECTION_INVALID",
+          `${base}.reference`,
+          `'reference' says how an entry whose '${projection.key}' holds a REFERENCE projects. ` +
+            `It is an object naming 'from' (the target field to read), 'keyword' (the schema ` +
+            `keyword its values become) and one of 'base' / 'baseFrom'.`,
+        ),
+      );
+    } else {
+      const absent = ["from", "keyword"].filter((f) => typeof reference[f] !== "string");
+      if (absent.length > 0) {
+        issues.push(
+          issue(
+            "SCHEMA_PROJECTION_INVALID",
+            `${base}.reference`,
+            `'reference' is missing ${absent.map((f) => `'${f}'`).join(" and ")}. Without them a ` +
+              `referenced entry projects to nothing, so it vanishes from every consumer's view.`,
+          ),
+        );
+      }
+      const bases = ["base", "baseFrom"].filter((f) => reference[f] !== undefined);
+      if (bases.length !== 1) {
+        issues.push(
+          issue(
+            "SCHEMA_PROJECTION_INVALID",
+            `${base}.reference`,
+            bases.length === 0
+              ? `'reference' declares neither 'base' nor 'baseFrom', so the projected node has no ` +
+                `type. Write 'base' where the named type IS its own base type, or 'baseFrom' ` +
+                `naming the target field that holds a value of this kind's own map.`
+              : `'reference' declares both 'base' and 'baseFrom'. They are two answers to one ` +
+                `question — where the projected node's type comes from — so declare exactly one.`,
+          ),
+        );
+      }
+    }
+  }
+
   const map = projectionKeyMap(schema, projection);
   if (!map) {
     return [
@@ -180,5 +223,11 @@ function keySchema(
       : undefined;
   if (!isObject(entry) || !isObject(entry.properties)) return undefined;
   const field = entry.properties[key];
-  return isObject(field) ? field : undefined;
+  if (!isObject(field)) return undefined;
+  // The vocabulary may sit on a BRANCH — a slot unioning a closed value set with
+  // a reference — and the branch carrying the map is the one whose `enum` the map
+  // has to answer for. Reading the union node instead finds no `enum` at all, so
+  // the completeness check would silently stop running exactly where the two
+  // halves can disagree. Asked through the single reader, never re-derived here.
+  return schemaMapBranch(field) ?? field;
 }

package/src/validate-template-dispatch.ts

@@ -0,0 +1,99 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
+import { distance } from "./levenshtein.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** The four slots a `Telo.Definition` names its dispatch target in. Each takes
+ *  the same grammar; which one is legal for a given capability is
+ *  `validate-provider-coherence`'s question, not this one's. */
+const DISPATCH_FIELDS = ["invoke", "run", "provide", "mount"] as const;
+
+/**
+ * A `!ref` at a definition's dispatch slot must name a sibling `resources:`
+ * entry.
+ *
+ * `!ref` is the one spelling an author — and the editor's rename, completion and
+ * go-to-definition — expects to be RESOLVED. But a `Telo.Definition` is in both
+ * `REF_VALIDATION_SKIP_KINDS` and `REF_RESOLUTION_SKIP_KINDS`, and the dispatch
+ * slots carry no `x-telo-ref` (the accepted targets are the definition's own
+ * template-internal entries, not resources of any module), so no reference pass
+ * reaches them. Introducing the tag at a slot nothing resolves would be worse
+ * than the string form it replaces: a typo that used to be an obvious runtime
+ * miss becomes a typo in a construct that advertises static resolution.
+ *
+ * Decidable only when every sibling name is LITERAL. A template routinely names
+ * its entries with CEL (`name: !cel "self.name + '-query'"`), and an expression
+ * could expand to the referenced name — so one dynamic sibling switches the
+ * check off for that definition rather than inventing a miss.
+ *
+ * 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 validateTemplateDispatch(
+  manifests: ResourceManifest[],
+  rootModules: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  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 && !rootModules.has(meta.module)) continue;
+
+    const bodies = (m as Record<string, unknown>).resources;
+    if (!Array.isArray(bodies)) continue;
+
+    const siblings: string[] = [];
+    let anyDynamic = false;
+    for (const entry of bodies) {
+      const entryName = (entry as { metadata?: { name?: unknown } } | undefined)?.metadata?.name;
+      if (typeof entryName === "string" && !entryName.includes("${{")) siblings.push(entryName);
+      else if (entryName !== undefined) anyDynamic = true;
+    }
+    if (anyDynamic) continue;
+
+    for (const field of DISPATCH_FIELDS) {
+      const value = (m as Record<string, unknown>)[field];
+      if (!isRefSentinel(value)) continue;
+      const source = value.source;
+      const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
+      if (siblings.includes(target)) continue;
+      const suggestion = nearest(target, siblings);
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "TEMPLATE_DISPATCH_UNKNOWN",
+        source: SOURCE,
+        message:
+          `${m.kind}/${name}: '${field}: !ref ${source}' names no entry in 'resources:'. ` +
+          `Available: ${siblings.join(", ") || "(none)"}.` +
+          (suggestion ? ` Did you mean '${suggestion}'?` : ""),
+        data: {
+          resource: { kind: m.kind, name },
+          filePath: meta?.source,
+          path: field,
+          ...(suggestion ? { fix: { replacement: suggestion } } : {}),
+        },
+      });
+    }
+  }
+
+  return out;
+}
+
+/** The closest sibling name, when one is close enough to be a typo rather than a
+ *  different name. */
+function nearest(target: string, candidates: readonly string[]): string | undefined {
+  let best: { name: string; d: number } | undefined;
+  for (const candidate of candidates) {
+    const d = distance(target, candidate);
+    if (!best || d < best.d) best = { name: candidate, d };
+  }
+  const limit = Math.max(1, Math.floor(target.length / 3));
+  return best && best.d <= limit ? best.name : undefined;
+}

package/src/with-synthetic-positions.ts

@@ -10,7 +10,7 @@ import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
  * manifest (the dedup that backs `DUPLICATE_RESOURCE_NAME` reads
  * `(source, sourceLine)` to distinguish pipeline echoes from real
  * collisions). Production callers — the `Loader`, `flattenForAnalyzer`,
- * the telo-editor's `emitDocsFor`, the VSCode extension — all stamp
+ * telo studio's `emitDocsFor`, the VSCode extension — all stamp
  * positions already. This helper is the escape hatch for **programmatic
  * callers** (tests, ad-hoc scripts) that construct `ResourceManifest`
  * literals without going through a loader: it gives every otherwise-naked