@telorun/analyzer 1.2.0 → 1.3.0

package/dist/analyzer.d.ts.map

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

package/dist/analyzer.js

@@ -7,6 +7,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, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
@@ -492,6 +493,11 @@ 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.
@@ -788,7 +794,12 @@ export class StaticAnalyzer {
     }
     normalize(manifests, registry) {
         const ctx = registry._context();
-        return normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        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(manifests, registry) {
         const ctx = registry._context();

package/dist/builtins.d.ts.map

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

package/dist/builtins.js

@@ -218,6 +218,20 @@ export const KERNEL_BUILTINS = [
                         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/dist/dependency-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CA6FjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAkHjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}

package/dist/dependency-graph.js

@@ -1,13 +1,6 @@
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
-/** 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"]);
+import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 const nodeKey = (kind, name) => `${kind}\0${name}`;
 /**
  * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
@@ -22,13 +15,19 @@ const nodeKey = (kind, name) => `${kind}\0${name}`;
  * not pre-compute or pass field maps separately.
  */
 export function buildDependencyGraph(resources, registry, aliases, aliasesByModule) {
-    // --- Build node set ---
+    // --- Build node set + name index ---
     const nodes = new Map();
+    // 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();
     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);
-        nodes.set(key, { kind: r.kind, name: r.metadata.name });
+        const node = { kind: r.kind, name: r.metadata.name };
+        nodes.set(nodeKey(node.kind, node.name), node);
+        nodesByName.set(node.name, node);
     }
     // --- Build adjacency: from → deps (from depends on dep) ---
     const deps = new Map();
@@ -66,7 +65,22 @@ export function buildDependencyGraph(resources, registry, aliases, aliasesByModu
             if (!isRefEntry(entry))
                 continue;
             for (const val of resolveFieldValues(r, fieldPath)) {
-                if (!val || typeof val !== "object")
+                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)

package/dist/position-metadata.d.ts

@@ -15,7 +15,12 @@ export interface DocumentPosition {
 export declare function buildDocumentPositions(text: string, parsedDocs: Document[]): DocumentPosition[];
 /** 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 declare function documentLineOffsets(text: string): number[];
 /** Byte-offset → start-of-line lookup table. Index `i` is the byte offset of
  *  the first character on line `i`. Used with `offsetToPosition` to turn a

package/dist/position-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position-metadata.d.ts","sourceRoot":"","sources":["../src/position-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;oBAKoB;AAEpB,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,EAAE,GACrB,gBAAgB,EAAE,CAOpB;AAED;;8CAE8C;AAC9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAaD;;;;;+CAK+C;AAC/C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CA0CtF"}
+{"version":3,"file":"position-metadata.d.ts","sourceRoot":"","sources":["../src/position-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;oBAKoB;AAEpB,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,EAAE,GACrB,gBAAgB,EAAE,CAOpB;AAED;;;;;;;wCAOwC;AACxC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW1D;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAaD;;;;;+CAK+C;AAC/C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CA0CtF"}

package/dist/position-metadata.js

@@ -10,14 +10,22 @@ export function buildDocumentPositions(text, parsedDocs) {
 }
 /** 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) {
     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("--- "))
+        if (t === "---" || t.startsWith("--- ")) {
+            if (i === 0)
+                continue;
             offsets.push(i + 1);
+        }
     }
     return offsets;
 }

package/dist/precompile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAmCrE"}
+{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CA0CrE"}

package/dist/precompile.js

@@ -1,5 +1,5 @@
 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
  * `!cel`-tagged sentinels) with CompiledValue wrappers. Throws on CEL syntax
@@ -19,6 +19,14 @@ export function precompileDoc(doc, env) {
     // 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/dist/reference-field-map.js

@@ -98,7 +98,7 @@ export function buildReferenceFieldMap(schema) {
     const map = new Map();
     if (schema.properties) {
         for (const [key, propSchema] of Object.entries(schema.properties)) {
-            traverseNode(propSchema, key, map);
+            traverseNode(propSchema, key, map, schema);
         }
     }
     return map;
@@ -123,10 +123,23 @@ function collectRefs(node) {
  *  hid behind the schema-from indirection. */
 export function buildFieldMapAtPath(schema, pathPrefix) {
     const map = new Map();
-    traverseNode(schema, pathPrefix, map);
+    traverseNode(schema, pathPrefix, map, schema);
     return map;
 }
-function traverseNode(node, path, map) {
+function traverseNode(node, path, map, root, visitedRefs = new Set()) {
+    // 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"] });
@@ -148,12 +161,32 @@ function traverseNode(node, path, map) {
     }
     // Array — recurse into items
     if (node.type === "array" && node.items) {
-        traverseNode(node.items, path + "[]", map);
+        traverseNode(node.items, path + "[]", map, root, visitedRefs);
     }
     // Object — recurse into properties
     if (node.properties) {
         for (const [key, propSchema] of Object.entries(node.properties)) {
-            traverseNode(propSchema, `${path}.${key}`, map);
+            traverseNode(propSchema, `${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"]) {
+        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);
         }
     }
     // Map — `additionalProperties: { ... }` describes every value in an
@@ -162,6 +195,25 @@ function traverseNode(node, path, map) {
     if (node.additionalProperties &&
         typeof node.additionalProperties === "object" &&
         !Array.isArray(node.additionalProperties)) {
-        traverseNode(node.additionalProperties, `${path}.{}`, map);
+        traverseNode(node.additionalProperties, `${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, path, map, root, visitedRefs = new Set()) {
+    if (variant.properties) {
+        for (const [key, propSchema] of Object.entries(variant.properties)) {
+            traverseNode(propSchema, `${path}.${key}`, map, root, visitedRefs);
+        }
+    }
+    if (variant.type === "array" && variant.items) {
+        traverseNode(variant.items, path + "[]", map, root, visitedRefs);
+    }
+    if (variant.additionalProperties &&
+        typeof variant.additionalProperties === "object" &&
+        !Array.isArray(variant.additionalProperties)) {
+        traverseNode(variant.additionalProperties, `${path}.{}`, map, root, visitedRefs);
     }
 }

package/dist/resolve-ref-sentinels.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.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 declare function resolveRefSentinels(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): void;
+//# sourceMappingURL=resolve-ref-sentinels.d.ts.map

package/dist/resolve-ref-sentinels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-ref-sentinels.d.ts","sourceRoot":"","sources":["../src/resolve-ref-sentinels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,IAAI,CAsBN"}

package/dist/resolve-ref-sentinels.js

@@ -0,0 +1,114 @@
+import { isRefSentinel } from "@telorun/templating";
+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, registry, aliases, aliasesByModule) {
+    const byName = new Map();
+    for (const r of resources) {
+        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
+            byName.set(r.metadata.name, 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, 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, fieldPath, byName) {
+    const parts = fieldPath.split(".");
+    descend(obj, parts, byName);
+}
+function descend(obj, parts, byName) {
+    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;
+        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, name: child.source };
+                }
+            }
+            else {
+                descend(child, rest, byName);
+            }
+        }
+        return;
+    }
+    const isArr = head.endsWith("[]");
+    const key = isArr ? head.slice(0, -2) : head;
+    const container = obj;
+    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, 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, name: val.source };
+            }
+        }
+        else {
+            descend(val, rest, byName);
+        }
+    }
+}

