@telorun/analyzer 0.21.0 → 0.22.0

package/README.md

@@ -58,8 +58,8 @@ imports:
   Http: std/http-server@0.9.0
   Sql: std/sql@0.8.0
 targets:
-  - Migrations
-  - Server
+  - !ref Migrations
+  - !ref Server
 ---
 # SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
 kind: Sql.Connection
@@ -72,9 +72,7 @@ file: ./tmp/feedback.db
 kind: Sql.Migrations
 metadata:
   name: Migrations
-connection:
-  kind: Sql.Connection
-  name: Db
+connection: !ref Db
 ---
 kind: Sql.Migration
 metadata:
@@ -101,7 +99,7 @@ openapi:
     version: 1.0.0
 mounts:
   - path: /v1
-    type: Http.Api.FeedbackRoutes
+    mount: !ref FeedbackRoutes
 ---
 kind: Http.Api
 metadata:
@@ -123,9 +121,7 @@ routes:
           required: [ text ]
     handler:
       kind: Sql.Exec
-      connection:
-        kind: Sql.Connection
-        name: Db
+      connection: !ref Db
     inputs:
       sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
       bindings:
@@ -146,9 +142,7 @@ routes:
       method: GET
     handler:
       kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
+      connection: !ref Db
       from: feedback
       columns: [ id, text, source, score, created_at ]
       orderBy:
@@ -172,9 +166,7 @@ routes:
           required: [ id ]
     handler:
       kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
+      connection: !ref Db
       from: feedback
       columns: [ id, text, source, score, created_at ]
       where:

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA2hB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAypBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAqBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4hB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAkqBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAerB,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

@@ -18,6 +18,7 @@ import { validateExtends } from "./validate-extends.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
+import { validateReferenceForms } from "./validate-reference-forms.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 const SELF_PREFIX = "Self.";
@@ -646,13 +647,21 @@ export class StaticAnalyzer {
                 : def;
             defs.register(normalized);
         }
+        // Reference-form validation — enforce `!ref` as the only reference shape.
+        // Runs on the RAW manifests, BEFORE inline extraction and sentinel
+        // resolution, while an author-written `{kind, name}` is still
+        // distinguishable from the resolver's own substitution (after Phase 2/2.5
+        // they are the same object).
+        if (!options?.skipValidation) {
+            diagnostics.push(...validateReferenceForms(manifests, defs, aliases, aliasesByModule));
+        }
         // 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);
