@telorun/analyzer 0.70.0 → 0.72.0

package/src/resolve-throws-union.ts

@@ -1,8 +1,12 @@
 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 { possibleUses, readRefSlot, transfersControl, type RefSlot } from "./ref-slot.js";
 import { readStepSlot } from "./step-slot.js";
+import { forEachDrivenSlot } from "./schema-walk.js";
 
 export interface ThrowsCodeMeta {
   data?: Record<string, any>;
@@ -40,6 +44,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 +71,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 +79,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 +215,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);
@@ -164,6 +265,16 @@ export function resolveThrowsUnion(
   }
 }
 
+/**
+ * `throws.inherit: true` — the union a composer's own STEP BODIES reach.
+ *
+ * Deliberately steps only, and not every slot the resource drives: `inherit` is
+ * a DECLARATION that a kind's union is the union of what it dispatches, and a
+ * kind that does not make that claim must not have it inferred — a kind holding
+ * a `call` ref it catches internally would silently gain codes it never lets
+ * escape. What a CATCH SCOPE needs is a different question with a different
+ * answer, and it has its own resolver below.
+ */
 function resolveInherited(
   manifest: ResourceManifest,
   definition: ResourceDefinition,
@@ -185,6 +296,66 @@ function resolveInherited(
   return result;
 }
 
+/**
+ * The union a SCOPE-LEVEL `catches:` list can be asked to render — everything
+ * the resource it is written on drives, transitively.
+ *
+ * `x-telo-catches-for: ""` is itself the claim that this is the denominator, so
+ * nothing is inferred from a kind that did not opt in, and no definition has to
+ * declare a `throws:` block to carry a catch scope (the kernel forbids one on a
+ * `Telo.Service` and a `Telo.Mount`, and rightly: what a router renders is not
+ * what a router THROWS).
+ *
+ * Three edges, three answers. A **step body** contributes its own traversal,
+ * subtraction included. A **control-transferring ref** contributes the target's
+ * own declared union — a route handler is a leaf here, and asking what IT drives
+ * would credit this scope with codes the handler catches internally. A
+ * **`throwsThrough` ref** recurses, because the target is another scope on the
+ * same ladder: a server renders what its mounts' routes throw, not what the
+ * mounts themselves declare.
+ */
+export function resolveScopeUnion(
+  manifest: ResourceManifest,
+  definition: ResourceDefinition,
+  ctx: ResolveCtx,
+  seen: Set<ResourceManifest> = new Set(),
+): ThrowsUnion {
+  const result: ThrowsUnion = { codes: new Map(), unbounded: false };
+  if (seen.has(manifest)) return result;
+  seen.add(manifest);
+  const ownerModule = (manifest.metadata as { module?: string } | undefined)?.module;
+
+  forEachDrivenSlot(definition.schema, manifest, (driven) => {
+    if (driven.kind === "step") {
+      unionInto(
+        result,
+        collectStepArrayThrows(driven.data, driven.slot.invoke, undefined, ctx, ownerModule),
+      );
+      return;
+    }
+    if (driven.slot.throwsThrough) {
+      const target = resolveRefManifest(driven.data, ctx, ownerModule);
+      const targetDef = target
+        ? definitionFor(
+            target.kind,
+            ctx.defs,
+            ctx.aliases,
+            scopeResolverFor(ctx, (target.metadata as { module?: string } | undefined)?.module),
+          )
+        : undefined;
+      if (target && targetDef) unionInto(result, resolveScopeUnion(target, targetDef, ctx, seen));
+      // A target that cannot be resolved says nothing about what it throws, so
+      // the scope's union is no longer enumerable.
+      else result.unbounded = true;
+      return;
+    }
+    if (!possibleUses(driven.slot).some(transfersControl)) return;
+    unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
+  });
+
+  return result;
+}
+
 function collectStepArrayThrows(
   steps: unknown[],
   invokeField: string,
@@ -311,36 +482,62 @@ function resolveStepInvokeThrows(
   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();
+  return resolveRefTargetThrows(step[invokeField], ctx, ownerModule, () =>
+    resolvePassthroughAtCallSite(step, enclosingTryCodes),
+  );
+}
+
+/**
+ * The effective throw union behind a resolved reference value.
+ *
+ * Shared by both ways a resource drives another: a step's `invoke:` and a
+ * reference slot that carries throws. The two used to differ only in where the
+ * ref value was read from, and keeping one copy is what stops a router's
+ * denominator and a sequence's from disagreeing about what a name resolves to.
+ *
+ * `onPassthrough` is the one genuine difference: a passthrough kind's union is a
+ * property of the CALL SITE (`inputs.code`), which only a step has. A reference
+ * slot has no such site, so the union is unbounded there rather than guessed.
+ */
+function resolveRefTargetThrows(
+  refValue: unknown,
+  ctx: ResolveCtx,
+  ownerModule: string | undefined,
+  onPassthrough?: () => ThrowsUnion,
+): ThrowsUnion {
+  if (!refValue || typeof refValue !== "object" || Array.isArray(refValue)) return emptyUnion();
+  const ref = refValue as Record<string, any>;
+  const invokedKind = ref.kind as string | undefined;
+  // 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(ref);
+    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
+  // resource that declares the slot), 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) {
-    return resolvePassthroughAtCallSite(step, enclosingTryCodes);
+    return onPassthrough ? onPassthrough() : { codes: new Map(), unbounded: true };
   }
 
   // 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) ||
-          (scopedInvokedKind !== undefined && m.kind === scopedInvokedKind)),
-    );
-    if (target) return resolveThrowsUnion(target, ctx);
-  }
+  const target = resolveRefManifest(ref, ctx, ownerModule);
+  if (target) return resolveThrowsUnion(target, ctx);
 
   // Fall back to the definition's own explicit codes. Mark unbounded when the
   // definition depends on call-site or transitive resolution we couldn't