package/dist/schema-compat.d.ts

@@ -1,6 +1,12 @@
 declare const Ajv: any;
 /** 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 declare function createAjv(): InstanceType<typeof Ajv>;
 export interface CompatibilityResult {
     compatible: boolean;

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;0FAC0F;AAC1F,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAMpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAe/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CA2BT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAOpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAe/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAqCT"}

package/dist/schema-compat.js

@@ -1,14 +1,21 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isTaggedSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
 const Ajv = AjvModule.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() {
     const instance = new Ajv({ allErrors: true, strict: false });
     addFormats.default
         ? addFormats.default(instance)
         : addFormats(instance);
+    instance.addSchema(ManifestRootSchema);
     return instance;
 }
 const ajv = createAjv();
@@ -270,6 +277,16 @@ export function substituteCelFields(data, schema, rootSchema) {
     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);
     }

package/dist/system-kinds.d.ts

@@ -0,0 +1,25 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export declare const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string>;
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export declare const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string>;
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export declare const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string>;
+//# sourceMappingURL=system-kinds.d.ts.map

package/dist/system-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-kinds.d.ts","sourceRoot":"","sources":["../src/system-kinds.ts"],"names":[],"mappings":"AAAA;;;;sEAIsE;AAEtE;;;;;;0CAM0C;AAC1C,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAGxD,CAAC;AAEH;;;4CAG4C;AAC5C,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAG1D,CAAC;AAEH;;;;0EAI0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAIxD,CAAC"}

package/dist/system-kinds.js

@@ -0,0 +1,34 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Abstract",
+]);
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Import",
+]);
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Abstract",
+    "Telo.Import",
+]);

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

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

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.
@@ -122,6 +118,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.3.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/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);
   }

package/src/system-kinds.ts

@@ -0,0 +1,37 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+]);
+
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Import",
+]);
+
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Import",
+]);

package/src/validate-references.ts

@@ -1,17 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues, type RefFieldEntry } 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, type AnalysisDiagnostic, type AnalysisContext } from "./types.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.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`.
@@ -145,6 +141,38 @@ export function validateReferences(
       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 as string, 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.