@telorun/analyzer 0.13.0 → 0.15.0

package/dist/alias-resolver.d.ts

@@ -4,6 +4,12 @@ export declare class AliasResolver {
     private readonly importAliases;
     private readonly importedKinds;
     registerImport(alias: string, targetModule: string, exportedKinds: string[]): void;
+    /** 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;
     /** Resolves "Http.Api" → "http-server.Api". Returns undefined if alias is unknown. */
     resolveKind(kind: string): string | undefined;
     hasAlias(alias: string): boolean;

package/dist/alias-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alias-resolver.d.ts","sourceRoot":"","sources":["../src/alias-resolver.ts"],"names":[],"mappings":"AAAA;gFACgF;AAChF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI;IAOlF,sFAAsF;IACtF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAe7C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,YAAY,IAAI,MAAM,EAAE;IAIxB;;qEAEiE;IACjE,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE;CAO3C"}
+{"version":3,"file":"alias-resolver.d.ts","sourceRoot":"","sources":["../src/alias-resolver.ts"],"names":[],"mappings":"AAAA;gFACgF;AAChF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAEhE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI;IAOlF;;;;qDAIiD;IACjD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIjD,sFAAsF;IACtF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAe7C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIhC,YAAY,IAAI,MAAM,EAAE;IAIxB;;qEAEiE;IACjE,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE;CAO3C"}

package/dist/alias-resolver.js

@@ -9,6 +9,14 @@ export class AliasResolver {
             this.importedKinds.set(alias, new Set(exportedKinds));
         }
     }