@@ -351,6 +548,42 @@ function resolveStepInvokeThrows(
   return { codes, unbounded };
 }
 
+/**
+ * The manifest a resolved reference value names, in either shape it arrives in —
+ * a `{kind, name}` pair, or a `!ref` still carrying its parse-time sentinel.
+ *
+ * Exported because the catch-scope enclosure walk asks the same question about
+ * the same values; resolving a name twice by two rules is how two passes end up
+ * disagreeing about which resource a slot points at.
+ */
+export function resolveRefManifest(
+  refValue: unknown,
+  ctx: ResolveCtx,
+  ownerModule: string | undefined,
+): ResourceManifest | undefined {
+  if (!refValue || typeof refValue !== "object" || Array.isArray(refValue)) return undefined;
+  const ref = refValue as Record<string, any>;
+  const kind = ref.kind as string | undefined;
+  if (!kind) {
+    const sentinel = refSentinelTarget(ref);
+    return sentinel ? findSentinelTarget(ctx, sentinel, ownerModule) : undefined;
+  }
+  const name = ref.name as string | undefined;
+  if (!name) return undefined;
+  const scopeResolver = scopeResolverFor(ctx, ownerModule);
+  const scopedKind = scopeResolver?.resolveKind(kind);
+  return findTarget(
+    ctx,
+    name,
+    ownerModule,
+    (m) =>
+      m.kind === kind ||
+      ctx.aliases.resolveKind(m.kind) === kind ||
+      m.kind === ctx.aliases.resolveKind(kind) ||
+      (scopedKind !== undefined && m.kind === scopedKind),
+  );
+}
+
 /** Resolve a passthrough-style invocable at a specific call site. Recognised forms
  *  (see "passthrough: true" in the plan):
  *  - constant literal (no template) → `{ <literal> }`

package/src/resolve-zone-requirements.ts

@@ -14,7 +14,7 @@
  * Browser-safe: no Node built-ins.
  */
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel } from "@telorun/templating";
+import { refSentinelTarget } from "./ref-sentinel-target.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import {
   buildCallGraph,
@@ -28,9 +28,10 @@ import {
   propertySchemas,
   resolveLocalRef,
 } from "./manifest-navigation.js";
