@telorun/analyzer 0.10.1 → 0.12.0

package/src/dependency-graph.ts

@@ -1,7 +1,9 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 export interface ResourceNode {
   kind: string;
@@ -17,16 +19,6 @@ export interface DependencyGraph {
   cycle?: ReadonlyArray<ResourceNode>;
 }
 
-/** System resource kinds that are not runtime nodes in the dependency graph.
- *  Module-identity docs (Telo.Application, Telo.Library) are intentionally
- *  not in this set: an Application's `targets` use `x-telo-ref` to real
- *  Runnable/Service resources, so the Application legitimately depends on
- *  them in boot order — modeling that as a graph edge is correct. A Library
- *  has no `targets`, so it becomes a zero-edge node, which is harmless.
- *  If the graph is ever consumed as "things to init", skip these kinds at
- *  the consumer site; the controller already runs them separately. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Import"]);
-
 const nodeKey = (kind: string, name: string) => `${kind}\0${name}`;
 
 /**
@@ -47,12 +39,18 @@ export function buildDependencyGraph(
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
 ): DependencyGraph {
-  // --- Build node set ---
+  // --- Build node set + name index ---
   const nodes = new Map<string, ResourceNode>();
+  // Sentinel lookup (`!ref <name>`) needs to resolve a bare name to its
+  // declared kind. Names are unique within a manifest scope, so a flat
+  // map suffices and lets the sentinel branch below avoid a full
+  // O(N) scan of the node set on every reference.
+  const nodesByName = new Map<string, ResourceNode>();
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
-    const key = nodeKey(r.kind, r.metadata.name as string);
-    nodes.set(key, { kind: r.kind, name: r.metadata.name as string });
+    const node = { kind: r.kind, name: r.metadata.name as string };
+    nodes.set(nodeKey(node.kind, node.name), node);
+    nodesByName.set(node.name, node);
   }
 
   // --- Build adjacency: from → deps (from depends on dep) ---
@@ -90,7 +88,22 @@ export function buildDependencyGraph(
       if (!isRefEntry(entry)) continue;
 
       for (const val of resolveFieldValues(r, fieldPath)) {
-        if (!val || typeof val !== "object") continue;
+        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 as Record<string, unknown>;
         if (!ref.kind || !ref.name) continue;
         // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG

package/src/index.ts

@@ -14,6 +14,7 @@ export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
+export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
 export {
     buildDocumentPositions,
     buildLineOffsets,
@@ -23,6 +24,7 @@ export {
 export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
+export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,

package/src/kernel-globals.ts

@@ -1,4 +1,5 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { residualEntrySchemaMap } from "./residual-schema.js";
 
 /**
  * Kernel global names available in every CEL evaluation context at runtime.
@@ -72,20 +73,17 @@ export function buildKernelGlobalsSchema(
 }
 
 /** Wrap a JSON Schema property map (like `Telo.Application.variables`) into a
- *  closed object schema suitable for chain-access validation. Falls back to
- *  an open map when the module declares no variables/secrets. */
+ *  closed object schema suitable for chain-access validation. For Application
+ *  entries the per-entry shape carries kernel-specific keys (`env`, `default`)
+ *  on top of an otherwise-standard JSON Schema property schema; those keys are
+ *  stripped via `residualEntrySchemaMap` so CEL sees the coerced shape, not
+ *  the env-binding wrapper. Library entries are pure JSON Schema property
+ *  schemas and pass through the same call unchanged. Falls back to an open map
+ *  when the module declares no variables/secrets. */
 function buildSchemaMapSchema(
   schemaMap: Record<string, any> | null | undefined,
 ): Record<string, any> {
-  if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
-    return { type: "object", additionalProperties: true };
-  }
-  const props: Record<string, any> = {};
-  for (const [key, value] of Object.entries(schemaMap)) {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      props[key] = value;
-    }
-  }
+  const props = residualEntrySchemaMap(schemaMap);
   if (Object.keys(props).length === 0) {
     return { type: "object", additionalProperties: true };
   }

