@telorun/analyzer 0.71.0 → 0.72.0

package/src/analyzer.ts

@@ -24,6 +24,7 @@ import {
   type CelHandlers,
 } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
+import { readDeprecation } from "./deprecation.js";
 import { type ContractDirection, effectiveAuthorSchema } from "./extends-resolution.js";
 import {
   analyzerContractScope,
@@ -125,7 +126,12 @@ import {
   type SchemaIssue,
 } from "./schema-compat.js";
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
-import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
+import {
+  DiagnosticSeverity,
+  DiagnosticTag,
+  type AnalysisDiagnostic,
+  type AnalysisOptions,
+} from "./types.js";
 import {
   extractAccessChains,
   extractContextsFromSchema,
@@ -1535,6 +1541,7 @@ export class StaticAnalyzer {
           aliases,
           rootModules,
           getCallGraph(),
+          { aliasesByModule, rootModules },
         ),
       );
       // A file embed resolves at resource creation, so one written on a doc that
@@ -1911,6 +1918,52 @@ export class StaticAnalyzer {
         continue;
       }
 
+      // A kind its own author marked `metadata.deprecated` still works exactly as
+      // it did — the manifest is valid and keeps running — so this is a WARNING,
+      // reported at the declaration because `kind:` is the line that has to
+      // change. Emitted here rather than in a pass of its own so it reads the
+      // kind THIS walk resolved: the resolution is alias- and gate-aware and
+      // scope-dependent, and a second implementation of it would eventually
+      // disagree about which definition a name means.
+      //
+      // Entry-module-scoped, like every other "not the consumer's to fix" check:
+      // a library's internal use of a kind its own author deprecated is that
+      // author's concern, and reporting it floods a consumer with lines they
+      // cannot act on.
+      //
+      // No `DiagnosticFix`. `replacedBy` names a kind through the DECLARING
+      // module's aliases; writing it into the consumer's file would produce a
+      // prefix that resolves to nothing there — and a kind swap is not a
+      // whole-value replacement anyway, since the successor needs its own import
+      // and usually a different configuration.
+      const deprecation = readDeprecation(definition.metadata);
+      if (deprecation && (!ownModule || rootModules.has(ownModule))) {
+        // Quoted CANONICALLY, not verbatim: `Self.Thing` is how the declaring
+        // library names its own kind and means nothing where the warning lands.
+        const declaringScope =
+          scopeResolverForModule(
+            (definition.metadata as { module?: string } | undefined)?.module,
+            rootModules,
+            aliasesByModule,
+          ) ?? aliases;
+        const replacement = deprecation.replacedBy
+          ? (declaringScope.resolveKind(deprecation.replacedBy) ?? deprecation.replacedBy)
+          : undefined;
+        diagnostics.push({
+          severity: DiagnosticSeverity.Warning,
+          code: "DEPRECATED_KIND",
+          source: SOURCE,
+          // Warning-grade AND a deprecation: the severity says it must
+          // eventually be dealt with, the tag says what it is, and an editor
+          // strikes the kind through on the strength of the second.
+          tags: [DiagnosticTag.Deprecated],
+          message:
+            `Kind '${m.kind}' is deprecated: ${deprecation.reason}` +
+            (replacement ? ` Use '${replacement}' instead.` : ""),
+          data: { resource, filePath, path: "kind" },
+        });
+      }
+
       // Validate resource config against the definition's AUTHOR-FACING schema —
       // inheritance-resolved, with `kind` / `metadata` injected. See
       // `validationSchemaFor`, which is where both derivations and the reason

package/src/catch-scope.ts

@@ -0,0 +1,157 @@
+/**
+ * Which `catches:` lists answer for one dispatch site.
+ *
+ * A catch list is one rung of a SCOPE LADDER — a route's, its router's, its
+ * server's — and every rule over those lists needs the same two answers: what
+ * a scope list is checked against, and which scopes enclose a given site. This
+ * module owns that model; the rule checks in `validate-throws-coverage.ts` read
+ * one answer instead of rebuilding it beside four unrelated jobs.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { DefinitionRegistry } from "./definition-registry.js";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { visitManifest } from "./manifest-visitor.js";
+import { forEachDrivenSlot } from "./schema-walk.js";
+import { resolveRefManifest, type ResolveCtx } from "./resolve-throws-union.js";
+
+/** What a list proves it renders: the codes its coverage-proving `when:` clauses
+ *  name, and whether it ends in a catch-all.
+ *
+ *  Unfiltered by any denominator, because this is also what an enclosing scope
+ *  contributes DOWNWARD — a server entry naming a code the server's own closure
+ *  could not enumerate still renders it for the route that throws it. Filtering
+ *  the local answer against the declared union happens where that answer is
+ *  used, and subtracting from the declared set makes the two equivalent there. */
+export interface ProvenCoverage {
+  codes: Set<string>;
+  hasCatchAll: boolean;
+}
+
+export const NO_COVERAGE: ProvenCoverage = { codes: new Set(), hasCatchAll: false };
+
+/** A declaration inside another resource's `x-telo-scope` array, kept with the
+ *  resource that encloses it and the path it is written at in that resource's
+ *  document. Both are needed: the owner is the only place its kind's alias scope
+ *  can be found, and the only document position lookup can reach. */
+export interface ScopedManifest {
+  manifest: ResourceManifest;
+  owner: ResourceManifest;
+  /** Concrete owner-relative path of the declaration (`with[0]`). */
+  path: string;
+}
+
+/** Every `with:`-scoped declaration in the set, once each.
+ *
+ *  Scoped resources are absent from the flat manifest list, so every check that
+ *  iterates it skips them — and standing a server up around a test is exactly
+ *  that shape, so the sanctioned pattern was the one the pass could not see.
+ *  Discovered through the shared visitor rather than a second scope walk. */
+export function collectScopedManifests(
+  manifests: ResourceManifest[],
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule: Map<string, AliasResolver>,
+  rootModules: Set<string>,
+): ScopedManifest[] {
+  const scoped: ScopedManifest[] = [];
+  visitManifest(
+    manifests,
+    defs,
+    {
+      onScope: (event) => {
+        for (const { manifest, path } of event.declarations) {
+          if (!manifest?.kind || !manifest.metadata?.name) continue;
+          scoped.push({ manifest, owner: event.source, path });
+        }
+      },
+    },
+    { aliases, aliasesByModule, rootModules },
+  );
+  return scoped;
+}
+
+/** Which resources each resource's scope list encloses, along the slots that
+ *  declare `throwsThrough` — one fact stated once, since the edge a throws
+ *  closure crosses is the edge a catch scope encloses through. */
+export function buildEnclosers(
+  manifests: ResourceManifest[],
+  definitionOf: (m: ResourceManifest) => { schema?: Record<string, any> } | undefined,
+  moduleOf: (m: ResourceManifest) => string | undefined,
+  ctx: ResolveCtx,
+): Map<ResourceManifest, ResourceManifest[]> {
+  const enclosers = new Map<ResourceManifest, ResourceManifest[]>();
+  for (const manifest of manifests) {
+    const definition = definitionOf(manifest);
+    if (!definition?.schema) continue;
+    forEachDrivenSlot(definition.schema, manifest, (driven) => {
+      if (driven.kind !== "ref" || !driven.slot.throwsThrough) return;
+      const target = resolveRefManifest(driven.data, ctx, moduleOf(manifest));
+      if (!target || target === manifest) return;
+      const list = enclosers.get(target);
+      if (list) list.push(manifest);
+      else enclosers.set(target, [manifest]);
+    });
+  }
+  return enclosers;
+}
+
+/**
+ * What every scope enclosing a resource is guaranteed to render for it.
+ *
+ * **Across enclosers this INTERSECTS, and that is the whole correctness of the
+ * reduction.** Coverage claims that a throw cannot escape unrendered, so it holds
+ * only when EVERY path to the site renders it — a router mounted on a public
+ * server with a catch-all and an internal one without is covered on one path and
+ * bare on the other, and unioning the two reported it as fully covered while the
+ * internal server answered with the built-in envelope. A resource with no
+ * encloser contributes nothing rather than everything: the empty set is the
+ * identity for the site's own coverage, and treating "no paths" as "all paths
+ * agree" would assert coverage no list provides.
+ *
+ * A resource's OWN scope list is unioned in, because it applies on every path.
+ *
+ * Memoized, and a cycle among `throwsThrough` edges resolves to what has been
+ * accumulated so far rather than raising: this answers what a scope renders, and
+ * no cycle makes that answer larger.
+ */
+export function enclosingCoverage(
+  manifest: ResourceManifest,
+  ownScope: Map<ResourceManifest, ProvenCoverage>,
+  enclosers: Map<ResourceManifest, ResourceManifest[]>,
+  memo: Map<ResourceManifest, ProvenCoverage> = new Map(),
+  walking: Set<ResourceManifest> = new Set(),
+): ProvenCoverage {
+  const cached = memo.get(manifest);
+  if (cached) return cached;
+  if (walking.has(manifest)) return NO_COVERAGE;
+  walking.add(manifest);
+  try {
+    const own = ownScope.get(manifest);
+    const result: ProvenCoverage = {
+      codes: new Set(own?.codes ?? []),
+      hasCatchAll: own?.hasCatchAll ?? false,
+    };
+
+    const outer = (enclosers.get(manifest) ?? []).map((e) =>
+      enclosingCoverage(e, ownScope, enclosers, memo, walking),
+    );
+    if (outer.length > 0) {
+      const [first, ...rest] = outer;
+      const shared = new Set(first.codes);
+      let everyCatchAll = first.hasCatchAll;
+      for (const other of rest) {
+        for (const code of [...shared]) if (!other.codes.has(code)) shared.delete(code);
+        everyCatchAll &&= other.hasCatchAll;
+      }
+      for (const code of shared) result.codes.add(code);
+      if (everyCatchAll) result.hasCatchAll = true;
+    }
+
+    memo.set(manifest, result);
+    return result;
+  } finally {
+    walking.delete(manifest);
+  }
+}

package/src/deprecation.ts

@@ -0,0 +1,36 @@
+/**
+ * `metadata.deprecated` — the annotation's single reader.
+ *
+ * Structural validity belongs to `validate-module-metadata.ts` (the strict half,
+ * the `ref-slot.ts` split). This side is deliberately lenient: it reads a
+ * well-formed block and treats everything else as absent, so a malformed
+ * declaration in a published dependency never becomes a warning at a consumer's
+ * use site. The consumer can fix neither one, and reporting the second blames
+ * the wrong author.
+ */
+
+/** A deprecation as declared: why, and optionally what to use instead. */
+export interface Deprecation {
+  /** What a consumer reads to know what to do instead. Always non-empty. */
+  reason: string;
+  /** Alias-qualified kind (kind docs) or module ref (module docs), **as written
+   *  in the declaring file's own scope** — `Self.Thing` means nothing to a
+   *  consumer, so a use site resolves it before quoting it. */
+  replacedBy?: string;
+}
+
+export function readDeprecation(metadata: unknown): Deprecation | undefined {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) return undefined;
+  const block = (metadata as Record<string, unknown>).deprecated;
+  if (block === null || typeof block !== "object" || Array.isArray(block)) return undefined;
+
+  const { reason, replacedBy } = block as Record<string, unknown>;
+  if (typeof reason !== "string" || reason.trim() === "") return undefined;
+
+  return {
+    reason: reason.trim(),
+    ...(typeof replacedBy === "string" && replacedBy.trim() !== ""
+      ? { replacedBy: replacedBy.trim() }
+      : {}),
+  };
+}