+        resolveRefSentinels(allManifests, 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.
@@ -1058,7 +1067,7 @@ export class StaticAnalyzer {
         // 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, crossModuleTargets ?? []);
+        resolveRefSentinels(normalized, ctx.aliases, ctx.aliasesByModule, crossModuleTargets ?? []);
         return normalized;
     }
     prepare(manifests, registry) {

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,EAsd/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,EAqd/C,CAAC"}

package/dist/builtins.js

@@ -234,7 +234,7 @@ export const KERNEL_BUILTINS = [
                             },
                             // Gated reference: run() a Runnable/Service only when the
                             // `when` CEL guard holds. Discriminated by the `ref` key. `ref`
-                            // is a bare name or a resolved `!ref` (`{ kind, name }`).
+                            // is a `!ref` that resolves to the `{ kind, name }` shape below.
                             {
                                 type: "object",
                                 required: ["ref"],
@@ -262,12 +262,11 @@ export const KERNEL_BUILTINS = [
                             // with an optional `name` (for steps.<name>.result plumbing),
                             // `when` guard, and `inputs`. Discriminated by the `invoke` key.
                             // Control flow (if/while/switch/try) is not available here —
-                            // reach for Run.Sequence. `invoke` is ref-only and must resolve
-                            // to a `{ kind, name }` reference (a `!ref` / `{kind,name}`):
-                            // requiring `name` rejects an inline `{ kind }` definition (no
-                            // name) at analysis instead of failing at boot with an undefined
-                            // resource name. The Invocable/Runnable kind set mirrors
-                            // Run.Sequence invoke steps.
+                            // reach for Run.Sequence. `invoke` is ref-only: a `!ref` that
+                            // resolves to the `{ kind, name }` shape below. Requiring `name`
+                            // rejects an inline `{ kind }` definition (no name) at analysis
+                            // instead of failing at boot with an undefined resource name. The
+                            // Invocable/Runnable kind set mirrors Run.Sequence invoke steps.
                             {
                                 type: "object",
                                 required: ["invoke"],

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

@@ -1,10 +1,23 @@
 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, name}` (local) or
- * `{kind, name, alias}` (cross-module).
+ * Rewrites every `!ref <name>` sentinel in each non-system resource's value tree
+ * to `{kind, name}` (local) or `{kind, name, alias}` (cross-module), in place.
+ *
+ * The walk is value-tree-driven, not field-map-driven: a `!ref` tag is an
+ * *explicit* reference marker, so any sentinel found anywhere is unambiguously a
+ * reference and is resolved. This reaches sites the field map intentionally does
+ * not descend — notably `Run.Sequence` step `invoke`s (behind a local `$ref`)
+ * and references nested inside inline definitions — so every downstream consumer
+ * (Phase-5 injection, the runtime controllers, the analyzer's step-context and
+ * dependency passes) sees the uniform `{kind, name}` shape regardless of where
+ * the reference was written.
+ *
+ * Resolving a sentinel here does NOT cause Phase-5 injection: that pass is
+ * driven by the field map, which still excludes step `invoke`s, so a resolved
+ * step invoke stays `{kind, name}` and is dispatched through
+ * `executeInvokeStep` (preserving `<Kind>.<Name>.Invoked` events) rather than
+ * being replaced with a live instance.
  *
  * Reference grammar — the tag's source string is split on the FIRST dot:
  *   - `!ref writeLine`          → local resource `writeLine`
@@ -14,12 +27,14 @@ import type { DefinitionRegistry } from "./definition-registry.js";
  *
  * Aliases are PascalCase identifiers without dots and resource names carry no dots
  * (enforced as a hard diagnostic), so the first-dot split is unambiguous. When the
- * name doesn't resolve, the sentinel is left in place so `validateReferences` emits the
- * `UNRESOLVED_REFERENCE` diagnostic with full context.
+ * name doesn't resolve (e.g. a scope-local target, or a cross-module reference in
+ * partial single-file analysis), the sentinel is left in place — the runtime
+ * resolves scope-local names on demand, and `validateReferences` emits the
+ * `UNRESOLVED_REFERENCE` diagnostic for genuine misses.
  *
  * Forwarded foreign resources (an imported library's exported instances, carrying a
  * `metadata.module` that isn't a root module) are resolution TARGETS only — they are not
  * re-walked as sources here, since their own ref slots belong to their own module scope.
  */
-export declare function resolveRefSentinels(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>, crossModuleTargets?: ResourceManifest[]): void;
+export declare function resolveRefSentinels(resources: ResourceManifest[], aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>, crossModuleTargets?: ResourceManifest[]): void;
 //# sourceMappingURL=resolve-ref-sentinels.d.ts.map

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

@@ -1 +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;AAQnE;;;;;;;;;;;;;;;;;;;GAmBG;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,EAK5C,kBAAkB,GAAE,gBAAgB,EAAO,GAC1C,IAAI,CAmFN"}
+{"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;AAOzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAK5C,kBAAkB,GAAE,gBAAgB,EAAO,GAC1C,IAAI,CAgFN"}

package/dist/resolve-ref-sentinels.js

@@ -1,10 +1,23 @@
-import { isRefSentinel } from "@telorun/templating";
-import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
+import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 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, name}` (local) or
- * `{kind, name, alias}` (cross-module).
+ * Rewrites every `!ref <name>` sentinel in each non-system resource's value tree
+ * to `{kind, name}` (local) or `{kind, name, alias}` (cross-module), in place.
+ *
+ * The walk is value-tree-driven, not field-map-driven: a `!ref` tag is an
+ * *explicit* reference marker, so any sentinel found anywhere is unambiguously a
+ * reference and is resolved. This reaches sites the field map intentionally does
+ * not descend — notably `Run.Sequence` step `invoke`s (behind a local `$ref`)
+ * and references nested inside inline definitions — so every downstream consumer
+ * (Phase-5 injection, the runtime controllers, the analyzer's step-context and
+ * dependency passes) sees the uniform `{kind, name}` shape regardless of where
+ * the reference was written.
+ *
+ * Resolving a sentinel here does NOT cause Phase-5 injection: that pass is
+ * driven by the field map, which still excludes step `invoke`s, so a resolved
+ * step invoke stays `{kind, name}` and is dispatched through
+ * `executeInvokeStep` (preserving `<Kind>.<Name>.Invoked` events) rather than
+ * being replaced with a live instance.
  *
  * Reference grammar — the tag's source string is split on the FIRST dot:
  *   - `!ref writeLine`          → local resource `writeLine`
@@ -14,14 +27,16 @@ import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
  *
  * Aliases are PascalCase identifiers without dots and resource names carry no dots
  * (enforced as a hard diagnostic), so the first-dot split is unambiguous. When the
- * name doesn't resolve, the sentinel is left in place so `validateReferences` emits the
- * `UNRESOLVED_REFERENCE` diagnostic with full context.
+ * name doesn't resolve (e.g. a scope-local target, or a cross-module reference in
+ * partial single-file analysis), the sentinel is left in place — the runtime
+ * resolves scope-local names on demand, and `validateReferences` emits the
+ * `UNRESOLVED_REFERENCE` diagnostic for genuine misses.
  *
  * Forwarded foreign resources (an imported library's exported instances, carrying a
  * `metadata.module` that isn't a root module) are resolution TARGETS only — they are not
  * re-walked as sources here, since their own ref slots belong to their own module scope.
  */
-export function resolveRefSentinels(resources, registry, aliases, aliasesByModule, 
+export function resolveRefSentinels(resources, aliases, aliasesByModule, 
 // Extra foreign resources used only as cross-module resolution TARGETS (not mutated, not
 // walked as sources). The kernel passes the analyzer-flattened set here so the runtime
 // pass — which loads the entry module only — can still resolve `!ref Alias.name` against
@@ -81,138 +96,33 @@ crossModuleTargets = []) {
         }
         return undefined;
     };
-    const processResource = (r) => {
-        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
-            return;
-        const fieldMap = aliases && aliasesByModule
-            ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
-            : registry.getFieldMapForKind(r.kind, aliases);
-        if (!fieldMap)
-            return;
-        for (const [fieldPath, entry] of fieldMap) {
-            const parts = fieldPath.split(".");
-            if (isRefEntry(entry)) {
-                descend(r, parts, resolveTarget);
-            }
-            else if (isScopeEntry(entry)) {
-                // x-telo-scope resources (e.g. a Run.Sequence `with` server) carry their own ref
-                // slots. The top-level walk skips scope contents, so recurse so a scoped resource's
-                // `!ref` (e.g. an Http.Server mount) is canonicalized to {kind, name} like any other.
-                forEachScopeResource(r, parts, processResource);
-            }
+    // Resolve every `!ref` sentinel in the tree; leave opaque tagged / precompiled
+    // nodes (e.g. `!cel`) untouched and don't descend into them.
+    const walk = (value) => {
+        if (isRefSentinel(value)) {
+            return resolveTarget(value.source) ?? value;
         }
+        if (value === null || typeof value !== "object")
+            return value;
+        if (isTaggedSentinel(value))
+            return value;
+        if (value.__compiled)
+            return value;
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++)
+                value[i] = walk(value[i]);
+            return value;
+        }
+        const obj = value;
+        for (const key of Object.keys(obj))
+            obj[key] = walk(obj[key]);
+        return value;
     };
     for (const r of resources) {
         if (isForeign(r))
             continue;
-        processResource(r);
-    }
-}
-/**
- * Navigates `obj` along the scope field path (dot notation, `[]` = array items) and
- * invokes `cb` on every resource-like object found — any value carrying a `kind` string.
- *
- * Two-phase design:
- *
- *  Phase 1 — path-walk: steps through each `parts` segment. `[]`-suffixed parts spread
- *  the array into individual elements so `current` always ends up holding scalars or
- *  plain objects, never intermediate arrays. Non-`[]` parts push the value as-is.
- *
- *  Phase 2 — terminal visit: after the walk, `current` contains the values at the end
- *  of the path. These are always scalars or plain objects because of the `[]` spreading
- *  above, EXCEPT when a scope field is typed as an array in the schema but the path
- *  was authored WITHOUT a `[]` suffix. The `visit` function handles that case by
- *  recursing one level into arrays so `cb` is always called on resource objects, not
- *  on their container.
- */
-function forEachScopeResource(obj, parts, cb) {
-    let current = [obj];
-    for (const part of parts) {
-        const isArr = part.endsWith("[]");
-        const key = isArr ? part.slice(0, -2) : part;
-        const next = [];
-        for (const node of current) {
-            if (!node || typeof node !== "object")
-                continue;
-            const val = node[key];
-            if (val == null)
-                continue;
-            if (isArr && Array.isArray(val))
-                next.push(...val);
-            else if (!isArr)
-                next.push(val);
-        }
-        current = next;
-    }
-    const visit = (node) => {
-        if (Array.isArray(node)) {
-            for (const elem of node)
-                visit(elem);
-        }
-        else if (node && typeof node === "object" && typeof node.kind === "string") {
-            cb(node);
-        }
-    };
-    for (const node of current)
-        visit(node);
-}
-/** Walks `obj` along `fieldPath` parts (dot notation with `[]` for arrays and `{}` for
- *  additionalProperties-typed maps) and replaces any `!ref` sentinel at the terminal slot
- *  with its resolved `{kind, name, alias?}`. Mutates the parent container in place. */
-function descend(obj, parts, resolve) {
-    if (obj == null || typeof obj !== "object" || parts.length === 0)
-        return;
-    const [head, ...rest] = parts;
-    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 = resolve(child.source);
-                    if (target)
-                        container[key] = target;
-                }
-            }
-            else {
-                descend(child, rest, resolve);
-            }
-        }
-        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 = resolve(elem.source);
-                    if (target)
-                        val[i] = target;
-                }
-            }
-            else {
-                descend(val[i], rest, resolve);
-            }
-        }
-    }
-    else {
-        if (rest.length === 0) {
-            if (isRefSentinel(val)) {
-                const target = resolve(val.source);
-                if (target)
-                    container[key] = target;
-            }
-        }
-        else {
-            descend(val, rest, resolve);
-        }
+        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
+            continue;
+        walk(r);
     }
 }

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;;;;;;;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,CAmB/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;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AAID,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUlF;AAED;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"}
+{"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;AAaD,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CA2B/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;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AAID,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUlF;AAED;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,6 +1,6 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
  *  Also registers the kernel manifest root schema under `telo://manifest` so
@@ -100,21 +100,41 @@ function ajvErrorToPath(err) {
     }
     return result;
 }
