@telorun/analyzer 0.72.0 → 0.74.0

package/src/validate-observed-state.ts

@@ -1,6 +1,7 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { OBSERVED_STATE_KEY } from "@telorun/sdk";
 import { effectiveStatusSchema } from "./extends-resolution.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 import { parseExportEntry } from "./flatten-for-analyzer.js";
 import {
   moduleScopedDefResolver,
@@ -129,11 +130,20 @@ export function collectRunReachableNames(graph: CallGraph): Set<string> {
 
 /** What a resource name resolves to for CEL purposes. `status` is present only
  *  when the kind declares one; `scoped` marks a resource declared inside an
- *  `x-telo-scope` slot, which resolves only within that scope's regions. */
+ *  `x-telo-scope` slot, which resolves only within that scope's regions.
+ *  `forwardedFrom` marks a dependency's declaration, keyed by
+ *  `forwardedResourceKey`: it is in no consumer's `resources`, but a read inside
+ *  that dependency's own manifests still resolves to it. */
 export interface AnalyzedResource {
   kind: string;
   status?: Record<string, any>;
   scoped?: boolean;
+  forwardedFrom?: string;
+}
+
+/** The index key of a name a dependency declares, as read from inside it. */
+export function forwardedResourceKey(module: string, name: string): string {
+  return `${module}\0${name}`;
 }
 
 /**
@@ -157,16 +167,35 @@ export function buildObservedStateIndex(
   /** `module` is the resource's DECLARING module: an exported instance is
    *  written with that library's aliases (`kind: Self.Listener`), which the
    *  consumer's table cannot resolve. */
-  const record = (kind: string, key: string, scoped: boolean, module?: string): void => {
+  const record = (
+    kind: string,
+    key: string,
+    scoped: boolean,
+    module?: string,
+    forwardedFrom?: string,
+  ): void => {
     const status = effectiveStatusSchema(resolve.in(kind, module), resolve);
-    out.set(key, { kind, ...(status ? { status } : {}), ...(scoped ? { scoped } : {}) });
+    out.set(key, {
+      kind,
+      ...(status ? { status } : {}),
+      ...(scoped ? { scoped } : {}),
+      ...(forwardedFrom !== undefined ? { forwardedFrom } : {}),
+    });
   };
 
   for (const manifest of manifests) {
     const kind = manifest.kind as string | undefined;
     const name = manifest.metadata?.name as string | undefined;
     if (!kind || SYSTEM_KINDS.has(kind)) continue;
-    if (name) record(kind, name, false, manifest.metadata?.module as string | undefined);
+    const module = manifest.metadata?.module as string | undefined;
+    // A dependency's declarations publish into ITS module's `resources`, not this
+    // one's: they are keyed by that module, and an export is also indexed under
+    // `<Alias>.<name>` below.
+    const forwardedFrom = isForwardedDeclaration(manifest) ? module : undefined;
+    if (forwardedFrom === undefined && isForwardedDeclaration(manifest)) continue;
+    const keyOf = (n: string) =>
+      forwardedFrom === undefined ? n : forwardedResourceKey(forwardedFrom, n);
+    if (name) record(kind, keyOf(name), false, module, forwardedFrom);
 
     const schema = resolve(kind)?.schema as Record<string, any> | undefined;
     if (!schema) continue;
@@ -177,7 +206,7 @@ export function buildObservedStateIndex(
           const scopedKind = (scopedEntry as ResourceManifest)?.kind;
           const scopedName = (scopedEntry as ResourceManifest)?.metadata?.name;
           if (typeof scopedKind === "string" && typeof scopedName === "string") {
-            record(scopedKind, scopedName, true);
+            record(scopedKind, keyOf(scopedName), true, forwardedFrom, forwardedFrom);
           }
         }
       }
@@ -254,8 +283,8 @@ export function buildObservedStateResourcesSchema(
   open: boolean,
 ): Record<string, any> {
   const properties: Record<string, any> = {};
-  for (const [key, { status }] of index) {
-    if (!status) continue;
+  for (const [key, { status, forwardedFrom }] of index) {
+    if (!status || forwardedFrom !== undefined) continue;
     applyObservedStateNode(properties, key, status);
   }
   return open

package/src/validate-provider-coherence.ts

@@ -1,7 +1,11 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
-import { controllerBearingAncestor, type DefResolver } from "./extends-resolution.js";
+import {
+  controllerBearingAncestor,
+  inheritedCapability,
+  type DefResolver,
+} from "./extends-resolution.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -16,20 +20,16 @@ const SOURCE = "telo-analyzer";
  *    `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).
  *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
  *    not `Telo.Mount`.
  *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
  *    entry-point (`invoke:` / `run:` / `provide:`).
- *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
- *    `resources:`.
- *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
- *    is registered but not a `Telo.Mount`.
+ *
+ * What a dispatch slot NAMES — that it is a `!ref`, that the entry exists, that
+ * its capability carries the method — is `validate-template-body`'s, for every
+ * slot alike.
  */
 export function validateProviderCoherence(
   manifests: ResourceManifest[],
@@ -57,13 +57,19 @@ export function validateProviderCoherence(
     const label = `${m.kind}/${name}`;
 
     const md = m as Record<string, unknown>;
-    const capability = typeof md.capability === "string" ? md.capability : undefined;
+    const resolveDef: DefResolver = (k) =>
+      registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
+    // The INHERITED capability, not the declared one: an `extends` child writes
+    // none of its own, so reading `md.capability` reported a child that inherits
+    // `Telo.Provider` and declares `provide:` as PROVIDE_ON_NON_PROVIDER
+    // "(found '<unset>')" — the same defect `celRuleApplies` and
+    // `validate-template-body` were fixed for, in the file next door.
+    const capability = inheritedCapability(m as ResourceDefinition, resolveDef);
     const provide = md.provide;
     const invoke = md.invoke;
     const run = md.run;
     const mount = md.mount;
     const controllers = md.controllers;
-    const resources = md.resources;
 
     const hasProvide = provide !== undefined && provide !== null;
     const hasInvoke = invoke !== undefined && invoke !== null;
@@ -96,70 +102,6 @@ export function validateProviderCoherence(
       });
     }
 
-    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 (hasMount && capability !== "Telo.Mount") {
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
@@ -185,61 +127,9 @@ export function validateProviderCoherence(
       });
     }
 
-    if (hasMount) {
-      // Resolve the target's name from either form: the bare string (the
-      // primary, documented form — `mount: api`) or the object's `name`. A CEL
-      // target (`${{ … }}`) can only be checked at runtime, so skip those.
-      let mountedName: string | undefined;
-      if (typeof mount === "string") {
-        if (!mount.includes("${{")) mountedName = mount;
-      } else if (typeof mount === "object" && !Array.isArray(mount)) {
-        const mountObj = mount as { name?: unknown };
-        if (typeof mountObj.name === "string" && !mountObj.name.includes("${{")) {
-          mountedName = mountObj.name;
-        }
-      }
-      const mountPath = typeof mount === "string" ? "mount" : "mount.name";
-      if (mountedName && Array.isArray(resources)) {
-        const match = resources.find((r) => {
-          const meta = (r as { metadata?: { name?: unknown } })?.metadata;
-          return typeof meta?.name === "string" && meta.name === mountedName;
-        }) as { kind?: unknown } | undefined;
-        if (!match) {
-          diagnostics.push({
-            severity: DiagnosticSeverity.Error,
-            code: "MOUNT_TARGET_UNKNOWN",
-            source: SOURCE,
-            message:
-              `${label}: '${mountPath}: ${mountedName}' does not match any entry's ` +
-              `metadata.name in 'resources:'.`,
-            data: { resource, filePath, path: mountPath },
-          });
-        } else if (typeof match.kind === "string") {
-          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.Mount") {
-              diagnostics.push({
-                severity: DiagnosticSeverity.Error,
-                code: "MOUNT_TARGET_NOT_MOUNTABLE",
-                source: SOURCE,
-                message:
-                  `${label}: '${mountPath}: ${mountedName}' resolves to a ${match.kind} ` +
-                  `(capability '${targetCap}'); 'mount:' requires a Telo.Mount target.`,
-                data: { resource, filePath, path: mountPath },
-              });
-            }
-          }
-        }
-      }
-    }
-
     // A definition that inherits a controller by delegation (concrete `extends`,
     // no own controller/template) satisfies the implementation requirement
     // through its parent — `base:` supplies the parent's config.
