@telorun/analyzer 0.22.0 → 0.23.1

package/src/flatten-for-analyzer.ts

@@ -1,7 +1,26 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import type { LoadedFile, LoadedGraph, LoadedModule } from "./loaded-types.js";
+import type { LoadedGraph, LoadedModule } from "./loaded-types.js";
+import type { LoadedFile } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
 
+/** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
+ *  instance name or kind suffix (the part after the dot, or the whole entry); `alias`
+ *  (when set) is this library's own import the entry RE-EXPORTS from. */
+export interface ParsedExportEntry {
+  name: string;
+  alias?: string;
+}
+
+/** Parse a single dotted export entry: `Alias.Name` → `{name: "Name", alias: "Alias"}`,
+ *  bare `Name` → `{name: "Name"}`. The single grammar for `exports.resources` and
+ *  `exports.kinds`, shared by the kernel's import controller and the analyzer/editor so
+ *  the dotted-name split can't drift. A leading dot (`.Name`) has no alias by design —
+ *  the empty prefix isn't a valid alias. */
+export function parseExportEntry(entry: string): ParsedExportEntry {
+  const dot = entry.indexOf(".");
+  return dot > 0 ? { name: entry.slice(dot + 1), alias: entry.slice(0, dot) } : { name: entry };
+}
+
 /** The import-boundary forwarding rule, shared by `flattenForAnalyzer` (the
  *  CLI / kernel loader path) and the telo-editor's workspace projection so the
  *  two cannot drift. Given one module's stamped manifests and whether that
@@ -29,9 +48,14 @@ export function selectModuleManifestsForAnalysis(
   if (isRoot) return moduleManifests;
 
   const libDoc = moduleManifests.find((m) => isModuleKind(m.kind));
-  const exportedResources = new Set<string>(
-    (libDoc as { exports?: { resources?: string[] } } | undefined)?.exports?.resources ?? [],
-  );
+  // An `exports.resources` entry is a bare name or a dotted `Alias.Name` (re-export). Only the
+  // export NAME matches a local instance below; re-exports are forwarded by `forwardReExports`.
+  const exportedResources = new Set<string>();
+  for (const entry of (libDoc as { exports?: { resources?: unknown[] } } | undefined)?.exports
+    ?.resources ?? []) {
+    if (typeof entry !== "string") continue;
+    exportedResources.add(parseExportEntry(entry).name);
+  }
 
   const out: ResourceManifest[] = [];
   for (const m of moduleManifests) {
@@ -96,6 +120,8 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
     }
   }
 
+  forwardReExports(graph, result);
+
   // Stamp resolved import identity on every Telo.Import in the result by
   // reading the edge's pre-resolved name/namespace — no re-derivation from
   // manifest metadata. The edge is keyed by (owner-file, alias) which is
@@ -120,6 +146,193 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
   return result;
 }
 
+/** A re-export declared in a library's `exports.resources` as a dotted `Alias.Name`:
+ *  module `module` re-exports the instance `name` reached through its own import
+ *  aliased `alias`. */
+export interface ReExportSpec {
+  module: string;
+  alias: string;
+  name: string;
+}
+
+/** Extract re-export specs from a library doc's `exports.resources` — the dotted `Alias.Name`
+ *  entries (bare-name locals are forwarded by the BFS instead). Shared by the CLI graph path
+ *  and the editor's workspace projection so the two cannot drift. */
+export function reExportSpecsFromExports(
+  moduleName: string,
+  exportsResources: readonly unknown[] | undefined,
+): ReExportSpec[] {
+  const specs: ReExportSpec[] = [];
+  for (const entry of exportsResources ?? []) {
+    if (typeof entry !== "string") continue;
+    const { name, alias } = parseExportEntry(entry);
+    if (!alias || alias === "Self") continue;
+    specs.push({ module: moduleName, alias, name });
+  }
+  return specs;
+}
+
+/** Forward re-exported instances (`exports.resources: [!ref Alias.name]`) transitively so a
+ *  consumer's `!ref Consumer.name` resolves in `resolveRefSentinels` (keyed by the RE-EXPORTING
+ *  module). The owning instance is already forwarded under its own module; here we emit an
+ *  additional copy stamped under each re-exporting module, with an already-canonical kind. A
+ *  fixpoint loop forwards chains of arbitrary depth (`app → api → domain → …`): each pass can
+ *  resolve a re-export whose source was emitted in a prior pass. Graph-agnostic: `aliasToModule`
+ *  maps `(module, alias)` to the imported module's name. Mutates `result` in place. */
+export function forwardReExportManifests(
+  result: ResourceManifest[],
+  specs: readonly ReExportSpec[],
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): void {
+  // Index forwarded instances by `module\0name` (only re-export TARGETS are forwarded).
+  const forwarded = new Map<string, ResourceManifest>();
+  for (const m of result) {
+    const meta = m.metadata as { module?: string; name?: string; forwardedExport?: boolean };
+    if (meta?.forwardedExport && meta.module && meta.name) {
+      forwarded.set(`${meta.module}\0${meta.name}`, m);
+    }
+  }
+
+  // Canonicalize an authored/forwarded kind to a scope-independent `<module>.<Kind>` using the
+  // owning module's own import aliases. Idempotent: an already-canonical kind whose prefix isn't
+  // an alias of `ownerModule` is returned unchanged, so re-exports of re-exports stay stable.
+  const canonicalKind = (kind: string, ownerModule: string): string => {
+    if (kind.startsWith("Self.")) return `${ownerModule}.${kind.slice("Self.".length)}`;
+    const dot = kind.indexOf(".");
+    if (dot <= 0) return kind;
+    const target = aliasToModule(ownerModule, kind.slice(0, dot));
+    return target ? `${target}.${kind.slice(dot + 1)}` : kind;
+  };
+
+  // Fixpoint — bounded by the number of specs (each can be satisfied at most once).
+  for (let pass = 0; pass <= specs.length; pass++) {
+    let added = false;
+    for (const spec of specs) {
+      const key = `${spec.module}\0${spec.name}`;
+      if (forwarded.has(key)) continue;
+      const sourceModule = aliasToModule(spec.module, spec.alias);
+      if (!sourceModule) continue;
+      const src = forwarded.get(`${sourceModule}\0${spec.name}`);
+      if (!src) continue; // source not forwarded yet — a later pass may satisfy it
+      const kind = canonicalKind(src.kind as string, sourceModule);
+      const manifest: ResourceManifest = {
+        ...src,
+        kind,
+        metadata: {
+          ...src.metadata,
+          name: spec.name,
+          module: spec.module,
+          forwardedExport: true,
+        } as ResourceManifest["metadata"],
+      };
+      result.push(manifest);
+      forwarded.set(key, manifest);
+      added = true;
+    }
+    if (!added) break;
+  }
+}
+
+/** Resolve every library's `exports.kinds` to a per-module map `suffix → canonical
+ *  <owningModule>.<Kind>`, following re-exports (`Alias.Kind`) transitively via a fixpoint.
+ *  `modules` lists each library's name + its raw `exports.kinds`; `aliasToModule(module, alias)`
+ *  maps one of that module's import aliases to the imported module's name. Graph-agnostic —
+ *  shared by the CLI graph path and the editor's workspace projection. */
+export function resolveExportedKinds(
+  modules: ReadonlyArray<{ module: string; exportsKinds: readonly string[] }>,
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): Map<string, Map<string, string>> {
+  const out = new Map<string, Map<string, string>>();
+  const tableFor = (m: string): Map<string, string> => {
+    let t = out.get(m);
+    if (!t) out.set(m, (t = new Map()));
+    return t;
+  };
+  for (let pass = 0; pass <= modules.length; pass++) {
+    let changed = false;
+    for (const { module, exportsKinds } of modules) {
+      const table = tableFor(module);
+      for (const entry of exportsKinds) {
+        const { name: suffix, alias } = parseExportEntry(entry);
+        if (table.has(suffix)) continue;
+        if (!alias) {
+          table.set(suffix, `${module}.${suffix}`);
+          changed = true;
+          continue;
+        }
+        const source = aliasToModule(module, alias);
+        const canonical = source ? out.get(source)?.get(suffix) : undefined;
+        if (canonical) {
+          table.set(suffix, canonical);
+          changed = true;
+        }
+      }
+    }
+    if (!changed) break;
+  }
+  return out;
+}
+
+/** Stamp `metadata.reExportedKinds` (suffix → canonical kind) onto every `Telo.Import` whose
+ *  target re-exports kinds, so the analyzer can register the re-export mappings. Only entries
+ *  that point at a module OTHER than the import's own target are stamped (genuine re-exports;
+ *  a locally-defined kind resolves through the normal alias path). Stamped on `metadata` (which
+ *  permits additional properties, like `resolvedModuleName`) since the `Telo.Import` schema
+ *  forbids extra top-level fields. Shared by both paths. */
+export function stampReExportedKinds(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetModule: string }>,
+  exportedKinds: Map<string, Map<string, string>>,
+): void {
+  for (const { manifest, targetModule } of imports) {
+    const table = exportedKinds.get(targetModule);
+    if (!table) continue;
+    const reExported: Record<string, string> = {};
+    for (const [suffix, canonical] of table) {
+      if (canonical !== `${targetModule}.${suffix}`) reExported[suffix] = canonical;
+    }
+    if (Object.keys(reExported).length === 0) continue;
+    (manifest.metadata as Record<string, unknown>).reExportedKinds = reExported;
+  }
+}
+
+/** CLI/kernel adapter: collect re-export specs + alias map from a LoadedGraph. */
+function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void {
+  const ownerSourceOf = new Map<string, string>();
+  const specs: ReExportSpec[] = [];
+  const kindModules: Array<{ module: string; exportsKinds: string[] }> = [];
+  for (const [source, mod] of graph.modules) {
+    if (source === graph.rootSource) continue; // root is an Application — no exports
+    const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as
+      | (ResourceManifest & { exports?: { resources?: unknown[]; kinds?: string[] } })
+      | undefined;
+    const moduleName = libDoc?.metadata?.name as string | undefined;
+    if (!libDoc || !moduleName) continue;
+    ownerSourceOf.set(moduleName, mod.owner.source);
+    specs.push(...reExportSpecsFromExports(moduleName, libDoc.exports?.resources));
+    kindModules.push({ module: moduleName, exportsKinds: libDoc.exports?.kinds ?? [] });
+  }
+  const aliasToModule = (module: string, alias: string): string | undefined => {
+    const ownerSource = ownerSourceOf.get(module);
+    return ownerSource
+      ? (graph.importEdges.get(ownerSource)?.get(alias)?.targetModuleName ?? undefined)
+      : undefined;
+  };
+  forwardReExportManifests(result, specs, aliasToModule);
+
+  // Resolve every library's re-exported kinds and stamp them onto the consumer-facing
+  // Telo.Import manifests so the analyzer can register the re-export mappings.
+  const exportedKinds = resolveExportedKinds(kindModules, aliasToModule);
+  const imports: Array<{ manifest: ResourceManifest; targetModule: string }> = [];
+  for (const m of result) {
+    if (m.kind !== "Telo.Import") continue;
+    const owner = (m.metadata as { source?: string } | undefined)?.source;
+    const alias = m.metadata?.name as string | undefined;
+    const target = owner && alias ? graph.importEdges.get(owner)?.get(alias)?.targetModuleName : undefined;
+    if (target) imports.push({ manifest: m, targetModule: target });
+  }
+  stampReExportedKinds(imports, exportedKinds);
+}
+
 /** Project a LoadedModule (owner + partials) to a flat ResourceManifest[]
  *  with `metadata.module` stamped on non-module docs. The kernel's runtime
  *  entry load uses this to convert a `Loader.loadModule` result into the

package/src/index.ts

@@ -12,7 +12,14 @@ export type {
 export {
     flattenForAnalyzer,
     flattenLoadedModule,
+    forwardReExportManifests,
+    parseExportEntry,
+    reExportSpecsFromExports,
+    resolveExportedKinds,
     selectModuleManifestsForAnalysis,
+    stampReExportedKinds,
+    type ParsedExportEntry,
+    type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {

package/src/resolve-throws-union.ts

@@ -1,6 +1,6 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isTaggedSentinel } from "@telorun/templating";
-import type { AliasResolver } from "./alias-resolver.js";
+import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
 export interface ThrowsCodeMeta {
@@ -32,6 +32,13 @@ export interface ResolveCtx {
   allManifests: ResourceManifest[];
   defs: DefinitionRegistry;
   aliases: AliasResolver;
+  /** Per-imported-library alias resolvers, keyed by module name. A manifest that
+   *  originated in an imported library resolves its kind aliases against its own
+   *  module's resolver, not the consumer's — an inline handler extracted from an
+   *  imported Http.Api inherits the lexical scope of the library that declares it. */
+  aliasesByModule: Map<string, AliasResolver>;
+  /** The consumer/root module names; resources owned by these resolve against `aliases`. */
+  rootModules: Set<string>;
   memo: Map<string, ThrowsUnion>;
   inProgress: Set<string>;
 }