+/** Does `schema` compile as-authored? Used to tell a malformed module schema
+ *  (the author's problem) apart from a fault we introduced while normalizing it. */
+function schemaCompiles(schema) {
+    try {
+        ajv.compile(schema);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export function validateAgainstSchema(data, schema) {
     let validate = compiledSchemaValidators.get(schema);
     if (!validate) {
+        // Normalize outside the try: a fault in our own ref-slot normalization must
+        // surface, never be mistaken for the module author's schema being malformed.
+        // Drop the legacy scalar `type` an older published module may still pin on
+        // its `x-telo-ref` slots so a resolved reference object validates.
+        const normalized = normalizeRefSlots(schema);
         try {
-            validate = ajv.compile(schema);
-            compiledSchemaValidators.set(schema, validate);
+            validate = ajv.compile(normalized);
         }
-        catch {
-            // A schema that won't compile is reported loudly (once, on the owning
-            // definition) by the analyzer's definition-schema compile check
-            // (`DefinitionRegistry.schemaCompileError`), so returning `[]` here does
-            // not silently accept resources of that kind.
+        catch (err) {
+            // The normalized schema didn't compile. If the original schema is itself
+            // malformed, that is the module author's error — already surfaced once,
+            // anchored on the definition, by the analyzer's `SCHEMA_COMPILE_ERROR`
+            // pre-check (`DefinitionRegistry.schemaCompileError`); re-reporting it per
+            // resource would be noise, so skip. If the original compiles and only the
+            // normalized form fails, the fault is ours — let it throw.
+            if (schemaCompiles(schema))
+                throw err;
             return [];
         }
+        compiledSchemaValidators.set(schema, validate);
     }
     if (validate(data))
         return [];

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAkCjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD"}

package/dist/validate-cel-context.js

@@ -27,6 +27,11 @@ export function resolveTypeFieldToSchema(value, allManifests) {
         if (obj.type || obj.properties) {
             return obj;
         }
+        // Named type reference resolved from a `!ref` → { kind, name } — resolve the
+        // named Telo.Type the same way as the bare-string form.
+        if (typeof obj.name === "string") {
+            return resolveTypeFieldToSchema(obj.name, allManifests);
+        }
     }
     return undefined;
 }

package/dist/validate-reference-forms.d.ts

@@ -0,0 +1,28 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Reference-form validation — the single enforcement point for "a reference is
+ * written `!ref <name>` (or `!ref <Alias>.<name>`), nothing else".
+ *
+ * Runs on the RAW manifest set, BEFORE inline-resource extraction and `!ref`
+ * sentinel resolution. That ordering is load-bearing: only at this point is an
+ * author-written value still distinguishable from the resolver's own
+ * substitution. After normalization both an author's `{kind, name}` and a
+ * resolved `!ref` are the same `{kind, name}` object, so no later pass — and no
+ * JSON Schema — can tell them apart.
+ *
+ * At every `x-telo-ref` slot the only accepted value is:
+ *   - a `!ref` sentinel (or any tagged sentinel — e.g. a `${{ }}` ref passed
+ *     through a template), or
+ *   - an inline definition: a plain object with a `kind` and NO `name` (the
+ *     extractor assigns the name), or
+ *   - a `${{ }}` CEL expression string (a reference flowed through CEL).
+ *
+ * Rejected, each with an actionable diagnostic pointing at `!ref`:
+ *   - the object form `{ kind, name }` (the old reference object), and
+ *   - a bare string (the old name / dotted-FQN reference).
+ */
+export declare function validateReferenceForms(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-reference-forms.d.ts.map

package/dist/validate-reference-forms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-reference-forms.d.ts","sourceRoot":"","sources":["../src/validate-reference-forms.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;AAGnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,kBAAkB,EAAE,CA+DtB"}

package/dist/validate-reference-forms.js

@@ -0,0 +1,91 @@
+import { isTaggedSentinel } from "@telorun/templating";
+import { visitManifest } from "./manifest-visitor.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Reference-form validation — the single enforcement point for "a reference is
+ * written `!ref <name>` (or `!ref <Alias>.<name>`), nothing else".
+ *
+ * Runs on the RAW manifest set, BEFORE inline-resource extraction and `!ref`
+ * sentinel resolution. That ordering is load-bearing: only at this point is an
+ * author-written value still distinguishable from the resolver's own
+ * substitution. After normalization both an author's `{kind, name}` and a
+ * resolved `!ref` are the same `{kind, name}` object, so no later pass — and no
+ * JSON Schema — can tell them apart.
+ *
+ * At every `x-telo-ref` slot the only accepted value is:
+ *   - a `!ref` sentinel (or any tagged sentinel — e.g. a `${{ }}` ref passed
+ *     through a template), or
+ *   - an inline definition: a plain object with a `kind` and NO `name` (the
+ *     extractor assigns the name), or
+ *   - a `${{ }}` CEL expression string (a reference flowed through CEL).
+ *
+ * Rejected, each with an actionable diagnostic pointing at `!ref`:
+ *   - the object form `{ kind, name }` (the old reference object), and
+ *   - a bare string (the old name / dotted-FQN reference).
+ */
+export function validateReferenceForms(resources, registry, aliases, aliasesByModule) {
+    if (!aliases)
+        return [];
+    const diagnostics = [];
+    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    const localResources = resources.filter((r) => !isForeign(r));
+    visitManifest(localResources, registry, {
+        onRef: (e) => {
+            const value = e.value;
+            // `!ref` and `!cel`/`${{ }}` sentinels are the supported shapes.
+            if (isTaggedSentinel(value))
+                return;
+            const r = e.source;
+            const resourceLabel = `${r.kind}/${r.metadata.name}`;
+            const resourceData = { kind: r.kind, name: r.metadata.name };
+            const filePath = r.metadata?.source;
+            const path = e.concretePath;
+            if (typeof value === "string") {
+                // A `${{ }}` reference flowed through CEL is fine; any other bare
+                // string at a ref slot is the removed string / dotted-FQN form.
+                if (value.includes("${{"))
+                    return;
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "INVALID_REFERENCE_FORM",
+                    source: SOURCE,
+                    message: `${resourceLabel}: string reference at '${path}' → '${value}' is not supported; write it as '!ref ${refHint(value)}'`,
+                    data: { resource: resourceData, filePath, path },
+                });
+                return;
+            }
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                const obj = value;
+                // A plain object is an inline definition unless it names a resource —
+                // a `name` makes it the removed `{ kind, name }` reference object.
+                if (typeof obj.name === "string" && typeof obj.kind === "string") {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "INVALID_REFERENCE_FORM",
+                        source: SOURCE,
+                        message: `${resourceLabel}: object reference '{ kind, name }' at '${path}' is not supported; write it as '!ref ${obj.name}'`,
+                        data: { resource: resourceData, filePath, path },
+                    });
+                }
+            }
+        },
+    }, {
+        aliases,
+        aliasesByModule,
+        skipKinds: SYSTEM_KINDS,
+        expand: true,
+        discoverNestedRefs: true,
+    });
+    return diagnostics;
+}
+/** Best-effort name for the `!ref` suggestion in a string-ref diagnostic: a
+ *  dotted-FQN (`Http.Api.UsersApi`) keeps its last segment, an alias-qualified
+ *  name (`Console.writeLine`) is left intact, a bare name passes through. */
+function refHint(value) {
+    const dotCount = (value.match(/\./g) ?? []).length;
+    if (dotCount >= 2)
+        return value.slice(value.lastIndexOf(".") + 1);
+    return value;
+}

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

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