+    /** 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) {
+        return this.importAliases.get(alias);
+    }
     /** Resolves "Http.Api" → "http-server.Api". Returns undefined if alias is unknown. */
     resolveKind(kind) {
         if (!kind) {

package/dist/analysis-registry.d.ts

@@ -33,6 +33,7 @@ export declare class AnalysisRegistry {
     visitManifest(resources: ResourceManifest[], visitor: ManifestVisitor, opts?: {
         skipKinds?: ReadonlySet<string>;
         expand?: boolean;
+        discoverNestedRefs?: boolean;
     }): void;
     /**
      * Returns the built-in kernel definitions. The underlying DefinitionRegistry already

package/dist/analysis-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3D,IAAI;IAQP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}
+{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzF,IAAI;IAQP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}

package/dist/analyzer.d.ts

@@ -25,7 +25,7 @@ export declare class StaticAnalyzer {
      */
     analyze(manifests: ResourceManifest[], options?: AnalysisOptions, registry?: AnalysisRegistry): AnalysisDiagnostic[];
     analyzeErrors(manifests: ResourceManifest[], options?: AnalysisOptions, registry?: AnalysisRegistry): AnalysisDiagnostic[];
-    normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[];
+    normalize(manifests: ResourceManifest[], registry: AnalysisRegistry, crossModuleTargets?: ResourceManifest[]): ResourceManifest[];
     prepare(manifests: ResourceManifest[], registry: AnalysisRegistry): {
         diagnostics: AnalysisDiagnostic[];
         order: string[] | null;

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;AA+c/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAyjBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"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;AAuhB/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;IAimBvB,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"}

package/dist/analyzer.js

@@ -307,6 +307,73 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
     }
     return undefined;
 }
+/**
+ * Collect every field annotated with `x-telo-error-context` anywhere in a
+ * definition schema (resolving local `$ref`s into `$defs`, cycle-safe), mapping
+ * the annotated field name to its declared error-shape schema. The field name
+ * is matched against CEL paths so the context applies at any nesting depth under
+ * that field — e.g. `error` inside a `catch:` nested inside another `try:`. No
+ * specific field name (or `Run.Sequence`) is hardcoded; any composer that tags
+ * its error-bearing branch fields opts in the same way.
+ */
+function collectErrorContextScopes(defSchema) {
+    const out = new Map();
+    if (!defSchema || typeof defSchema !== "object")
+        return out;
+    const seen = new Set();
+    const walk = (schema) => {
+        if (!schema || typeof schema !== "object" || seen.has(schema))
+            return;
+        seen.add(schema);
+        const props = schema.properties;
+        if (props) {
+            for (const [fieldName, fieldSchema] of Object.entries(props)) {
+                if (fieldSchema && typeof fieldSchema === "object") {
+                    const errCtx = fieldSchema["x-telo-error-context"];
+                    if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+                        out.set(fieldName, errCtx);
+                    }
+                }
+                walk(resolveLocalRef(fieldSchema, defSchema));
+            }
+        }
+        if (schema.items)
+            walk(resolveLocalRef(schema.items, defSchema));
+        for (const key of ["oneOf", "anyOf", "allOf"]) {
+            const arr = schema[key];
+            if (Array.isArray(arr))
+                for (const sub of arr)
+                    walk(resolveLocalRef(sub, defSchema));
+        }
+        if (schema.$defs && typeof schema.$defs === "object") {
+            for (const sub of Object.values(schema.$defs)) {
+                walk(sub);
+            }
+        }
+    };
+    walk(defSchema);
+    return out;
+}
+/**
+ * Return the error-context schema for a CEL `path` when the path lies within
+ * (any depth under) one of the error-bearing fields, else undefined. A path is
+ * "within" field `f` when it contains a segment `f[<index>]`. When multiple
+ * error-bearing fields match (e.g. a `finally` nested inside a `catch`), the
+ * deepest — the one whose segment appears latest in the path — wins, so the
+ * innermost branch's schema governs.
+ */
+function errorContextForPath(path, scopes) {
+    let best;
+    for (const [fieldName, schema] of scopes) {
+        const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        for (const match of path.matchAll(new RegExp(`(^|\\.)${escaped}\\[\\d+\\]`, "g"))) {
+            if (best === undefined || match.index > best.index) {
+                best = { index: match.index, schema };
+            }
+        }
+    }
+    return best?.schema;
+}
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 /** Recursively walk `data`+`schema` together, type-checking every pure CEL template
@@ -444,9 +511,12 @@ export class StaticAnalyzer {
                 // through the same alias machinery as user-declared Telo.Imports —
                 // honours the library's `exports.kinds` list, no special cases.
                 if (moduleName) {
-                    const exportedKinds = m.exports?.kinds ?? [];
+                    // `Self` resolves the library's own kinds UNGATED — a library may reference
+                    // its own kinds regardless of `exports.kinds`, which gates importers, not
+                    // internal use. This is what lets a library declare an instance of a kind it
+                    // does not export (e.g. console's `writeLine`) to enforce a singleton.
                     if (rootModules.has(moduleName)) {
-                        aliases.registerImport("Self", moduleName, exportedKinds);
+                        aliases.registerImport("Self", moduleName, []);
                     }
                     else {
                         let libResolver = aliasesByModule.get(moduleName);
@@ -454,7 +524,7 @@ export class StaticAnalyzer {
                             libResolver = new AliasResolver();
                             aliasesByModule.set(moduleName, libResolver);
                         }
-                        libResolver.registerImport("Self", moduleName, exportedKinds);
+                        libResolver.registerImport("Self", moduleName, []);
                     }
                 }
             }
@@ -626,6 +696,14 @@ export class StaticAnalyzer {
             if (m.kind === "Telo.Abstract") {
                 continue;
             }
+            // Forwarded exports (flagged by flattenForAnalyzer) are an imported library's exported
+            // instances, already validated in their own module's standalone analysis; their
+            // `kind`/CEL are authored in that module's scope (e.g. `Self.X` → that module, not the
+            // consumer). Re-validating against the consumer's scope yields false UNDEFINED_KIND /
+            // scope-mismatch errors, so skip — they participate here only as resolution targets.
+            if (m.metadata?.forwardedExport === true) {
+                continue;
+            }
             const resource = { kind: m.kind, name: m.metadata?.name };
             // Resolve kind through alias if needed; direct lookup takes priority so that
             // aliases whose name matches the module name (the common case) work without
@@ -784,6 +862,7 @@ export class StaticAnalyzer {
         // context — which require analyzer state to build — are stashed here.
         let celStepContextSchema;
         let celInvocationContext;
+        let celErrorScopes = new Map();
         visitManifest(allManifests, defs, {
             onResourceEnter: (e) => {
                 const m = e.source;
@@ -791,6 +870,7 @@ export class StaticAnalyzer {
                 celStepContextSchema = e.definition?.schema
                     ? buildStepContextSchema(m, e.definition.schema, allManifests, defs, aliases)
                     : undefined;
+                celErrorScopes = collectErrorContextScopes(e.definition?.schema);
             },
             onCel: (e) => {
                 const m = e.source;
@@ -808,6 +888,19 @@ export class StaticAnalyzer {
                         },
                     };
                 }
+                // `error` is only in scope inside an error-bearing branch (e.g. a
+                // `catch:` / `finally:`), so it's merged per-path, not resource-wide.
+                const errorSchema = celErrorScopes.size > 0 ? errorContextForPath(path, celErrorScopes) : undefined;
+                if (errorSchema) {
+                    const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
+                    matchedContext = {
+                        ...base,
+                        properties: {
+                            ...(base.properties ?? {}),
+                            error: errorSchema,
+                        },
+                    };
+                }
                 let effectiveContext = null;
                 if (matchedContext) {
                     const manifestItem = matchedScope
@@ -855,6 +948,15 @@ export class StaticAnalyzer {
                             data: { resource, filePath, path },
                         });
                     }
+                    else if (f.code === "CEL_NULLABLE_ACCESS") {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "CEL_NULLABLE_ACCESS",
+                            source: SOURCE,
+                            message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
+                            data: { resource, filePath, path },
+                        });
+                    }
                     else {
                         // Unknown code from a future engine — pass the message through,
                         // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
@@ -887,13 +989,17 @@ export class StaticAnalyzer {
     analyzeErrors(manifests, options, registry) {
         return this.analyze(manifests, options, registry).filter((d) => d.severity === DiagnosticSeverity.Error);
     }
-    normalize(manifests, registry) {
+    normalize(manifests, registry, 
+    // Forwarded foreign exports used only as cross-module resolution targets (see
+    // resolveRefSentinels). The kernel passes its analyzer-flattened set so the
+    // entry-only runtime pass can still resolve `!ref Alias.name`.
+    crossModuleTargets) {
         const ctx = registry._context();
         const normalized = normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
         // Resolve !ref sentinels after normalize so both the original and
         // inline-extracted manifests get their refs canonicalized to
         // {kind, name} for the kernel that consumes this output.
-        resolveRefSentinels(normalized, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        resolveRefSentinels(normalized, ctx.definitions, 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,EA0V/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,EA4Z/C,CAAC"}

package/dist/builtins.js

@@ -232,6 +232,66 @@ export const KERNEL_BUILTINS = [
                                 },
                                 additionalProperties: true,
                             },
+                            // 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 }`).
+                            {
+                                type: "object",
+                                required: ["ref"],
+                                properties: {
+                                    ref: {
+                                        anyOf: [
+                                            { type: "string", "x-telo-ref": "telo#Runnable" },
+                                            { type: "string", "x-telo-ref": "telo#Service" },
+                                            {
+                                                type: "object",
+                                                required: ["kind", "name"],
+                                                properties: {
+                                                    kind: { type: "string" },
+                                                    name: { type: "string" },
+                                                },
+                                                additionalProperties: true,
+                                            },
+                                        ],
+                                    },
+                                    when: { type: "string" },
+                                },
+                                additionalProperties: false,
+                            },
+                            // Inline flat invoke step: invoke an Invocable / Runnable on boot
+                            // 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.
+                            {
+                                type: "object",
+                                required: ["invoke"],
+                                properties: {
+                                    name: { type: "string" },
+                                    invoke: {
+                                        "x-telo-topology-role": "invoke",
+                                        type: "object",
+                                        required: ["kind", "name"],
+                                        properties: {
+                                            kind: { type: "string" },
+                                            name: { type: "string" },
+                                        },
+                                        additionalProperties: true,
+                                        anyOf: [
+                                            { "x-telo-ref": "telo#Invocable" },
+                                            { "x-telo-ref": "telo#Runnable" },
+                                        ],
+                                    },
+                                    inputs: { type: "object", additionalProperties: true },
+                                    when: { type: "string" },
+                                },
+                                additionalProperties: false,
+                            },
                         ],
                     },
                 },
@@ -336,6 +396,12 @@ export const KERNEL_BUILTINS = [
                     type: "object",
                     properties: {
                         kinds: { type: "array", items: { type: "string" } },
+                        // `variables` / `secrets` are reserved on the resources.<Alias> value-flow
+                        // surface, so a library may not export instances under those names.
+                        resources: {
+                            type: "array",
+                            items: { type: "string", not: { enum: ["variables", "secrets"] } },
+                        },
                     },
                     additionalProperties: true,
                 },

package/dist/flatten-for-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten-for-analyzer.d.ts","sourceRoot":"","sources":["../src/flatten-for-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAc,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG/E;;;;;;;;;;;;;;;;;;6EAkB6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB,EAAE,CAyDzE;AAED;;;;;6BAK6B;AAC7B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAEzE"}
+{"version":3,"file":"flatten-for-analyzer.d.ts","sourceRoot":"","sources":["../src/flatten-for-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAc,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG/E;;;;;;;;;;;;;;;;;;6EAkB6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB,EAAE,CA6EzE;AAED;;;;;6BAK6B;AAC7B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAEzE"}

package/dist/flatten-for-analyzer.js

@@ -38,12 +38,29 @@ export function flattenForAnalyzer(graph) {
             if (!targetModule)
                 continue;
             const stamped = collectModuleManifests(targetModule);
+            const libDoc = stamped.find((m) => isModuleKind(m.kind));
+            const exportedResources = new Set(libDoc?.exports?.resources ?? []);
             for (const m of stamped) {
                 if (m.kind === "Telo.Definition" ||
                     m.kind === "Telo.Abstract" ||
                     m.kind === "Telo.Import") {
                     result.push(m);
                 }
+                else if (!isModuleKind(m.kind) &&
+                    typeof m.metadata?.name === "string" &&
+                    exportedResources.has(m.metadata.name)) {
+                    // Forward instances listed in the library's `exports.resources` so the
+                    // consumer's analyzer can resolve, gate, kind-check, and draw topology edges
+                    // for cross-module `!ref Alias.name`. The gate IS this forwarding — only
+                    // exported names cross the boundary. `metadata.forwardedExport` marks them as
+                    // cross-module resolution targets only (keyed by `metadata.module`), so ref
+                    // resolution / validation treats them as targets, never as local sources to
+                    // re-validate or walk.
+                    result.push({
+                        ...m,
+                        metadata: { ...m.metadata, forwardedExport: true },
+                    });
+                }
             }
         }
     }

package/dist/manifest-visitor.d.ts

@@ -65,6 +65,13 @@ export interface RefSiteEvent {
     inScope: boolean;
     /** Scope manifests visible to this ref path (non-empty only when `inScope`). */
     visibleScopeManifests: ResourceManifest[];
