@telorun/analyzer 0.21.0 → 0.23.0

package/src/flatten-for-analyzer.ts

@@ -1,7 +1,26 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import type { LoadedFile, LoadedGraph, LoadedModule } from "./loaded-types.js";
+import type { LoadedGraph, LoadedModule } from "./loaded-types.js";
+import type { LoadedFile } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
 
+/** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
+ *  instance name or kind suffix (the part after the dot, or the whole entry); `alias`
+ *  (when set) is this library's own import the entry RE-EXPORTS from. */
+export interface ParsedExportEntry {
+  name: string;
+  alias?: string;
+}
+
+/** Parse a single dotted export entry: `Alias.Name` → `{name: "Name", alias: "Alias"}`,
+ *  bare `Name` → `{name: "Name"}`. The single grammar for `exports.resources` and
+ *  `exports.kinds`, shared by the kernel's import controller and the analyzer/editor so
+ *  the dotted-name split can't drift. A leading dot (`.Name`) has no alias by design —
+ *  the empty prefix isn't a valid alias. */
+export function parseExportEntry(entry: string): ParsedExportEntry {
+  const dot = entry.indexOf(".");
+  return dot > 0 ? { name: entry.slice(dot + 1), alias: entry.slice(0, dot) } : { name: entry };
+}
+
 /** The import-boundary forwarding rule, shared by `flattenForAnalyzer` (the
  *  CLI / kernel loader path) and the telo-editor's workspace projection so the
  *  two cannot drift. Given one module's stamped manifests and whether that
@@ -29,9 +48,14 @@ export function selectModuleManifestsForAnalysis(
   if (isRoot) return moduleManifests;
 
   const libDoc = moduleManifests.find((m) => isModuleKind(m.kind));
-  const exportedResources = new Set<string>(
-    (libDoc as { exports?: { resources?: string[] } } | undefined)?.exports?.resources ?? [],
-  );
+  // An `exports.resources` entry is a bare name or a dotted `Alias.Name` (re-export). Only the
+  // export NAME matches a local instance below; re-exports are forwarded by `forwardReExports`.
+  const exportedResources = new Set<string>();
+  for (const entry of (libDoc as { exports?: { resources?: unknown[] } } | undefined)?.exports
+    ?.resources ?? []) {
+    if (typeof entry !== "string") continue;
+    exportedResources.add(parseExportEntry(entry).name);
+  }
 
   const out: ResourceManifest[] = [];
   for (const m of moduleManifests) {
@@ -96,6 +120,8 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
     }
   }
 
+  forwardReExports(graph, result);
+
   // Stamp resolved import identity on every Telo.Import in the result by
   // reading the edge's pre-resolved name/namespace — no re-derivation from
   // manifest metadata. The edge is keyed by (owner-file, alias) which is
@@ -120,6 +146,193 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
   return result;
 }
 
+/** A re-export declared in a library's `exports.resources` as a dotted `Alias.Name`:
+ *  module `module` re-exports the instance `name` reached through its own import
+ *  aliased `alias`. */
+export interface ReExportSpec {
+  module: string;
+  alias: string;
+  name: string;
+}
+
+/** Extract re-export specs from a library doc's `exports.resources` — the dotted `Alias.Name`
+ *  entries (bare-name locals are forwarded by the BFS instead). Shared by the CLI graph path
+ *  and the editor's workspace projection so the two cannot drift. */
+export function reExportSpecsFromExports(
+  moduleName: string,
+  exportsResources: readonly unknown[] | undefined,
+): ReExportSpec[] {
+  const specs: ReExportSpec[] = [];
+  for (const entry of exportsResources ?? []) {
+    if (typeof entry !== "string") continue;
+    const { name, alias } = parseExportEntry(entry);
+    if (!alias || alias === "Self") continue;
+    specs.push({ module: moduleName, alias, name });
+  }
+  return specs;
+}
+
+/** Forward re-exported instances (`exports.resources: [!ref Alias.name]`) transitively so a
+ *  consumer's `!ref Consumer.name` resolves in `resolveRefSentinels` (keyed by the RE-EXPORTING
+ *  module). The owning instance is already forwarded under its own module; here we emit an
+ *  additional copy stamped under each re-exporting module, with an already-canonical kind. A
+ *  fixpoint loop forwards chains of arbitrary depth (`app → api → domain → …`): each pass can
+ *  resolve a re-export whose source was emitted in a prior pass. Graph-agnostic: `aliasToModule`
+ *  maps `(module, alias)` to the imported module's name. Mutates `result` in place. */
+export function forwardReExportManifests(
+  result: ResourceManifest[],
+  specs: readonly ReExportSpec[],
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): void {
+  // Index forwarded instances by `module\0name` (only re-export TARGETS are forwarded).
+  const forwarded = new Map<string, ResourceManifest>();
+  for (const m of result) {
+    const meta = m.metadata as { module?: string; name?: string; forwardedExport?: boolean };
+    if (meta?.forwardedExport && meta.module && meta.name) {
+      forwarded.set(`${meta.module}\0${meta.name}`, m);
+    }
+  }
+
+  // Canonicalize an authored/forwarded kind to a scope-independent `<module>.<Kind>` using the
+  // owning module's own import aliases. Idempotent: an already-canonical kind whose prefix isn't
+  // an alias of `ownerModule` is returned unchanged, so re-exports of re-exports stay stable.
+  const canonicalKind = (kind: string, ownerModule: string): string => {
+    if (kind.startsWith("Self.")) return `${ownerModule}.${kind.slice("Self.".length)}`;
+    const dot = kind.indexOf(".");
+    if (dot <= 0) return kind;
+    const target = aliasToModule(ownerModule, kind.slice(0, dot));
+    return target ? `${target}.${kind.slice(dot + 1)}` : kind;
+  };
+
+  // Fixpoint — bounded by the number of specs (each can be satisfied at most once).
+  for (let pass = 0; pass <= specs.length; pass++) {
+    let added = false;
+    for (const spec of specs) {
+      const key = `${spec.module}\0${spec.name}`;
+      if (forwarded.has(key)) continue;
+      const sourceModule = aliasToModule(spec.module, spec.alias);
+      if (!sourceModule) continue;
+      const src = forwarded.get(`${sourceModule}\0${spec.name}`);
+      if (!src) continue; // source not forwarded yet — a later pass may satisfy it
+      const kind = canonicalKind(src.kind as string, sourceModule);
+      const manifest: ResourceManifest = {
+        ...src,
+        kind,
+        metadata: {
+          ...src.metadata,
+          name: spec.name,
+          module: spec.module,
+          forwardedExport: true,
+        } as ResourceManifest["metadata"],
+      };
+      result.push(manifest);
+      forwarded.set(key, manifest);
+      added = true;
+    }
+    if (!added) break;
+  }
+}
+
+/** Resolve every library's `exports.kinds` to a per-module map `suffix → canonical
+ *  <owningModule>.<Kind>`, following re-exports (`Alias.Kind`) transitively via a fixpoint.
+ *  `modules` lists each library's name + its raw `exports.kinds`; `aliasToModule(module, alias)`
+ *  maps one of that module's import aliases to the imported module's name. Graph-agnostic —
+ *  shared by the CLI graph path and the editor's workspace projection. */
+export function resolveExportedKinds(
+  modules: ReadonlyArray<{ module: string; exportsKinds: readonly string[] }>,
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): Map<string, Map<string, string>> {
+  const out = new Map<string, Map<string, string>>();
+  const tableFor = (m: string): Map<string, string> => {
+    let t = out.get(m);
+    if (!t) out.set(m, (t = new Map()));
+    return t;
+  };
+  for (let pass = 0; pass <= modules.length; pass++) {
+    let changed = false;
+    for (const { module, exportsKinds } of modules) {
+      const table = tableFor(module);
+      for (const entry of exportsKinds) {
+        const { name: suffix, alias } = parseExportEntry(entry);
+        if (table.has(suffix)) continue;
+        if (!alias) {
+          table.set(suffix, `${module}.${suffix}`);
+          changed = true;
+          continue;
+        }
+        const source = aliasToModule(module, alias);
+        const canonical = source ? out.get(source)?.get(suffix) : undefined;
+        if (canonical) {
+          table.set(suffix, canonical);
+          changed = true;
+        }
+      }
+    }
+    if (!changed) break;
+  }
+  return out;
+}
+
+/** Stamp `metadata.reExportedKinds` (suffix → canonical kind) onto every `Telo.Import` whose
+ *  target re-exports kinds, so the analyzer can register the re-export mappings. Only entries
+ *  that point at a module OTHER than the import's own target are stamped (genuine re-exports;
+ *  a locally-defined kind resolves through the normal alias path). Stamped on `metadata` (which
+ *  permits additional properties, like `resolvedModuleName`) since the `Telo.Import` schema
+ *  forbids extra top-level fields. Shared by both paths. */
+export function stampReExportedKinds(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetModule: string }>,
+  exportedKinds: Map<string, Map<string, string>>,
+): void {
+  for (const { manifest, targetModule } of imports) {
+    const table = exportedKinds.get(targetModule);
+    if (!table) continue;
+    const reExported: Record<string, string> = {};
+    for (const [suffix, canonical] of table) {
+      if (canonical !== `${targetModule}.${suffix}`) reExported[suffix] = canonical;
+    }
+    if (Object.keys(reExported).length === 0) continue;
+    (manifest.metadata as Record<string, unknown>).reExportedKinds = reExported;
+  }
+}
+
+/** CLI/kernel adapter: collect re-export specs + alias map from a LoadedGraph. */
+function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void {
+  const ownerSourceOf = new Map<string, string>();
+  const specs: ReExportSpec[] = [];
+  const kindModules: Array<{ module: string; exportsKinds: string[] }> = [];
+  for (const [source, mod] of graph.modules) {
+    if (source === graph.rootSource) continue; // root is an Application — no exports
+    const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as
+      | (ResourceManifest & { exports?: { resources?: unknown[]; kinds?: string[] } })
+      | undefined;
+    const moduleName = libDoc?.metadata?.name as string | undefined;
+    if (!libDoc || !moduleName) continue;
+    ownerSourceOf.set(moduleName, mod.owner.source);
+    specs.push(...reExportSpecsFromExports(moduleName, libDoc.exports?.resources));
+    kindModules.push({ module: moduleName, exportsKinds: libDoc.exports?.kinds ?? [] });
+  }
+  const aliasToModule = (module: string, alias: string): string | undefined => {
+    const ownerSource = ownerSourceOf.get(module);
+    return ownerSource
+      ? (graph.importEdges.get(ownerSource)?.get(alias)?.targetModuleName ?? undefined)
+      : undefined;
+  };
+  forwardReExportManifests(result, specs, aliasToModule);
+
+  // Resolve every library's re-exported kinds and stamp them onto the consumer-facing
+  // Telo.Import manifests so the analyzer can register the re-export mappings.
+  const exportedKinds = resolveExportedKinds(kindModules, aliasToModule);
+  const imports: Array<{ manifest: ResourceManifest; targetModule: string }> = [];
+  for (const m of result) {
+    if (m.kind !== "Telo.Import") continue;
+    const owner = (m.metadata as { source?: string } | undefined)?.source;
+    const alias = m.metadata?.name as string | undefined;
+    const target = owner && alias ? graph.importEdges.get(owner)?.get(alias)?.targetModuleName : undefined;
+    if (target) imports.push({ manifest: m, targetModule: target });
+  }
+  stampReExportedKinds(imports, exportedKinds);
+}
+
 /** Project a LoadedModule (owner + partials) to a flat ResourceManifest[]
  *  with `metadata.module` stamped on non-module docs. The kernel's runtime
  *  entry load uses this to convert a `Loader.loadModule` result into the

package/src/index.ts

@@ -12,7 +12,14 @@ export type {
 export {
     flattenForAnalyzer,
     flattenLoadedModule,
+    forwardReExportManifests,
+    parseExportEntry,
+    reExportSpecsFromExports,
+    resolveExportedKinds,
     selectModuleManifestsForAnalysis,
+    stampReExportedKinds,
+    type ParsedExportEntry,
+    type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {

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