package/dist/validate-references.js

@@ -272,43 +272,10 @@ export function validateReferences(resources, context) {
                 }
                 return;
             }
-            // 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.
-            if (typeof val === "string") {
-                const lastDot = val.lastIndexOf(".");
-                const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
-                const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
-                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-                if (!target) {
-                    // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
-                    // The resource lives in the imported module's scope and can't be validated here.
-                    // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
-                    // kinds — those must be validated.
-                    if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
-                        return;
-                    }
-                    diagnostics.push({
-                        severity: DiagnosticSeverity.Error,
-                        code: "UNRESOLVED_REFERENCE",
-                        source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
-                        data: { resource: resourceData, filePath, path: concretePath },
-                    });
-                    return;
-                }
-                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 },
-                    });
-                }
-                return;
-            }
+            // Bare strings are no longer a reference shape — `validateReferenceForms`
+            // rejects an author-written string at a ref slot before this pass runs,
+            // and a `${{ }}` reference flowed through CEL is resolved/typed
+            // elsewhere. Anything still a string here is not a reference to resolve.
             if (typeof val !== "object")
                 return;
             const refVal = val;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.7.0"
+    "@telorun/templating": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analyzer.ts

@@ -36,6 +36,7 @@ import { validateExtends } from "./validate-extends.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
+import { validateReferenceForms } from "./validate-reference-forms.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
@@ -774,6 +775,15 @@ export class StaticAnalyzer {
       defs.register(normalized);
     }
 