package/src/index.ts

@@ -185,6 +185,8 @@ export {
 export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
 export { isStepSlot, readStepSlot, STEP_FRAGMENT } from "./step-slot.js";
 export type { StepSlot } from "./step-slot.js";
+export { readDeprecation } from "./deprecation.js";
+export type { Deprecation } from "./deprecation.js";
 export {
   ANNOTATION_KEYWORDS,
   registerTeloKeywords,
@@ -489,7 +491,12 @@ export type { CelScopeQueryContext, ContextDeclarationSite } from "./cel-scope-q
 export { navigateConcretePath } from "./manifest-path.js";
 export { ManifestAnalysis } from "./manifest-analysis.js";
 export type { ManifestRef } from "./manifest-analysis.js";
-export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
+export {
+  DEFAULT_MANIFEST_FILENAME,
+  DiagnosticSeverity,
+  DiagnosticTag,
+  diagnosticFix,
+} from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions,

package/src/manifest-visitor.ts

@@ -66,8 +66,21 @@ export interface ScopeBoundaryEvent {
   source: ResourceManifest;
   /** Dot-form prefixes of every `x-telo-scope` field on this resource. */
   scopePrefixes: string[];
-  /** Scope-field JSON Pointer → manifests declared within that scope. */
+  /** VISIBILITY pointer (an `x-telo-scope` entry, e.g. `/steps`) → the manifests
+   *  visible there. Keyed by where scoped names may be REFERENCED, which is not
+   *  where they are DECLARED: `Run.Sequence` declares `x-telo-scope:
+   *  ["/steps", "/targets"]` on its `with:` field, so one declaration appears
+   *  under two keys and neither names `with`. Use {@link declarations} for the
+   *  declaration site. */
   manifestsByPointer: Map<string, ResourceManifest[]>;
+  /** Every inline declaration inside this resource's scopes, ONCE each, with the
+   *  concrete path it is written at in the owner's document (`with[0]`).
+   *
+   *  A diagnostic about a scoped resource has to anchor there: the resource is
+   *  not a top-level document, so position lookup finds the OWNER and then walks
+   *  this path into it. Deriving one from a visibility pointer instead names a
+   *  region the declaration is not in (`steps[0]`). */
+  declarations: { manifest: ResourceManifest; path: string }[];
   /** Names of every resource declared inside this resource's scopes. Used by
    *  the dependency graph to drop boot edges to scoped (on-demand) targets. */
   enclosedNames: Set<string>;
@@ -271,6 +284,7 @@ export function visitManifest(
       if (refScopeMap && (wantsRefs || wantsScope)) {
         const manifestsByPointer = new Map<string, ResourceManifest[]>();
         const scopeRefEntries: { path: string; refName: string }[] = [];
+        const declarations: { manifest: ResourceManifest; path: string }[] = [];
         for (const [fieldPath, entry] of refScopeMap) {
           if (!isScopeEntry(entry)) continue;
           const raw: ResourceManifest[] = [];
@@ -278,6 +292,7 @@ export function visitManifest(
             const items = Array.isArray(fe.value) ? fe.value : [fe.value];
             items.forEach((v, i) => {
               if (!v || typeof v !== "object") return;
+              const declarationPath = Array.isArray(fe.value) ? `${fe.path}[${i}]` : fe.path;
               // A scope entry must be an inline resource definition; a `!ref`
               // (tagged sentinel or resolved `{kind, name}`) is not — record it
               // so a static diagnostic flags it instead of registering a
@@ -288,12 +303,13 @@ export function visitManifest(
                 (typeof rec.kind === "string" && typeof rec.name === "string")
               ) {
                 scopeRefEntries.push({
-                  path: Array.isArray(fe.value) ? `${fe.path}[${i}]` : fe.path,
+                  path: declarationPath,
                   refName: isRefSentinel(v) ? v.source : String(rec.name),
                 });
                 return;
               }
               raw.push(v as ResourceManifest);
+              declarations.push({ manifest: v as ResourceManifest, path: declarationPath });
             });
           }
           const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
@@ -313,6 +329,7 @@ export function visitManifest(
             source: r,
             scopePrefixes,
             manifestsByPointer,
+            declarations,
             enclosedNames,
             scopeRefEntries,
           });

package/src/migrations/report.ts

@@ -21,7 +21,7 @@ import type {
   MigrationPath,
   MigrationRewrite,
 } from "./types.js";
-import type { AnalysisDiagnostic, DiagnosticFix } from "../types.js";
+import { DiagnosticTag, type AnalysisDiagnostic, type DiagnosticFix } from "../types.js";
 
 /** One patch that applied, as the reporting side needs to see it. */
 export interface AppliedPatch {
@@ -63,6 +63,10 @@ export function toDiagnostic(
     severity: applied.entry.severity,
     code: applied.entry.code,
     source: "telo-analyzer",
+    // A migration IS a deprecation — a legacy spelling still read, and the one
+    // an author is being asked to stop writing — so the range carries the tag
+    // whatever severity the entry chose for itself.
+    tags: [DiagnosticTag.Deprecated],
     message: `${rewrite.summary}\n${applied.entry.reason}\n${closing}`,
     data: {
       filePath: source,

package/src/ref-slot.ts

@@ -94,6 +94,21 @@ export interface RefSlot {
    *  that carries this call's arguments. Replaces
    *  `x-telo-topology-role: inputs`. */
   inputs?: string;
+  /** Throws raised by the target — or by anything the target drives — surface
+   *  through the DECLARING resource, so its own throws union includes the
+   *  target's and its catch scope encloses the target's.
+   *
+   *  It exists because the relation is real where `use` correctly says nothing:
+   *  `Http.Server.mounts[].mount` is a `dependency` (the server holds the mount
+   *  and calls a convention method on it — control reaches a route through the
+   *  MOUNT's own `trigger.inbound` slot, not through this one), yet a throw from
+   *  that route is exactly what the server renders. Following every `dependency`
+   *  edge instead would drag a connection's throws into a router's denominator.
+   *
+   *  Declared by the kind that HOLDS, because only it knows the throws surface
+   *  through it, and it is the same fact its runtime establishes by rethrowing —
+   *  so the annotation and the behaviour cannot disagree. */
+  throwsThrough?: boolean;
   /** `x-telo-inline: true` on the slot or any `anyOf` branch — accepts an inline
    *  `{kind, ...config}` definition, not only a `!ref`. */
   inline: boolean;
@@ -228,6 +243,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
   const uses = new Set<RefUse>();
   let useCases: RefUseCases | undefined;
   let inputs: string | undefined;
+  let throwsThrough = false;
 
   for (const carrier of nodes) {
     const annotation = carrier["x-telo-ref"];
@@ -239,6 +255,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
     for (const use of normalizeUses(obj.use)) uses.add(use);
     useCases ??= readUseCases(obj.use);
     if (typeof obj.inputs === "string") inputs ??= obj.inputs;
+    if (obj.throwsThrough === true) throwsThrough = true;
   }
 
   const slot: RefSlot = {
@@ -249,6 +266,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
   };
   if (useCases) slot.useCases = useCases;
   if (inputs !== undefined) slot.inputs = inputs;
+  if (throwsThrough) slot.throwsThrough = true;
   return slot;
 }
 
@@ -274,6 +292,7 @@ export function refSlotAnnotation(slot: RefSlot): Record<string, unknown> {
   else if (slot.uses.length === 1) annotation.use = slot.uses[0];
   else if (slot.uses.length > 1) annotation.use = slot.uses;
   if (slot.inputs !== undefined) annotation.inputs = slot.inputs;
+  if (slot.throwsThrough) annotation.throwsThrough = true;
   return annotation;
 }
 

package/src/resolve-throws-union.ts

@@ -4,7 +4,9 @@ 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>;
@@ -263,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,
@@ -284,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,
@@ -410,9 +482,32 @@ 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;
+  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
@@ -422,7 +517,7 @@ function resolveStepInvokeThrows(
   // its consumer and get the consumer's `catches:` rejected for the code the
   // entry point documents.
   if (!invokedKind) {
-    const sentinel = refSentinelTarget(invokeRef);
+    const sentinel = refSentinelTarget(ref);
     if (!sentinel) return emptyUnion();
     const target = findSentinelTarget(ctx, sentinel, ownerModule);
     if (target) return resolveThrowsUnion(target, ctx);
@@ -430,32 +525,19 @@ function resolveStepInvokeThrows(
   }
 
   // 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 = findTarget(
-      ctx,
-      invokeName,
-      ownerModule,
-      (m) =>
-        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
@@ -466,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/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) =>