@telorun/analyzer 0.11.0 → 0.12.0

package/src/schema-compat.ts

@@ -1,16 +1,23 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isTaggedSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
- *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+ *  Also registers the kernel manifest root schema under `telo://manifest` so
+ *  module YAMLs can `$ref` into the shared `$defs/ResourceRef` (and any future
+ *  shared fragments) from this analyzer's AJV without each module having to
+ *  bundle its own copy.
+ *
+ *  Called once for the module-level instance and once per
+ *  DefinitionRegistry instance. */
 export function createAjv(): InstanceType<typeof Ajv> {
   const instance = new Ajv({ allErrors: true, strict: false });
   (addFormats as any).default
     ? (addFormats as any).default(instance)
     : (addFormats as any)(instance);
+  instance.addSchema(ManifestRootSchema);
   return instance;
 }
 
@@ -301,6 +308,16 @@ export function substituteCelFields(
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     return celPlaceholderForSchema(resolved);
   }
+  // `!ref <name>` sentinels are identity markers, not runtime values —
+  // schemas that opt into `$ref: "telo://manifest#/$defs/ResourceRef"`
+  // (or `anyOf` it alongside other shapes) need the actual sentinel
+  // object so AJV validates it against ResourceRefSchema. Collapsing it
+  // to a CEL placeholder would either fail the schema (when the slot
+  // expects the ResourceRef shape) or mask validation errors (when the
+  // slot expects something else entirely).
+  if (isRefSentinel(data)) {
+    return data;
+  }
   if (isTaggedSentinel(data)) {
     return celPlaceholderForSchema(resolved);
   }

package/src/system-kinds.ts

@@ -0,0 +1,37 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+]);
+
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Import",
+]);
+
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Import",
+]);

package/src/types.ts

