@telorun/analyzer 0.12.1 → 1.0.0

package/dist/dependency-graph.js

@@ -1,5 +1,5 @@
 import { isRefSentinel } from "@telorun/templating";
-import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+import { visitManifest } from "./manifest-visitor.js";
 import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 const nodeKey = (kind, name) => `${kind}\0${name}`;
 /**
@@ -33,68 +33,47 @@ export function buildDependencyGraph(resources, registry, aliases, aliasesByModu
     const deps = new Map();
     for (const key of nodes.keys())
         deps.set(key, new Set());
-    for (const r of resources) {
-        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
-            continue;
-        const sourceKey = nodeKey(r.kind, r.metadata.name);
-        // Use the expanded map so refs nested behind x-telo-schema-from contribute
-        // edges to the DAG. Without these, a parent (e.g. Http.Server) can init
-        // before its extracted encoder and Phase 5 injection fires against a
-        // not-yet-created dependency.
-        const fieldMap = aliases && aliasesByModule
-            ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
-            : registry.getFieldMapForKind(r.kind, aliases);
-        if (!fieldMap)
-            continue;
-        // Collect names of resources declared inside scope fields — these are initialized
-        // on-demand at runtime, not at boot, so edges pointing to them are excluded from the DAG.
-        const scopedNames = new Set();
-        for (const [scopeFieldPath, entry] of fieldMap) {
-            if (!isScopeEntry(entry))
-                continue;
-            const scopeVal = r[scopeFieldPath];
-            if (!Array.isArray(scopeVal))
-                continue;
-            for (const item of scopeVal) {
-                const name = item?.metadata?.name;
-                if (typeof name === "string")
-                    scopedNames.add(name);
+    // Names of resources declared inside the *current* resource's scope fields —
+    // initialized on-demand at runtime, not at boot, so edges pointing to them
+    // are excluded. Scoping is per-source-resource: an edge A → B is dropped only
+    // when B is declared inside A's own scope (the visitor's ScopeBoundary fires
+    // before that resource's RefSites, so this is set before any edge is added).
+    let scopedNames = new Set();
+    // Expanded map so refs nested behind x-telo-schema-from contribute edges to
+    // the DAG. Without these, a parent (e.g. Http.Server) can init before its
+    // extracted encoder and Phase 5 injection fires against a not-yet-created
+    // dependency.
+    visitManifest(resources, registry, {
+        onScope: (e) => {
+            scopedNames = e.enclosedNames;
+        },
+        onRef: (e) => {
+            const sourceKey = nodeKey(e.source.kind, e.source.metadata.name);
+            const val = e.value;
+            // `!ref <name>` sentinel — look up the target's kind from the name
+            // (resources are unique by name) so the edge carries the concrete kind,
+            // matching the {kind, name} edge shape below.
+            if (isRefSentinel(val)) {
+                const refName = val.source;
+                if (scopedNames.has(refName))
+                    return;
+                const node = nodesByName.get(refName);
+                if (node)
+                    deps.get(sourceKey).add(nodeKey(node.kind, node.name));
+                return;
             }
-        }
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isRefEntry(entry))
-                continue;
-            for (const val of resolveFieldValues(r, fieldPath)) {
-                if (!val)
-                    continue;
-                // `!ref <name>` sentinel — look up the target's kind from the
-                // name (resources are unique by name) so the edge carries the
-                // concrete kind, matching the {kind, name} edge shape below.
-                if (isRefSentinel(val)) {
-                    const refName = val.source;
-                    if (scopedNames.has(refName))
-                        continue;
-                    const node = nodesByName.get(refName);
-                    if (node) {
-                        deps.get(sourceKey).add(nodeKey(node.kind, node.name));
-                    }
-                    continue;
-                }
-                if (typeof val !== "object")
-                    continue;
-                const ref = val;
-                if (!ref.kind || !ref.name)
-                    continue;
-                // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG
-                if (scopedNames.has(ref.name))
-                    continue;
-                const targetKey = nodeKey(ref.kind, ref.name);
-                if (nodes.has(targetKey)) {
-                    deps.get(sourceKey).add(targetKey);
-                }
-            }
-        }
-    }
+            if (typeof val !== "object")
+                return;
+            const ref = val;
+            if (!ref.kind || !ref.name)
+                return;
+            if (scopedNames.has(ref.name))
+                return;
+            const targetKey = nodeKey(ref.kind, ref.name);
+            if (nodes.has(targetKey))
+                deps.get(sourceKey).add(targetKey);
+        },
+    }, { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: true });
     // --- Kahn's topological sort ---
     // in-degree[X] = number of X's dependencies (size of deps[X])
     // reverse[dep] = set of nodes that depend on dep (for degree decrement)

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { AnalysisRegistry } from "./analysis-registry.js";
 export { StaticAnalyzer } from "./analyzer.js";
 export type { GraphLoadError, ImportEdge, LoadedFile, LoadedGraph, LoadedModule, ParseError, } from "./loaded-types.js";
 export { flattenForAnalyzer, flattenLoadedModule } from "./flatten-for-analyzer.js";
+export { visitManifest } from "./manifest-visitor.js";
+export type { CelSiteEvent, ManifestVisitor, RefSiteEvent, ResourceEnterEvent, ResourceExitEvent, ScopeBoundaryEvent, SchemaFromSiteEvent, VisitOptions, } from "./manifest-visitor.js";
 export { Loader } from "./manifest-loader.js";
 export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACH,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACR,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,YAAY,EACR,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EACH,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,aAAa,EACb,KAAK,EACR,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { AnalysisRegistry } from "./analysis-registry.js";
 export { StaticAnalyzer } from "./analyzer.js";
 export { flattenForAnalyzer, flattenLoadedModule } from "./flatten-for-analyzer.js";
+export { visitManifest } from "./manifest-visitor.js";
 export { Loader } from "./manifest-loader.js";
 export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";

package/dist/kernel-globals.d.ts

@@ -10,7 +10,7 @@ import type { ResourceManifest } from "@telorun/sdk";
  * There is no `imports` namespace at runtime — import snapshots are stored
  * under `resources.<alias>`.
  */