-import type { ZoneModuleDocuments } from "./zone-module-documents.js";
+import type { ModuleDocuments } from "./module-documents.js";
 import { readProvidesZone, readRequiresZone } from "./zone-slot.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -125,7 +126,7 @@ function definitionResolver(
   aliasesByModule: Map<string, AliasResolver>,
 ) {
   return (kind: string, module?: string): ResourceDefinition | undefined => {
-    const scope = (module ? aliasesByModule.get(module) : undefined) ?? aliases;
+    const scope = moduleAliasScope({ module }, aliases, aliasesByModule);
     const canonical = scope.resolveKind(kind);
     return defs.resolve(kind) ?? (canonical ? defs.resolve(canonical) : undefined);
   };
@@ -193,17 +194,16 @@ function schemaNodeAt(
  * under-approximating direction the whole pass leans on. `Self.` is a local
  * name written the long way and does resolve.
  *
- * This deliberately differs from `call-graph`'s `refTargetName`, which answers a
- * different question (what an EDGE points at, cross-module included, for a graph
- * whose consumers tolerate an unresolved target) — hence two functions rather
- * than one shared helper.
+ * This is this pass's REDUCTION over the shared `refSentinelTarget` parse, not a
+ * second reading of the tag: `call-graph`'s answers a different question (what
+ * an EDGE points at, cross-module included, for a graph whose consumers tolerate
+ * an unresolved target) and states its own reduction the same way.
  */
 function refName(value: unknown): string | undefined {
-  if (isRefSentinel(value)) {
-    const source = value.source;
-    const dot = source.indexOf(".");
-    if (dot <= 0) return source;
-    return source.slice(0, dot) === "Self" ? source.slice(dot + 1) : undefined;
+  const sentinel = refSentinelTarget(value);
+  if (sentinel) {
+    if (sentinel.alias === undefined) return sentinel.name;
+    return sentinel.alias === "Self" ? sentinel.name : undefined;
   }
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const v = value as Record<string, unknown>;
@@ -712,7 +712,7 @@ export function zoneDocumentsSignature(manifests: readonly ResourceManifest[]):
  * the projection derive-only, and keep what reaches an exported instance.
  */
 export function deriveLibraryExportRequirements(
-  docs: ZoneModuleDocuments,
+  docs: ModuleDocuments,
   defs: DefinitionRegistry,
   aliases: AliasResolver,
   aliasesByModule: Map<string, AliasResolver>,
@@ -745,7 +745,7 @@ export interface ZoneAnalysisArgs {
   aliases: AliasResolver;
   aliasesByModule: Map<string, AliasResolver>;
   rootModules: ReadonlySet<string>;
-  moduleDocuments?: readonly ZoneModuleDocuments[];
+  moduleDocuments?: readonly ModuleDocuments[];
   cache?: ZoneExportCache;
 }
 

package/src/schema-compat.ts

@@ -8,6 +8,7 @@ import {
 import {
   celBaseOfValueType,
   celTypeOfValueType,
+  isCompiledValue,
   readValueTypeSlot,
   valueBrandBases,
   valueTypeOf,
@@ -799,6 +800,18 @@ export function substituteCelFields(
     mark();
     return celPlaceholderForSchema(resolved);
   }
+  // The same fact in its third spelling. An expression reaches this walk as a
+  // `${{ … }}` string or a `!cel` sentinel BEFORE `precompileDoc`, and as a
+  // CompiledValue after — so a caller running under `compile: true` (every
+  // `telo run`, unlike `telo check`) handed one to AJV as a plain object, and a
+  // slot typed `boolean` rejected a `when:` the author wrote correctly. The
+  // kernel's `stripCompiledValues` has always substituted here; missing it on
+  // this side made one manifest mean two things depending on which command read
+  // it.
+  if (isCompiledValue(data)) {
+    mark();
+    return celPlaceholderForSchema(resolved);
+  }
   if (Array.isArray(data)) {
     const item = resolveRefIn((resolved.items ?? {}) as Record<string, any>, root, external);
     return data.map((element, i) =>

package/src/schema-error-report.ts

@@ -53,10 +53,42 @@ const UNION_KEYWORDS = new Set(["anyOf", "oneOf"]);
  *  further in. These are what make a branch implausible. */
 const SHAPE_KEYWORDS = new Set(["required", "type", "additionalProperties", "enum", "const"]);
 
+/** Keywords that exist to DISCRIMINATE, so a mismatch is positive evidence that
+ *  the value is not this branch — at any depth, not only at the union node.
+ *
+ *  Depth is otherwise the tiebreak, and it inverts exactly here: a branch that
+ *  agreed on the discriminator and failed one constraint reported at the union
+ *  node loses to every branch that disagreed about the discriminator one level
+ *  in. That is how a `capability: Telo.Service` document declaring a forbidden
+ *  key was reported as `/capability must be equal to constant` — naming neither
+ *  the key at fault nor a branch the value could ever have been. */
+const DISCRIMINATOR_KEYWORDS = new Set(["const", "enum"]);
+
+/** RFC 6901 escapes: `~1` is a literal `/` in the key, `~0` a literal `~`.
+ *  Decoded wherever a segment is shown or matched, because encoded it is not the
+ *  key the manifest holds — a content map (`application/json`) anchors nowhere
+ *  and reads wrong in the sentence. `~0` is expanded LAST, or `~01` would decode
+ *  to `/` instead of the literal `~1` it encodes. */
+function unescapeSegment(part: string): string {
+  return part.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** The whole pointer, segment by segment, for prose that quotes it verbatim. */
+function unescapePointer(pointer: string): string {
+  return pointer
+    .split("/")
+    .map((segment, i) => (i === 0 ? segment : unescapeSegment(segment)))
+    .join("/");
+}
+
 /* ------------------------------------------------------------------ prose */
 
 export function formatSingleError(err: AjvErrorLike): string {
-  const p = err.instancePath || "/";
+  // Unescaped for the same reason the path is: a reader acting on this sentence
+  // needs the key the manifest holds (`application/json`), not its RFC 6901
+  // encoding. Reporting one form in `path` and the other in `message` made one
+  // diagnostic disagree with itself.
+  const p = unescapePointer(err.instancePath || "") || "/";
   const params = err.params ?? {};
   switch (err.keyword) {
     case "additionalProperties":
@@ -67,6 +99,16 @@ export function formatSingleError(err: AjvErrorLike): string {
       return `${p} ${err.message ?? "is invalid"} (${(params.allowedValues as unknown[])?.join(" | ")})`;
     case "type":
       return `${p} must be ${params.type}${describeActual(err)}`;
+    // A `false` schema at a property is how a branch forbids a key it otherwise
+    // declares. AJV's own text ("boolean schema is false") describes the schema
+    // rather than the value, and the path is the only part a reader can act on.
+    case "false schema":
+      return `${p} is not allowed here`;
+    // `not:` says a forbidden shape matched, and AJV reports nothing about the
+    // inner schema — so the honest message says where, and no more. A branch
+    // that wants to name the key writes `properties: { <key>: false }` instead.
+    case "not":
+      return `${p} matches a shape that is not allowed here`;
     default:
       return `${p} ${err.message ?? "is invalid"}`;
   }
@@ -130,11 +172,13 @@ function describeAlternatives(errors: AjvErrorLike[], unionInstancePath: string)
 }
 
 /** Is this branch a plausible reading of the value — does it accept the value's
- *  shape at the union node itself, and only disagree further in? */
+ *  shape at the union node itself, and agree with every discriminator it pins? */
 function isPlausible(errors: AjvErrorLike[], unionInstancePath: string): boolean {
-  return !errors.some(
-    (e) => (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(e.keyword ?? ""),
-  );
+  return !errors.some((e) => {
+    const keyword = e.keyword ?? "";
+    if (DISCRIMINATOR_KEYWORDS.has(keyword)) return true;
+    return (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(keyword);
+  });
 }
 
 /**
@@ -392,7 +436,7 @@ export function ajvErrorToPath(err: AjvErrorLike): string {
   let result = "";
   for (const part of parts) {
     if (/^\d+$/.test(part)) result += `[${part}]`;
-    else result += result ? `.${part}` : part;
+    else result += result ? `.${unescapeSegment(part)}` : unescapeSegment(part);
   }
   if (err.keyword === "required" && err.params?.missingProperty) {
     const missing = err.params.missingProperty as string;

package/src/schema-keywords.ts

@@ -386,7 +386,10 @@ export const TELO_SCHEMA_ANNOTATIONS: Record<
   },
   "x-telo-catches-for": {
     title: "Catches for",
-    description: "Names the field whose failures this branch list handles.",
+    description:
+      "Whose failures this catch list renders: a sibling field naming the handler, " +
+      "or the EMPTY string for everything this resource drives — a scope-level list, " +
+      "which owes coverage of nothing itself and answers for every site it encloses.",
     type: "string",
   },
 };

package/src/schema-walk.ts

@@ -9,6 +9,8 @@
  * scope rule is consumed by the IDE, which must not pull the pass in behind it.
  */
 import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
+import { readRefSlot, type RefSlot } from "./ref-slot.js";
+import { readStepSlot, type StepSlot } from "./step-slot.js";
 
 /** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
  *  Non-refs and unresolved refs pass through unchanged. */
@@ -142,3 +144,57 @@ export function walkStepArray(
     }
   });
 }
+/** A slot through which a resource drives another. */
+export type DrivenSlot =
+  | { kind: "step"; slot: StepSlot; data: unknown[]; path: string }
+  | { kind: "ref"; slot: RefSlot; data: unknown; path: string };
+
+/**
+ * Every slot of one resource through which it drives another, schema and data in
+ * tandem.
+ *
+ * One traversal with two consumers — the inherited union here, and the catch
+ * scope enclosure in `validate-throws-coverage.ts` — because both ask the same
+ * structural question and two copies would eventually disagree about where the
+ * walk stops. It terminates on the manifest's own depth, and it stops AT a step
+ * slot (that traversal owns everything below it, `try`/`catch` subtraction
+ * included) and AT a reference slot (a resolved ref is a leaf, `{kind, name}`,
+ * with nothing beneath it to visit).
+ */
+export function forEachDrivenSlot(
+  schema: unknown,
+  data: unknown,
+  visit: (slot: DrivenSlot) => void,
+  path = "",
+): void {
+  if (!schema || typeof schema !== "object" || data === undefined || data === null) return;
+  const node = schema as Record<string, any>;
+
+  const stepSlot = readStepSlot(node);
+  if (stepSlot) {
+    if (Array.isArray(data)) visit({ kind: "step", slot: stepSlot, data, path });
+    return;
+  }
+
+  const refSlot = readRefSlot(node);
+  if (refSlot) {
+    visit({ kind: "ref", slot: refSlot, data, path });
+    return;
+  }
+
+  const props = node.properties as Record<string, any> | undefined;
+  if (props && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data as Record<string, unknown>;
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (obj[key] === undefined) continue;
+      forEachDrivenSlot(propSchema, obj[key], visit, path ? `${path}.${key}` : key);
+    }
+  }
+
+  if (node.items && Array.isArray(data)) {
+    for (const [i, item] of data.entries()) {
+      forEachDrivenSlot(node.items, item, visit, `${path}[${i}]`);
+    }
+  }
+}
+

package/src/telo-version.ts

@@ -6,4 +6,4 @@
 // written against, and every kernel in every language reports the same scale.
 
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.86.0";
+export const TELO_SURFACE_VERSION = "0.88.0";

package/src/template-body.ts

@@ -2,6 +2,7 @@ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import type { ModuleScopes } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 /**
  * A `Telo.Definition`'s `resources:` entries — the bodies a kind writes for
@@ -47,11 +48,7 @@ export function templateBodies(
   // A nested kind is written through the alias scope of the module that DECLARED
   // the definition, never the consumer's — the same rule every other kind
   // resolution in a forwarded manifest follows.
-  const ownModule = (m.metadata as { module?: string } | undefined)?.module;
-  const scope =
-    (ownModule && scopes && !scopes.rootModules.has(ownModule)
-      ? scopes.aliasesByModule.get(ownModule)
-      : undefined) ?? aliases;
+  const scope = moduleAliasScope(m.metadata, aliases, scopes?.aliasesByModule);
 
   const out: TemplateBody[] = [];
   for (let i = 0; i < bodies.length; i++) {