@@ -81,6 +81,18 @@ export interface LoaderInitOptions {
 
 export interface AnalysisOptions {
   strictContexts?: boolean;
+  /** When true, `analyze()` runs the state-mutating setup (module identity /
+   *  alias / definition registration plus `normalizeInlineResources`) but
+   *  skips every diagnostic-producing pass — per-resource validation, the
+   *  Library `env:` check, `validateExtends`, `validateProviderCoherence`,
+   *  and `validateThrowsCoverage`. Used by the kernel when a previous load
+   *  has already stamped the manifest set as valid (by content hash), so
+   *  the registry still gets populated without paying the validation walk
+   *  on every cold start. The caller takes responsibility for the
+   *  correctness guarantee — pass this only when something durable
+   *  (on-disk stamp) attests that the manifests passed a real analyze
+   *  pass at the same analyzer / kernel version. */
+  skipValidation?: boolean;
 }
 
 /** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does

package/src/validate-cel-context.ts

@@ -119,6 +119,11 @@ export function pathMatchesScope(exprPath: string, scope: string): boolean {
  *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
  *   and returns the `outputType` schema.
  *
+ *   Accepts either a single string or an array of strings. With an array, paths
+ *   are tried in order and the first one that resolves to a usable schema wins —
+ *   used by `result:` to find its dispatch target under whichever entry-point
+ *   field (`provide:` or `invoke:`) the definition declares.
+ *
  * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
  *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
  *
@@ -153,8 +158,16 @@ export function resolveContextAnnotations(
   }
 
   const fromRoot = schema["x-telo-context-from-root"] as string | undefined;
-  const fromRefKind = schema["x-telo-context-from-ref-kind"] as string | undefined;
-  if (fromRoot || fromRefKind) {
+  const fromRefKindRaw = schema["x-telo-context-from-ref-kind"] as
+    | string
+    | string[]
+    | undefined;
+  const fromRefKinds = fromRefKindRaw == null
+    ? []
+    : Array.isArray(fromRefKindRaw)
+      ? fromRefKindRaw
+      : [fromRefKindRaw];
+  if (fromRoot || fromRefKinds.length > 0) {
     if (fromRoot) {
       const resolved = navigatePath(manifestRoot, fromRoot.split("/")) as
         | Record<string, any>
@@ -163,22 +176,22 @@ export function resolveContextAnnotations(
         return resolved;
       }
     }
-    if (fromRefKind && defs) {
-      const hashIdx = fromRefKind.indexOf("#");
-      if (hashIdx > 0) {
+    if (defs) {
+      for (const fromRefKind of fromRefKinds) {
+        const hashIdx = fromRefKind.indexOf("#");
+        if (hashIdx <= 0) continue;
         const refPath = fromRefKind.slice(0, hashIdx);
         const field = fromRefKind.slice(hashIdx + 1);
         const kindValue = navigatePath(manifestRoot, refPath.split("/"));
-        if (typeof kindValue === "string" && kindValue.length > 0) {
-          const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
-          const def = defs.resolve(canonical);
-          const typeField = def
-            ? (def as Record<string, unknown>)[field]
-            : undefined;
-          const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
-          if (resolved && typeof resolved === "object") {
-            return resolved;
-          }
+        if (typeof kindValue !== "string" || kindValue.length === 0) continue;
+        const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
+        const def = defs.resolve(canonical);
+        const typeField = def
+          ? (def as Record<string, unknown>)[field]
+          : undefined;
+        const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
+        if (resolved && typeof resolved === "object") {
+          return resolved;
         }
       }
     }

package/src/validate-provider-coherence.ts

@@ -0,0 +1,166 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Validates coherence rules for `Telo.Definition` documents that use the `provide:`
+ * template target, plus the implementation-presence rule on `Telo.Provider`
+ * definitions.
+ *
+ * Diagnostics:
+ *  - PROVIDE_ON_NON_PROVIDER: `provide:` declared on a definition whose
+ *    `capability` is not `Telo.Provider`.
+ *  - PROVIDE_DISPATCHER_CONFLICT: `provide:` co-exists with `invoke:` or `run:`
+ *    on the same definition.
+ *  - PROVIDE_TARGET_UNKNOWN: `provide.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - PROVIDE_TARGET_NOT_INVOCABLE: `provide.name` resolves to a resource whose
+ *    kind is registered but not a `Telo.Invocable`.
+ *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
+ *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ */
+export function validateProviderCoherence(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  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 m of manifests) {
+    if (m.kind !== "Telo.Definition") continue;
+    const name = m.metadata?.name as string | undefined;
+    if (!name) continue;
+    const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+    if (ownModule && importedModules.has(ownModule)) continue;
+    const filePath = (m.metadata as { source?: string } | undefined)?.source;
+    const resource = { kind: m.kind, name };
+    const label = `${m.kind}/${name}`;
+
+    const md = m as Record<string, unknown>;
+    const capability = typeof md.capability === "string" ? md.capability : undefined;
+    const provide = md.provide;
+    const invoke = md.invoke;
+    const run = md.run;
+    const controllers = md.controllers;
+    const resources = md.resources;
+
+    const hasProvide = provide !== undefined && provide !== null;
+    const hasInvoke = invoke !== undefined && invoke !== null;
+    const hasRun = run !== undefined && run !== null;
+    const hasControllers = Array.isArray(controllers) && controllers.length > 0;
+
+    if (hasProvide && capability !== "Telo.Provider") {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDE_ON_NON_PROVIDER",
+        source: SOURCE,
+        message:
+          `${label}: 'provide:' is only valid on definitions with 'capability: Telo.Provider' ` +
+          `(found '${capability ?? "<unset>"}'). Use 'invoke:' or 'run:' for other capabilities.`,
+        data: { resource, filePath, path: "provide" },
+      });
+    }
+
+    if (hasProvide && (hasInvoke || hasRun)) {
+      const conflict = hasInvoke ? "invoke" : "run";
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDE_DISPATCHER_CONFLICT",
+        source: SOURCE,
+        message:
+          `${label}: 'provide:' cannot co-exist with '${conflict}:'. ` +
+          `A definition declares exactly one dispatch entry-point.`,
+        data: { resource, filePath, path: "provide" },
+      });
+    }
+
+    if (hasProvide && typeof provide === "object" && !Array.isArray(provide)) {
+      const provideObj = provide as { kind?: unknown; name?: unknown };
+      const providedName = typeof provideObj.name === "string" ? provideObj.name : undefined;
+      const providedKind = typeof provideObj.kind === "string" ? provideObj.kind : undefined;
+      if (providedName && Array.isArray(resources)) {
+        const match = resources.find((r) => {
+          const meta = (r as { metadata?: { name?: unknown } })?.metadata;
+          return typeof meta?.name === "string" && meta.name === providedName;
+        }) as { kind?: unknown } | undefined;
+        if (!match) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "PROVIDE_TARGET_UNKNOWN",
+            source: SOURCE,
+            message:
+              `${label}: 'provide.name: ${providedName}' does not match any entry's ` +
+              `metadata.name in 'resources:'.`,
+            data: { resource, filePath, path: "provide.name" },
+          });
+        } else if (typeof match.kind === "string") {
+          // `provide.kind` is the type contract the analyzer uses to type
+          // `result` CEL against the target's `outputType`. The runtime
+          // dispatches on `provide.name` and ignores `provide.kind`, so a
+          // mismatch silently degrades `result` typing to an open schema
+          // (and at runtime quietly invokes the actually-matched resource).
+          // Flag the divergence so result-typing never lies.
+          if (providedKind) {
+            const providedCanonical = aliases.resolveKind(providedKind) ?? providedKind;
+            const matchCanonical = aliases.resolveKind(match.kind) ?? match.kind;
+            if (providedCanonical !== matchCanonical) {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_KIND_MISMATCH",
+                source: SOURCE,
+                message:
+                  `${label}: 'provide.kind: ${providedKind}' disagrees with the matched ` +
+                  `'resources:' entry's kind '${match.kind}' (matched by metadata.name ` +
+                  `'${providedName}'). The runtime dispatches by name, so 'provide.kind' ` +
+                  `is decorative — but the analyzer types 'result:' against it, and a ` +
+                  `mismatch silently turns off that typing.`,
+                data: { resource, filePath, path: "provide.kind" },
+              });
+            }
+          }
+          const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
+          const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
+          if (targetDef && targetDef.kind === "Telo.Definition") {
+            const targetCap = (targetDef as { capability?: unknown }).capability;
+            if (typeof targetCap === "string" && targetCap !== "Telo.Invocable") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "PROVIDE_TARGET_NOT_INVOCABLE",
+                source: SOURCE,
+                message:
+                  `${label}: 'provide.name: ${providedName}' resolves to a ${match.kind} ` +
+                  `(capability '${targetCap}'); 'provide:' requires a Telo.Invocable target.`,
+                data: { resource, filePath, path: "provide.name" },
+              });
+            }
+          }
+        }
+      }
+    }
+
+    if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "PROVIDER_MISSING_IMPLEMENTATION",
+        source: SOURCE,
+        message:
+          `${label}: 'capability: Telo.Provider' requires either 'controllers:' ` +
+          `(TS-backed) or 'provide:' (template-backed) to declare an implementation.`,
+        data: { resource, filePath, path: "capability" },
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/validate-references.ts