@@ -40,11 +47,15 @@ export function createResolveCtx(
   allManifests: ResourceManifest[],
   defs: DefinitionRegistry,
   aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver> = new Map(),
+  rootModules: Set<string> = new Set(),
 ): ResolveCtx {
   return {
     allManifests,
     defs,
     aliases,
+    aliasesByModule,
+    rootModules,
     memo: new Map(),
     inProgress: new Set(),
   };
@@ -54,6 +65,11 @@ function emptyUnion(): ThrowsUnion {
   return { codes: new Map(), unbounded: false };
 }
 
+/** The owning module's alias resolver for a manifest in this resolve context. */
+function scopeResolverFor(ctx: ResolveCtx, ownModule: string | undefined): AliasResolver | undefined {
+  return scopeResolverForModule(ownModule, ctx.rootModules, ctx.aliasesByModule);
+}
+
 function unionInto(target: ThrowsUnion, src: ThrowsUnion): void {
   for (const [code, meta] of src.codes) {
     if (!target.codes.has(code)) target.codes.set(code, meta);
@@ -66,9 +82,17 @@ function definitionFor(
   kind: string,
   defs: DefinitionRegistry,
   aliases: AliasResolver,
+  scopeResolver?: AliasResolver,
 ): ResourceDefinition | undefined {
+  const direct = defs.resolve(kind);
+  if (direct) return direct;
+  const scoped = scopeResolver?.resolveKind(kind);
+  if (scoped) {
+    const d = defs.resolve(scoped);
+    if (d) return d;
+  }
   const resolved = aliases.resolveKind(kind);
-  return defs.resolve(kind) ?? (resolved ? defs.resolve(resolved) : undefined);
+  return resolved ? defs.resolve(resolved) : undefined;
 }
 
 function codesFromDefinition(definition: ResourceDefinition): Map<string, ThrowsCodeMeta> {
@@ -97,7 +121,9 @@ export function resolveThrowsUnion(
     if (ctx.inProgress.has(name)) return emptyUnion();
   }
 
-  const definition = definitionFor(manifest.kind, ctx.defs, ctx.aliases);
+  const ownModule = (manifest.metadata as { module?: string } | undefined)?.module;
+  const scopeResolver = scopeResolverFor(ctx, ownModule);
+  const definition = definitionFor(manifest.kind, ctx.defs, ctx.aliases, scopeResolver);
   if (!definition) {
     const u: ThrowsUnion = { codes: new Map(), unbounded: true };
     if (name) ctx.memo.set(name, u);
@@ -126,7 +152,7 @@ export function resolveThrowsUnion(
     }
 
     if (throws.inherit) {
-      const inherited = resolveInherited(manifest, definition, ctx);
+      const inherited = resolveInherited(manifest, definition, ctx, ownModule);
       unionInto(result, inherited);
     }
 
@@ -141,6 +167,7 @@ function resolveInherited(
   manifest: ResourceManifest,
   definition: ResourceDefinition,
   ctx: ResolveCtx,
+  ownerModule: string | undefined,
 ): ThrowsUnion {
   const result: ThrowsUnion = { codes: new Map(), unbounded: false };
   const props = definition.schema?.properties as Record<string, any> | undefined;
@@ -151,7 +178,7 @@ function resolveInherited(
     if (!stepCtx?.invoke) continue;
     const steps = (manifest as Record<string, any>)[fieldName];
     if (!Array.isArray(steps)) continue;
-    unionInto(result, collectStepArrayThrows(steps, stepCtx.invoke, undefined, ctx));
+    unionInto(result, collectStepArrayThrows(steps, stepCtx.invoke, undefined, ctx, ownerModule));
   }
 
   return result;
@@ -162,13 +189,14 @@ function collectStepArrayThrows(
   invokeField: string,
   enclosingTryCodes: Set<string> | undefined,
   ctx: ResolveCtx,
+  ownerModule: string | undefined,
 ): ThrowsUnion {
   const result = emptyUnion();
   for (const step of steps) {
     if (!step || typeof step !== "object") continue;
     unionInto(
       result,
-      collectStepThrows(step as Record<string, any>, invokeField, enclosingTryCodes, ctx),
+      collectStepThrows(step as Record<string, any>, invokeField, enclosingTryCodes, ctx, ownerModule),
     );
   }
   return result;
@@ -184,11 +212,14 @@ function collectStepThrows(
   invokeField: string,
   enclosingTryCodes: Set<string> | undefined,
   ctx: ResolveCtx,
+  ownerModule: string | undefined,
 ): ThrowsUnion {
   if (step[invokeField]) {
     // Any invoked resource can throw a non-InvokeError at runtime, which an
     // enclosing catch surfaces as PLAIN_ERROR_CODE — record that possibility.
-    const u = cloneUnion(resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx));
+    const u = cloneUnion(
+      resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx, ownerModule),
+    );
     u.canThrowPlain = true;
     return u;
   }
@@ -198,7 +229,7 @@ function collectStepThrows(
   }
 
   if (Array.isArray(step.try)) {
-    const tryUnion = collectStepArrayThrows(step.try, invokeField, enclosingTryCodes, ctx);
+    const tryUnion = collectStepArrayThrows(step.try, invokeField, enclosingTryCodes, ctx, ownerModule);
     let propagated: ThrowsUnion;
     if (Array.isArray(step.catch)) {
       // Catch absorbs the try block's codes; the catch's own throws propagate
@@ -209,7 +240,7 @@ function collectStepThrows(
       // `error.code === PLAIN_ERROR_CODE`, so a `throw: { code: error.code }`
       // rethrow can propagate it — seed the set the catch resolves against.
       if (tryUnion.canThrowPlain) tryCodes.add(PLAIN_ERROR_CODE);
-      propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx);
+      propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx, ownerModule);
       // Unbounded in the try block still signals the caller to expect
       // arbitrary codes to flow through the catch (e.g. via passthrough).
       if (tryUnion.unbounded) propagated.unbounded = true;
@@ -219,7 +250,7 @@ function collectStepThrows(
     if (Array.isArray(step.finally)) {
       unionInto(
         propagated,
-        collectStepArrayThrows(step.finally, invokeField, enclosingTryCodes, ctx),
+        collectStepArrayThrows(step.finally, invokeField, enclosingTryCodes, ctx, ownerModule),
       );
     }
     return propagated;
@@ -227,16 +258,16 @@ function collectStepThrows(
 
   if (Array.isArray(step.then)) {
     const result = emptyUnion();
-    unionInto(result, collectStepArrayThrows(step.then, invokeField, enclosingTryCodes, ctx));
+    unionInto(result, collectStepArrayThrows(step.then, invokeField, enclosingTryCodes, ctx, ownerModule));
     if (Array.isArray(step.else)) {
-      unionInto(result, collectStepArrayThrows(step.else, invokeField, enclosingTryCodes, ctx));
+      unionInto(result, collectStepArrayThrows(step.else, invokeField, enclosingTryCodes, ctx, ownerModule));
     }
     if (Array.isArray(step.elseif)) {
       for (const branch of step.elseif) {
         if (Array.isArray(branch?.then)) {
           unionInto(
             result,
-            collectStepArrayThrows(branch.then, invokeField, enclosingTryCodes, ctx),
+            collectStepArrayThrows(branch.then, invokeField, enclosingTryCodes, ctx, ownerModule),
           );
         }
       }
@@ -245,18 +276,18 @@ function collectStepThrows(
   }
 
   if (Array.isArray(step.do)) {
-    return collectStepArrayThrows(step.do, invokeField, enclosingTryCodes, ctx);
+    return collectStepArrayThrows(step.do, invokeField, enclosingTryCodes, ctx, ownerModule);
   }
 
   if (step.cases && typeof step.cases === "object") {
     const result = emptyUnion();
     for (const arr of Object.values(step.cases as Record<string, unknown>)) {
       if (Array.isArray(arr)) {
-        unionInto(result, collectStepArrayThrows(arr, invokeField, enclosingTryCodes, ctx));
+        unionInto(result, collectStepArrayThrows(arr, invokeField, enclosingTryCodes, ctx, ownerModule));
       }
     }
     if (Array.isArray(step.default)) {
-      unionInto(result, collectStepArrayThrows(step.default, invokeField, enclosingTryCodes, ctx));
+      unionInto(result, collectStepArrayThrows(step.default, invokeField, enclosingTryCodes, ctx, ownerModule));
     }
     return result;
   }
@@ -277,13 +308,18 @@ function resolveStepInvokeThrows(
   invokeField: string,
   enclosingTryCodes: Set<string> | undefined,
   ctx: ResolveCtx,
+  ownerModule: string | undefined,
 ): ThrowsUnion {
   const invokeRef = step[invokeField];
   if (!invokeRef || typeof invokeRef !== "object") return emptyUnion();
   const invokedKind = invokeRef.kind as string | undefined;
   if (!invokedKind) return emptyUnion();
 
-  const definition = definitionFor(invokedKind, ctx.defs, ctx.aliases);
+  // The invoked kind's alias resolves in the OWNER manifest's lexical scope (the
+  // composer that declares the step), so a library's step referencing its own
+  // import resolves against that library, not the consumer.
+  const scopeResolver = scopeResolverFor(ctx, ownerModule);
+  const definition = definitionFor(invokedKind, ctx.defs, ctx.aliases, scopeResolver);
   if (!definition) return { codes: new Map(), unbounded: true };
 
   if (definition.throws?.passthrough) {
@@ -293,12 +329,14 @@ function resolveStepInvokeThrows(
   // Named manifest: resolve the full chain (covers transitive inherit).
   const invokeName = invokeRef.name as string | undefined;
   if (invokeName) {
+    const scopedInvokedKind = scopeResolver?.resolveKind(invokedKind);
     const target = ctx.allManifests.find(
       (m) =>
         m.metadata?.name === invokeName &&
         (m.kind === invokedKind ||
           ctx.aliases.resolveKind(m.kind) === invokedKind ||
-          m.kind === ctx.aliases.resolveKind(invokedKind)),
+          m.kind === ctx.aliases.resolveKind(invokedKind) ||
+          (scopedInvokedKind !== undefined && m.kind === scopedInvokedKind)),
     );
     if (target) return resolveThrowsUnion(target, ctx);
   }

package/src/validate-throws-coverage.ts

@@ -1,6 +1,6 @@
 import type { ASTNode, Environment } from "@marcbachmann/cel-js";
 import type { ResourceManifest } from "@telorun/sdk";
-import type { AliasResolver } from "./alias-resolver.js";
+import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
   createResolveCtx,
@@ -490,16 +490,28 @@ export function validateThrowsCoverage(
   defs: DefinitionRegistry,
   aliases: AliasResolver,
   env: Environment,
+  aliasesByModule: Map<string, AliasResolver> = new Map(),
+  rootModules: Set<string> = new Set(),
 ): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   diagnostics.push(...validateThrowsDeclarations(manifests));
 
-  const resolveCtx = createResolveCtx(manifests, defs, aliases);
+  const resolveCtx = createResolveCtx(manifests, defs, aliases, aliasesByModule, rootModules);
+
+  // The alias resolver for a manifest's own lexical scope — an imported library's
+  // resolver when it owns the manifest, else undefined (fall back to root aliases).
+  const scopeResolverFor = (m: ResourceManifest): AliasResolver | undefined =>
+    scopeResolverForModule(
+      (m.metadata as { module?: string } | undefined)?.module,
+      rootModules,
+      aliasesByModule,
+    );
 
   for (const manifest of manifests) {
     if (!manifest.kind || !manifest.metadata?.name) continue;
     if (manifest.kind === "Telo.Definition" || manifest.kind === "Telo.Abstract") continue;
-    const resolvedKind = aliases.resolveKind(manifest.kind);
+    const scopeResolver = scopeResolverFor(manifest);
+    const resolvedKind = scopeResolver?.resolveKind(manifest.kind) ?? aliases.resolveKind(manifest.kind);
     const definition =
       defs.resolve(manifest.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
     if (!definition?.schema) continue;
@@ -519,7 +531,7 @@ export function validateThrowsCoverage(
           ...checkCatchAllPlacement(entries, resource, "catches", filePath, arrayPath),
         );
         const handlerRef = resolveHandlerRef(siblingData[catchesFor]);
-        const union = handlerRefUnion(handlerRef, manifests, resolveCtx);
+        const union = handlerRefUnion(handlerRef, manifests, resolveCtx, scopeResolver);
         diagnostics.push(
           ...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env),
         );
@@ -539,20 +551,24 @@ function handlerRefUnion(
   handlerRef: { kind: string; name?: string } | null,
   manifests: ResourceManifest[],
   ctx: ReturnType<typeof createResolveCtx>,
+  scopeResolver: AliasResolver | undefined,
 ): ThrowsUnion {
   if (!handlerRef) return { codes: new Map(), unbounded: false };
   if (handlerRef.name) {
-    const resolvedKind = ctx.aliases.resolveKind(handlerRef.kind);
+    const resolvedKind = scopeResolver?.resolveKind(handlerRef.kind) ?? ctx.aliases.resolveKind(handlerRef.kind);
     const targetManifest = manifests.find(
       (m) =>
         m.metadata?.name === handlerRef.name &&
         (m.kind === handlerRef.kind ||
           m.kind === resolvedKind ||
+          scopeResolver?.resolveKind(m.kind) === handlerRef.kind ||
           ctx.aliases.resolveKind(m.kind) === handlerRef.kind),
     );
     if (targetManifest) return resolveThrowsUnion(targetManifest, ctx);
   }
-  const resolved = ctx.aliases.resolveKind(handlerRef.kind);
+  // No named target — fall back to the handler kind's own declared codes,
+  // resolving the kind in the owner's lexical scope first, then root aliases.
+  const resolved = scopeResolver?.resolveKind(handlerRef.kind) ?? ctx.aliases.resolveKind(handlerRef.kind);
   const def =
     ctx.defs.resolve(handlerRef.kind) ?? (resolved ? ctx.defs.resolve(resolved) : undefined);
   if (!def?.throws) return { codes: new Map(), unbounded: false };