@telorun/analyzer 0.13.0 → 0.15.0

package/src/analyzer.ts

@@ -379,6 +379,78 @@ function buildStepContextSchema(
   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: Record<string, any> | undefined,
+): Map<string, Record<string, any>> {
+  const out = new Map<string, Record<string, any>>();
+  if (!defSchema || typeof defSchema !== "object") return out;
+  const seen = new Set<Record<string, any>>();
+
+  const walk = (schema: Record<string, any> | undefined): void => {
+    if (!schema || typeof schema !== "object" || seen.has(schema)) return;
+    seen.add(schema);
+
+    const props = schema.properties as Record<string, any> | undefined;
+    if (props) {
+      for (const [fieldName, fieldSchema] of Object.entries(props)) {
+        if (fieldSchema && typeof fieldSchema === "object") {
+          const errCtx = (fieldSchema as Record<string, any>)["x-telo-error-context"];
+          if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+            out.set(fieldName, errCtx as Record<string, any>);
+          }
+        }
+        walk(resolveLocalRef(fieldSchema as Record<string, any>, defSchema));
+      }
+    }
+    if (schema.items) walk(resolveLocalRef(schema.items as Record<string, any>, defSchema));
+    for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+      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 as Record<string, any>)) {
+        walk(sub as Record<string, any>);
+      }
+    }
+  };
+
+  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: string,
+  scopes: Map<string, Record<string, any>>,
+): Record<string, any> | undefined {
+  let best: { index: number; schema: Record<string, any> } | undefined;
+  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*\}\}/;
 
@@ -561,16 +633,19 @@ 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: string[] = ((m as any).exports?.kinds as string[] | undefined) ?? [];
+          // `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);
             if (!libResolver) {
               libResolver = new AliasResolver();
               aliasesByModule.set(moduleName, libResolver);
             }
-            libResolver.registerImport("Self", moduleName, exportedKinds);
+            libResolver.registerImport("Self", moduleName, []);
           }
         }
       }
@@ -753,6 +828,15 @@ export class StaticAnalyzer {
         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 as { forwardedExport?: boolean } | undefined)?.forwardedExport === true) {
+        continue;
+      }
+
       const resource = { kind: m.kind, name: m.metadata?.name as string };
 
       // Resolve kind through alias if needed; direct lookup takes priority so that
@@ -954,6 +1038,7 @@ export class StaticAnalyzer {
     // context — which require analyzer state to build — are stashed here.
     let celStepContextSchema: Record<string, any> | undefined;
     let celInvocationContext: Record<string, any> | undefined;
+    let celErrorScopes: Map<string, Record<string, any>> = new Map();
 
     visitManifest(
       allManifests,
@@ -973,6 +1058,9 @@ export class StaticAnalyzer {
                 aliases,
               )
             : undefined;
+          celErrorScopes = collectErrorContextScopes(
+            e.definition?.schema as Record<string, any> | undefined,
+          );
         },
         onCel: (e) => {
           const m = e.source;
@@ -995,6 +1083,22 @@ 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: Record<string, any> | null = null;
           if (matchedContext) {
             const manifestItem = matchedScope
@@ -1046,6 +1150,14 @@ export class StaticAnalyzer {
                 message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
                 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
@@ -1096,7 +1208,14 @@ export class StaticAnalyzer {
     );
   }
 
-  normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
+  normalize(
+    manifests: ResourceManifest[],
+    registry: AnalysisRegistry,
+    // 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?: ResourceManifest[],
+  ): ResourceManifest[] {
     const ctx = registry._context();
     const normalized = normalizeInlineResources(
       manifests,
@@ -1107,7 +1226,13 @@ export class StaticAnalyzer {
     // Resolve !ref sentinels after normalize so both the original and
     // inline-extracted manifests get their refs canonicalized to
     // {kind, name} for the kernel that consumes this output.
-    resolveRefSentinels(normalized, ctx.definitions!, ctx.aliases, ctx.aliasesByModule);
+    resolveRefSentinels(
+      normalized,
+      ctx.definitions!,
+      ctx.aliases,
+      ctx.aliasesByModule,
+      crossModuleTargets ?? [],
+    );
     return normalized;
   }
 

package/src/builtins.ts

@@ -234,6 +234,66 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 },
                 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,
+              },
             ],
           },
         },
@@ -338,6 +398,12 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           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/src/flatten-for-analyzer.ts

@@ -44,6 +44,10 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
       if (!targetModule) continue;
 
       const stamped = collectModuleManifests(targetModule);
+      const libDoc = stamped.find((m) => isModuleKind(m.kind));
+      const exportedResources = new Set<string>(
+        (libDoc as { exports?: { resources?: string[] } } | undefined)?.exports?.resources ?? [],
+      );
       for (const m of stamped) {
         if (
           m.kind === "Telo.Definition" ||
@@ -51,6 +55,22 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
           m.kind === "Telo.Import"
         ) {
           result.push(m);
+        } else if (
+          !isModuleKind(m.kind) &&
+          typeof m.metadata?.name === "string" &&
+          exportedResources.has(m.metadata.name as string)
+        ) {
+          // 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 } as ResourceManifest["metadata"],
+          });
         }
       }
     }

package/src/manifest-visitor.ts

@@ -1,5 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { walkCelExpressions } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -80,6 +80,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 {
@@ -123,6 +130,58 @@ 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;
+}
+
+/** Synthetic entry for a value-tree-discovered ref — these carry no declared
+ *  x-telo-ref constraint. */
+const NESTED_REF_ENTRY: RefFieldEntry = { 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: unknown,
+  path: string,
+  cb: (value: unknown, path: string) => void,
+): void {
+  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 as { __compiled?: unknown }).__compiled) return;
+  const obj = value as Record<string, unknown>;
+  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: string): string =>
@@ -139,12 +198,13 @@ export function visitManifest(
   visitor: ManifestVisitor,
   options: VisitOptions = {},
 ): void {
-  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;
@@ -157,6 +217,10 @@ export function visitManifest(
 
     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<string>() : null;
+
     if (wantsRefs || wantsScope || wantsSchemaFrom) {
       const baseMap = aliases
         ? registry.getFieldMapForKind(r.kind, aliases)
@@ -208,6 +272,7 @@ export function visitManifest(
 
             for (const { value, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
               if (!value) continue;
+              emittedRefPaths?.add(concretePath);
               visitor.onRef!({
                 source: r,
                 fieldPath,
@@ -230,6 +295,30 @@ export function visitManifest(
       }
     }
 
+    // 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: unknown, path: string) => {
+        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 as Record<string, unknown>)) {
+        walkRefValues(value, key, emitNested);
+      }
+    }
+
     if (wantsCel) {
       const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
       walkCelExpressions(r, "", (expr, path, engineName) => {

package/src/reference-field-map.ts

@@ -213,6 +213,20 @@ function traverseNode(
     const entry: RefFieldEntry = { refs, isArray: path.includes("[]") };
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
     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"] as const) {
+      const variants = node[variantKey];
+      if (!Array.isArray(variants)) continue;
+      for (const variant of variants) {
+        if (!variant || typeof variant !== "object") continue;
+        traverseVariant(variant as Record<string, any>, path, map, root, visitedRefs);
+      }
+    }
     return;
   }