@@ -1,17 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
+import { isRefSentinel } from "@telorun/templating";
+import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisContext } from "./types.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
 const SOURCE = "telo-analyzer";
-/** Kinds skipped by reference validation. Telo.Application and Telo.Library
- *  are intentionally not here: Application has `targets` with x-telo-ref that
- *  must be validated, and Library has no ref-bearing fields so flows through
- *  harmlessly. Telo.Import is also not here for the same reason — its
- *  `source` field isn't x-telo-ref, so nothing gets checked. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -76,13 +72,88 @@ export function validateReferences(
   const aliasesByModule = context.aliasesByModule;
   if (!aliases || !registry) return diagnostics;
 
-  // Build outer resource lookup by name for resolution check.
-  // Exclude system kinds (Telo.Definition) — they are type blueprints, not instances,
-  // and their names (e.g. "Server", "Job") would shadow user-defined resource instances.
-  const byName = new Map<string, ResourceManifest>();
+  // 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:
+  //
+  //   1. Some analyzer hosts emit the SAME physical document twice through
+  //      their pipeline — e.g. the telo-editor'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.
+  const byNameAll = new Map<string, ResourceManifest[]>();
+  const seen = new Set<string>();
   for (const r of resources) {
-    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) byName.set(r.metadata.name as string, r);
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import") continue;
+    const name = r.metadata.name as string;
+    // `analyze()` guarantees both fields are present on non-system manifests.
+    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);
+    const existing = byNameAll.get(name);
+    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",
+        },
+      });
+    }
   }
+  // Single-resource map for the resolution / scope lookups below — when a
+  // collision exists, falling back to the first occurrence keeps the rest
+  // of the pass behaving the same as before the duplicate diagnostic was
+  // added (resolution still finds *something*; the duplicate diagnostic
+  // is what surfaces the underlying problem to the user).
+  const byName = new Map<string, ResourceManifest>();
+  for (const [name, list] of byNameAll) byName.set(name, list[0]);
 
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
@@ -142,9 +213,41 @@ export function validateReferences(
         }
       }
 
-      for (const val of resolveFieldValues(r, fieldPath)) {
+      for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
         if (!val) continue;
 
+        // `!ref <name>` sentinel — bare resource name marked at parse time as a
+        // reference. Look it up against the slot's x-telo-ref constraint exactly
+        // like the legacy bare-string path; the only difference is the value's
+        // shape (a TaggedSentinel rather than a raw string), which removed the
+        // string/inline ambiguity at the source.
+        if (isRefSentinel(val)) {
+          const refName = val.source;
+          const target =
+            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+          if (!target) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "UNRESOLVED_REFERENCE",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+            continue;
+          }
+          const kindErrors = checkKind(target.kind as string, entry, registry, aliases);
+          if (kindErrors.length > 0) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "REFERENCE_KIND_MISMATCH",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+          }
+          continue;
+        }
+
         // Name-only reference (plain string) — look up by name to validate.
         // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
         // extract the resource name from the last dot segment.
@@ -166,8 +269,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${fieldPath}' → resource '${val}' not found`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
             continue;
           }
@@ -177,8 +280,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "REFERENCE_KIND_MISMATCH",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
           }
           continue;
@@ -196,8 +299,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "INVALID_REFERENCE",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' must have string 'kind' and 'name' fields`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -209,8 +312,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "REFERENCE_KIND_MISMATCH",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
 
@@ -223,8 +326,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "UNRESOLVED_REFERENCE",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' → resource '${refVal.name}' not found`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
       }
@@ -317,7 +420,7 @@ export function validateReferences(
           continue;
         }
 
-        for (const fieldValue of resolveFieldValues(r, fieldPath)) {
+        for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
           if (fieldValue == null) continue;
           const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
           for (const issue of issues) {
@@ -325,8 +428,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "DEPENDENT_SCHEMA_MISMATCH",
               source: SOURCE,
-              message: `${resourceLabel}: '${fieldPath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
           }
         }
@@ -347,10 +450,10 @@ export function validateReferences(
       const anchorValues = resolveFieldValues(r, anchorPath);
       if (anchorValues.length === 0) continue; // anchor field not set — nothing to validate
 
-      const fieldValues = resolveFieldValues(r, fieldPath);
+      const fieldEntries = resolveFieldEntries(r, fieldPath);
 
-      for (let i = 0; i < fieldValues.length; i++) {
-        const fieldValue = fieldValues[i];
+      for (let i = 0; i < fieldEntries.length; i++) {
+        const { value: fieldValue, path: concretePath } = fieldEntries[i];
         if (fieldValue == null) continue;
 
         // For absolute paths, the single anchor applies to all field values.
@@ -367,8 +470,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "SCHEMA_FROM_MISSING_PATH",
             source: SOURCE,
-            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -379,8 +482,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "SCHEMA_FROM_MISSING_PATH",
             source: SOURCE,
-            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -391,8 +494,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "DEPENDENT_SCHEMA_MISMATCH",
             source: SOURCE,
-            message: `${resourceLabel}: '${fieldPath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: '${concretePath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
       }

package/src/with-synthetic-positions.ts

@@ -0,0 +1,48 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
+
+/**
+ * Stamp `metadata.source` and `metadata.sourceLine` on every non-system
+ * manifest that lacks them, returning a new array with cloned `metadata`
+ * objects for the affected entries.
+ *
+ * `StaticAnalyzer.analyze()` requires position info on every non-system
+ * 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
+ * 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
+ * manifest a synthetic, deterministic position so the analyzer's
+ * invariant holds without each test having to spell positions out.
+ *
+ * The synthetic source defaults to `"<programmatic>"` — override via
+ * `source` when a stable, recognisable label helps diagnostic output.
+ * Each unstamped manifest gets a unique `sourceLine` (1-based array
+ * index) so two real duplicates supplied without positions retain
+ * distinct fingerprints and still trip `DUPLICATE_RESOURCE_NAME`.
+ *
+ * Manifests that already carry `metadata.source` and `metadata.sourceLine`
+ * pass through unchanged.
+ */
+export function withSyntheticPositions(
+  manifests: ResourceManifest[],
+  source: string = "<programmatic>",
+): ResourceManifest[] {
+  return manifests.map((m, i) => {
+    if (REF_VALIDATION_SKIP_KINDS.has(m.kind)) return m;
+    const meta = m.metadata as { source?: string; sourceLine?: number } | undefined;
+    const hasSource = typeof meta?.source === "string" && meta.source.length > 0;
+    const hasLine = typeof meta?.sourceLine === "number";
+    if (hasSource && hasLine) return m;
+    return {
+      ...m,
+      metadata: {
+        ...m.metadata,
+        source: hasSource ? meta!.source : source,
+        sourceLine: hasLine ? meta!.sourceLine : i,
+      },
+    } as ResourceManifest;
+  });
+}