@telorun/analyzer 1.2.0 → 1.4.0

package/dist/validate-references.js

@@ -1,13 +1,9 @@
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
-/** Kinds skipped by reference validation. Telo.Application and Telo.Library
- *  are intentionally not here: Application has `targets` with x-telo-ref that
- *  must be validated, and Library has no ref-bearing fields so flows through
- *  harmlessly. Telo.Import is also not here for the same reason — its
- *  `source` field isn't x-telo-ref, so nothing gets checked. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
  * Returns an empty array when valid, or mismatch error strings when not.
@@ -64,14 +60,57 @@ export function validateReferences(resources, context) {
     const aliasesByModule = context.aliasesByModule;
     if (!aliases || !registry)
         return diagnostics;
-    // Build outer resource lookup by name for resolution check.
-    // Exclude system kinds (Telo.Definition) — they are type blueprints, not instances,
-    // and their names (e.g. "Server", "Job") would shadow user-defined resource instances.
-    const byName = new Map();
+    // Build outer resource lookup by name for resolution check, collecting
+    // every entry per name so we can surface name collisions as diagnostics
+    // (the kernel's resource registry shares one namespace across all
+    // non-system kinds — e.g. `Telo.Application HelloApi` and `Http.Api
+    // HelloApi` collide at boot with `ERR_DUPLICATE_RESOURCE`. Catching it
+    // statically removes a class of "everything analyzes clean, then the
+    // kernel refuses to start" surprises.)
+    //
+    // Telo.Import is excluded from the duplicate check on top of the
+    // SYSTEM_KINDS skip: its `metadata.name` is an alias, not a resource
+    // identity (aliases live in a separate namespace from resources, and
+    // colliding aliases vs. resource names is benign — the alias is only
+    // ever read as a kind prefix).
+    const byNameAll = new Map();
     for (const r of resources) {
-        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind))
-            byName.set(r.metadata.name, r);
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import")
+            continue;
+        const name = r.metadata.name;
+        const existing = byNameAll.get(name);
+        if (existing)
+            existing.push(r);
+        else
+            byNameAll.set(name, [r]);
     }
+    for (const [name, list] of byNameAll) {
+        if (list.length <= 1)
+            continue;
+        const [first, ...rest] = list;
+        const firstLabel = `${first.kind}/${name}`;
+        for (const dup of rest) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "DUPLICATE_RESOURCE_NAME",
+                source: SOURCE,
+                message: `${dup.kind}/${name}: resource name collides with ${firstLabel} declared earlier (kernel runtime would fail with ERR_DUPLICATE_RESOURCE)`,
+                data: {
+                    resource: { kind: dup.kind, name },
+                    filePath: dup.metadata?.source,
+                    path: "metadata.name",
+                },
+            });
+        }
+    }
+    // Single-resource map for the resolution / scope lookups below — when a
+    // collision exists, falling back to the first occurrence keeps the rest
+    // of the pass behaving the same as before the duplicate diagnostic was
+    // added (resolution still finds *something*; the duplicate diagnostic
+    // is what surfaces the underlying problem to the user).
+    const byName = new Map();
+    for (const [name, list] of byNameAll)
+        byName.set(name, list[0]);
     for (const r of resources) {
         if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
             continue;
@@ -122,6 +161,36 @@ export function validateReferences(resources, context) {
             for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                 if (!val)
                     continue;
+                // `!ref <name>` sentinel — bare resource name marked at parse time as a
+                // reference. Look it up against the slot's x-telo-ref constraint exactly
+                // like the legacy bare-string path; the only difference is the value's
+                // shape (a TaggedSentinel rather than a raw string), which removed the
+                // string/inline ambiguity at the source.
+                if (isRefSentinel(val)) {
+                    const refName = val.source;
+                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                    if (!target) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "UNRESOLVED_REFERENCE",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+                            data: { resource: resourceData, filePath, path: concretePath },
+                        });
+                        continue;
+                    }
+                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
+                    if (kindErrors.length > 0) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "REFERENCE_KIND_MISMATCH",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                            data: { resource: resourceData, filePath, path: concretePath },
+                        });
+                    }
+                    continue;
+                }
                 // Name-only reference (plain string) — look up by name to validate.
                 // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
                 // extract the resource name from the last dot segment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "1.2.0",
+  "version": "1.4.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": "1.0.0"
+    "@telorun/templating": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analyzer.ts

@@ -14,6 +14,7 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
   celTypeSatisfiesJsonSchema,
@@ -623,6 +624,12 @@ export class StaticAnalyzer {
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
     const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
 
+    // Phase 2.5: resolve `!ref <name>` sentinels at every ref slot to canonical
+    // {kind, name} objects so downstream phases (validation, dependency graph,
+    // kernel controllers) see a uniform shape. Runs after normalize so both
+    // original and inline-extracted manifests have their sentinels resolved.
+    resolveRefSentinels(allManifests, defs, aliases, aliasesByModule);
+
     // Trusted-input fast path: when the caller has already attested that
     // this exact manifest set passes analysis (e.g. via the kernel's
     // hash-stamped `.validated.json` cache), skip the validation walk.
@@ -982,12 +989,17 @@ export class StaticAnalyzer {
 
   normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
     const ctx = registry._context();
-    return normalizeInlineResources(
+    const normalized = normalizeInlineResources(
       manifests,
       ctx.definitions!,
       ctx.aliases,
       ctx.aliasesByModule,
     );
+    // Resolve !ref sentinels after normalize so both the original and
+    // inline-extracted manifests get their refs canonicalized to
+    // {kind, name} for the kernel that consumes this output.
+    resolveRefSentinels(normalized, ctx.definitions!, ctx.aliases, ctx.aliasesByModule);
+    return normalized;
   }
 
   prepare(

package/src/builtins.ts

@@ -220,6 +220,20 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             anyOf: [
               { type: "string", "x-telo-ref": "telo#Runnable" },
               { type: "string", "x-telo-ref": "telo#Service" },
+              // Post-resolution shape that `resolveRefSentinels`
+              // substitutes a `!ref <name>` sentinel into. The
+              // adjacent `x-telo-ref` constraints govern the kind
+              // check; this branch only admits the structural form so
+              // AJV doesn't reject a resolved ref.
+              {
+                type: "object",
+                required: ["kind", "name"],
+                properties: {
+                  kind: { type: "string" },
+                  name: { type: "string" },
+                },
+                additionalProperties: true,
+              },
             ],
           },
         },

package/src/definition-registry.ts

@@ -80,6 +80,21 @@ export class DefinitionRegistry {
    *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
    *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
   registerModuleIdentity(namespace: string | null, moduleName: string): void {
+    // The "telo" identity is reserved for the Telo built-in module and gets
+    // populated automatically when a Telo.Abstract definition registers (see
+    // `register` below). A user app / library without a namespace must NOT
+    // claim it — silently overwriting the built-in entry breaks every
+    // x-telo-ref that resolves through "telo#…". Concretely, the
+    // `Http.Api.routes[].handler` slot in the http-server schema carries
+    // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
+    // `Telo.Application/HelloApi` (no namespace), this method previously
+    // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
+    // ref then resolved to a nonexistent `HelloApi.Invocable`, the
+    // kind-mismatch check inside `validate-references.ts` short-circuited
+    // on partial context, and the analyzer reported zero issues for a
+    // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
+    // they have no x-telo-ref identity to declare anyway.
+    if (!namespace && moduleName !== "Telo") return;
     const identity = namespace ? `${namespace}/${moduleName}` : "telo";
     this.identityMap.set(identity, moduleName);
     this.reverseIdentityMap.set(moduleName, identity);

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/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;
 }

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

@@ -142,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;
@@ -172,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"] });
@@ -200,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);
     }
   }
 
@@ -218,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,
+    );
   }
 }

package/src/resolve-ref-sentinels.ts

@@ -0,0 +1,127 @@
+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 } from "./reference-field-map.js";
+import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+
+/**
+ * Walks every `x-telo-ref` slot in every non-system resource and rewrites
+ * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ *
+ * The downstream pipeline (inline normalization, dependency graph, kernel
+ * controllers) expects every ref-slot value to be either a `{kind, name}`
+ * object, an inline-definition object, or a legacy bare string — resolving
+ * sentinels here keeps that contract intact so each consumer doesn't need
+ * its own sentinel branch.
+ *
+ * The walker assigns `kind` by name lookup (resource names are unique
+ * within a manifest scope). When the name doesn't resolve in the local
+ * `byName` map, the sentinel is left in place so `validateReferences`
+ * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ *
+ * Mutation strategy: the field-path walker descends the resource tree
+ * directly and replaces the sentinel on its parent container. Re-parsing
+ * a string-encoded concrete path (the earlier shape) coupled the writer
+ * to the path-encoding rules of `resolveFieldEntries` — any new path
+ * marker would silently break this writer. Descending directly avoids
+ * that coupling.
+ */
+export function resolveRefSentinels(
+  resources: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+): void {
+  const byName = new Map<string, ResourceManifest>();
+  for (const r of resources) {
+    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
+      byName.set(r.metadata.name as string, r);
+    }
+  }
+
+  for (const r of resources) {
+    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+
+    const fieldMap =
+      aliases && aliasesByModule
+        ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
+        : registry.getFieldMapForKind(r.kind, aliases);
+    if (!fieldMap) continue;
+
+    for (const [fieldPath, entry] of fieldMap) {
+      if (!isRefEntry(entry)) continue;
+      replaceSentinelsAtPath(r as Record<string, unknown>, fieldPath, byName);
+    }
+  }
+}
+
+/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
+ *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
+ *  sentinel value at the terminal slot with `{kind, name}` looked up
+ *  via `byName`. Mutates the parent container in place; no string-path
+ *  round-trip. */
+function replaceSentinelsAtPath(
+  obj: Record<string, unknown>,
+  fieldPath: string,
+  byName: Map<string, ResourceManifest>,
+): void {
+  const parts = fieldPath.split(".");
+  descend(obj, parts, byName);
+}
+
+function descend(
+  obj: unknown,
+  parts: string[],
+  byName: Map<string, ResourceManifest>,
+): void {
+  if (obj == null || typeof obj !== "object" || parts.length === 0) return;
+  const [head, ...rest] = parts;
+
+  // Map iteration: descend into every value of the current object.
+  if (head === "{}") {
+    const container = obj as Record<string, unknown>;
+    for (const key of Object.keys(container)) {
+      const child = container[key];
+      if (rest.length === 0) {
+        if (isRefSentinel(child)) {
+          const target = byName.get(child.source);
+          if (target) container[key] = { kind: target.kind as string, name: child.source };
+        }
+      } else {
+        descend(child, rest, byName);
+      }
+    }
+    return;
+  }
+
+  const isArr = head.endsWith("[]");
+  const key = isArr ? head.slice(0, -2) : head;
+  const container = obj as Record<string, unknown>;
+  const val = container[key];
+  if (val == null) return;
+
+  if (isArr) {
+    if (!Array.isArray(val)) return;
+    for (let i = 0; i < val.length; i++) {
+      if (rest.length === 0) {
+        const elem = val[i];
+        if (isRefSentinel(elem)) {
+          const target = byName.get(elem.source);
+          if (target) val[i] = { kind: target.kind as string, name: elem.source };
+        }
+      } else {
+        descend(val[i], rest, byName);
+      }
+    }
+  } else {
+    if (rest.length === 0) {
+      if (isRefSentinel(val)) {
+        const target = byName.get(val.source);
+        if (target) container[key] = { kind: target.kind as string, name: val.source };
+      }
+    } else {
+      descend(val, rest, byName);
+    }
+  }
+}

