@telorun/analyzer 0.70.0 → 0.71.0

package/src/call-graph.ts

@@ -40,6 +40,7 @@
  */
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import { refSentinelTarget } from "./ref-sentinel-target.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -63,6 +64,7 @@ import {
   type RefFieldEntry,
 } from "./reference-field-map.js";
 import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 export interface ResourceGraphNode {
   type: "resource";
@@ -693,8 +695,7 @@ export function buildCallGraph(
   const definitionFor = (manifest: ResourceManifest): ResourceDefinition | undefined => {
     const direct = registry.resolve(manifest.kind as string);
     if (direct) return direct;
-    const module = (manifest.metadata as { module?: string } | undefined)?.module;
-    const scope = (module ? options.aliasesByModule?.get(module) : undefined) ?? options.aliases;
+    const scope = moduleAliasScope(manifest.metadata, options.aliases, options.aliasesByModule);
     const canonical = scope?.resolveKind(manifest.kind as string);
     return canonical ? registry.resolve(canonical) : undefined;
   };
@@ -962,7 +963,12 @@ export function buildCallGraph(
  *  here: an unresolved `!ref <name>` sentinel and the `{kind, name}` object
  *  `resolveRefSentinels` rewrites it into. */
 function refTargetName(value: unknown): string | undefined {
-  if (isRefSentinel(value)) return value.source;
+  // An edge's target is taken VERBATIM — `resolveScopedName` and the node index
+  // are what resolve it, and a cross-module `Alias.name` is a target this graph
+  // legitimately carries unresolved. That is this pass's reduction over the
+  // shared parse, not a second reading of the tag.
+  const sentinel = refSentinelTarget(value);
+  if (sentinel) return sentinel.source;
   if (!value || typeof value !== "object") return undefined;
   const name = (value as Record<string, unknown>).name;
   return typeof name === "string" ? name : undefined;

package/src/cel-scope-query.ts

@@ -18,6 +18,7 @@ import { buildCelEnvironment } from "./cel-environment.js";
 import { CelScopeResolver, type CelScope } from "./cel-scope.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { buildKernelGlobalsIndex } from "./kernel-globals.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { isModuleKind } from "./module-kinds.js";
 import { navigateConcretePath } from "./manifest-path.js";
 import { findManifest } from "./find-manifest.js";
@@ -41,6 +42,12 @@ export interface ContextDeclarationSite {
   kind: string;
   name: string;
   path: string;
+  /** The declaring module, when the manifest carries one. Part of the identity,
+   *  not decoration: a resource name is unique inside its module and not across a
+   *  flattened set, so `(kind, name)` alone lets a host locating this site land on
+   *  another library's same-named document — which for go-to-declaration means
+   *  jumping to the wrong file with nothing to indicate it. */
+  module?: string;
 }
 
 /** Join a concrete path segment, tolerating an empty base (the manifest root). */
@@ -210,9 +217,14 @@ export class CelScopeQuery {
       base = hit;
     }
 
-    const metadata = origin.manifest.metadata as { name?: string } | undefined;
+    const metadata = origin.manifest.metadata as { name?: string; module?: string } | undefined;
     if (!origin.manifest.kind || !metadata?.name) return undefined;
-    return { kind: origin.manifest.kind, name: metadata.name, path: base };
+    return {
+      kind: origin.manifest.kind,
+      name: metadata.name,
+      path: base,
+      ...(metadata.module === undefined ? {} : { module: metadata.module }),
+    };
   }
 
   /** The manifest and path an annotated context property is derived from, and
@@ -265,13 +277,29 @@ export class CelScopeQuery {
       if (hash <= 0) return undefined;
       const kindValue = navigateConcretePath(root, first.slice(0, hash).split("/").join("."));
       if (typeof kindValue !== "string") return undefined;
-      const canonical = this.ctx.aliases.resolveKind(kindValue) ?? kindValue;
-      const suffix = canonical.slice(canonical.indexOf(".") + 1);
-      const target = this.manifests.find(
+      // The kind was read off THIS resource, so it is spelled in the alias scope
+      // of the module that declared it — not the entry's.
+      const scope = moduleAliasScope(resource.metadata, this.ctx.aliases, this.ctx.aliasesByModule);
+      const canonical = scope.resolveKind(kindValue) ?? kindValue;
+      const dot = canonical.indexOf(".");
+      const owningModule = dot === -1 ? undefined : canonical.slice(0, dot);
+      const suffix = canonical.slice(dot + 1);
+      // Matched by MODULE AND NAME once the canonical form carries a module: a
+      // definition name is unique inside its module and not across a flattened
+      // set, so two libraries each declaring an `Api` would otherwise resolve to
+      // whichever came first — and the editor would type a context region off the
+      // wrong kind's annotations, silently. Falls back to name alone only when the
+      // kind did not resolve to a canonical form, where there is nothing to narrow
+      // by and a best-effort match is still better than none.
+      const named = this.manifests.filter(
         (m) =>
           (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") &&
           (m.metadata as { name?: string } | undefined)?.name === suffix,
-      ) as Record<string, any> | undefined;
+      ) as Record<string, any>[];
+      const target =
+        (owningModule
+          ? named.find((m) => (m.metadata as { module?: string } | undefined)?.module === owningModule)
+          : undefined) ?? (owningModule && named.length > 1 ? undefined : named[0]);
       if (!target) return undefined;
       return { manifest: target, path: first.slice(hash + 1), propertyMap: false };
     }
@@ -313,9 +341,18 @@ export class CelScopeQuery {
     return undefined;
   }
 
+  /** The kind's declaration, resolved in the scope of the module that DECLARED
+   *  this resource — the same rule the manifest visitor applies, and the reason
+   *  it has to be the same one: everything this query offers is read off the
+   *  definition, so resolving a forwarded library resource's `kind: Http.Api`
+   *  through the entry's aliases alone found nothing and the editor silently
+   *  offered no `request` / `result` at a site `telo check` accepts. A
+   *  completion list is a claim that the name it offers will pass the checker,
+   *  so the two must resolve a kind identically. */
   private definitionFor(resource: ResourceManifest): ResourceDefinition | undefined {
-    const { defs, aliases } = this.ctx;
-    const canonical = aliases.resolveKind(resource.kind);
+    const { defs, aliases, aliasesByModule } = this.ctx;
+    const scope = moduleAliasScope(resource.metadata, aliases, aliasesByModule);
+    const canonical = scope.resolveKind(resource.kind);
     return defs.resolve(resource.kind) ?? (canonical ? defs.resolve(canonical) : undefined);
   }
 

package/src/definition-registry.ts

@@ -2,6 +2,7 @@ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import {
   buildFieldMapAtPath,
   buildReferenceFieldMap,
@@ -372,9 +373,7 @@ export class DefinitionRegistry {
     // (e.g. `Ai.AgentStream` in a library that imports `Ai`), which the root/global
     // resolver doesn't know — using the global scope here left the base field map
     // unresolved, so Phase-5 injection saw no ref fields and skipped injection.
-    const ownModule = (resource.metadata as { module?: string } | undefined)?.module;
-    const moduleScope =
-      (ownModule ? aliasesByModule.get(ownModule) : undefined) ?? aliases;
+    const moduleScope = moduleAliasScope(resource.metadata, aliases, aliasesByModule);
 
     const baseMap = this.getFieldMapForKind(resource.kind, moduleScope);
     if (!baseMap) return undefined;
@@ -383,9 +382,7 @@ export class DefinitionRegistry {
     const def = this.resolve(resource.kind) ?? this.resolve(resolvedKind);
     // schema-from anchors resolve in the DEFINITION's module scope (where the anchor
     // kind is declared), which may differ from the resource's own module.
-    const ownerModule = (def?.metadata as { module?: string } | undefined)?.module;
-    const ownerScope =
-      (ownerModule ? aliasesByModule.get(ownerModule) : undefined) ?? aliases;
+    const ownerScope = moduleAliasScope(def?.metadata, aliases, aliasesByModule);
 
     const expanded: ReferenceFieldMap = new Map();
     for (const [path, entry] of baseMap) {

package/src/flatten-for-analyzer.ts

@@ -8,7 +8,7 @@ import {
   readResourceInputs,
   type ResourceInput,
 } from "./resource-input.js";
-import type { ZoneModuleDocuments } from "./zone-module-documents.js";
+import type { ModuleDocuments } from "./module-documents.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`
@@ -557,8 +557,8 @@ function canonicalizeInputKind(
  *  projection needs the internal dispatch chain to derive an export's open
  *  requirements. Only libraries that actually export instances are included:
  *  a library exporting nothing has no export contract to derive. */
-export function collectZoneModuleDocuments(graph: LoadedGraph): ZoneModuleDocuments[] {
-  const out: ZoneModuleDocuments[] = [];
+export function collectModuleDocuments(graph: LoadedGraph): ModuleDocuments[] {
+  const out: ModuleDocuments[] = [];
   for (const [source, mod] of graph.modules) {
     if (source === graph.rootSource) continue;
     const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as

package/src/index.ts

@@ -11,7 +11,7 @@ export type {
     ParseError,
 } from "./loaded-types.js";
 export {
-    collectZoneModuleDocuments,
+    collectModuleDocuments,
     flattenForAnalyzer,
     flattenLoadedModule,
     forwardReExportManifests,
@@ -246,7 +246,7 @@ export type {
   ZoneExportRequirements,
   ZoneRequirementSpec,
 } from "./resolve-zone-requirements.js";
-export type { ZoneModuleDocuments } from "./zone-module-documents.js";
+export type { ModuleDocuments } from "./module-documents.js";
 export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
 export {
   RESOURCE_RULES_ANNOTATION,

package/src/manifest-visitor.ts

@@ -17,6 +17,7 @@ import {
   type SchemaFromFieldEntry,
 } from "./reference-field-map.js";
 import type { ModuleScopes } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { templateBodies, withTemplateSelf } from "./template-body.js";
 import { extractContextsFromSchema, pathMatchesScope } from "./validate-cel-context.js";
 
@@ -237,7 +238,14 @@ export function visitManifest(
     if (!r.metadata?.name || !r.kind) continue;
     if (skipKinds?.has(r.kind)) continue;
 
-    const resolvedKind = aliases?.resolveKind(r.kind);
+    // A resource's own kind is written in the alias scope of the module that
+    // DECLARED it — see `moduleAliasScope`, which is the one place that rule
+    // lives. Resolving it through the entry's aliases alone left `definition`
+    // undefined for every forwarded resource, so its `x-telo-context` regions
+    // contributed nothing and `request` / `result` read as unknown identifiers
+    // inside the library's own routes, on a file the consumer cannot fix.
+    const moduleScope = moduleAliasScope(r.metadata, aliases, aliasesByModule);
+    const resolvedKind = moduleScope?.resolveKind(r.kind);
     const definition =
       registry.resolve(r.kind) ??
       (resolvedKind ? registry.resolve(resolvedKind) : undefined);
@@ -249,8 +257,8 @@ export function visitManifest(
     const emittedRefPaths = wantsNested ? new Set<string>() : null;
 
     if (wantsRefs || wantsScope || wantsSchemaFrom) {
-      const baseMap = aliases
-        ? registry.getFieldMapForKind(r.kind, aliases)
+      const baseMap = moduleScope
+        ? registry.getFieldMapForKind(r.kind, moduleScope)
         : registry.getFieldMap(r.kind);
 
       // Expanded map drives ref/scope sites when requested; schema-from sites

package/src/module-alias-scope.ts

@@ -0,0 +1,94 @@
+import { AliasResolver, scopeResolverForModule, type ModuleScopes } from "./alias-resolver.js";
+
+/**
+ * WHICH ALIAS TABLE A MANIFEST'S OWN NAMES ARE WRITTEN IN.
+ *
+ * An application analysis is flattened, so an imported library's definitions and
+ * exported instances are checked in the CONSUMER's pass. But every alias-qualified
+ * name on such a manifest — its `kind:`, its `extends:`, an `x-telo-schema-from`
+ * anchor — was written against the alias map of the module that DECLARED it. A
+ * library writes `kind: Http.Api` through an import the consumer has no reason to
+ * have, so resolving it through the entry's table finds nothing, and everything
+ * derived from the definition silently goes missing: the field map (Phase-5
+ * injection blind to a forwarded resource's ref slots) and the `x-telo-context`
+ * regions (`request` / `result` reported as unknown identifiers on a file the
+ * consumer cannot edit).
+ *
+ * **There are TWO fallbacks, not one, and this file is where they are told
+ * apart** — that is the whole reason they live together. They agree on every
+ * module that has a table, and differ on a non-root module that has none:
+ *
+ *  - {@link moduleAliasScope} falls back to the GLOBAL table. For a question
+ *    asked about an arbitrary manifest, where a missing entry means "this is the
+ *    entry's own", which is what the global table answers correctly.
+ *  - {@link declaringModuleScope} falls back to an EMPTY table for a non-root
+ *    module. For canonicalizing what a library DECLARED, where resolving its
+ *    `Http.Api` through the consumer's imports would silently bind a library's
+ *    kind to whatever the app happens to import under that alias — a wrong
+ *    answer, which is worse than none.
+ *
+ * Both rest on one invariant neither states inline: **a root module is never a
+ * key in `aliasesByModule`** — a root's imports are registered into the global
+ * table instead (see the `rootModules` guards in `analyze()`) — so for a
+ * consumer-owned manifest the two rules coincide and neither fallback is a
+ * degradation.
+ *
+ * Every READ of the rule goes through one of these two. What legitimately does
+ * not, and why, so the next reader does not have to re-derive it: the three
+ * sites in `analyze()` that POPULATE `aliasesByModule` (a write, not a lookup),
+ * and `resolve-ref-sentinels`, whose module is known non-root by construction and
+ * whose fallback is the raw kind rather than another table — a different rule
+ * that happens to read the same map.
+ */
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M;
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A | undefined,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M | undefined;
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A | undefined,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M | undefined {
+  const declaringModule = metadata?.module;
+  if (typeof declaringModule !== "string") return aliases;
+  return aliasesByModule?.get(declaringModule) ?? aliases;
+}
+
+/** All this rule needs of a resolver, and deliberately all it asks for:
+ *  `ModuleScopes` already types its map this way so a caller can hand over a
+ *  lighter table, and requiring the full `AliasResolver` here would have made
+ *  the one site that does (a template body) reach for a cast. */
+interface KindResolver {
+  resolveKind(kind: string): string | undefined;
+}
+
+/** An empty table, shared: a non-root module with no aliases of its own resolves
+ *  nothing rather than resolving through the consumer's. One instance because it
+ *  is immutable in use and allocating one per call put a resolver on a per-schema
+ *  loop. */
+const NO_ALIASES = new AliasResolver();
+
+/**
+ * The scope a DECLARING module's own alias-form names are canonicalized in — the
+ * root-aware half of the rule above, and the one that must never fall through to
+ * the consumer's table. See this file's header for why the two differ.
+ */
+export function declaringModuleScope(
+  ownModule: string | undefined,
+  aliases: AliasResolver,
+  scopes: { aliasesByModule: Map<string, AliasResolver>; rootModules: Set<string> },
+): AliasResolver {
+  const own = scopeResolverForModule(ownModule, scopes.rootModules, scopes.aliasesByModule);
+  if (own) return own;
+  // Root (or unknown-and-therefore-treated-as-root): the global table IS its
+  // import map. A non-root module with no table of its own resolves nothing.
+  return ownModule && !scopes.rootModules.has(ownModule) ? NO_ALIASES : aliases;
+}
+
+export type { ModuleScopes };

package/src/{zone-module-documents.ts → module-documents.ts}

@@ -1,19 +1,23 @@
 import type { ResourceManifest } from "@telorun/sdk";
 
 /**
- * One imported library's FULL document set, for the zone stage's per-library
- * export derivation — what the flattened analysis view no longer holds, since
- * it forwards only each library's export surface and never its internal
- * dispatch chain.
+ * One imported library's FULL document set — what the flattened analysis view
+ * no longer holds, since it forwards only each library's export surface and
+ * never its internal dispatch chain.
+ *
+ * Named for what it CARRIES rather than for who asked first: the zone stage's
+ * per-library export derivation was the original consumer, and the throws walk
+ * is the second — a third should not have to import "zone" to ask about
+ * something else again.
  *
  * Plain data in a module of its own, deliberately. It is produced by the
- * loading side (`collectZoneModuleDocuments`), named in `AnalysisOptions`, and
+ * loading side (`collectModuleDocuments`), named in `AnalysisOptions`, and
  * consumed by the projection; putting it in any of the three would make the
  * other two import that one, and `types.ts` ↔ the projection is a genuine
  * cycle. A leaf module with no imports of its own breaks it without an inline
  * `import(...)` type expression standing in for the dependency nobody wanted.
  */
-export interface ZoneModuleDocuments {
+export interface ModuleDocuments {
   /** The library's module name (its `Telo.Library` doc's `metadata.name`). */
   module: string;
   /** Stable source identity of the library's owner file — the cache key. */

package/src/ref-sentinel-target.ts

@@ -0,0 +1,46 @@
+import { isRefSentinel } from "@telorun/templating";
+
+/**
+ * What a `!ref` names, parsed once.
+ *
+ * THE single reader of the tag's grammar, on the `ref-slot.ts` / `zone-slot.ts`
+ * precedent. Three passes had grown their own parse of the same scalar and they
+ * disagreed: one took the source verbatim, one split on the first dot and
+ * dropped every alias but `Self`, one split on the LAST dot and dropped the
+ * alias entirely — so the same `!ref Alias.name` named three different things
+ * depending on which pass was asking, and the loosest of the three resolved a
+ * bare name against whatever manifest happened to share it.
+ *
+ * The grammar itself is one line and is not in dispute: `!ref <name>` or
+ * `!ref <Alias>.<name>`, split on the FIRST dot, because that is what
+ * `resolveRefSentinels` does and a name may not contain one
+ * (`INVALID_NAME` rejects it at every declaration site).
+ *
+ * What this deliberately does NOT do is decide what to look up. A reduction is
+ * the caller's, and the three genuinely differ: an edge in the call graph points
+ * at a cross-module target and tolerates not resolving it; a zone correlation
+ * refuses to bind anything it cannot resolve exactly; a throws walk resolves in
+ * the DECLARING library first. Each states its own, over one parse.
+ *
+ * Browser-safe.
+ */
+export interface RefSentinelTarget {
+  /** The scalar as written, for a caller that wants the author's spelling. */
+  source: string;
+  /** The prefix before the first dot, `Self` included and not normalized away —
+   *  a caller that treats `Self` as "no alias" says so itself. */
+  alias?: string;
+  /** The segment after the first dot, or the whole scalar when there is none. */
+  name: string;
+}
+
+/** Parse a `!ref` sentinel. Returns `undefined` for anything that is not one —
+ *  including the `{kind, name}` object `resolveRefSentinels` rewrites it into,
+ *  which is a different shape with a different reader. */
+export function refSentinelTarget(value: unknown): RefSentinelTarget | undefined {
+  if (!isRefSentinel(value)) return undefined;
+  const source = value.source;
+  const dot = source.indexOf(".");
+  if (dot <= 0) return { source, name: source };
+  return { source, alias: source.slice(0, dot), name: source.slice(dot + 1) };
+}

package/src/resolve-schema-type-refs.ts

@@ -1,6 +1,7 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId, parseTeloTypeRef } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 /** Schema-bearing fields on a Telo.Definition / Telo.Type resource. */
 const SCHEMA_FIELDS = ["schema", "inputType", "outputType"];
@@ -96,7 +97,7 @@ export function resolveSchemaTypeRefs(
 
   for (const r of resources) {
     const ownModule = (r.metadata as { module?: string } | undefined)?.module;
-    const resolver = (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
+    const resolver = moduleAliasScope(r.metadata, aliases, aliasesByModule);
     const resolveAuthority = (authority: string): string | undefined =>
       authority === "Self" ? ownModule : resolver?.moduleForAlias(authority);
     for (const field of SCHEMA_FIELDS) {

package/src/resolve-throws-union.ts

@@ -1,6 +1,8 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isTaggedSentinel } from "@telorun/templating";
 import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js";
+import { resolveScopedName } from "./call-graph.js";
+import { refSentinelTarget, type RefSentinelTarget } from "./ref-sentinel-target.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { readStepSlot } from "./step-slot.js";
 
@@ -40,6 +42,23 @@ export interface ResolveCtx {
   aliasesByModule: Map<string, AliasResolver>;
   /** The consumer/root module names; resources owned by these resolve against `aliases`. */
   rootModules: Set<string>;
+  /**
+   * Every imported library's FULL manifest list, keyed by module name.
+   *
+   * A consumer's flat set holds a library's EXPORTED instances and nothing else,
+   * so the siblings an exported entry point invokes are not in it. Without this
+   * the walk stops at the first such hop, and the difference is not academic: a
+   * library whose entry point raises its own code through an internal guard
+   * presented an empty union to its consumer, which then had its `catches:`
+   * rejected for the very code the entry point documents.
+   *
+   * Consulted only as a FALLBACK, after the flat set — the flat set is what the
+   * consumer's own resources resolve against, and a library-internal name must
+   * never shadow one of them.
+   */
+  moduleManifests: Map<string, ResourceManifest[]>;
+  /** Keyed `<module>\0<name>`: resource names are module-scoped, so two
+   *  libraries each declaring a `query` are two different unions. */
   memo: Map<string, ThrowsUnion>;
   inProgress: Set<string>;
 }
@@ -50,6 +69,7 @@ export function createResolveCtx(
   aliases: AliasResolver,
   aliasesByModule: Map<string, AliasResolver> = new Map(),
   rootModules: Set<string> = new Set(),
+  moduleManifests: Map<string, ResourceManifest[]> = new Map(),
 ): ResolveCtx {
   return {
     allManifests,
@@ -57,11 +77,90 @@ export function createResolveCtx(
     aliases,
     aliasesByModule,
     rootModules,
+    moduleManifests,
     memo: new Map(),
     inProgress: new Set(),
   };
 }
 
+/**
+ * A dispatch target named by a resolved `{kind, name}` ref.
+ *
+ * The flat set is the scope such a ref was resolved in, so it is asked first;
+ * the owning library's own documents are the fallback for a name the flattened
+ * view dropped. `kindMatches` applies to BOTH — one function, one rule, or the
+ * next caller inherits whichever half it happened to hit.
+ */
+function findTarget(
+  ctx: ResolveCtx,
+  name: string,
+  ownerModule: string | undefined,
+  kindMatches: (m: ResourceManifest) => boolean,
+): ResourceManifest | undefined {
+  const flat = ctx.allManifests.find((m) => m.metadata?.name === name && kindMatches(m));
+  if (flat) return flat;
+  if (!ownerModule) return undefined;
+  return ctx.moduleManifests
+    .get(ownerModule)
+    ?.find((m) => m.metadata?.name === name && kindMatches(m));
+}
+
+/**
+ * The target of a `!ref` that still carries its sentinel — a library-internal
+ * reference inside a manifest forwarded into a consumer's flat set, where Phase
+ * 2.5 had nothing to resolve it against.
+ *
+ * **The declaring library is asked FIRST**, and that ordering is the whole rule:
+ * a bare name in a library manifest is unambiguously library-internal, so
+ * searching the consumer's flat set first let any consumer resource that
+ * happened to share the name supply another library's throw union — the same
+ * false `{∅}` this branch exists to remove, arrived at from the other side.
+ *
+ * An ALIAS-qualified source is the cross-module case and is resolved through the
+ * declaring module's own alias table, never by dropping the alias and matching
+ * the bare name anywhere.
+ *
+ * Ambiguity resolves to NOTHING rather than to a guess (`resolveScopedName`'s
+ * rule), and the caller reads that as unbounded — the safe direction here, since
+ * a union that cannot be enumerated must not read as empty.
+ */
+function findSentinelTarget(
+  ctx: ResolveCtx,
+  target: RefSentinelTarget,
+  ownerModule: string | undefined,
+): ResourceManifest | undefined {
+  const named = (pool: readonly ResourceManifest[] | undefined): ResourceManifest[] =>
+    (pool ?? []).filter((m) => m.metadata?.name === target.name);
+
+  if (target.alias !== undefined && target.alias !== "Self") {
+    // A forwarded export: its module is whatever the DECLARING module aliases
+    // that prefix to, and it keeps its export name in the flat set.
+    // A root-owned manifest resolves aliases against the global table, which is
+    // what `scopeResolverForModule` returns undefined for — so fall back to it
+    // rather than reading a root's own alias as unresolvable.
+    const resolver = scopeResolverFor(ctx, ownerModule) ?? ctx.aliases;
+    const module = resolver.moduleForAlias(target.alias);
+    if (!module) return undefined;
+    return named(ctx.allManifests).find((m) => declaringModuleOf(m) === module);
+  }
+
+  const own = named(ctx.moduleManifests.get(ownerModule ?? ""));
+  if (own.length === 1) return own[0];
+  if (own.length > 1) return undefined;
+  return resolveScopedName(named(ctx.allManifests), declaringModuleOf, ownerModule);
+}
+
+const declaringModuleOf = (m: ResourceManifest): string | undefined =>
+  (m.metadata as { module?: string } | undefined)?.module;
+
+/** Memo key. Module-scoped, because resource names are. */
+function memoKey(manifest: ResourceManifest): string | undefined {
+  const name = manifest.metadata?.name as string | undefined;
+  if (!name) return undefined;
+  const mod = (manifest.metadata as { module?: string } | undefined)?.module ?? "";
+  return `${mod}\0${name}`;
+}
+
 function emptyUnion(): ThrowsUnion {
   return { codes: new Map(), unbounded: false };
 }
@@ -114,7 +213,7 @@ export function resolveThrowsUnion(
   manifest: ResourceManifest,
   ctx: ResolveCtx,
 ): ThrowsUnion {
-  const name = manifest.metadata?.name as string | undefined;
+  const name = memoKey(manifest);
 
   if (name) {
     const cached = ctx.memo.get(name);
@@ -314,7 +413,21 @@ function resolveStepInvokeThrows(
   const invokeRef = step[invokeField];
   if (!invokeRef || typeof invokeRef !== "object") return emptyUnion();
   const invokedKind = invokeRef.kind as string | undefined;
-  if (!invokedKind) return emptyUnion();
+  // A reference that still carries its parse-time sentinel — a library-internal
+  // `!ref` inside a manifest forwarded into a consumer's flat set, where Phase
+  // 2.5 had nothing to resolve it against. The target is in the declaring
+  // library's own documents, so it is looked up there; only a name that is not
+  // there either is UNKNOWN, which is unbounded rather than empty. Reading it as
+  // empty is what made a library's exported entry point present a `{∅}` union to
+  // its consumer and get the consumer's `catches:` rejected for the code the
+  // entry point documents.
+  if (!invokedKind) {
+    const sentinel = refSentinelTarget(invokeRef);
+    if (!sentinel) return emptyUnion();
+    const target = findSentinelTarget(ctx, sentinel, ownerModule);
+    if (target) return resolveThrowsUnion(target, ctx);
+    return { codes: new Map(), unbounded: true };
+  }
 
   // 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
@@ -331,13 +444,15 @@ function resolveStepInvokeThrows(
   const invokeName = invokeRef.name as string | undefined;
   if (invokeName) {
     const scopedInvokedKind = scopeResolver?.resolveKind(invokedKind);
-    const target = ctx.allManifests.find(
+    const target = findTarget(
+      ctx,
+      invokeName,
+      ownerModule,
       (m) =>
-        m.metadata?.name === invokeName &&
-        (m.kind === invokedKind ||
-          ctx.aliases.resolveKind(m.kind) === invokedKind ||
-          m.kind === ctx.aliases.resolveKind(invokedKind) ||
-          (scopedInvokedKind !== undefined && m.kind === scopedInvokedKind)),
+        m.kind === invokedKind ||
+        ctx.aliases.resolveKind(m.kind) === invokedKind ||
+        m.kind === ctx.aliases.resolveKind(invokedKind) ||
+        (scopedInvokedKind !== undefined && m.kind === scopedInvokedKind),
     );
     if (target) return resolveThrowsUnion(target, ctx);
   }