package/src/manifest-loader.ts

@@ -33,6 +33,14 @@ export class Loader {
    *  get distinct entries, so neither sees the wrong manifest tree. */
   private readonly fileCache = new Map<string, LoadedFile>();
 
+  /** requestUrl → canonical `source`. Lets `loadFile` skip the source read
+   *  when a URL it has already canonicalised is requested again — kernel
+   *  load → boot and the import-controller each ask the loader for the same
+   *  modules. Without this fast path every duplicate request re-runs the
+   *  source's `read()` (a `fetch` for `RegistrySource`, a disk read for
+   *  `LocalFileSource`). */
+  private readonly urlToSource = new Map<string, string>();
+
   protected sources: ManifestSource[];
   private readonly celEnv: Environment;
 
@@ -67,8 +75,22 @@ export class Loader {
   }
 
   async resolveEntryPoint(url: string): Promise<string> {
-    const { source } = await this.pick(url).read(url);
-    return source;
+    // Route through `loadFile` so the resolved source URL and parsed
+    // entry are populated in `urlToSource` + `fileCache` in one read.
+    // Callers (kernel.load) immediately call `loadGraph(entryUrl)`
+    // afterwards — without this priming, the entry file would be read
+    // twice (twice over the network for `RegistrySource`).
+    const file = await this.loadFile(url);
+    return file.source;
+  }
+
+  /** Returns the canonical source URL the loader has already mapped `url`
+   *  to during a prior `loadFile`/`loadModule`/`loadGraph` call, or
+   *  `undefined` when the URL has not been seen. Callers use it to test
+   *  set-membership against a previous graph walk's modules without
+   *  triggering an extra source read. */
+  canonicalize(url: string): string | undefined {
+    return this.urlToSource.get(url);
   }
 
   // --- New API: returns LoadedFile / LoadedModule / LoadedGraph ----------
@@ -78,8 +100,42 @@ export class Loader {
    *  private mutable copy must call `parseLoadedFile` directly with the
    *  LoadedFile's `text`. */
   async loadFile(url: string, options?: LoadOptions): Promise<LoadedFile> {
+    const compileKey = options?.compile ? "compiled" : "raw";
+    const knownSource = this.urlToSource.get(url);
+    if (knownSource) {
+      const cached = this.fileCache.get(`${compileKey}:${knownSource}`);
+      if (cached) return cached;
+      // The other compile-mode entry is cached — reparse from its text
+      // instead of re-reading the source.
+      //
+      // NOTE for watch-mode reactivation (cli/nodejs/src/commands/run.ts
+      // currently has `setupWatchMode` commented out): this branch
+      // assumes file contents don't change underneath a single Loader.
+      // Reviving watch mode will need a public `invalidate(url)` (or
+      // similar) that drops both `urlToSource[url]` and the cached
+      // entries for its canonical source before the loader serves the
+      // file again.
+      const altKey = `${compileKey === "compiled" ? "raw" : "compiled"}:${knownSource}`;
+      const alt = this.fileCache.get(altKey);
+      if (alt) {
+        const reparsed = parseLoadedFile(knownSource, url, alt.text, {
+          compile: options?.compile,
+          celEnv: this.celEnv,
+        });
+        this.fileCache.set(`${compileKey}:${knownSource}`, reparsed);
+        return reparsed;
+      }
+    }
+
     const { text, source } = await this.pick(url).read(url);
-    const cacheKey = `${options?.compile ? "compiled" : "raw"}:${source}`;
+    this.urlToSource.set(url, source);
+    // Also map the canonical source to itself so subsequent `loadFile`
+    // calls that already received a canonical URL — `kernel.load` passes
+    // the result of `resolveEntryPoint` to `loadGraph`, which then asks
+    // for that exact URL — hit the urlToSource fast path instead of
+    // falling through to a redundant `pick(url).read(url)`.
+    this.urlToSource.set(source, source);
+    const cacheKey = `${compileKey}:${source}`;
     const cached = this.fileCache.get(cacheKey);
     if (cached && cached.text === text) return cached;
 
@@ -224,7 +280,16 @@ export class Loader {
     return { rootSource, entry, modules, importEdges, errors };
   }
 
-  private resolveImportUrl(fromSource: string, importSource: string): string {
+  /** Resolve an `import` URL against the file it appears in. Relative /
+   *  absolute-path forms run through the owning `ManifestSource`'s
+   *  `resolveRelative`; registry refs and full URLs pass through
+   *  unchanged. Exposed so the import-controller (and any other
+   *  caller-side resolver) lands on the *exact same* canonical URL the
+   *  loader used when walking the entry graph — divergent resolution
+   *  would silently break optimizations like `canonicalize()`-keyed
+   *  cache hits whenever a non-trivial `ManifestSource.resolveRelative`
+   *  is in play. */
+  resolveImportUrl(fromSource: string, importSource: string): string {
     if (importSource.startsWith(".") || importSource.startsWith("/")) {
       return this.pick(fromSource).resolveRelative(fromSource, importSource);
     }

package/src/normalize-inline-resources.ts

@@ -82,7 +82,14 @@ export function normalizeInlineResources(
       );
 
       const invocationContext = isRefEntry(entry) ? entry.context : undefined;
-      const extracted = extractInlinesAtPath(resource, fieldPath, parentName, parentModule, invocationContext);
+      const extracted = extractInlinesAtPath(
+        resource,
+        fieldPath,
+        parentName,
+        resource.kind,
+        parentModule,
+        invocationContext,
+      );
       for (const manifest of extracted) {
         result.push(manifest);
         queue.push(manifest as ResourceManifest & { metadata: { name: string } });
@@ -99,18 +106,42 @@ export function normalizeInlineResources(
  * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal).
  * Mutates the resource in-place: replaces each inline value with `{kind, name}`.
  * Returns the extracted manifests.
+ *
+ * Each extracted manifest carries `metadata.xTeloOrigin` so downstream
+ * diagnostics can be rerouted back to the parent doc's YAML position:
+ *   - `parentKind` / `parentName` — the resource that owned the inline slot
+ *   - `pathFromParent` — concrete dotted path with `[N]` indices, matching
+ *     `buildPositionIndex` keys (e.g. `routes[0].handler`)
  */
 function extractInlinesAtPath(
   resource: ResourceManifest,
   fieldPath: string,
   parentName: string,
+  parentKind: string,
   parentModule: string | undefined,
   invocationContext?: Record<string, any>,
 ): ResourceManifest[] {
   const extracted: ResourceManifest[] = [];
   const parts = fieldPath.split(".");
 
-  function traverse(obj: unknown, partsLeft: string[], nameParts: string[]): void {
+  function emit(
+    inline: Record<string, unknown>,
+    nameSegments: string[],
+    concretePath: string,
+  ): string {
+    const name = sanitizeName([parentName, ...nameSegments].join("_"));
+    extracted.push(
+      buildManifest(inline, name, parentKind, parentName, concretePath, parentModule, invocationContext),
+    );
+    return name;
+  }
+
+  function traverse(
+    obj: unknown,
+    partsLeft: string[],
+    nameParts: string[],
+    pathSoFar: string,
+  ): void {
     if (!obj || typeof obj !== "object" || partsLeft.length === 0) return;
 
     const [head, ...rest] = partsLeft;
@@ -123,15 +154,15 @@ function extractInlinesAtPath(
         const elem = container[mapKey];
         if (!elem || typeof elem !== "object") continue;
         const sanitizedKey = sanitizeName(mapKey);
+        const childPath = pathSoFar ? `${pathSoFar}.${mapKey}` : mapKey;
 
         if (rest.length === 0) {
           if (isInlineResource(elem as Record<string, unknown>)) {
-            const name = sanitizeName([parentName, ...nameParts, sanitizedKey].join("_"));
-            extracted.push(buildManifest(elem as Record<string, unknown>, name, parentModule, invocationContext));
+            const name = emit(elem as Record<string, unknown>, [...nameParts, sanitizedKey], childPath);
             container[mapKey] = { kind: (elem as Record<string, unknown>).kind, name };
           }
         } else {
-          traverse(elem, rest, [...nameParts, sanitizedKey]);
+          traverse(elem, rest, [...nameParts, sanitizedKey], childPath);
         }
       }
       return;
@@ -142,6 +173,7 @@ function extractInlinesAtPath(
     const container = obj as Record<string, unknown>;
     const val = container[key];
     if (val == null) return;
+    const keyPath = pathSoFar ? `${pathSoFar}.${key}` : key;
 
     if (isArr) {
       if (!Array.isArray(val)) return;
@@ -152,39 +184,41 @@ function extractInlinesAtPath(
           typeof (elem as Record<string, unknown>).name === "string"
             ? ((elem as Record<string, unknown>).name as string)
             : String(idx);
+        const childPath = `${keyPath}[${idx}]`;
 
         if (rest.length === 0) {
           // Array element itself is the ref slot
           if (isInlineResource(elem as Record<string, unknown>)) {
-            const name = sanitizeName([parentName, ...nameParts, key, elemId].join("_"));
-            extracted.push(buildManifest(elem as Record<string, unknown>, name, parentModule, invocationContext));
+            const name = emit(elem as Record<string, unknown>, [...nameParts, key, elemId], childPath);
             val[idx] = { kind: (elem as Record<string, unknown>).kind, name };
           }
         } else {
-          traverse(elem, rest, [...nameParts, key, elemId]);
+          traverse(elem, rest, [...nameParts, key, elemId], childPath);
         }
       }
     } else {
       if (rest.length === 0) {
         // val is the ref slot
         if (val && typeof val === "object" && !Array.isArray(val) && isInlineResource(val as Record<string, unknown>)) {
-          const name = sanitizeName([parentName, ...nameParts, key].join("_"));
-          extracted.push(buildManifest(val as Record<string, unknown>, name, parentModule, invocationContext));
+          const name = emit(val as Record<string, unknown>, [...nameParts, key], keyPath);
           container[key] = { kind: (val as Record<string, unknown>).kind, name };
         }
       } else {
-        traverse(val, rest, [...nameParts, key]);
+        traverse(val, rest, [...nameParts, key], keyPath);
       }
     }
   }
 
-  traverse(resource, parts, []);
+  traverse(resource, parts, [], "");
   return extracted;
 }
 
 function buildManifest(
   inline: Record<string, unknown>,
   name: string,
+  parentKind: string,
+  parentName: string,
+  pathFromParent: string,
   parentModule: string | undefined,
   invocationContext?: Record<string, any>,
 ): ResourceManifest {
@@ -200,6 +234,7 @@ function buildManifest(
       // Inherit parent module only if the inline doesn't already declare one
       ...(parentModule && !existingMeta.module ? { module: parentModule } : {}),
       ...(invocationContext ? { xTeloInvocationContext: invocationContext } : {}),
+      xTeloOrigin: { parentKind, parentName, pathFromParent },
     },
-  } as ResourceManifest;
+  } as unknown as ResourceManifest;
 }

package/src/position-metadata.ts

@@ -29,13 +29,21 @@ export function buildDocumentPositions(
 
 /** Line numbers (0-indexed) where each YAML document in a multi-doc file
  *  starts. The first document is always at line 0; subsequent entries point
- *  to the line after each `---` directive. */
+ *  to the line after each `---` separator.
+ *
+ *  A `---` at line 0 is the doc-start marker for doc 0 (the parser still
+ *  emits a single document), not a separator before an empty doc — skipping
+ *  it keeps `offsets.length === parsedDocs.length` so diagnostics for doc N
+ *  don't land inside doc N-1's text. */
 export function documentLineOffsets(text: string): number[] {
   const offsets = [0];
   const lines = text.split("\n");
   for (let i = 0; i < lines.length; i++) {
     const t = lines[i].trimEnd();
-    if (t === "---" || t.startsWith("--- ")) offsets.push(i + 1);
+    if (t === "---" || t.startsWith("--- ")) {
+      if (i === 0) continue;
+      offsets.push(i + 1);
+    }
   }
   return offsets;
 }
@@ -63,7 +71,11 @@ function offsetToPosition(offset: number, lineOffsets: number[]): Position {
 }
 
 /** Walks the YAML AST and records source ranges for every field value, keyed
- *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path"). */
+ *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path").
+ *  Map keys are also recorded under the `@key:<path>` namespace so diagnostic
+ *  resolvers can squiggle just the key identifier instead of the full value
+ *  block — used when a diagnostic targets a missing child property and the
+ *  resolver has to fall back to the parent. */
 export function buildPositionIndex(doc: Document, lineOffsets: number[]): PositionIndex {
   const index: PositionIndex = new Map();
 
@@ -83,6 +95,9 @@ export function buildPositionIndex(doc: Document, lineOffsets: number[]): Positi
         const key = isScalar(pair.key) ? String(pair.key.value) : null;
         if (key == null) continue;
         const childPath = path ? `${path}.${key}` : key;
+        if (pair.key && (pair.key as any).range) {
+          recordNode(pair.key, `@key:${childPath}`);
+        }
         if (pair.value != null) {
           recordNode(pair.value, childPath);
           walk(pair.value, childPath);

package/src/precompile.ts

@@ -1,6 +1,6 @@
 import type { Environment } from "@marcbachmann/cel-js";
 import { isCompiledValue } from "@telorun/sdk";
-import { compileString, defaultRegistry, isTaggedSentinel } from "@telorun/templating";
+import { compileString, defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 
 /**
  * Walks a raw YAML document and replaces all `${{ expr }}` strings (and
@@ -21,6 +21,13 @@ export function precompileDoc(doc: unknown, env: Environment): unknown {
   // analyzer's diagnostic walk can identify it on compiled trees too;
   // engines returning plain values (e.g. `literal` → a string) pass through
   // verbatim — the runtime contract is "any scalar value is fine."
+  // `!ref` sentinels are identity markers, not templating values. They must
+  // survive precompile intact so the analyzer's `resolveRefSentinels` pass
+  // can substitute them with `{kind, name}` objects against the resolved
+  // resource manifest. Running the engine's `compile` here would prematurely
+  // collapse the sentinel into its source string and the ref slot would
+  // arrive at the controller as a bare name with no kind.
+  if (isRefSentinel(doc)) return doc;
   if (isTaggedSentinel(doc)) {
     const engine = defaultRegistry().get(doc.engine);
     if (!engine) {

package/src/reference-field-map.ts

@@ -63,23 +63,39 @@ export function isInlineResource(val: Record<string, unknown>): boolean {
   return true;
 }
 
-/** Resolves all values at a field map path in a resource config.
- *  Path-segment markers:
- *   - `[]`  iterate array values at this key
+/** A value found at a field-map path, paired with the concrete path that
+ *  produced it. `path` has every `[]` substituted with `[N]` and every `{}`
+ *  substituted with the actual map key, matching the format produced by
+ *  `buildPositionIndex`. Used so diagnostics emitted against a specific
+ *  array element / map entry can be resolved back to a YAML range. */
+export interface ResolvedFieldEntry {
+  value: unknown;
+  path: string;
+}
+
+/** Resolves all `{value, path}` entries at a field map path in a resource
+ *  config. The returned `path` is the concrete dotted path produced by the
+ *  substitutions below, matching the format `buildPositionIndex` keys on.
+ *  Path-segment markers accepted in the input `path`:
+ *   - `[]`  iterate array values at this key, substituting `[N]` per item
+ *           (e.g. `routes[]` → `routes[0]`, `routes[1]`, …).
  *   - `{}`  iterate map values (every value in an `additionalProperties`-typed
  *           object — used for fields like `content[mime]` whose schema declares
- *           a key-as-MIME map). The path is `<key>.{}.<rest>`. */
-export function resolveFieldValues(obj: unknown, path: string): unknown[] {
+ *           a key-as-MIME map). Substituted with the literal map key joined by
+ *           a dot, so the input `content.{}.encoder` yields concrete paths
+ *           like `content.application/json.encoder`. */
+export function resolveFieldEntries(obj: unknown, path: string): ResolvedFieldEntry[] {
   const parts = path.split(".");
-  let current: unknown[] = [obj];
+  let current: ResolvedFieldEntry[] = [{ value: obj, path: "" }];
   for (const part of parts) {
     if (part === "{}") {
-      // Iterate the values of every map currently in `current`.
-      const next: unknown[] = [];
-      for (const item of current) {
-        if (!item || typeof item !== "object") continue;
-        for (const v of Object.values(item as Record<string, unknown>)) {
-          if (v != null) next.push(v);
+      const next: ResolvedFieldEntry[] = [];
+      for (const entry of current) {
+        if (!entry.value || typeof entry.value !== "object") continue;
+        for (const [k, v] of Object.entries(entry.value as Record<string, unknown>)) {
+          if (v != null) {
+            next.push({ value: v, path: entry.path ? `${entry.path}.${k}` : k });
+          }
         }
       }
       current = next;
@@ -87,19 +103,31 @@ export function resolveFieldValues(obj: unknown, path: string): unknown[] {
     }
     const isArray = part.endsWith("[]");
     const key = isArray ? part.slice(0, -2) : part;
-    const next: unknown[] = [];
-    for (const item of current) {
-      if (!item || typeof item !== "object") continue;
-      const val = (item as Record<string, unknown>)[key];
+    const next: ResolvedFieldEntry[] = [];
+    for (const entry of current) {
+      if (!entry.value || typeof entry.value !== "object") continue;
+      const val = (entry.value as Record<string, unknown>)[key];
       if (val == null) continue;
-      if (isArray && Array.isArray(val)) next.push(...val);
-      else if (!isArray) next.push(val);
+      const basePath = entry.path ? `${entry.path}.${key}` : key;
+      if (isArray && Array.isArray(val)) {
+        for (let i = 0; i < val.length; i++) {
+          if (val[i] != null) next.push({ value: val[i], path: `${basePath}[${i}]` });
+        }
+      } else if (!isArray) {
+        next.push({ value: val, path: basePath });
+      }
     }
     current = next;
   }
   return current;
 }
 
+/** Backwards-compat wrapper that drops the concrete path. Prefer
+ *  `resolveFieldEntries` for new code that wants positions. */
+export function resolveFieldValues(obj: unknown, path: string): unknown[] {
+  return resolveFieldEntries(obj, path).map((e) => e.value);
+}
+
 /**
  * Traverses a definition's JSON Schema once and returns a field map recording every
  * x-telo-ref slot and every x-telo-scope slot.
@@ -114,7 +142,7 @@ export function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFi
   const map: ReferenceFieldMap = new Map();
   if (schema.properties) {
     for (const [key, propSchema] of Object.entries(schema.properties)) {
-      traverseNode(propSchema as Record<string, any>, key, map);
+      traverseNode(propSchema as Record<string, any>, key, map, schema);
     }
   }
   return map;
@@ -144,11 +172,29 @@ export function buildFieldMapAtPath(
   pathPrefix: string,
 ): ReferenceFieldMap {
   const map: ReferenceFieldMap = new Map();
-  traverseNode(schema, pathPrefix, map);
+  traverseNode(schema, pathPrefix, map, schema);
   return map;
 }
 
-function traverseNode(node: Record<string, any>, path: string, map: ReferenceFieldMap): void {
+function traverseNode(
+  node: Record<string, any>,
+  path: string,
+  map: ReferenceFieldMap,
+  root?: Record<string, any>,
+  visitedRefs: Set<string> = new Set(),
+): void {
+  // Local `$ref` is intentionally NOT followed. Descending into shared
+  // `$defs` (notably `Run.Sequence`'s `step` definition) would surface
+  // ref slots like `steps[].invoke` that Phase 5 then injects live
+  // instances into; today's `Run.Sequence` controller calls
+  // `instance.invoke()` directly when handed an instance, bypassing
+  // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
+  // dispatcher fix need to land together — see the follow-up in
+  // [kernel/nodejs/plans/reference-syntax-unification.md] and the
+  // stopgap in `resource-context.ts:resolveChildren`. `visitedRefs`
+  // stays as a parameter so the recursive calls below thread the right
+  // signature; turning the descent back on is a single-branch change.
+  if (typeof node?.$ref === "string") return;
   // Scope slot — record and stop; do not recurse into scope contents
   if ("x-telo-scope" in node) {
     map.set(path, { scope: node["x-telo-scope"] });
@@ -172,13 +218,32 @@ function traverseNode(node: Record<string, any>, path: string, map: ReferenceFie
 
   // Array — recurse into items
   if (node.type === "array" && node.items) {
-    traverseNode(node.items as Record<string, any>, path + "[]", map);
+    traverseNode(node.items as Record<string, any>, path + "[]", map, root, visitedRefs);
   }
 
   // Object — recurse into properties
   if (node.properties) {
     for (const [key, propSchema] of Object.entries(node.properties)) {
-      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map);
+      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map, root, visitedRefs);
+    }
+  }
+
+  // Variant branches — descend into every alternative's properties / items.
+  // Schemas that discriminate on shape (Run.Sequence's step kinds:
+  // `oneOf: [{properties: {invoke}}, {properties: {try}}, ...]`) hide ref
+  // slots inside the branch. Walking each branch surfaces those slots into
+  // the field map so downstream passes (ref validation, sentinel
+  // resolution, dependency graph) cover them without a runtime fallback.
+  // The same field path may be added by multiple branches; the later
+  // assignment wins, which is fine — branches with the same field path
+  // share the same ref/context configuration (any divergence is already
+  // a schema bug).
+  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);
     }
   }
 
@@ -190,6 +255,46 @@ function traverseNode(node: Record<string, any>, path: string, map: ReferenceFie
     typeof node.additionalProperties === "object" &&
     !Array.isArray(node.additionalProperties)
   ) {
-    traverseNode(node.additionalProperties as Record<string, any>, `${path}.{}`, map);
+    traverseNode(
+      node.additionalProperties as Record<string, any>,
+      `${path}.{}`,
+      map,
+      root,
+      visitedRefs,
+    );
+  }
+}
+
+/** Walk a single variant of a `oneOf` / `anyOf` / `allOf` branch. Only
+ *  the properties / items / map slots are followed — collectRefs at the
+ *  variant root is handled by the parent's `collectRefs(node)` already
+ *  (anyOf of x-telo-ref branches is the canonical multi-ref shape). */
+function traverseVariant(
+  variant: Record<string, any>,
+  path: string,
+  map: ReferenceFieldMap,
+  root?: Record<string, any>,
+  visitedRefs: Set<string> = new Set(),
+): void {
+  if (variant.properties) {
+    for (const [key, propSchema] of Object.entries(variant.properties)) {
+      traverseNode(propSchema as Record<string, any>, `${path}.${key}`, map, root, visitedRefs);
+    }
+  }
+  if (variant.type === "array" && variant.items) {
+    traverseNode(variant.items as Record<string, any>, path + "[]", map, root, visitedRefs);
+  }
+  if (
+    variant.additionalProperties &&
+    typeof variant.additionalProperties === "object" &&
+    !Array.isArray(variant.additionalProperties)
+  ) {
+    traverseNode(
+      variant.additionalProperties as Record<string, any>,
+      `${path}.{}`,
+      map,
+      root,
+      visitedRefs,
+    );
   }
 }