@telorun/analyzer 0.13.0 → 1.0.0

package/dist/analysis-registry.d.ts

@@ -33,6 +33,7 @@ export declare class AnalysisRegistry {
     visitManifest(resources: ResourceManifest[], visitor: ManifestVisitor, opts?: {
         skipKinds?: ReadonlySet<string>;
         expand?: boolean;
+        discoverNestedRefs?: boolean;
     }): void;
     /**
      * Returns the built-in kernel definitions. The underlying DefinitionRegistry already

package/dist/analysis-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3D,IAAI;IAQP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}
+{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzF,IAAI;IAQP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA+c/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAyjBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuhB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAqlBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -307,6 +307,73 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
     }
     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) {
+    const out = new Map();
+    if (!defSchema || typeof defSchema !== "object")
+        return out;
+    const seen = new Set();
+    const walk = (schema) => {
+        if (!schema || typeof schema !== "object" || seen.has(schema))
+            return;
+        seen.add(schema);
+        const props = schema.properties;
+        if (props) {
+            for (const [fieldName, fieldSchema] of Object.entries(props)) {
+                if (fieldSchema && typeof fieldSchema === "object") {
+                    const errCtx = fieldSchema["x-telo-error-context"];
+                    if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+                        out.set(fieldName, errCtx);
+                    }
+                }
+                walk(resolveLocalRef(fieldSchema, defSchema));
+            }
+        }
+        if (schema.items)
+            walk(resolveLocalRef(schema.items, defSchema));
+        for (const key of ["oneOf", "anyOf", "allOf"]) {
+            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)) {
+                walk(sub);
+            }
+        }
+    };
+    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, scopes) {
+    let best;
+    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*\}\}/;
 /** Recursively walk `data`+`schema` together, type-checking every pure CEL template
@@ -784,6 +851,7 @@ export class StaticAnalyzer {
         // context — which require analyzer state to build — are stashed here.
         let celStepContextSchema;
         let celInvocationContext;
+        let celErrorScopes = new Map();
         visitManifest(allManifests, defs, {
             onResourceEnter: (e) => {
                 const m = e.source;
@@ -791,6 +859,7 @@ export class StaticAnalyzer {
                 celStepContextSchema = e.definition?.schema
                     ? buildStepContextSchema(m, e.definition.schema, allManifests, defs, aliases)
                     : undefined;
+                celErrorScopes = collectErrorContextScopes(e.definition?.schema);
             },
             onCel: (e) => {
                 const m = e.source;
@@ -808,6 +877,19 @@ 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 = null;
                 if (matchedContext) {
                     const manifestItem = matchedScope
@@ -855,6 +937,15 @@ export class StaticAnalyzer {
                             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/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA0V/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAsZ/C,CAAC"}

package/dist/builtins.js

@@ -232,6 +232,66 @@ export const KERNEL_BUILTINS = [
                                 },
                                 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/dist/manifest-visitor.d.ts

@@ -65,6 +65,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 {
     source: ResourceManifest;
@@ -104,6 +111,14 @@ 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;
 }
 export declare function visitManifest(resources: ResourceManifest[], registry: DefinitionRegistry, visitor: ManifestVisitor, options?: VisitOptions): void;
 //# sourceMappingURL=manifest-visitor.d.ts.map

package/dist/manifest-visitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-visitor.d.ts","sourceRoot":"","sources":["../src/manifest-visitor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manifest-visitor.d.ts","sourceRoot":"","sources":["../src/manifest-visitor.ts"],"names":[],"mappings":"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"}

package/dist/manifest-visitor.js

@@ -1,16 +1,59 @@
-import { walkCelExpressions } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
 import { isRefEntry, isSchemaFromEntry, isScopeEntry, resolveFieldEntries, resolveFieldValues, } from "./reference-field-map.js";
 import { extractContextsFromSchema, pathMatchesScope } from "./validate-cel-context.js";
+/** Synthetic entry for a value-tree-discovered ref — these carry no declared
+ *  x-telo-ref constraint. */
+const NESTED_REF_ENTRY = { 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, path, cb) {
+    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.__compiled)
+        return;
+    const obj = value;
+    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) => pointer.replace(/^\//, "").replace(/\//g, ".");
 const pathUnderPrefix = (fieldPath, prefix) => fieldPath === prefix ||
     fieldPath.startsWith(prefix + ".") ||
     fieldPath.startsWith(prefix + "[");
 export function visitManifest(resources, registry, visitor, options = {}) {
-    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;
@@ -20,6 +63,9 @@ export function visitManifest(resources, registry, visitor, options = {}) {
         const definition = registry.resolve(r.kind) ??
             (resolvedKind ? registry.resolve(resolvedKind) : undefined);
         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() : null;
         if (wantsRefs || wantsScope || wantsSchemaFrom) {
             const baseMap = aliases
                 ? registry.getFieldMapForKind(r.kind, aliases)
@@ -69,6 +115,7 @@ export function visitManifest(resources, registry, visitor, options = {}) {
                         for (const { value, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                             if (!value)
                                 continue;
+                            emittedRefPaths?.add(concretePath);
                             visitor.onRef({
                                 source: r,
                                 fieldPath,
@@ -90,6 +137,30 @@ export function visitManifest(resources, registry, visitor, options = {}) {
                 }
             }
         }
+        // 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, path) => {
+                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)) {
+                walkRefValues(value, key, emitNested);
+            }
+        }
         if (wantsCel) {
             const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
             walkCelExpressions(r, "", (expr, path, engineName) => {

package/dist/reference-field-map.js

@@ -157,6 +157,22 @@ function traverseNode(node, path, map, root, visitedRefs = new Set()) {
         if (node["x-telo-context"])
             entry.context = node["x-telo-context"];
         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"]) {
+            const variants = node[variantKey];
+            if (!Array.isArray(variants))
+                continue;
+            for (const variant of variants) {
+                if (!variant || typeof variant !== "object")
+                    continue;
+                traverseVariant(variant, path, map, root, visitedRefs);
+            }
+        }
         return;
     }
     // Array — recurse into items

package/dist/resolve-throws-union.d.ts

@@ -4,6 +4,10 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 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 declare 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>;
@@ -12,6 +16,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 {
     allManifests: ResourceManifest[];

package/dist/resolve-throws-union.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,GACrB,UAAU,CAQZ;AA+BD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CA+Cb"}
+{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;gFAEgF;AAChF,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;gDAI4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,GACrB,UAAU,CAQZ;AAgCD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CA+Cb"}

package/dist/resolve-throws-union.js

@@ -1,3 +1,8 @@
+import { isTaggedSentinel } from "@telorun/templating";
+/** 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 function createResolveCtx(allManifests, defs, aliases) {
     return {
         allManifests,
@@ -17,6 +22,8 @@ function unionInto(target, src) {
     }
     if (src.unbounded)
         target.unbounded = true;
+    if (src.canThrowPlain)
+        target.canThrowPlain = true;
 }
 function definitionFor(kind, defs, aliases) {
     const resolved = aliases.resolveKind(kind);
@@ -115,7 +122,11 @@ function collectStepArrayThrows(steps, invokeField, enclosingTryCodes, ctx) {
  *  composers that reuse those shape conventions work without changes here. */
 function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
     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") {
         return resolveThrowStepCode(step.throw, enclosingTryCodes);
@@ -128,6 +139,11 @@ function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
             // 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).
@@ -179,6 +195,8 @@ function cloneUnion(u) {
     for (const [c, m] of u.codes)
         out.codes.set(c, m);
     out.unbounded = u.unbounded;
+    if (u.canThrowPlain)
+        out.canThrowPlain = true;
     return out;
 }
 function resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx) {
@@ -226,14 +244,24 @@ function resolveThrowStepCode(throwSpec, enclosingTryCodes) {
     return resolveCodeExpression(throwSpec.code, enclosingTryCodes);
 }
 function resolveCodeExpression(codeInput, enclosingTryCodes) {
-    if (typeof codeInput !== "string" || codeInput.length === 0) {
-        return { codes: new Map(), unbounded: true };
+    // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+    // normalize both to the inner CEL expression (or a bare literal code).
+    let expr;
+    if (isTaggedSentinel(codeInput)) {
+        if (codeInput.engine !== "cel")
+            return { codes: new Map(), unbounded: true };
+        expr = codeInput.source.trim();
     }
-    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
-    if (!match) {
-        return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    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 expr = match[1].trim();
     const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
     if (litMatch) {
         const code = litMatch[1] ?? litMatch[2];

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA0YtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAiZtB"}

package/dist/validate-references.js

@@ -232,6 +232,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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.13.0",
+  "version": "1.0.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": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -50,7 +50,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "1.0.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]!;

package/src/validate-references.ts

@@ -248,6 +248,13 @@ export function validateReferences(
         // 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({