package/src/schema-compat.ts

@@ -1,16 +1,23 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isTaggedSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
- *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+ *  Also registers the kernel manifest root schema under `telo://manifest` so
+ *  module YAMLs can `$ref` into the shared `$defs/ResourceRef` (and any future
+ *  shared fragments) from this analyzer's AJV without each module having to
+ *  bundle its own copy.
+ *
+ *  Called once for the module-level instance and once per
+ *  DefinitionRegistry instance. */
 export function createAjv(): InstanceType<typeof Ajv> {
   const instance = new Ajv({ allErrors: true, strict: false });
   (addFormats as any).default
     ? (addFormats as any).default(instance)
     : (addFormats as any)(instance);
+  instance.addSchema(ManifestRootSchema);
   return instance;
 }
 
@@ -301,6 +308,16 @@ export function substituteCelFields(
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     return celPlaceholderForSchema(resolved);
   }
+  // `!ref <name>` sentinels are identity markers, not runtime values —
+  // schemas that opt into `$ref: "telo://manifest#/$defs/ResourceRef"`
+  // (or `anyOf` it alongside other shapes) need the actual sentinel
+  // object so AJV validates it against ResourceRefSchema. Collapsing it
+  // to a CEL placeholder would either fail the schema (when the slot
+  // expects the ResourceRef shape) or mask validation errors (when the
+  // slot expects something else entirely).
+  if (isRefSentinel(data)) {
+    return data;
+  }
   if (isTaggedSentinel(data)) {
     return celPlaceholderForSchema(resolved);
   }