@telorun/analyzer 0.13.0 → 0.15.0

package/dist/resolve-ref-sentinels.js

@@ -3,36 +3,89 @@ import { isRefEntry } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 /**
  * Walks every `x-telo-ref` slot in every non-system resource and rewrites
- * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ * `!ref <name>` sentinels in-place to `{kind, name}` (local) or
+ * `{kind, name, alias}` (cross-module).
  *
- * The downstream pipeline (inline normalization, dependency graph, kernel
- * controllers) expects every ref-slot value to be either a `{kind, name}`
- * object, an inline-definition object, or a legacy bare string — resolving
- * sentinels here keeps that contract intact so each consumer doesn't need
- * its own sentinel branch.
+ * Reference grammar — the tag's source string is split on the FIRST dot:
+ *   - `!ref writeLine`          → local resource `writeLine`
+ *   - `!ref Self.writeLine`     → local resource `writeLine` (explicit self-qualifier)
+ *   - `!ref Console.writeLine`  → instance `writeLine` exported by the import aliased
+ *                                 `Console`, resolved against the forwarded foreign set
  *
- * The walker assigns `kind` by name lookup (resource names are unique
- * within a manifest scope). When the name doesn't resolve in the local
- * `byName` map, the sentinel is left in place so `validateReferences`
- * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ * 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.
  *
- * Mutation strategy: the field-path walker descends the resource tree
- * directly and replaces the sentinel on its parent container. Re-parsing
- * a string-encoded concrete path (the earlier shape) coupled the writer
- * to the path-encoding rules of `resolveFieldEntries` — any new path
- * marker would silently break this writer. Descending directly avoids
- * that coupling.
+ * 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, registry, 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
+// imported libraries' exported instances.
+crossModuleTargets = []) {
+    const moduleOf = (r) => r.metadata?.module;
+    // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
+    // cross-module resolution targets only — never walked as local ref sources here.
+    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    // Local resources resolve a bare / `Self.`-qualified name; forwarded foreign exports
+    // resolve an `Alias.`-qualified name keyed by (module, name).
     const byName = new Map();
+    const byModuleName = new Map();
     for (const r of resources) {
-        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
-            byName.set(r.metadata.name, r);
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const name = r.metadata.name;
+        if (isForeign(r)) {
+            byModuleName.set(`${moduleOf(r)}\0${name}`, r);
+        }
+        else {
+            byName.set(name, r);
         }
     }
+    for (const r of crossModuleTargets) {
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+            continue;
+        byModuleName.set(`${moduleOf(r)}\0${r.metadata.name}`, r);
+    }
+    const resolveTarget = (source) => {
+        const dot = source.indexOf(".");
+        if (dot === -1) {
+            const t = byName.get(source);
+            return t ? { kind: t.kind, name: source } : undefined;
+        }
+        const alias = source.slice(0, dot);
+        const name = source.slice(dot + 1);
+        if (alias === "Self") {
+            const t = byName.get(name);
+            return t ? { kind: t.kind, name } : undefined;
+        }
+        const module = aliases?.moduleForAlias(alias);
+        if (module) {
+            const t = byModuleName.get(`${module}\0${name}`);
+            if (t) {
+                // The foreign instance's `kind` is authored in ITS module's scope (e.g.
+                // `Self.WriteLine`); canonicalize to a scope-independent `<module>.<Kind>` for the
+                // consumer's kind check. `Self.` maps to the owning module directly — the forwarded
+                // library's Library doc (hence its `Self` alias) isn't in the consumer's manifest
+                // set — while other alias prefixes resolve via that module's forwarded import scope.
+                const rawKind = t.kind;
+                const foreignKind = rawKind.startsWith("Self.")
+                    ? `${module}.${rawKind.slice("Self.".length)}`
+                    : aliasesByModule?.get(module)?.resolveKind(rawKind) ?? rawKind;
+                return { kind: foreignKind, name, alias };
+            }
+        }
+        return undefined;
+    };
     for (const r of resources) {
         if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
             continue;
+        if (isForeign(r))
+            continue;
         const fieldMap = aliases && aliasesByModule
             ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
             : registry.getFieldMapForKind(r.kind, aliases);
@@ -41,37 +94,30 @@ export function resolveRefSentinels(resources, registry, aliases, aliasesByModul
         for (const [fieldPath, entry] of fieldMap) {
             if (!isRefEntry(entry))
                 continue;
-            replaceSentinelsAtPath(r, fieldPath, byName);
+            descend(r, fieldPath.split("."), resolveTarget);
         }
     }
 }
-/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
- *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
- *  sentinel value at the terminal slot with `{kind, name}` looked up
- *  via `byName`. Mutates the parent container in place; no string-path
- *  round-trip. */
-function replaceSentinelsAtPath(obj, fieldPath, byName) {
-    const parts = fieldPath.split(".");
-    descend(obj, parts, byName);
-}
-function descend(obj, parts, byName) {
+/** 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;
-    // Map iteration: descend into every value of the current object.
     if (head === "{}") {
         const container = obj;
         for (const key of Object.keys(container)) {
             const child = container[key];
             if (rest.length === 0) {
                 if (isRefSentinel(child)) {
-                    const target = byName.get(child.source);
+                    const target = resolve(child.source);
                     if (target)
-                        container[key] = { kind: target.kind, name: child.source };
+                        container[key] = target;
                 }
             }
             else {
-                descend(child, rest, byName);
+                descend(child, rest, resolve);
             }
         }
         return;
@@ -89,26 +135,26 @@ function descend(obj, parts, byName) {
             if (rest.length === 0) {
                 const elem = val[i];
                 if (isRefSentinel(elem)) {
-                    const target = byName.get(elem.source);
+                    const target = resolve(elem.source);
                     if (target)
-                        val[i] = { kind: target.kind, name: elem.source };
+                        val[i] = target;
                 }
             }
             else {
-                descend(val[i], rest, byName);
+                descend(val[i], rest, resolve);
             }
         }
     }
     else {
         if (rest.length === 0) {
             if (isRefSentinel(val)) {
-                const target = byName.get(val.source);
+                const target = resolve(val.source);
                 if (target)
-                    container[key] = { kind: target.kind, name: val.source };
+                    container[key] = target;
             }
         }
         else {
-            descend(val, rest, byName);
+            descend(val, rest, resolve);
         }
     }
 }

package/dist/resolve-throws-union.d.ts

@@ -4,6 +4,10 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 export interface ThrowsCodeMeta {
     data?: Record<string, any>;
 }
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export declare const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
 export interface ThrowsUnion {
     /** Code → per-code metadata (data schema, etc). Keys are the declared codes. */
     codes: Map<string, ThrowsCodeMeta>;
@@ -12,6 +16,12 @@ export interface ThrowsUnion {
      *  an unknown kind was encountered, or a cycle short-circuited resolution.
      *  Callers must treat unbounded unions as requiring a catch-all entry. */
     unbounded: boolean;
+    /** True when the block can fail with a non-`InvokeError` (any `invoke:` step).
+     *  Such a failure surfaces inside an enclosing `catch` as `PLAIN_ERROR_CODE`,
+     *  so a `throw: { code: "${{ error.code }}" }` rethrow can propagate it. Not
+     *  injected into `codes` — only seeds `enclosingTryCodes` at a try/catch site,
+     *  leaving non-rethrow unions untouched. */
+    canThrowPlain?: boolean;
 }
 export interface ResolveCtx {
     allManifests: ResourceManifest[];

package/dist/resolve-throws-union.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,GACrB,UAAU,CAQZ;AA+BD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CA+Cb"}
+{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;gFAEgF;AAChF,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;gDAI4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,GACrB,UAAU,CAQZ;AAgCD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CA+Cb"}

package/dist/resolve-throws-union.js

@@ -1,3 +1,8 @@
+import { isTaggedSentinel } from "@telorun/templating";
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
 export function createResolveCtx(allManifests, defs, aliases) {
     return {
         allManifests,
@@ -17,6 +22,8 @@ function unionInto(target, src) {
     }
     if (src.unbounded)
         target.unbounded = true;
+    if (src.canThrowPlain)
+        target.canThrowPlain = true;
 }
 function definitionFor(kind, defs, aliases) {
     const resolved = aliases.resolveKind(kind);
@@ -115,7 +122,11 @@ function collectStepArrayThrows(steps, invokeField, enclosingTryCodes, ctx) {
  *  composers that reuse those shape conventions work without changes here. */
 function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
     if (step[invokeField]) {
-        return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+        // Any invoked resource can throw a non-InvokeError at runtime, which an
+        // enclosing catch surfaces as PLAIN_ERROR_CODE — record that possibility.
+        const u = cloneUnion(resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx));
+        u.canThrowPlain = true;
+        return u;
     }
     if (step.throw && typeof step.throw === "object") {
         return resolveThrowStepCode(step.throw, enclosingTryCodes);
@@ -128,6 +139,11 @@ function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
             // out instead. Sequence-specific subtraction — the plan explicitly
             // anchors this to Run.Sequence's try/catch schema shape.
             const tryCodes = new Set(tryUnion.codes.keys());
+            // A plain (non-InvokeError) failure in the try block reaches the catch as
+            // `error.code === PLAIN_ERROR_CODE`, so a `throw: { code: error.code }`
+            // rethrow can propagate it — seed the set the catch resolves against.
+            if (tryUnion.canThrowPlain)
+                tryCodes.add(PLAIN_ERROR_CODE);
             propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx);
             // Unbounded in the try block still signals the caller to expect
             // arbitrary codes to flow through the catch (e.g. via passthrough).
@@ -179,6 +195,8 @@ function cloneUnion(u) {
     for (const [c, m] of u.codes)
         out.codes.set(c, m);
     out.unbounded = u.unbounded;
+    if (u.canThrowPlain)
+        out.canThrowPlain = true;
     return out;
 }
 function resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx) {
@@ -226,14 +244,24 @@ function resolveThrowStepCode(throwSpec, enclosingTryCodes) {
     return resolveCodeExpression(throwSpec.code, enclosingTryCodes);
 }
 function resolveCodeExpression(codeInput, enclosingTryCodes) {
-    if (typeof codeInput !== "string" || codeInput.length === 0) {
-        return { codes: new Map(), unbounded: true };
+    // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+    // normalize both to the inner CEL expression (or a bare literal code).
+    let expr;
+    if (isTaggedSentinel(codeInput)) {
+        if (codeInput.engine !== "cel")
+            return { codes: new Map(), unbounded: true };
+        expr = codeInput.source.trim();
     }
-    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
-    if (!match) {
-        return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    else if (typeof codeInput === "string" && codeInput.length > 0) {
+        const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+        if (!match) {
+            return { codes: new Map([[codeInput, {}]]), unbounded: false };
+        }
+        expr = match[1].trim();
+    }
+    else {
+        return { codes: new Map(), unbounded: true };
     }
-    const expr = match[1].trim();
     const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
     if (litMatch) {
         const code = litMatch[1] ?? litMatch[2];

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,CA0YtB"}
+{"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"}

package/dist/validate-references.js

@@ -95,10 +95,45 @@ export function validateReferences(resources, context) {
     // source, different sourceLine) keep separate fingerprints and still
     // trip the diagnostic. `analyze()` enforces that every non-system
     // manifest carries both positional fields — no defensive guard needed.
+    // Forwarded foreign exports (an imported library's exported instances, carrying a
+    // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
+    // duplicate detection and local name resolution, and never walked as ref sources.
+    const moduleOf = (r) => r.metadata?.module;
+    // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
+    // cross-module resolution targets only — excluded from duplicate detection and local name
+    // resolution, and never walked as ref sources.
+    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    // Forwarded exported instances keyed `${module}\0${name}` — the lookup that resolves
+    // whether a cross-module `!ref Alias.name` names a real exported instance.
+    const byModuleName = new Map();
+    /** Modules whose import subtree was actually loaded in this analysis. A resolved
+     *  `Telo.Import` carries `resolvedModuleName` (stamped only once the edge — and thus the
+     *  imported module — resolved); forwarded exports carry `metadata.module`. Either marks
+     *  the module loaded independent of how many instances it exports, so a loaded library
+     *  that exports nothing still reports invalid cross-module refs, while partial single-file
+     *  analysis (neither present) is skipped to avoid false `UNRESOLVED_REFERENCE`. */
+    const loadedModules = new Set();
+    for (const r of resources) {
+        if (r.kind === "Telo.Import") {
+            const m = r.metadata?.resolvedModuleName;
+            if (typeof m === "string")
+                loadedModules.add(m);
+            continue;
+        }
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+            continue;
+        const m = moduleOf(r);
+        if (!m)
+            continue;
+        byModuleName.set(`${m}\0${r.metadata.name}`, r);
+        loadedModules.add(m);
+    }
+    const moduleLoaded = (module) => loadedModules.has(module);
+    const localResources = resources.filter((r) => !isForeign(r));
     const byNameAll = new Map();
     const seen = new Set();
     for (const r of resources) {
-        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import")
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import" || isForeign(r))
             continue;
         const name = r.metadata.name;
         // `analyze()` guarantees both fields are present on non-system manifests.
@@ -140,6 +175,32 @@ export function validateReferences(resources, context) {
             });
         }
     }
+    // A resource name must contain no dot. The `!ref` resolver splits the tag's source on
+    // the first dot to separate an import alias from the resource name, so a dotted name
+    // would mis-resolve into a cross-module lookup. This is the load-bearing invariant of
+    // the reference grammar, so it is enforced here rather than left to the (unenforced)
+    // casing convention.
+    for (const [name, list] of byNameAll) {
+        if (!name.includes("."))
+            continue;
+        for (const r of list) {
+            const m = r.metadata;
+            const range = typeof m?.sourceLine === "number"
+                ? {
+                    start: { line: m.sourceLine, character: 0 },
+                    end: { line: m.sourceLine, character: Number.MAX_SAFE_INTEGER },
+                }
+                : undefined;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "INVALID_RESOURCE_NAME",
+                source: SOURCE,
+                message: `${r.kind}/${name}: resource name must not contain '.' — in a '!ref' the '.' separates an import alias from the resource name`,
+                ...(range ? { range } : {}),
+                data: { resource: { kind: r.kind, name }, filePath: m?.source, path: "metadata.name" },
+            });
+        }
+    }
     // Single-resource map for the resolution / scope lookups below — when a
     // collision exists, falling back to the first occurrence keeps the rest
     // of the pass behaving the same as before the duplicate diagnostic was
@@ -152,7 +213,7 @@ export function validateReferences(resources, context) {
     // resolved against the schema-from-expanded field map, with its source
     // enclosure (`inScope`) and the scope manifests visible to it — so this
     // handler only validates, it does not re-walk.
-    visitManifest(resources, registry, {
+    visitManifest(localResources, registry, {
         onRef: (e) => {
             const r = e.source;
             const resourceLabel = `${r.kind}/${r.metadata.name}`;
@@ -166,13 +227,35 @@ export function validateReferences(resources, context) {
             // string/inline ambiguity at the source.
             if (isRefSentinel(val)) {
                 const refName = val.source;
-                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                const dot = refName.indexOf(".");
+                const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+                // Cross-module sentinel left unresolved by Phase 2.5 — it qualifies an import
+                // alias. If that module's exports are loaded in this analysis, the miss is real
+                // (name not in exports.resources, or a typo); if not (partial single-file
+                // analysis), skip rather than emit a false UNRESOLVED_REFERENCE.
+                if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+                    const module = aliases.moduleForAlias(aliasPrefix);
+                    if (module && !moduleLoaded(module))
+                        return;
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "UNRESOLVED_REFERENCE",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${concretePath}' → '${refName}' is not exported by module '${module ?? aliasPrefix}' (add it to exports.resources)`,
+                        data: { resource: resourceData, filePath, path: concretePath },
+                    });
+                    return;
+                }
+                // Local reference (bare name or explicit `Self.`-qualified).
+                const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
+                const target = byName.get(localName) ??
+                    visibleScopeManifests.find((m) => m.metadata?.name === localName);
                 if (!target) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${localName}' not found`,
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
                     return;
@@ -232,6 +315,13 @@ export function validateReferences(resources, context) {
             // Skip inline resources — Phase 2 normalization hasn't run yet.
             if (isInlineResource(refVal))
                 return;
+            // Polymorphic ref slots (Application `targets`) accept object forms
+            // whose references live in nested slots rather than being a `{kind,
+            // name}` ref themselves — inline `{ invoke }` and gated `{ ref }`.
+            // Those nested refs are validated via their own field-map entries, so
+            // skip the item-level structural check here.
+            if (typeof refVal.kind !== "string" && ("invoke" in refVal || "ref" in refVal))
+                return;
             // 1. Structural check
             if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
                 diagnostics.push({
@@ -255,8 +345,19 @@ export function validateReferences(resources, context) {
                 });
             }
             // 3. Resolution check — resource with this name must exist.
-            const exists = byName.has(refVal.name) ||
-                visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+            let exists;
+            if (typeof refVal.alias === "string" && refVal.alias !== "Self") {
+                // Cross-module ref resolved by Phase 2.5. Validate against the forwarded
+                // exports when loaded; in partial context (module not loaded) assume resolvable.
+                const module = aliases.moduleForAlias(refVal.alias);
+                exists =
+                    !module || !moduleLoaded(module) || byModuleName.has(`${module}\0${refVal.name}`);
+            }
+            else {
+                exists =
+                    byName.has(refVal.name) ||
+                        visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+            }
             if (!exists) {
                 diagnostics.push({
                     severity: DiagnosticSeverity.Error,
@@ -273,7 +374,7 @@ export function validateReferences(resources, context) {
     // concrete kind, navigate the JSON Pointer into that kind's definition schema, and
     // validate the field value against the resulting sub-schema. Driven off the base map
     // (un-expanded) so each schema-from slot is seen as its own site.
-    visitManifest(resources, registry, {
+    visitManifest(localResources, registry, {
         onSchemaFrom: (e) => {
             const r = e.source;
             const fieldPath = e.fieldPath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,15 +42,16 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.3.1"
+    "@telorun/templating": "0.4.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "@telorun/sdk": "0.16.0"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "*"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",

package/src/alias-resolver.ts

@@ -11,6 +11,15 @@ export class AliasResolver {
     }
   }
 
+  /** Real module name an alias points at (e.g. "Console" → "console"), or undefined.
+   *  Used to resolve an alias-qualified instance reference "Console.writeLine" to the
+   *  forwarded resource declared in that module. The `exports.resources` gate is enforced
+   *  upstream by `flattenForAnalyzer` (only exported instances are forwarded), so a name
+   *  that isn't exported simply won't be found. */
+  moduleForAlias(alias: string): string | undefined {
+    return this.importAliases.get(alias);
+  }
+
   /** Resolves "Http.Api" → "http-server.Api". Returns undefined if alias is unknown. */
   resolveKind(kind: string): string | undefined {
     if (!kind) {

package/src/analysis-registry.ts

@@ -73,7 +73,7 @@ export class AnalysisRegistry {
   visitManifest(
     resources: ResourceManifest[],
     visitor: ManifestVisitor,
-    opts?: { skipKinds?: ReadonlySet<string>; expand?: boolean },
+    opts?: { skipKinds?: ReadonlySet<string>; expand?: boolean; discoverNestedRefs?: boolean },
   ): void {
     runVisitManifest(resources, this.defs, visitor, {
       aliases: this.aliases,