-    const resolveDef: DefResolver = (k) =>
-      registry.resolve(aliases.resolveKind(k) ?? k) ?? registry.resolve(k);
     const inheritsController =
       typeof md.extends === "string" &&
       controllerBearingAncestor(m as ResourceDefinition, resolveDef) !== undefined;

package/src/validate-reference-forms.ts

@@ -2,6 +2,7 @@ import type { ResourceManifest } from "@telorun/sdk";
 import { isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 import { visitManifest } from "./manifest-visitor.js";
 import { satisfiesValueBranch } from "./reference-field-map.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
@@ -50,9 +51,7 @@ export function validateReferenceForms(
   if (!aliases) return [];
   const diagnostics: AnalysisDiagnostic[] = [];
 
-  const isForeign = (r: ResourceManifest): boolean =>
-    (r.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true;
-  const localResources = resources.filter((r) => !isForeign(r));
+  const localResources = resources.filter((r) => !isForwardedDeclaration(r));
 
   visitManifest(
     localResources,

package/src/validate-references.ts

@@ -15,10 +15,143 @@ 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";
+import { outsideScopesOf } from "./scope-declarations.js";
+import { isForwardedDeclaration, isForwardedExport } from "./forwarded-declaration.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,50 +295,25 @@ 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.)
+  // 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.
   //
-  // 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. 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.
   const moduleOf = (r: ResourceManifest): string | undefined =>
     (r.metadata as { module?: string } | undefined)?.module;
-  // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
-  // cross-module resolution targets only — excluded from duplicate detection and local name
-  // resolution, and never walked as ref sources.
-  const isForeign = (r: ResourceManifest): boolean =>
-    (r.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true;
+  // A dependency's code — a forwarded export, or what extraction pulled out of one — is
+  // excluded from duplicate detection and local name resolution, and never walked as a
+  // ref source. Only an EXPORT is a cross-module resolution target.
+  const isForeign = isForwardedDeclaration;
   // Forwarded exported instances keyed `${module}\0${name}` — the lookup that resolves
   // whether a cross-module `!ref Alias.name` names a real exported instance.
   const byModuleName = new Map<string, ResourceManifest>();
@@ -222,7 +330,7 @@ export function validateReferences(
       if (typeof m === "string") loadedModules.add(m);
       continue;
     }
-    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r)) continue;
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForwardedExport(r)) continue;
     const m = moduleOf(r);
     if (!m) continue;
     byModuleName.set(`${m}\0${r.metadata.name as string}`, r);
@@ -246,33 +354,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
@@ -341,6 +423,9 @@ export function validateReferences(
             visibleScopeManifests.find((m) => m.metadata?.name === localName) ??
             byName.get(localName);
           if (!target) {
+            // A scoped name out of this declaration's reach has its own
+            // diagnostic, which says why; this one would say only "not found".
+            if (outsideScopesOf(r).some((scope) => scope.names.includes(localName))) return;
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",