@telorun/analyzer 0.13.0 → 0.14.0

package/dist/validate-references.js

@@ -4,6 +4,7 @@ import { isInlineResource, resolveFieldEntries, resolveFieldValues } from "./ref
 import { navigateJsonPointer } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
+import { isModuleKind } from "./module-kinds.js";
 const SOURCE = "telo-analyzer";
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -95,10 +96,41 @@ export function validateReferences(resources, context) {
     // source, different sourceLine) keep separate fingerprints and still
     // trip the diagnostic. `analyze()` enforces that every non-system
     // manifest carries both positional fields — no defensive guard needed.
+    // Forwarded foreign exports (an imported library's exported instances, carrying a
+    // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
+    // duplicate detection and local name resolution, and never walked as ref sources.
+    const rootModules = new Set();
+    for (const r of resources) {
+        if (isModuleKind(r.kind) && typeof r.metadata?.name === "string") {
+            rootModules.add(r.metadata.name);
+        }
+    }
+    const moduleOf = (r) => r.metadata?.module;
+    const isForeign = (r) => {
+        const mod = moduleOf(r);
+        return typeof mod === "string" && !rootModules.has(mod);
+    };
+    const byModuleName = new Map();
+    for (const r of resources) {
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+            continue;
+        byModuleName.set(`${moduleOf(r)}\0${r.metadata.name}`, r);
+    }
+    /** Whether the analysis set actually carries the named module's exported instances.
+     *  False in partial single-file analysis (the import subtree wasn't loaded) — used to
+     *  skip cross-module resolution checks rather than emit false `UNRESOLVED_REFERENCE`. */
+    const moduleLoaded = (module) => {
+        const prefix = `${module}\0`;
+        for (const key of byModuleName.keys())
+            if (key.startsWith(prefix))
+                return true;
+        return false;
+    };
+    const localResources = resources.filter((r) => !isForeign(r));
     const byNameAll = new Map();
     const seen = new Set();
     for (const r of resources) {
-        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import")
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import" || isForeign(r))
             continue;
         const name = r.metadata.name;
         // `analyze()` guarantees both fields are present on non-system manifests.
@@ -140,6 +172,32 @@ export function validateReferences(resources, context) {
             });
         }
     }
+    // A resource name must contain no dot. The `!ref` resolver splits the tag's source on
+    // the first dot to separate an import alias from the resource name, so a dotted name
+    // would mis-resolve into a cross-module lookup. This is the load-bearing invariant of
+    // the reference grammar, so it is enforced here rather than left to the (unenforced)
+    // casing convention.
+    for (const [name, list] of byNameAll) {
+        if (!name.includes("."))
+            continue;
+        for (const r of list) {
+            const m = r.metadata;
+            const range = typeof m?.sourceLine === "number"
+                ? {
+                    start: { line: m.sourceLine, character: 0 },
+                    end: { line: m.sourceLine, character: Number.MAX_SAFE_INTEGER },
+                }
+                : undefined;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "INVALID_RESOURCE_NAME",
+                source: SOURCE,
+                message: `${r.kind}/${name}: resource name must not contain '.' — in a '!ref' the '.' separates an import alias from the resource name`,
+                ...(range ? { range } : {}),
+                data: { resource: { kind: r.kind, name }, filePath: m?.source, path: "metadata.name" },
+            });
+        }
+    }
     // Single-resource map for the resolution / scope lookups below — when a
     // collision exists, falling back to the first occurrence keeps the rest
     // of the pass behaving the same as before the duplicate diagnostic was
