@telorun/analyzer 0.73.0 → 0.74.0

package/src/validate-module-artifact.ts

@@ -4,6 +4,7 @@ import { parseLayerIndex, LayerIndexError } from "./artifact-layer-index.js";
 import {
   ArtifactSelectorError,
   PLATFORM_AXES,
+  selectorContradictions,
   selectorFromQualifiers,
   selectorKey,
 } from "./artifact-selector.js";
@@ -26,10 +27,12 @@ const SOURCE = "telo-analyzer";
  * selector (spec §1), which is what every module with two `js` controllers relies
  * on.
  *
- * 1. **Controller selector qualifiers.** `os` / `arch` / `libc` / `siblings` are
+ * 1. **Controller selector qualifiers.** The platform axes and `siblings` are
  *    authored surface. An unknown qualifier is reported rather than ignored, since
  *    ignoring is what makes a typo invisible; an invalid value is reported here
- *    instead of throwing from the loader later.
+ *    instead of throwing from the loader later, and so is a combination no host
+ *    can match (`selectorContradictions`, shared with `native:` and
+ *    `exports.code:`).
  * 2. **The published layer index.** The owner doc's JSON Schema covers shape; the
  *    semantic rules — controller-requires-selector, singletons carry none, no
  *    duplicate selector, the token grammar (`os: Linux` passes the schema and
@@ -79,6 +82,16 @@ function validateLibraryCandidates(manifest: ResourceManifest, out: AnalysisDiag
   // mean a consumer's import resolves by whichever candidate is read first.
   const seen = new Map<string, LibraryCandidate>();
   for (const candidate of candidates) {
+    for (const contradiction of selectorContradictions(candidate.selector)) {
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: `LIBRARY_${contradiction.rule}`,
+        source: SOURCE,
+        message:
+          `Telo.Library/${metadata?.name ?? "(unnamed)"}: ${candidate.origin}: ${contradiction.detail}`,
+        data: { resource, filePath: metadata?.source, path: "exports/code" },
+      });
+    }
     const key = selectorKey(candidate.selector);
     const first = seen.get(key);
     if (first) {
@@ -162,7 +175,37 @@ function validateControllerSelectors(
     // Validate the selector; the value is not otherwise needed here, since
     // candidates sharing a selector legitimately share a layer.
     try {
-      selectorFromQualifiers(parsed.format, parsed.qualifiers, candidate);
+      const selector = selectorFromQualifiers(parsed.format, parsed.qualifiers, candidate);
+      for (const contradiction of selectorContradictions(selector)) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: `CONTROLLER_${contradiction.rule}`,
+          source: SOURCE,
+          message:
+            `${manifest.kind}/${name ?? "(unnamed)"}: controller candidate "${candidate}": ` +
+            contradiction.detail,
+          data: { resource, filePath, path: `${at}?${contradiction.axis}` },
+        });
+      }
+      // A `dylib` opens over the Rust controller ABI, and a library built
+      // against another version of it must never match — so the candidate states
+      // which, in the `telo` family.
+      if (parsed.format === "dylib" && !selector.abi?.startsWith("telo-")) {
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "CONTROLLER_DYLIB_ABI_MISSING",
+          source: SOURCE,
+          message:
+            `${manifest.kind}/${name ?? "(unnamed)"}: dylib candidate "${candidate}" ` +
+            (selector.abi === undefined
+              ? `states no abi. `
+              : `states abi=${selector.abi}, which is not a Rust controller ABI. `) +
+            `A dylib is built against one version of the Rust controller ABI and must say which — ` +
+            `add abi=telo-<version>, e.g. abi=telo-2. Without it the Rust kernel downloads the ` +
+            `library on every host and refuses it only when it opens it.`,
+          data: { resource, filePath, path: at },
+        });
+      }
     } catch (err) {
       if (!(err instanceof ArtifactSelectorError)) throw err;
       out.push({

package/src/validate-native-entries.ts

@@ -0,0 +1,147 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import { describeSelector, selectorContradictions, selectorKey } from "./artifact-selector.js";
+import { moduleDocumentClaims } from "./module-file-claims.js";
+import { describeClaim, nativeClaimConflicts } from "./module-named-files.js";
+import { readNativeEntries, type NativeEntry } from "./native-entries.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * The strict half of `native-entries.ts`: what `telo check` reports about a
+ * module doc's `native:` block.
+ *
+ * Every rule is decidable from the manifest and would otherwise surface only on
+ * a consumer's host, as a native file that never matches or a layer that
+ * overwrites another's file. Shape errors (a missing key, an unknown one) are
+ * left to the owner doc's JSON Schema, which reports them in the same pass.
+ *
+ * Entry-module-scoped: a dependency's block is not the consumer's to fix.
+ */
+export function validateNativeEntries(
+  manifests: ResourceManifest[],
+  entryModules?: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library") continue;
+    const metadata = (manifest.metadata ?? {}) as Record<string, unknown>;
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const owned =
+      entryModules === undefined ||
+      (typeof metadata.module === "string"
+        ? entryModules.has(metadata.module)
+        : name === undefined || entryModules.has(name));
+    if (!owned) continue;
+
+    const label = `${manifest.kind}/${name ?? "(unnamed)"}`;
+    const report = (code: string, path: string, message: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        data: {
+          resource: { kind: manifest.kind, name },
+          filePath: typeof metadata.source === "string" ? metadata.source : undefined,
+          path,
+        },
+      });
+
+    const { entries, problems } = readNativeEntries(manifest);
+    for (const problem of problems) {
+      if (problem.kind === "shape") continue;
+      report(
+        problem.kind === "escape" ? "NATIVE_PATH_ESCAPES_MODULE" : "NATIVE_ENTRY_INVALID",
+        problem.path,
+        problem.message,
+      );
+    }
+    if (entries.length === 0) continue;
+
+    const moduleName = typeof metadata.module === "string" ? metadata.module : name;
+    for (const { entry, claim } of nativeClaimConflicts(
+      entries,
+      moduleDocumentClaims(manifests, moduleName),
+    )) {
+      report(
+        "NATIVE_PATH_CLAIMED",
+        `native[${entry.index}].path`,
+        `${entry.origin}: path '${entry.path}' is also named by ${describeClaim(claim)}. A native ` +
+          `file ships only in its platform's native layer and a file extracts from exactly one ` +
+          `layer, so publish refuses it — give the native entry its own file, or drop the other ` +
+          `declaration.`,
+      );
+    }
+
+    const bySelector = new Map<string, NativeEntry>();
+    const byPath = new Map<string, NativeEntry>();
+    for (const entry of entries) {
+      const at = `native[${entry.index}]`;
+      if (entry.selector.format === "node" && entry.selector.abi === undefined) {
+        report(
+          "NATIVE_NODE_ABI_MISSING",
+          at,
+          `${entry.origin}: a 'node' addon is built against one Node ABI and must state it — ` +
+            `add abi: node-<NODE_MODULE_VERSION>, e.g. 'node-137'. Without it the file matches ` +
+            `every Node release and fails to load on all but one.`,
+        );
+      }
+      for (const contradiction of selectorContradictions(entry.selector)) {
+        report(
+          `NATIVE_${contradiction.rule}`,
+          `${at}.${contradiction.axis}`,
+          `${entry.origin}: ${contradiction.detail}`,
+        );
+      }
+
+      const key = `${entry.name}\0${selectorKey(entry.selector)}`;
+      const twin = bySelector.get(key);
+      if (twin) {
+        report(
+          "NATIVE_ENTRY_DUPLICATE",
+          at,
+          `${entry.origin}: ${twin.origin} already declares '${entry.name}' for ` +
+            `${describeSelector(entry.selector)}. A name has one entry per platform tuple, or ` +
+            `a lookup by name could resolve to either file.`,
+        );
+      } else {
+        bySelector.set(key, entry);
+      }
+
+      const sharer = byPath.get(entry.path);
+      if (sharer && selectorKey(sharer.selector) !== selectorKey(entry.selector)) {
+        report(
+          "NATIVE_PATH_SHARED",
+          `${at}.path`,
+          `${entry.origin}: path '${entry.path}' is also declared by ${sharer.origin} for ` +
+            `${describeSelector(sharer.selector)}. Every layer of a module extracts into one ` +
+            `directory, so each platform tuple needs its own path — e.g. ` +
+            `'native/<os>-<arch>/…'.`,
+        );
+      } else if (!sharer) {
+        byPath.set(entry.path, entry);
+      }
+
+      const through = [...byPath.values()].find(
+        (other) =>
+          other !== entry &&
+          (entry.path.startsWith(`${other.path}/`) || other.path.startsWith(`${entry.path}/`)),
+      );
+      if (through) {
+        const relation = entry.path.startsWith(`${through.path}/`)
+          ? `runs through '${through.path}' as a directory`
+          : `is a directory that '${through.path}' runs through`;
+        report(
+          "NATIVE_PATH_NESTED",
+          `${at}.path`,
+          `${entry.origin}: path '${entry.path}' ${relation}, and ${through.origin} declares ` +
+            `'${through.path}'. Every layer of a module extracts into one directory, so a path ` +
+            `cannot be both a file and a directory — give each entry its own path.`,
+        );
+      }
+    }
+  }
+  return out;
+}

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-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

@@ -17,6 +17,8 @@ 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";
 
@@ -308,11 +310,10 @@ export function validateReferences(
   // 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>();
@@ -329,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);
@@ -422,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",

package/src/validate-scope-reach.ts

@@ -0,0 +1,213 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { walkCelExpressions } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
+import { definitionInScope } from "./module-alias-scope.js";
+import { isRefEntry, resolveFieldEntries } from "./reference-field-map.js";
+import {
+  declaredScopes,
+  isScopeMember,
+  outsideScopesOf,
+  scopeEncloses,
+  type DeclaredScope,
+  type OutsideScope,
+} from "./scope-declarations.js";
+import { forEachStep, stepBodiesOf } from "./step-bodies.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+const DECLARATION_KINDS = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+]);
+
+/**
+ * `SCOPED_NAME_OUT_OF_REACH` — a declaration written inside a scope's region but
+ * created outside the scope (see {@link OutsideScope}) naming one of the scope's
+ * resources.
+ *
+ * Written there, the name reads as reachable — the scope's names shadow the
+ * module's in its regions — while at run time it resolves to nothing, or to a
+ * module-level resource that merely shares it. Reported at the reference, in
+ * each spelling a name can be read in:
+ *
+ *  - a `!ref` sentinel, anywhere — the tag is unambiguous;
+ *  - a resolved `{kind, name}`, but ONLY where the declaring kind says a
+ *    reference is: a reference slot of its field map, or a step's dispatch slot.
+ *    An object that merely has those keys is data;
+ *  - `resources.<name>` in a CEL expression.
+ *
+ * Lexical: a scope declared on the way from the out-of-reach declaration down to
+ * the reference — found through the kinds' own scope slots — shadows the name
+ * again, since that one IS created around it. Entry-module-scoped: a
+ * dependency's code is its own analysis's to report.
+ *
+ * Browser-safe.
+ */
+export function validateScopedNameReach(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver>,
+  rootModules: ReadonlySet<string>,
+  /** Member-access chains of a CEL expression — the analyzer's own parse. */
+  accessChains: (expression: string) => string[][],
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+
+  for (const root of manifests) {
+    if (!root.kind || DECLARATION_KINDS.has(root.kind) || isForwardedDeclaration(root)) continue;
+    const meta = root.metadata as { name?: unknown; module?: unknown; source?: unknown } | undefined;
+    if (typeof meta?.name !== "string") continue;
+    const module = typeof meta.module === "string" ? meta.module : undefined;
+    if (module && !rootModules.has(module)) continue;
+
+    const resource = { kind: root.kind, name: meta.name };
+    const filePath = typeof meta.source === "string" ? meta.source : undefined;
+    const report = (path: string, name: string, scope: OutsideScope) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "SCOPED_NAME_OUT_OF_REACH",
+        source: SOURCE,
+        message:
+          `${scope.ownerKind}/${scope.ownerName}: '${name}' is declared in '${scope.field}:', but ` +
+          `the inline declaration referencing it is created where '${scope.ownerName}' is ` +
+          `declared, outside that scope, so the reference cannot reach it. Declare the ` +
+          `referencing resource under '${scope.field}:' with a name of its own and point at it ` +
+          `with '!ref'.`,
+        data: { resource, filePath, path },
+      });
+
+    /** A declaration's kind, field map and scopes, read in its module's aliases. */
+    const shape = (declaration: ResourceManifest) => {
+      const view =
+        module !== undefined && typeof declaration.metadata?.module !== "string"
+          ? ({ ...declaration, metadata: { ...declaration.metadata, module } } as ResourceManifest)
+          : declaration;
+      const fieldMap = registry.expandedFieldMapForResource(view, aliases, aliasesByModule);
+      const definition = definitionInScope<ResourceDefinition>(
+        registry,
+        view.kind,
+        view.metadata,
+        aliases,
+        aliasesByModule,
+      );
+      return {
+        fieldMap,
+        scopes: declaredScopes(declaration as Record<string, unknown>, fieldMap),
+        schema: registry.effectiveSchemaOf(definition) as Record<string, any> | undefined,
+      };
+    };
+
+    const check = (
+      declaration: ResourceManifest,
+      prefix: string,
+      reach: ReadonlyMap<string, OutsideScope>,
+      shadowed: ReadonlySet<string>,
+    ): void => {
+      const stamped = outsideScopesOf(declaration);
+      const nextReach = new Map(reach);
+      const nextShadowed = new Set(shadowed);
+      for (const scope of stamped) {
+        for (const name of scope.names) {
+          nextReach.set(name, scope);
+          nextShadowed.delete(name);
+        }
+      }
+      const { fieldMap, scopes, schema } = shape(declaration);
+      for (const scope of scopes) {
+        for (const member of scope.declarations) {
+          if (isScopeMember(member)) nextShadowed.add(member.metadata.name);
+        }
+      }
+
+      const at = (path: string) => (prefix ? (path ? `${prefix}.${path}` : prefix) : path);
+      const test = (name: string | undefined, path: string) => {
+        if (name === undefined || nextShadowed.has(name)) return;
+        const scope = nextReach.get(name);
+        if (scope) report(at(path), name, scope);
+      };
+      const inScopeArray = (path: string) =>
+        scopes.some((scope: DeclaredScope) => scopeEncloses({ ...scope, regions: [scope.path] }, path));
+
+      // Tagged `!ref`s and CEL, anywhere but the declaration's own metadata and
+      // scope arrays (their members are checked below, with their own shadowing).
+      walkCelExpressions(declaration, "", (source, path, engine) => {
+        if (path === "metadata" || path.startsWith("metadata.") || inScopeArray(path)) return;
+        if (engine === "ref") {
+          test(localName(source), path);
+        } else if (engine === "cel") {
+          for (const chain of accessChains(source)) {
+            if (chain[0] === "resources" && chain.length > 1) test(chain[1], path);
+          }
+        }
+      });
+
+      // A resolved reference, where the kind declares one.
+      if (fieldMap) {
+        for (const [fieldPath, entry] of fieldMap) {
+          if (!isRefEntry(entry)) continue;
+          for (const { value, path } of resolveFieldEntries(declaration, fieldPath)) {
+            if (inScopeArray(path)) continue;
+            test(resolvedLocalName(value), path);
+          }
+        }
+      }
+      if (schema) {
+        for (const body of stepBodiesOf(declaration as Record<string, unknown>, schema)) {
+          forEachStep(body, schema, (step, stepPath) =>
+            test(resolvedLocalName(step[body.invokeField]), `${stepPath}.${body.invokeField}`),
+          );
+        }
+      }
+
+      for (const scope of scopes) {
+        scope.declarations.forEach((member, i) => {
+          if (isScopeMember(member)) {
+            check(member, at(`${scope.path}[${i}]`), nextReach, nextShadowed);
+          }
+        });
+      }
+    };
+
+    /** Only a stamped declaration can hold an out-of-reach reference; the rest
+     *  is searched through the scope arrays that can hold one. */
+    const visit = (declaration: ResourceManifest, prefix: string): void => {
+      if (outsideScopesOf(declaration).length > 0) {
+        check(declaration, prefix, new Map(), new Set());
+        return;
+      }
+      for (const scope of shape(declaration).scopes) {
+        scope.declarations.forEach((member, i) => {
+          if (!isScopeMember(member)) return;
+          visit(member, `${prefix ? `${prefix}.` : ""}${scope.path}[${i}]`);
+        });
+      }
+    };
+
+    visit(root, "");
+  }
+
+  return out;
+}
+
+/** The local name a `!ref` source names, or undefined for a cross-module one. */
+function localName(source: string): string | undefined {
+  const dot = source.indexOf(".");
+  if (dot === -1) return source;
+  return source.slice(0, dot) === "Self" ? source.slice(dot + 1) : undefined;
+}
+
+/** The local name a resolved `{kind, name, alias?}` reference names. */
+function resolvedLocalName(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const ref = value as { kind?: unknown; name?: unknown; alias?: unknown };
+  if (typeof ref.kind !== "string" || typeof ref.name !== "string") return undefined;
+  if (typeof ref.alias === "string" && ref.alias !== "Self") return undefined;
+  return ref.name;
+}