-export declare const KERNEL_GLOBAL_NAMES: readonly ["variables", "secrets", "resources", "env"];
+export declare const KERNEL_GLOBAL_NAMES: readonly ["variables", "secrets", "resources", "ports", "env"];
 /**
  * Build a typed JSON Schema describing the kernel globals available in the
  * given manifest set. Used to merge into `x-telo-context` schemas so that

package/dist/kernel-globals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel-globals.d.ts","sourceRoot":"","sources":["../src/kernel-globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,uDAAwD,CAAC;AASzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiCrB;AAwBD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB"}
+{"version":3,"file":"kernel-globals.d.ts","sourceRoot":"","sources":["../src/kernel-globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,gEAAiE,CAAC;AASlG;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAkCrB;AA4CD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB"}

package/dist/kernel-globals.js

@@ -10,7 +10,7 @@ import { residualEntrySchemaMap } from "./residual-schema.js";
  * There is no `imports` namespace at runtime — import snapshots are stored
  * under `resources.<alias>`.
  */
-export const KERNEL_GLOBAL_NAMES = ["variables", "secrets", "resources", "env"];
+export const KERNEL_GLOBAL_NAMES = ["variables", "secrets", "resources", "ports", "env"];
 const SYSTEM_KINDS = new Set([
     "Telo.Definition",
     "Telo.Application",
@@ -55,10 +55,28 @@ export function buildKernelGlobalsSchema(manifests) {
                 properties: resourceProps,
                 additionalProperties: false,
             },
+            ports: buildPortsSchema(moduleManifest?.ports),
             env: { type: "object", additionalProperties: true },
         },
     };
 }