+    // Reference-form validation — enforce `!ref` as the only reference shape.
+    // Runs on the RAW manifests, BEFORE inline extraction and sentinel
+    // resolution, while an author-written `{kind, name}` is still
+    // distinguishable from the resolver's own substitution (after Phase 2/2.5
+    // they are the same object).
+    if (!options?.skipValidation) {
+      diagnostics.push(...validateReferenceForms(manifests, defs, aliases, aliasesByModule));
+    }
+
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
     const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
 
@@ -781,7 +791,7 @@ export class StaticAnalyzer {
     // {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);
+    resolveRefSentinels(allManifests, 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
@@ -1286,13 +1296,7 @@ export class StaticAnalyzer {
     // 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,
-      crossModuleTargets ?? [],
-    );
+    resolveRefSentinels(normalized, ctx.aliases, ctx.aliasesByModule, crossModuleTargets ?? []);
     return normalized;
   }
 

package/src/builtins.ts

@@ -236,7 +236,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               },
               // Gated reference: run() a Runnable/Service only when the
               // `when` CEL guard holds. Discriminated by the `ref` key. `ref`
-              // is a bare name or a resolved `!ref` (`{ kind, name }`).
+              // is a `!ref` that resolves to the `{ kind, name }` shape below.
               {
                 type: "object",
                 required: ["ref"],
@@ -264,12 +264,11 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               // with an optional `name` (for steps.<name>.result plumbing),
               // `when` guard, and `inputs`. Discriminated by the `invoke` key.
               // Control flow (if/while/switch/try) is not available here —
-              // reach for Run.Sequence. `invoke` is ref-only and must resolve
-              // to a `{ kind, name }` reference (a `!ref` / `{kind,name}`):
-              // requiring `name` rejects an inline `{ kind }` definition (no
-              // name) at analysis instead of failing at boot with an undefined
-              // resource name. The Invocable/Runnable kind set mirrors
-              // Run.Sequence invoke steps.
+              // reach for Run.Sequence. `invoke` is ref-only: a `!ref` that
+              // resolves to the `{ kind, name }` shape below. Requiring `name`
+              // rejects an inline `{ kind }` definition (no name) at analysis
+              // instead of failing at boot with an undefined resource name. The
+              // Invocable/Runnable kind set mirrors Run.Sequence invoke steps.
               {
                 type: "object",
                 required: ["invoke"],

package/src/resolve-ref-sentinels.ts

@@ -1,8 +1,6 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
-import type { DefinitionRegistry } from "./definition-registry.js";
-import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 /** Resolved ref shape written in place of a `!ref` sentinel. `alias` is set only for
@@ -10,9 +8,23 @@ import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 type ResolvedRef = { kind: string; name: string; alias?: string };
 
 /**
- * Walks every `x-telo-ref` slot in every non-system resource and rewrites
- * `!ref <name>` sentinels in-place to `{kind, name}` (local) or
- * `{kind, name, alias}` (cross-module).
+ * Rewrites every `!ref <name>` sentinel in each non-system resource's value tree
+ * to `{kind, name}` (local) or `{kind, name, alias}` (cross-module), in place.
+ *
+ * The walk is value-tree-driven, not field-map-driven: a `!ref` tag is an
+ * *explicit* reference marker, so any sentinel found anywhere is unambiguously a
+ * reference and is resolved. This reaches sites the field map intentionally does
+ * not descend — notably `Run.Sequence` step `invoke`s (behind a local `$ref`)
+ * and references nested inside inline definitions — so every downstream consumer
+ * (Phase-5 injection, the runtime controllers, the analyzer's step-context and
+ * dependency passes) sees the uniform `{kind, name}` shape regardless of where
+ * the reference was written.
+ *
+ * Resolving a sentinel here does NOT cause Phase-5 injection: that pass is
+ * driven by the field map, which still excludes step `invoke`s, so a resolved
+ * step invoke stays `{kind, name}` and is dispatched through
+ * `executeInvokeStep` (preserving `<Kind>.<Name>.Invoked` events) rather than
+ * being replaced with a live instance.
  *
  * Reference grammar — the tag's source string is split on the FIRST dot:
  *   - `!ref writeLine`          → local resource `writeLine`
@@ -22,8 +34,10 @@ type ResolvedRef = { kind: string; name: string; alias?: string };
  *
  * Aliases are PascalCase identifiers without dots and resource names carry no dots
  * (enforced as a hard diagnostic), so the first-dot split is unambiguous. When the
- * name doesn't resolve, the sentinel is left in place so `validateReferences` emits the
- * `UNRESOLVED_REFERENCE` diagnostic with full context.
+ * name doesn't resolve (e.g. a scope-local target, or a cross-module reference in
+ * partial single-file analysis), the sentinel is left in place — the runtime
+ * resolves scope-local names on demand, and `validateReferences` emits the
+ * `UNRESOLVED_REFERENCE` diagnostic for genuine misses.
  *
  * Forwarded foreign resources (an imported library's exported instances, carrying a
  * `metadata.module` that isn't a root module) are resolution TARGETS only — they are not
@@ -31,7 +45,6 @@ type ResolvedRef = { kind: string; name: string; alias?: string };
  */
 export function resolveRefSentinels(
   resources: ResourceManifest[],
-  registry: DefinitionRegistry,
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
   // Extra foreign resources used only as cross-module resolution TARGETS (not mutated, not
@@ -96,134 +109,27 @@ export function resolveRefSentinels(
     return undefined;
   };
 
-  const processResource = (r: ResourceManifest): void => {
-    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) return;
-
-    const fieldMap =
-      aliases && aliasesByModule
-        ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
-        : registry.getFieldMapForKind(r.kind, aliases);
-    if (!fieldMap) return;
-
-    for (const [fieldPath, entry] of fieldMap) {
-      const parts = fieldPath.split(".");
-      if (isRefEntry(entry)) {
-        descend(r as Record<string, unknown>, parts, resolveTarget);
-      } else if (isScopeEntry(entry)) {
-        // x-telo-scope resources (e.g. a Run.Sequence `with` server) carry their own ref
-        // slots. The top-level walk skips scope contents, so recurse so a scoped resource's
-        // `!ref` (e.g. an Http.Server mount) is canonicalized to {kind, name} like any other.
-        forEachScopeResource(r as Record<string, unknown>, parts, processResource);
-      }
+  // Resolve every `!ref` sentinel in the tree; leave opaque tagged / precompiled
+  // nodes (e.g. `!cel`) untouched and don't descend into them.
+  const walk = (value: unknown): unknown => {
+    if (isRefSentinel(value)) {
+      return resolveTarget(value.source) ?? value;
     }
+    if (value === null || typeof value !== "object") return value;
+    if (isTaggedSentinel(value)) return value;
+    if ((value as { __compiled?: unknown }).__compiled) return value;
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) value[i] = walk(value[i]);
+      return value;
+    }
+    const obj = value as Record<string, unknown>;
+    for (const key of Object.keys(obj)) obj[key] = walk(obj[key]);
+    return value;
   };
 
   for (const r of resources) {
     if (isForeign(r)) continue;
-    processResource(r);
-  }
-}
-
-/**
- * Navigates `obj` along the scope field path (dot notation, `[]` = array items) and
- * invokes `cb` on every resource-like object found — any value carrying a `kind` string.
- *
- * Two-phase design:
- *
- *  Phase 1 — path-walk: steps through each `parts` segment. `[]`-suffixed parts spread
- *  the array into individual elements so `current` always ends up holding scalars or
- *  plain objects, never intermediate arrays. Non-`[]` parts push the value as-is.
- *
- *  Phase 2 — terminal visit: after the walk, `current` contains the values at the end
- *  of the path. These are always scalars or plain objects because of the `[]` spreading
- *  above, EXCEPT when a scope field is typed as an array in the schema but the path
- *  was authored WITHOUT a `[]` suffix. The `visit` function handles that case by
- *  recursing one level into arrays so `cb` is always called on resource objects, not
- *  on their container.
- */
-function forEachScopeResource(
-  obj: Record<string, unknown>,
-  parts: string[],
-  cb: (resource: ResourceManifest) => void,
-): void {
-  let current: unknown[] = [obj];
-  for (const part of parts) {
-    const isArr = part.endsWith("[]");
-    const key = isArr ? part.slice(0, -2) : part;
-    const next: unknown[] = [];
-    for (const node of current) {
-      if (!node || typeof node !== "object") continue;
-      const val = (node as Record<string, unknown>)[key];
-      if (val == null) continue;
-      if (isArr && Array.isArray(val)) next.push(...val);
-      else if (!isArr) next.push(val);
-    }
-    current = next;
-  }
-  const visit = (node: unknown): void => {
-    if (Array.isArray(node)) {
-      for (const elem of node) visit(elem);
-    } else if (node && typeof node === "object" && typeof (node as { kind?: unknown }).kind === "string") {
-      cb(node as ResourceManifest);
-    }
-  };
-  for (const node of current) visit(node);
-}
-
-/** Walks `obj` along `fieldPath` parts (dot notation with `[]` for arrays and `{}` for
- *  additionalProperties-typed maps) and replaces any `!ref` sentinel at the terminal slot
- *  with its resolved `{kind, name, alias?}`. Mutates the parent container in place. */
-function descend(
-  obj: unknown,
-  parts: string[],
-  resolve: (source: string) => ResolvedRef | undefined,
-): void {
-  if (obj == null || typeof obj !== "object" || parts.length === 0) return;
-  const [head, ...rest] = parts;
-
-  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 = resolve(child.source);
-          if (target) container[key] = target;
-        }
-      } else {
-        descend(child, rest, resolve);
-      }
-    }
-    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 = resolve(elem.source);
-          if (target) val[i] = target;
-        }
-      } else {
-        descend(val[i], rest, resolve);
-      }
-    }
-  } else {
-    if (rest.length === 0) {
-      if (isRefSentinel(val)) {
-        const target = resolve(val.source);
-        if (target) container[key] = target;
-      }
-    } else {
-      descend(val, rest, resolve);
-    }
+    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+    walk(r as Record<string, unknown>);
   }
 }