@@ -152,7 +210,7 @@ export function validateReferences(resources, context) {
     // resolved against the schema-from-expanded field map, with its source
     // enclosure (`inScope`) and the scope manifests visible to it — so this
     // handler only validates, it does not re-walk.
-    visitManifest(resources, registry, {
+    visitManifest(localResources, registry, {
         onRef: (e) => {
             const r = e.source;
             const resourceLabel = `${r.kind}/${r.metadata.name}`;
@@ -166,13 +224,35 @@ export function validateReferences(resources, context) {
             // string/inline ambiguity at the source.
             if (isRefSentinel(val)) {
                 const refName = val.source;
-                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                const dot = refName.indexOf(".");
+                const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+                // Cross-module sentinel left unresolved by Phase 2.5 — it qualifies an import
+                // alias. If that module's exports are loaded in this analysis, the miss is real
+                // (name not in exports.resources, or a typo); if not (partial single-file
+                // analysis), skip rather than emit a false UNRESOLVED_REFERENCE.
+                if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+                    const module = aliases.moduleForAlias(aliasPrefix);
+                    if (module && !moduleLoaded(module))
+                        return;
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "UNRESOLVED_REFERENCE",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${concretePath}' → '${refName}' is not exported by module '${module ?? aliasPrefix}' (add it to exports.resources)`,
+                        data: { resource: resourceData, filePath, path: concretePath },
+                    });
+                    return;
+                }
+                // Local reference (bare name or explicit `Self.`-qualified).
+                const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+                const target = byName.get(localName) ??
+                    visibleScopeManifests.find((m) => m.metadata?.name === localName);
                 if (!target) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${localName}' not found`,
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
                     return;
@@ -232,6 +312,13 @@ export function validateReferences(resources, context) {
             // Skip inline resources — Phase 2 normalization hasn't run yet.
             if (isInlineResource(refVal))
                 return;
+            // Polymorphic ref slots (Application `targets`) accept object forms
+            // whose references live in nested slots rather than being a `{kind,
+            // name}` ref themselves — inline `{ invoke }` and gated `{ ref }`.
+            // Those nested refs are validated via their own field-map entries, so
+            // skip the item-level structural check here.
+            if (typeof refVal.kind !== "string" && ("invoke" in refVal || "ref" in refVal))
+                return;
             // 1. Structural check
             if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
                 diagnostics.push({
@@ -255,8 +342,19 @@ export function validateReferences(resources, context) {
                 });
             }
             // 3. Resolution check — resource with this name must exist.
-            const exists = byName.has(refVal.name) ||
-                visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+            let exists;
+            if (typeof refVal.alias === "string" && refVal.alias !== "Self") {
+                // Cross-module ref resolved by Phase 2.5. Validate against the forwarded
+                // exports when loaded; in partial context (module not loaded) assume resolvable.
+                const module = aliases.moduleForAlias(refVal.alias);
+                exists =
+                    !module || !moduleLoaded(module) || byModuleName.has(`${module}\0${refVal.name}`);
+            }
+            else {
+                exists =
+                    byName.has(refVal.name) ||
+                        visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+            }
             if (!exists) {
                 diagnostics.push({
                     severity: DiagnosticSeverity.Error,
@@ -273,7 +371,7 @@ export function validateReferences(resources, context) {
     // concrete kind, navigate the JSON Pointer into that kind's definition schema, and
     // validate the field value against the resulting sub-schema. Driven off the base map
     // (un-expanded) so each schema-from slot is seen as its own site.
-    visitManifest(resources, registry, {
+    visitManifest(localResources, registry, {
         onSchemaFrom: (e) => {
             const r = e.source;
             const fieldPath = e.fieldPath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.3.1"
+    "@telorun/templating": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -50,7 +50,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "0.13.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",

package/src/analysis-registry.ts

@@ -73,7 +73,7 @@ export class AnalysisRegistry {
   visitManifest(
     resources: ResourceManifest[],
     visitor: ManifestVisitor,
-    opts?: { skipKinds?: ReadonlySet<string>; expand?: boolean },
+    opts?: { skipKinds?: ReadonlySet<string>; expand?: boolean; discoverNestedRefs?: boolean },
   ): void {
     runVisitManifest(resources, this.defs, visitor, {
       aliases: this.aliases,

package/src/analyzer.ts

@@ -379,6 +379,78 @@ function buildStepContextSchema(
   return undefined;
 }
 
+/**
+ * Collect every field annotated with `x-telo-error-context` anywhere in a
+ * definition schema (resolving local `$ref`s into `$defs`, cycle-safe), mapping
+ * the annotated field name to its declared error-shape schema. The field name
+ * is matched against CEL paths so the context applies at any nesting depth under
+ * that field — e.g. `error` inside a `catch:` nested inside another `try:`. No
+ * specific field name (or `Run.Sequence`) is hardcoded; any composer that tags
+ * its error-bearing branch fields opts in the same way.
+ */
+function collectErrorContextScopes(
+  defSchema: Record<string, any> | undefined,
+): Map<string, Record<string, any>> {
+  const out = new Map<string, Record<string, any>>();
+  if (!defSchema || typeof defSchema !== "object") return out;
+  const seen = new Set<Record<string, any>>();
+
+  const walk = (schema: Record<string, any> | undefined): void => {
+    if (!schema || typeof schema !== "object" || seen.has(schema)) return;
+    seen.add(schema);
+
+    const props = schema.properties as Record<string, any> | undefined;
+    if (props) {
+      for (const [fieldName, fieldSchema] of Object.entries(props)) {
+        if (fieldSchema && typeof fieldSchema === "object") {
+          const errCtx = (fieldSchema as Record<string, any>)["x-telo-error-context"];
+          if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+            out.set(fieldName, errCtx as Record<string, any>);
+          }
+        }
+        walk(resolveLocalRef(fieldSchema as Record<string, any>, defSchema));
+      }
+    }
+    if (schema.items) walk(resolveLocalRef(schema.items as Record<string, any>, defSchema));
+    for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+      const arr = schema[key];
+      if (Array.isArray(arr)) for (const sub of arr) walk(resolveLocalRef(sub, defSchema));
+    }
+    if (schema.$defs && typeof schema.$defs === "object") {
+      for (const sub of Object.values(schema.$defs as Record<string, any>)) {
+        walk(sub as Record<string, any>);
+      }
+    }
+  };
+
+  walk(defSchema);
+  return out;
+}
+
+/**
+ * Return the error-context schema for a CEL `path` when the path lies within
+ * (any depth under) one of the error-bearing fields, else undefined. A path is
+ * "within" field `f` when it contains a segment `f[<index>]`. When multiple
+ * error-bearing fields match (e.g. a `finally` nested inside a `catch`), the
+ * deepest — the one whose segment appears latest in the path — wins, so the
+ * innermost branch's schema governs.
+ */
+function errorContextForPath(
+  path: string,
+  scopes: Map<string, Record<string, any>>,
+): Record<string, any> | undefined {
+  let best: { index: number; schema: Record<string, any> } | undefined;
+  for (const [fieldName, schema] of scopes) {
+    const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    for (const match of path.matchAll(new RegExp(`(^|\\.)${escaped}\\[\\d+\\]`, "g"))) {
+      if (best === undefined || match.index > best.index) {
+        best = { index: match.index, schema };
+      }
+    }
+  }
+  return best?.schema;
+}
+
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 
@@ -954,6 +1026,7 @@ export class StaticAnalyzer {
     // context — which require analyzer state to build — are stashed here.
     let celStepContextSchema: Record<string, any> | undefined;
     let celInvocationContext: Record<string, any> | undefined;
+    let celErrorScopes: Map<string, Record<string, any>> = new Map();
 
     visitManifest(
       allManifests,
@@ -973,6 +1046,9 @@ export class StaticAnalyzer {
                 aliases,
               )
             : undefined;
+          celErrorScopes = collectErrorContextScopes(
+            e.definition?.schema as Record<string, any> | undefined,
+          );
         },
         onCel: (e) => {
           const m = e.source;
@@ -995,6 +1071,22 @@ export class StaticAnalyzer {
             };
           }
 
+          // `error` is only in scope inside an error-bearing branch (e.g. a
+          // `catch:` / `finally:`), so it's merged per-path, not resource-wide.
+          const errorSchema =
+            celErrorScopes.size > 0 ? errorContextForPath(path, celErrorScopes) : undefined;
+          if (errorSchema) {
+            const base =
+              matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
+            matchedContext = {
+              ...base,
+              properties: {
+                ...(base.properties ?? {}),
+                error: errorSchema,
+              },
+            };
+          }
+
           let effectiveContext: Record<string, any> | null = null;
           if (matchedContext) {
             const manifestItem = matchedScope
@@ -1046,6 +1138,14 @@ export class StaticAnalyzer {
                 message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
                 data: { resource, filePath, path },
               });
+            } else if (f.code === "CEL_NULLABLE_ACCESS") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CEL_NULLABLE_ACCESS",
+                source: SOURCE,
+                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
+                data: { resource, filePath, path },
+              });
             } else {
               // Unknown code from a future engine — pass the message through,
               // tagged with a generic ENGINE_DIAGNOSTIC code so downstream

package/src/builtins.ts

@@ -234,6 +234,66 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 },
                 additionalProperties: true,
               },
+              // Gated reference: run() a Runnable/Service only when the
+              // `when` CEL guard holds. Discriminated by the `ref` key. `ref`
+              // is a bare name or a resolved `!ref` (`{ kind, name }`).
+              {
+                type: "object",
+                required: ["ref"],
+                properties: {
+                  ref: {
+                    anyOf: [
+                      { type: "string", "x-telo-ref": "telo#Runnable" },
+                      { type: "string", "x-telo-ref": "telo#Service" },
+                      {
+                        type: "object",
+                        required: ["kind", "name"],
+                        properties: {
+                          kind: { type: "string" },
+                          name: { type: "string" },
+                        },
+                        additionalProperties: true,
+                      },
+                    ],
+                  },
+                  when: { type: "string" },
+                },
+                additionalProperties: false,
+              },
+              // Inline flat invoke step: invoke an Invocable / Runnable on boot
+              // with an optional `name` (for steps.<name>.result plumbing),
+              // `when` guard, and `inputs`. Discriminated by the `invoke` key.
+              // Control flow (if/while/switch/try) is not available here —
+              // reach for Run.Sequence. `invoke` is ref-only and must resolve
+              // to a `{ kind, name }` reference (a `!ref` / `{kind,name}`):
+              // requiring `name` rejects an inline `{ kind }` definition (no
+              // name) at analysis instead of failing at boot with an undefined
+              // resource name. The Invocable/Runnable kind set mirrors
+              // Run.Sequence invoke steps.
+              {
+                type: "object",
+                required: ["invoke"],
+                properties: {
+                  name: { type: "string" },
+                  invoke: {
+                    "x-telo-topology-role": "invoke",
+                    type: "object",
+                    required: ["kind", "name"],
+                    properties: {
+                      kind: { type: "string" },
+                      name: { type: "string" },
+                    },
+                    additionalProperties: true,
+                    anyOf: [
+                      { "x-telo-ref": "telo#Invocable" },
+                      { "x-telo-ref": "telo#Runnable" },
+                    ],
+                  },
+                  inputs: { type: "object", additionalProperties: true },
+                  when: { type: "string" },
+                },
+                additionalProperties: false,
+              },
             ],
           },
         },

package/src/manifest-visitor.ts

@@ -1,5 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { walkCelExpressions } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -80,6 +80,13 @@ export interface RefSiteEvent {
   inScope: boolean;
   /** Scope manifests visible to this ref path (non-empty only when `inScope`). */
   visibleScopeManifests: ResourceManifest[];
+  /** True when the site was found by value-tree scanning rather than the field
+   *  map (only when `discoverNestedRefs` is set) — a ref nested behind a `$ref`
+   *  the field map doesn't descend (e.g. `Run.Sequence` `steps[].invoke`).
+   *  Nested sites carry no x-telo-ref constraint (`entry.refs` is empty) and no
+   *  scope info; `concretePath` still points at the exact location, so consumers
+   *  can anchor to it. */
+  nested?: boolean;
 }
 
 export interface SchemaFromSiteEvent {
@@ -123,6 +130,58 @@ export interface VisitOptions {
    *  so refs nested behind `x-telo-schema-from` are surfaced. `SchemaFromSite`
    *  events are always emitted from the base map regardless of this flag. */
   expand?: boolean;
+  /** When true, additionally discover refs by scanning each resource's value
+   *  tree for `!ref` sentinels and `{kind, name}` reference objects — surfacing
+   *  refs the field map never lists because they sit behind a `$ref` it doesn't
+   *  descend (notably `Run.Sequence` step `invoke`s). Emitted as `RefSite`s with
+   *  `nested: true`, deduped against the field-map sites by concrete path.
+   *  Opt-in: the validators / dependency graph must NOT enable it (those refs
+   *  are runtime-resolved, not boot dependencies). */
+  discoverNestedRefs?: boolean;
+}
+
+/** Synthetic entry for a value-tree-discovered ref — these carry no declared
+ *  x-telo-ref constraint. */
+const NESTED_REF_ENTRY: RefFieldEntry = { refs: [], isArray: false };
+
+/** Scans a value tree for ref-shaped values, emitting each with its concrete
+ *  path. Recognizes `!ref <name>` sentinels and named `{kind, name}` reference
+ *  objects. Other tagged sentinels (`!cel`, `!literal`) and precompiled nodes
+ *  are leaves. Path format matches `resolveFieldEntries` / `walkCelExpressions`
+ *  (`a.b[0].c`).
+ *
+ *  Stops at every `{kind, …}` resource boundary: a named ref is emitted, an
+ *  inline resource (`{kind}` with no name) is left alone, and **neither is
+ *  descended into**. A nested resource's own refs belong to its inner topology,
+ *  not the enclosing node — e.g. an inline `Sql.Exec` step's `connection` is the
+ *  Exec's dependency, not the surrounding `Run.Sequence`'s. The scan is started
+ *  per top-level field (not on the resource object) so the resource's own
+ *  `kind` doesn't trip this boundary. */
+function walkRefValues(
+  value: unknown,
+  path: string,
+  cb: (value: unknown, path: string) => void,
+): void {
+  if (isRefSentinel(value)) {
+    cb(value, path);
+    return;
+  }
+  if (isTaggedSentinel(value)) return;
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => walkRefValues(v, `${path}[${i}]`, cb));
+    return;
+  }
+  if (value === null || typeof value !== "object") return;
+  if ((value as { __compiled?: unknown }).__compiled) return;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.kind === "string") {
+    // Resource boundary — emit if it's a named ref, then stop descending.
+    if (typeof obj.name === "string") cb(value, path);
+    return;
+  }
+  for (const [k, v] of Object.entries(obj)) {
+    walkRefValues(v, path ? `${path}.${k}` : k, cb);
+  }
 }
 
 const scopePrefixOf = (pointer: string): string =>
@@ -139,12 +198,13 @@ export function visitManifest(
   visitor: ManifestVisitor,
   options: VisitOptions = {},
 ): void {
-  const { aliases, aliasesByModule, skipKinds, expand } = options;
+  const { aliases, aliasesByModule, skipKinds, expand, discoverNestedRefs } = options;
 
   const wantsRefs = !!visitor.onRef;
   const wantsScope = !!visitor.onScope;
   const wantsSchemaFrom = !!visitor.onSchemaFrom;
   const wantsCel = !!visitor.onCel;
+  const wantsNested = wantsRefs && !!discoverNestedRefs;
 
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind) continue;
@@ -157,6 +217,10 @@ export function visitManifest(
 
     visitor.onResourceEnter?.({ source: r, definition });
 
+    // Concrete paths emitted from the field map — so the value-tree scan below
+    // doesn't re-emit a ref the field map already covered.
+    const emittedRefPaths = wantsNested ? new Set<string>() : null;
+
     if (wantsRefs || wantsScope || wantsSchemaFrom) {
       const baseMap = aliases
         ? registry.getFieldMapForKind(r.kind, aliases)
@@ -208,6 +272,7 @@ export function visitManifest(
 
             for (const { value, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
               if (!value) continue;
+              emittedRefPaths?.add(concretePath);
               visitor.onRef!({
                 source: r,
                 fieldPath,
@@ -230,6 +295,30 @@ export function visitManifest(
       }
     }
 
+    // Value-tree-driven nested ref discovery — refs the field map can't reach
+    // because they sit behind a `$ref` it doesn't descend (e.g. Run.Sequence
+    // step `invoke`s). Deduped against the field-map sites by concrete path.
+    // Scanned per top-level field so the resource's own `kind` isn't treated as
+    // a resource boundary by `walkRefValues`.
+    if (wantsNested) {
+      const emitNested = (value: unknown, path: string) => {
+        if (emittedRefPaths!.has(path)) return;
+        visitor.onRef!({
+          source: r,
+          fieldPath: path,
+          concretePath: path,
+          value,
+          entry: NESTED_REF_ENTRY,
+          inScope: false,
+          visibleScopeManifests: [],
+          nested: true,
+        });
+      };
+      for (const [key, value] of Object.entries(r as Record<string, unknown>)) {
+        walkRefValues(value, key, emitNested);
+      }
+    }
+
     if (wantsCel) {
       const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
       walkCelExpressions(r, "", (expr, path, engineName) => {

package/src/reference-field-map.ts

@@ -213,6 +213,20 @@ function traverseNode(
     const entry: RefFieldEntry = { refs, isArray: path.includes("[]") };
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
     map.set(path, entry);
+    // A node can mix item-level ref branches (a bare string / `{kind, name}`)
+    // with object branches that carry their OWN nested refs — e.g. Application
+    // `targets`: a bare ref vs inline `{ invoke }` vs gated `{ ref }`. Descend
+    // into the variant objects so those nested slots register too (and their
+    // `!ref` sentinels resolve). Pure x-telo-ref branches have no properties
+    // and contribute nothing here.
+    for (const variantKey of ["oneOf", "anyOf", "allOf"] as const) {
+      const variants = node[variantKey];
+      if (!Array.isArray(variants)) continue;
+      for (const variant of variants) {
+        if (!variant || typeof variant !== "object") continue;
+        traverseVariant(variant as Record<string, any>, path, map, root, visitedRefs);
+      }
+    }
     return;
   }
 

package/src/resolve-throws-union.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
@@ -6,6 +7,11 @@ export interface ThrowsCodeMeta {
   data?: Record<string, any>;
 }
 
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
+
 export interface ThrowsUnion {
   /** Code → per-code metadata (data schema, etc). Keys are the declared codes. */
   codes: Map<string, ThrowsCodeMeta>;
@@ -14,6 +20,12 @@ export interface ThrowsUnion {
    *  an unknown kind was encountered, or a cycle short-circuited resolution.
    *  Callers must treat unbounded unions as requiring a catch-all entry. */
   unbounded: boolean;
+  /** True when the block can fail with a non-`InvokeError` (any `invoke:` step).
+   *  Such a failure surfaces inside an enclosing `catch` as `PLAIN_ERROR_CODE`,
+   *  so a `throw: { code: "${{ error.code }}" }` rethrow can propagate it. Not
+   *  injected into `codes` — only seeds `enclosingTryCodes` at a try/catch site,
+   *  leaving non-rethrow unions untouched. */
+  canThrowPlain?: boolean;
 }
 
 export interface ResolveCtx {
@@ -47,6 +59,7 @@ function unionInto(target: ThrowsUnion, src: ThrowsUnion): void {
     if (!target.codes.has(code)) target.codes.set(code, meta);
   }
   if (src.unbounded) target.unbounded = true;
+  if (src.canThrowPlain) target.canThrowPlain = true;
 }
 
 function definitionFor(
@@ -173,7 +186,11 @@ function collectStepThrows(
   ctx: ResolveCtx,
 ): ThrowsUnion {
   if (step[invokeField]) {
-    return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+    // 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));
+    u.canThrowPlain = true;
+    return u;
   }
 
   if (step.throw && typeof step.throw === "object") {
@@ -188,6 +205,10 @@ function collectStepThrows(
       // out instead. Sequence-specific subtraction — the plan explicitly
       // anchors this to Run.Sequence's try/catch schema shape.
       const tryCodes = new Set(tryUnion.codes.keys());
+      // A plain (non-InvokeError) failure in the try block reaches the catch as
+      // `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);
       // Unbounded in the try block still signals the caller to expect
       // arbitrary codes to flow through the catch (e.g. via passthrough).
@@ -247,6 +268,7 @@ function cloneUnion(u: ThrowsUnion): ThrowsUnion {
   const out = emptyUnion();
   for (const [c, m] of u.codes) out.codes.set(c, m);
   out.unbounded = u.unbounded;
+  if (u.canThrowPlain) out.canThrowPlain = true;
   return out;
 }
 
@@ -316,16 +338,22 @@ function resolveCodeExpression(
   codeInput: unknown,
   enclosingTryCodes: Set<string> | undefined,
 ): ThrowsUnion {
-  if (typeof codeInput !== "string" || codeInput.length === 0) {
+  // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+  // normalize both to the inner CEL expression (or a bare literal code).
+  let expr: string;
+  if (isTaggedSentinel(codeInput)) {
+    if (codeInput.engine !== "cel") return { codes: new Map(), unbounded: true };
+    expr = codeInput.source.trim();
+  } else if (typeof codeInput === "string" && codeInput.length > 0) {
+    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+    if (!match) {
+      return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    }
+    expr = match[1].trim();
+  } else {
     return { codes: new Map(), unbounded: true };
   }
 
-  const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
-  if (!match) {
-    return { codes: new Map([[codeInput, {}]]), unbounded: false };
-  }
-
-  const expr = match[1].trim();
   const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
   if (litMatch) {
     const code = litMatch[1] ?? litMatch[2]!;