+    /** True when the site was found by value-tree scanning rather than the field
+     *  map (only when `discoverNestedRefs` is set) — a ref nested behind a `$ref`
+     *  the field map doesn't descend (e.g. `Run.Sequence` `steps[].invoke`).
+     *  Nested sites carry no x-telo-ref constraint (`entry.refs` is empty) and no
+     *  scope info; `concretePath` still points at the exact location, so consumers
+     *  can anchor to it. */
+    nested?: boolean;
 }
 export interface SchemaFromSiteEvent {
     source: ResourceManifest;
@@ -104,6 +111,14 @@ export interface VisitOptions {
      *  so refs nested behind `x-telo-schema-from` are surfaced. `SchemaFromSite`
      *  events are always emitted from the base map regardless of this flag. */
     expand?: boolean;
+    /** When true, additionally discover refs by scanning each resource's value
+     *  tree for `!ref` sentinels and `{kind, name}` reference objects — surfacing
+     *  refs the field map never lists because they sit behind a `$ref` it doesn't
+     *  descend (notably `Run.Sequence` step `invoke`s). Emitted as `RefSite`s with
+     *  `nested: true`, deduped against the field-map sites by concrete path.
+     *  Opt-in: the validators / dependency graph must NOT enable it (those refs
+     *  are runtime-resolved, not boot dependencies). */
+    discoverNestedRefs?: boolean;
 }
 export declare function visitManifest(resources: ResourceManifest[], registry: DefinitionRegistry, visitor: ManifestVisitor, options?: VisitOptions): void;
 //# sourceMappingURL=manifest-visitor.d.ts.map

package/dist/manifest-visitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-visitor.d.ts","sourceRoot":"","sources":["../src/manifest-visitor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manifest-visitor.d.ts","sourceRoot":"","sources":["../src/manifest-visitor.ts"],"names":[],"mappings":"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"}

package/dist/manifest-visitor.js

@@ -1,16 +1,59 @@
-import { walkCelExpressions } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
 import { isRefEntry, isSchemaFromEntry, isScopeEntry, resolveFieldEntries, resolveFieldValues, } from "./reference-field-map.js";
 import { extractContextsFromSchema, pathMatchesScope } from "./validate-cel-context.js";
+/** Synthetic entry for a value-tree-discovered ref — these carry no declared
+ *  x-telo-ref constraint. */
+const NESTED_REF_ENTRY = { refs: [], isArray: false };
+/** Scans a value tree for ref-shaped values, emitting each with its concrete
+ *  path. Recognizes `!ref <name>` sentinels and named `{kind, name}` reference
+ *  objects. Other tagged sentinels (`!cel`, `!literal`) and precompiled nodes
+ *  are leaves. Path format matches `resolveFieldEntries` / `walkCelExpressions`
+ *  (`a.b[0].c`).
+ *
+ *  Stops at every `{kind, …}` resource boundary: a named ref is emitted, an
+ *  inline resource (`{kind}` with no name) is left alone, and **neither is
+ *  descended into**. A nested resource's own refs belong to its inner topology,
+ *  not the enclosing node — e.g. an inline `Sql.Exec` step's `connection` is the
+ *  Exec's dependency, not the surrounding `Run.Sequence`'s. The scan is started
+ *  per top-level field (not on the resource object) so the resource's own
+ *  `kind` doesn't trip this boundary. */
+function walkRefValues(value, path, cb) {
+    if (isRefSentinel(value)) {
+        cb(value, path);
+        return;
+    }
+    if (isTaggedSentinel(value))
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => walkRefValues(v, `${path}[${i}]`, cb));
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    if (value.__compiled)
+        return;
+    const obj = value;
+    if (typeof obj.kind === "string") {
+        // Resource boundary — emit if it's a named ref, then stop descending.
+        if (typeof obj.name === "string")
+            cb(value, path);
+        return;
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        walkRefValues(v, path ? `${path}.${k}` : k, cb);
+    }
+}
 const scopePrefixOf = (pointer) => pointer.replace(/^\//, "").replace(/\//g, ".");
 const pathUnderPrefix = (fieldPath, prefix) => fieldPath === prefix ||
     fieldPath.startsWith(prefix + ".") ||
     fieldPath.startsWith(prefix + "[");
 export function visitManifest(resources, registry, visitor, options = {}) {
-    const { aliases, aliasesByModule, skipKinds, expand } = options;
+    const { aliases, aliasesByModule, skipKinds, expand, discoverNestedRefs } = options;
     const wantsRefs = !!visitor.onRef;
     const wantsScope = !!visitor.onScope;
     const wantsSchemaFrom = !!visitor.onSchemaFrom;
     const wantsCel = !!visitor.onCel;
+    const wantsNested = wantsRefs && !!discoverNestedRefs;
     for (const r of resources) {
         if (!r.metadata?.name || !r.kind)
             continue;
@@ -20,6 +63,9 @@ export function visitManifest(resources, registry, visitor, options = {}) {
         const definition = registry.resolve(r.kind) ??
             (resolvedKind ? registry.resolve(resolvedKind) : undefined);
         visitor.onResourceEnter?.({ source: r, definition });
+        // Concrete paths emitted from the field map — so the value-tree scan below
+        // doesn't re-emit a ref the field map already covered.
+        const emittedRefPaths = wantsNested ? new Set() : null;
         if (wantsRefs || wantsScope || wantsSchemaFrom) {
             const baseMap = aliases
                 ? registry.getFieldMapForKind(r.kind, aliases)
@@ -69,6 +115,7 @@ export function visitManifest(resources, registry, visitor, options = {}) {
                         for (const { value, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                             if (!value)
                                 continue;
+                            emittedRefPaths?.add(concretePath);
                             visitor.onRef({
                                 source: r,
                                 fieldPath,
@@ -90,6 +137,30 @@ export function visitManifest(resources, registry, visitor, options = {}) {
                 }
             }
         }
+        // Value-tree-driven nested ref discovery — refs the field map can't reach
+        // because they sit behind a `$ref` it doesn't descend (e.g. Run.Sequence
+        // step `invoke`s). Deduped against the field-map sites by concrete path.
+        // Scanned per top-level field so the resource's own `kind` isn't treated as
+        // a resource boundary by `walkRefValues`.
+        if (wantsNested) {
+            const emitNested = (value, path) => {
+                if (emittedRefPaths.has(path))
+                    return;
+                visitor.onRef({
+                    source: r,
+                    fieldPath: path,
+                    concretePath: path,
+                    value,
+                    entry: NESTED_REF_ENTRY,
+                    inScope: false,
+                    visibleScopeManifests: [],
+                    nested: true,
+                });
+            };
+            for (const [key, value] of Object.entries(r)) {
+                walkRefValues(value, key, emitNested);
+            }
+        }
         if (wantsCel) {
             const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
             walkCelExpressions(r, "", (expr, path, engineName) => {

package/dist/reference-field-map.js

@@ -157,6 +157,22 @@ function traverseNode(node, path, map, root, visitedRefs = new Set()) {
         if (node["x-telo-context"])
             entry.context = node["x-telo-context"];
         map.set(path, entry);
+        // A node can mix item-level ref branches (a bare string / `{kind, name}`)
+        // with object branches that carry their OWN nested refs — e.g. Application
+        // `targets`: a bare ref vs inline `{ invoke }` vs gated `{ ref }`. Descend
+        // into the variant objects so those nested slots register too (and their
+        // `!ref` sentinels resolve). Pure x-telo-ref branches have no properties
+        // and contribute nothing here.
+        for (const variantKey of ["oneOf", "anyOf", "allOf"]) {
+            const variants = node[variantKey];
+            if (!Array.isArray(variants))
+                continue;
+            for (const variant of variants) {
+                if (!variant || typeof variant !== "object")
+                    continue;
+                traverseVariant(variant, path, map, root, visitedRefs);
+            }
+        }
         return;
     }
     // Array — recurse into items

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

@@ -3,25 +3,23 @@ import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 /**
  * Walks every `x-telo-ref` slot in every non-system resource and rewrites
- * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ * `!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 declare function resolveRefSentinels(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): void;
+export declare function resolveRefSentinels(resources: ResourceManifest[], registry: DefinitionRegistry, 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;AAInE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,IAAI,CAsBN"}
+{"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,CAwEN"}