package/src/schema-compat.ts

@@ -1,6 +1,6 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
 
@@ -138,20 +138,39 @@ export interface SchemaIssue {
   path: string;
 }
 
+/** Does `schema` compile as-authored? Used to tell a malformed module schema
+ *  (the author's problem) apart from a fault we introduced while normalizing it. */
+function schemaCompiles(schema: Record<string, any>): boolean {
+  try {
+    ajv.compile(schema);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[] {
   let validate = compiledSchemaValidators.get(schema);
   if (!validate) {
+    // Normalize outside the try: a fault in our own ref-slot normalization must
+    // surface, never be mistaken for the module author's schema being malformed.
+    // Drop the legacy scalar `type` an older published module may still pin on
+    // its `x-telo-ref` slots so a resolved reference object validates.
+    const normalized = normalizeRefSlots(schema) as Record<string, any>;
     try {
-      validate = ajv.compile(schema);
-      compiledSchemaValidators.set(schema, validate);
-    } catch {
-      // A schema that won't compile is reported loudly (once, on the owning
-      // definition) by the analyzer's definition-schema compile check
-      // (`DefinitionRegistry.schemaCompileError`), so returning `[]` here does
-      // not silently accept resources of that kind.
+      validate = ajv.compile(normalized);
+    } catch (err) {
+      // The normalized schema didn't compile. If the original schema is itself
+      // malformed, that is the module author's error — already surfaced once,
+      // anchored on the definition, by the analyzer's `SCHEMA_COMPILE_ERROR`
+      // pre-check (`DefinitionRegistry.schemaCompileError`); re-reporting it per
+      // resource would be noise, so skip. If the original compiles and only the
+      // normalized form fails, the fault is ours — let it throw.
+      if (schemaCompiles(schema)) throw err;
       return [];
     }
+    compiledSchemaValidators.set(schema, validate);
   }
   if (validate(data)) return [];
   return (validate.errors ?? []).map((err: any) => ({

package/src/validate-cel-context.ts

@@ -51,6 +51,11 @@ export function resolveTypeFieldToSchema(
     if (obj.type || obj.properties) {
       return obj;
     }
+    // Named type reference resolved from a `!ref` → { kind, name } — resolve the
+    // named Telo.Type the same way as the bare-string form.
+    if (typeof obj.name === "string") {
+      return resolveTypeFieldToSchema(obj.name, allManifests);
+    }
   }
 
   return undefined;

package/src/validate-reference-forms.ts

@@ -0,0 +1,110 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { isTaggedSentinel } from "@telorun/templating";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { visitManifest } from "./manifest-visitor.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Reference-form validation — the single enforcement point for "a reference is
+ * written `!ref <name>` (or `!ref <Alias>.<name>`), nothing else".
+ *
+ * Runs on the RAW manifest set, BEFORE inline-resource extraction and `!ref`
+ * sentinel resolution. That ordering is load-bearing: only at this point is an
+ * author-written value still distinguishable from the resolver's own
+ * substitution. After normalization both an author's `{kind, name}` and a
+ * resolved `!ref` are the same `{kind, name}` object, so no later pass — and no
+ * JSON Schema — can tell them apart.
+ *
+ * At every `x-telo-ref` slot the only accepted value is:
+ *   - a `!ref` sentinel (or any tagged sentinel — e.g. a `${{ }}` ref passed
+ *     through a template), or
+ *   - an inline definition: a plain object with a `kind` and NO `name` (the
+ *     extractor assigns the name), or
+ *   - a `${{ }}` CEL expression string (a reference flowed through CEL).
+ *
+ * Rejected, each with an actionable diagnostic pointing at `!ref`:
+ *   - the object form `{ kind, name }` (the old reference object), and
+ *   - a bare string (the old name / dotted-FQN reference).
+ */
+export function validateReferenceForms(
+  resources: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+): AnalysisDiagnostic[] {
+  if (!aliases) return [];
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  const isForeign = (r: ResourceManifest): boolean =>
+    (r.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true;
+  const localResources = resources.filter((r) => !isForeign(r));
+
+  visitManifest(
+    localResources,
+    registry,
+    {
+      onRef: (e) => {
+        const value = e.value;
+        // `!ref` and `!cel`/`${{ }}` sentinels are the supported shapes.
+        if (isTaggedSentinel(value)) return;
+
+        const r = e.source;
+        const resourceLabel = `${r.kind}/${r.metadata!.name as string}`;
+        const resourceData = { kind: r.kind, name: r.metadata!.name as string };
+        const filePath = (r.metadata as { source?: string } | undefined)?.source;
+        const path = e.concretePath;
+
+        if (typeof value === "string") {
+          // A `${{ }}` reference flowed through CEL is fine; any other bare
+          // string at a ref slot is the removed string / dotted-FQN form.
+          if (value.includes("${{")) return;
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "INVALID_REFERENCE_FORM",
+            source: SOURCE,
+            message: `${resourceLabel}: string reference at '${path}' → '${value}' is not supported; write it as '!ref ${refHint(value)}'`,
+            data: { resource: resourceData, filePath, path },
+          });
+          return;
+        }
+
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const obj = value as Record<string, unknown>;
+          // A plain object is an inline definition unless it names a resource —
+          // a `name` makes it the removed `{ kind, name }` reference object.
+          if (typeof obj.name === "string" && typeof obj.kind === "string") {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "INVALID_REFERENCE_FORM",
+              source: SOURCE,
+              message: `${resourceLabel}: object reference '{ kind, name }' at '${path}' is not supported; write it as '!ref ${obj.name}'`,
+              data: { resource: resourceData, filePath, path },
+            });
+          }
+        }
+      },
+    },
+    {
+      aliases,
+      aliasesByModule,
+      skipKinds: SYSTEM_KINDS,
+      expand: true,
+      discoverNestedRefs: true,
+    },
+  );
+
+  return diagnostics;
+}
+
+/** Best-effort name for the `!ref` suggestion in a string-ref diagnostic: a
+ *  dotted-FQN (`Http.Api.UsersApi`) keeps its last segment, an alias-qualified
+ *  name (`Console.writeLine`) is left intact, a bare name passes through. */
+function refHint(value: string): string {
+  const dotCount = (value.match(/\./g) ?? []).length;
+  if (dotCount >= 2) return value.slice(value.lastIndexOf(".") + 1);
+  return value;
+}

package/src/validate-references.ts

@@ -289,45 +289,10 @@ export function validateReferences(
           return;
         }
 
-        // 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.
-        if (typeof val === "string") {
-          const lastDot = val.lastIndexOf(".");
-          const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
-          const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
-          const target =
-            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-          if (!target) {
-            // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
-            // The resource lives in the imported module's scope and can't be validated here.
-            // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
-            // kinds — those must be validated.
-            if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
-              return;
-            }
-            diagnostics.push({
-              severity: DiagnosticSeverity.Error,
-              code: "UNRESOLVED_REFERENCE",
-              source: SOURCE,
-              message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
-              data: { resource: resourceData, filePath, path: concretePath },
-            });
-            return;
-          }
-          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 },
-            });
-          }
-          return;
-        }
-
+        // Bare strings are no longer a reference shape — `validateReferenceForms`
+        // rejects an author-written string at a ref slot before this pass runs,
+        // and a `${{ }}` reference flowed through CEL is resolved/typed
+        // elsewhere. Anything still a string here is not a reference to resolve.
         if (typeof val !== "object") return;
         const refVal = val as Record<string, unknown>;