+/** Build the closed `ports` chain-access schema: each declared port is an
+ *  integer, so `ports.<name>` resolves and `ports.typo` (or member access past
+ *  a port, like `ports.http.foo`) is flagged. Falls back to an open map when
+ *  the module declares no ports. */
+function buildPortsSchema(ports) {
+    if (!ports || typeof ports !== "object" || Array.isArray(ports)) {
+        return { type: "object", additionalProperties: true };
+    }
+    const props = {};
+    for (const name of Object.keys(ports)) {
+        props[name] = { type: "integer" };
+    }
+    if (Object.keys(props).length === 0) {
+        return { type: "object", additionalProperties: true };
+    }
+    return { type: "object", properties: props, additionalProperties: false };
+}
 /** Wrap a JSON Schema property map (like `Telo.Application.variables`) into a
  *  closed object schema suitable for chain-access validation. For Application
  *  entries the per-entry shape carries kernel-specific keys (`env`, `default`)

package/dist/manifest-visitor.d.ts

@@ -0,0 +1,124 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type RefFieldEntry, type SchemaFromFieldEntry } from "./reference-field-map.js";
+/**
+ * One descent surface over a manifest's resources, emitting the annotation
+ * sites every analyzer pass needs. It replaces the iteration scaffolding that
+ * `validate-references`, `dependency-graph`, and the analyzer's CEL walk each
+ * reimplemented (field-map fetch, scope collection, ref/schema-from iteration,
+ * CEL expression walk + context matching).
+ *
+ * Two discovery mechanics ride one per-resource pass:
+ *
+ * - **Path-driven** — ref / scope / schema-from sites come from the resource's
+ *   per-kind field map (`RefSite`, `ScopeBoundary`, `SchemaFromSite`). This is
+ *   map iteration resolved against the resource value, not a node-by-node tree
+ *   descent; the field map already unifies all three annotation types.
+ * - **Value-tree-driven** — compiled `${{...}}` / `!cel` nodes are found by
+ *   scanning the resource value tree (`CelSite`). CEL can sit in any string
+ *   field, including ones the field map never lists, so its discovery is
+ *   fundamentally not path-driven; the field map only supplies the matched
+ *   `x-telo-context` schema at the enclosing path.
+ *
+ * Handlers are optional (Babel-style): the walker computes and emits only what
+ * the visitor subscribes to, and skips the work behind absent handlers.
+ *
+ * **Scope is per-resource.** `ScopeBoundary` is emitted once per resource at
+ * enter time, before that resource's `RefSite`s, carrying both the source
+ * enclosure prefixes (for refs written *inside* a scope) and the enclosed
+ * resource-name set (for consumers that drop edges to scoped targets). No
+ * cross-resource ordering or global enclosed-name union is implied — every
+ * consumer's scope decision is local to the resource being visited, matching
+ * the semantics each pass had before this walker existed.
+ */
+export interface ResourceEnterEvent {
+    source: ResourceManifest;
+    /** Resolved definition for the resource's kind, or undefined when unknown. */
+    definition?: ResourceDefinition;
+}
+export interface ResourceExitEvent {
+    source: ResourceManifest;
+}
+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. */
+    manifestsByPointer: Map<string, ResourceManifest[]>;
+    /** 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>;
+}
+export interface RefSiteEvent {
+    source: ResourceManifest;
+    /** Field-map path with `[]` / `{}` markers (e.g. `steps[].invoke`). */
+    fieldPath: string;
+    /** Concrete path with `[N]` / map keys, matching `buildPositionIndex` keys. */
+    concretePath: string;
+    /** The ref value at this concrete site (sentinel, string, or `{kind,name}`). */
+    value: unknown;
+    /** The ref constraint (`refs[]`, `isArray`, optional `context`). */
+    entry: RefFieldEntry;
+    /** True when `fieldPath` falls within one of this resource's scope prefixes —
+     *  source enclosure, used to scope a ref's candidate set. */
+    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;
+    /** Field-map path of the `x-telo-schema-from` slot. */
+    fieldPath: string;
+    entry: SchemaFromFieldEntry;
+}
+export interface CelSiteEvent {
+    source: ResourceManifest;
+    /** Concrete dotted path of the expression (from `walkCelExpressions`). */
+    path: string;
+    /** The CEL source expression. */
+    expr: string;
+    /** Engine that owns the expression (`cel`, `literal`, …). */
+    engineName: string;
+    /** Raw `x-telo-context` schema matched at the enclosing path, if any. The
+     *  consumer resolves `x-telo-context-*` annotations and merges its own
+     *  globals — the walker only does the path → context match. */
+    contextSchema?: Record<string, any>;
+    /** Scope of the matched context (e.g. `$.routes[*].handler`), if matched. */
+    matchedScope?: string;
+}
+export interface ManifestVisitor {
+    onResourceEnter?(e: ResourceEnterEvent): void;
+    onScope?(e: ScopeBoundaryEvent): void;
+    onRef?(e: RefSiteEvent): void;
+    onSchemaFrom?(e: SchemaFromSiteEvent): void;
+    onCel?(e: CelSiteEvent): void;
+    onResourceExit?(e: ResourceExitEvent): void;
+}
+export interface VisitOptions {
+    aliases?: AliasResolver;
+    aliasesByModule?: Map<string, AliasResolver>;
+    /** Resource kinds to skip entirely (kind blueprints, import metadata, …). */
+    skipKinds?: ReadonlySet<string>;
+    /** When true, ref / scope sites come from the schema-from-expanded field map
+     *  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

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

package/dist/manifest-visitor.js

@@ -0,0 +1,181 @@
+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, 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;
+        if (skipKinds?.has(r.kind))
+            continue;
+        const resolvedKind = aliases?.resolveKind(r.kind);
+        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)
+                : registry.getFieldMap(r.kind);
+            // Expanded map drives ref/scope sites when requested; schema-from sites
+            // come from the base map (expansion replaces them with nested refs).
+            const refScopeMap = expand && aliases && aliasesByModule
+                ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
+                : baseMap;
+            if (refScopeMap && (wantsRefs || wantsScope)) {
+                const manifestsByPointer = new Map();
+                for (const [fieldPath, entry] of refScopeMap) {
+                    if (!isScopeEntry(entry))
+                        continue;
+                    const raw = resolveFieldValues(r, fieldPath)
+                        .flatMap((v) => (Array.isArray(v) ? v : [v]))
+                        .filter((v) => !!v && typeof v === "object");
+                    const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
+                    for (const pointer of pointers)
+                        manifestsByPointer.set(pointer, raw);
+                }
+                const scopePrefixes = Array.from(manifestsByPointer.keys()).map(scopePrefixOf);
+                if (wantsScope) {
+                    const enclosedNames = new Set();
+                    for (const manifests of manifestsByPointer.values()) {
+                        for (const m of manifests) {
+                            const name = m.metadata?.name;
+                            if (typeof name === "string")
+                                enclosedNames.add(name);
+                        }
+                    }
+                    visitor.onScope({ source: r, scopePrefixes, manifestsByPointer, enclosedNames });
+                }
+                if (wantsRefs) {
+                    for (const [fieldPath, entry] of refScopeMap) {
+                        if (!isRefEntry(entry))
+                            continue;
+                        const inScope = scopePrefixes.some((prefix) => pathUnderPrefix(fieldPath, prefix));
+                        const visibleScopeManifests = [];
+                        if (inScope) {
+                            for (const [pointer, manifests] of manifestsByPointer) {
+                                if (pathUnderPrefix(fieldPath, scopePrefixOf(pointer))) {
+                                    visibleScopeManifests.push(...manifests);
+                                }
+                            }
+                        }
+                        for (const { value, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
+                            if (!value)
+                                continue;
+                            emittedRefPaths?.add(concretePath);
+                            visitor.onRef({
+                                source: r,
+                                fieldPath,
+                                concretePath,
+                                value,
+                                entry,
+                                inScope,
+                                visibleScopeManifests,
+                            });
+                        }
+                    }
+                }
+            }
+            if (wantsSchemaFrom && baseMap) {
+                for (const [fieldPath, entry] of baseMap) {
+                    if (!isSchemaFromEntry(entry))
+                        continue;
+                    visitor.onSchemaFrom({ source: r, fieldPath, entry });
+                }
+            }
+        }
+        // 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) => {
+                let contextSchema;
+                let matchedScope;
+                for (const ctx of contexts) {
+                    if (pathMatchesScope(path, ctx.scope)) {
+                        contextSchema = ctx.schema;
+                        matchedScope = ctx.scope;
+                        break;
+                    }
+                }
+                visitor.onCel({ source: r, path, expr, engineName, contextSchema, matchedScope });
+            });
+        }
+        visitor.onResourceExit?.({ source: r });
+    }
+}

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"}