@telorun/analyzer 0.6.0 → 0.7.0

package/README.md

@@ -1,6 +1,21 @@
-# ⚡ Telo
+<p align="center">
+  <img src="./assets/telo.png" alt="Telo" width="200" />
+</p>
 
-Runtime for declarative backends.
+<h1 align="center">Telo</h1>
+
+<p align="center">Runtime for declarative backends.</p>
+
+<p align="center">
+  <a href="https://github.com/telorun/telo/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/telorun/telo/actions/workflows/test.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@telorun/cli"><img alt="node" src="https://img.shields.io/node/v/@telorun/cli" /></a>
+  <br />
+  <a href="https://github.com/telorun/telo/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/issues"><img alt="Issues" src="https://img.shields.io/github/issues/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/pulls"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr/telorun/telo" /></a>
+  <br />
+  <img alt="Changesets" src="https://img.shields.io/badge/maintained%20with-changesets-176de3" />
+</p>
 
 Telo is an execution engine (Micro-Kernel) that runs logic defined entirely in YAML manifests. Instead of writing imperative backend code, you define your routes, databases, schemas, and AI workflows as atomic, interconnected YAML documents. Telo takes those manifests and runs them.
 
@@ -27,8 +42,6 @@ $ telo ./examples/hello-api.yaml
 - **Indexes** resources by Kind and Name for constant-time lookup.
 - **Dispatches** execution to the controller that owns each Kind.
 
-Manifests also support directives for dynamic generation: `$let`, `$if`, `$for`, `$eval`, and `$include`. See [CEL-YAML Templating](./yaml-cel-templating/README.md) for documentation.
-
 ## Example manifest
 
 Here is an example Telo application that defines a simple HTTP API:
@@ -221,7 +234,6 @@ Those manifests were taken to the next level by allowing them to run inside a st
 ## See more at
 
 - [Telo Kernel](./kernel/README.md)
-- [CEL-YAML Templating](./yaml-cel-templating/README.md)
 - [Telo SDK for module authors](sdk/README.md)
 - [Modules](modules/README.md)
 

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;AAGzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAmT/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,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA2TvB,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;IAKxF,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;CAiB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAoY/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,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA2TvB,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;IAKxF,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;CAiB5F"}

package/dist/analyzer.js

@@ -81,6 +81,43 @@ function extractContextsFromSchema(schema, path = "$") {
     }
     return results;
 }
+/** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
+ *  Non-refs and unresolved refs pass through unchanged. */
+function resolveLocalRef(schema, root) {
+    if (!schema)
+        return undefined;
+    const ref = schema.$ref;
+    if (typeof ref === "string" && ref.startsWith("#/$defs/")) {
+        const defName = ref.slice("#/$defs/".length);
+        const resolved = root.$defs?.[defName];
+        if (resolved && typeof resolved === "object")
+            return resolved;
+    }
+    return schema;
+}
+/** Gather property schemas from a (possibly variant-bearing) object schema:
+ *  top-level `properties` plus every `oneOf` / `anyOf` / `allOf` branch. */
+function gatherPropertySchemas(schema) {
+    const out = [];
+    if (schema.properties && typeof schema.properties === "object") {
+        for (const [k, v] of Object.entries(schema.properties)) {
+            out.push([k, v]);
+        }
+    }
+    for (const variantKey of ["oneOf", "anyOf", "allOf"]) {
+        const arr = schema[variantKey];
+        if (!Array.isArray(arr))
+            continue;
+        for (const variant of arr) {
+            if (variant && typeof variant === "object" && variant.properties) {
+                for (const [k, v] of Object.entries(variant.properties)) {
+                    out.push([k, v]);
+                }
+            }
+        }
+    }
+    return out;
+}
 /**
  * Build a `steps` context schema from `x-telo-step-context` annotation.
  * Walks each step in the manifest array, resolves the invoked resource's outputType,
@@ -97,6 +134,15 @@ function extractContextsFromSchema(schema, path = "$") {
  * Layer 2 is what makes `x-telo-stream` properties on definitions actually
  * govern step-result chain validation — without it, the validator falls back
  * to permissive and the stream-opacity rule never fires.
+ *
+ * Recursion into nested step arrays is annotation-driven via
+ * `x-telo-topology-role`. The analyzer recognises three role values:
+ *   - `branch`     — value is an array of steps (e.g. then / else / do / catch).
+ *   - `branch-list`— value is an array of objects each carrying further roled
+ *                    sub-properties (e.g. elseif: [{ if, then }]).
+ *   - `case-map`   — value is an object whose values are step arrays (e.g. cases).
+ * No specific Run.Sequence field name is hardcoded; any kind that uses
+ * `x-telo-step-context` and tags its branch fields with these roles works.
  */
 function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases) {
     const props = defSchema.properties;
@@ -113,8 +159,35 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
         const steps = manifest[fieldName];
         if (!Array.isArray(steps))
             continue;
+        const stepItemSchema = resolveLocalRef(fieldSchema.items, defSchema);
         const stepProperties = {};
-        const collectSteps = (items) => {
+        const dispatchRole = (data, role, itemsSchema) => {
+            if (role === "branch" && Array.isArray(data)) {
+                collectSteps(data);
+            }
+            else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+                for (const arr of Object.values(data)) {
+                    if (Array.isArray(arr))
+                        collectSteps(arr);
+                }
+            }
+            else if (role === "branch-list" && Array.isArray(data)) {
+                const entrySchema = resolveLocalRef(itemsSchema, defSchema);
+                if (!entrySchema)
+                    return;
+                for (const entry of data) {
+                    if (!entry || typeof entry !== "object")
+                        continue;
+                    for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
+                        const subRole = subSchema["x-telo-topology-role"];
+                        if (typeof subRole !== "string")
+                            continue;
+                        dispatchRole(entry[subKey], subRole, subSchema.items);
+                    }
+                }
+            }
+        };
+        function collectSteps(items) {
             for (const step of items) {
                 if (!step || typeof step !== "object")
                     continue;
@@ -149,20 +222,16 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
                         },
                     };
                 }
-                // Recurse into nested step arrays (then, else, do, catch, finally, try, default, cases)
-                for (const nested of ["then", "else", "do", "catch", "finally", "try", "default"]) {
-                    if (Array.isArray(s[nested]))
-                        collectSteps(s[nested]);
-                }
-                // cases is an object map of arrays
-                if (s.cases && typeof s.cases === "object") {
-                    for (const arr of Object.values(s.cases)) {
-                        if (Array.isArray(arr))
-                            collectSteps(arr);
+                if (stepItemSchema) {
+                    for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
+                        const role = propSchema["x-telo-topology-role"];
+                        if (typeof role !== "string")
+                            continue;
+                        dispatchRole(s[propKey], role, propSchema.items);
                     }
                 }
             }
-        };
+        }
         collectSteps(steps);
         if (Object.keys(stepProperties).length > 0) {
             return {

package/dist/cel-environment.d.ts

@@ -2,6 +2,7 @@ import { Environment } from "@marcbachmann/cel-js";
 import { type ResourceManifest } from "@telorun/sdk";
 export interface CelHandlers {
     sha256: (s: string) => string;
+    json: (value: unknown) => string;
 }
 /** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
  *  same function signatures (so `env.check()` succeeds for type-inference) — the

package/dist/cel-environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAU,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B;AAaD;;;;;;;;;;;;yDAYyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,WAA2B,GAAG,WAAW,CAetF;AAED;;;;;;;;;uEASuE;AACvE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAC9C,WAAW,CAyCb"}
+{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAU,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG7D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAcD;;;;;;;;;;;;yDAYyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,WAA2B,GAAG,WAAW,CAgBtF;AAED;;;;;;;;;uEASuE;AACvE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAC9C,WAAW,CAyCb"}

package/dist/cel-environment.js

@@ -7,6 +7,7 @@ const stub = (name) => () => {
 };
 const STUB_HANDLERS = {
     sha256: stub("sha256"),
+    json: stub("json"),
 };
 /** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
  *  same function signatures (so `env.check()` succeeds for type-inference) — the
@@ -22,7 +23,7 @@ const STUB_HANDLERS = {
  *  member access raises a CEL error at runtime — matching the analyzer's
  *  static check on `x-telo-stream`-marked properties. */
 export function buildCelEnvironment(handlers = STUB_HANDLERS) {
-    return new Environment({ unlistedVariablesAreDyn: true })
+    return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
         .registerFunction("join(list, string): string", (list, sep) => list.map(String).join(sep))
         .registerFunction("keys(map): list", (map) => {
         if (map instanceof Map)
@@ -35,6 +36,7 @@ export function buildCelEnvironment(handlers = STUB_HANDLERS) {
         return Object.values(map);
     })
         .registerFunction("sha256(string): string", (s) => handlers.sha256(s))
+        .registerFunction("json(dyn): string", (value) => handlers.json(value))
         .registerType("Stream", Stream);
 }
 /** Clone `baseEnv` and register typed variable declarations so that

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

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IAEJ,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,qBAAqB,GAAE,cAAc,EAAE,GAAG,iBAAsB;IAmB5E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqGnE,eAAe;YAoBf,eAAe;IAgEvB,iBAAiB,CACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;KAClD,GAAG,IAAI,CAAC;IAiCH,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA2GnE"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IAEJ,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,qBAAqB,GAAE,cAAc,EAAE,GAAG,iBAAsB;IAmB5E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAqGnE,eAAe;YAoBf,eAAe;IAgEvB,iBAAiB,CACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,gBAAgB,EAAE,CAAC;QAC9B,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;KAClD,GAAG,IAAI,CAAC;IAiCH,eAAe,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAsCrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA+HnE"}

package/dist/manifest-loader.js

@@ -336,6 +336,23 @@ export class Loader {
                     e.sourceLine = m.metadata?.sourceLine ?? 0;
                     throw e;
                 }
+                if (!importedLibrary) {
+                    const kinds = imported
+                        .map((im) => im.kind)
+                        .filter((k) => typeof k === "string");
+                    // Prefer the URL the source layer actually fetched (stamped onto every
+                    // loaded manifest's metadata.source) over the raw input — for registry
+                    // refs the input is e.g. "std/foo@1.0.0", not a URL.
+                    const fetchedFrom = (imported[0]?.metadata?.source) ?? importUrl;
+                    const detail = kinds.length
+                        ? `Fetched ${imported.length} document(s) with kinds [${kinds.join(", ")}].`
+                        : `Fetched manifest contained no recognizable Telo documents — check that the source ` +
+                            `serves a Telo.Library manifest and not an upstream error page.`;
+                    const e = new Error(`Telo.Import target '${importSource}' did not resolve to a Telo.Library. ` +
+                        `Fetched from: ${fetchedFrom}. ${detail}`);
+                    e.sourceLine = m.metadata?.sourceLine ?? 0;
+                    throw e;
+                }
                 if (importedLibrary?.metadata?.name) {
                     libraryIdentityByUrl.set(importUrl, {
                         name: importedLibrary.metadata.name,

package/dist/sources/registry-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry-source.d.ts","sourceRoot":"","sources":["../../src/sources/registry-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7E,qBAAa,cAAe,YAAW,cAAc;IACvC,OAAO,CAAC,WAAW;gBAAX,WAAW,SAAuB;IAEtD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWxB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAWxE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMvD,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;CAmBvB"}
+{"version":3,"file":"registry-source.d.ts","sourceRoot":"","sources":["../../src/sources/registry-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7E,qBAAa,cAAe,YAAW,cAAc;IACvC,OAAO,CAAC,WAAW;gBAAX,WAAW,SAAuB;IAEtD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWxB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA4BxE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMvD,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;CAmBvB"}

package/dist/sources/registry-source.js

@@ -19,7 +19,21 @@ export class RegistrySource {
         if (!response.ok) {
             throw new Error(`Failed to fetch manifest ${moduleRef}: ${response.status} ${response.statusText}`);
         }
-        return { text: await response.text(), source: fetchUrl };
+        const text = await response.text();
+        // Some object-storage backends (e.g. Cloudflare R2 / S3) surface auth or
+        // permission failures by returning a 200 status with an XML error body.
+        // Catch this here so the loader produces a precise error rather than
+        // silently parsing the XML as YAML and reporting a downstream UNDEFINED_KIND.
+        if (text.trimStart().startsWith("<?xml") || text.trimStart().startsWith("<Error")) {
+            const codeMatch = text.match(/<Code>([^<]+)<\/Code>/);
+            const messageMatch = text.match(/<Message>([^<]+)<\/Message>/);
+            const detail = codeMatch && messageMatch
+                ? `${codeMatch[1]}: ${messageMatch[1]}`
+                : text.slice(0, 200);
+            throw new Error(`Registry returned a non-manifest response for ${moduleRef} ` +
+                `(URL: ${fetchUrl}): ${detail}`);
+        }
+        return { text, source: fetchUrl };
     }
     resolveRelative(base, relative) {
         const baseUrl = this.supports(base) ? this.toRegistryModuleBase(base) : base;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",

package/src/analyzer.ts

@@ -126,6 +126,45 @@ function extractContextsFromSchema(
   return results;
 }
 
+/** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
+ *  Non-refs and unresolved refs pass through unchanged. */
+function resolveLocalRef(
+  schema: Record<string, any> | undefined,
+  root: Record<string, any>,
+): Record<string, any> | undefined {
+  if (!schema) return undefined;
+  const ref = schema.$ref;
+  if (typeof ref === "string" && ref.startsWith("#/$defs/")) {
+    const defName = ref.slice("#/$defs/".length);
+    const resolved = root.$defs?.[defName];
+    if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
+  }
+  return schema;
+}
+
+/** Gather property schemas from a (possibly variant-bearing) object schema:
+ *  top-level `properties` plus every `oneOf` / `anyOf` / `allOf` branch. */
+function gatherPropertySchemas(schema: Record<string, any>): Array<[string, Record<string, any>]> {
+  const out: Array<[string, Record<string, any>]> = [];
+  if (schema.properties && typeof schema.properties === "object") {
+    for (const [k, v] of Object.entries(schema.properties as Record<string, any>)) {
+      out.push([k, v as Record<string, any>]);
+    }
+  }
+  for (const variantKey of ["oneOf", "anyOf", "allOf"] as const) {
+    const arr = schema[variantKey];
+    if (!Array.isArray(arr)) continue;
+    for (const variant of arr) {
+      if (variant && typeof variant === "object" && variant.properties) {
+        for (const [k, v] of Object.entries(variant.properties as Record<string, any>)) {
+          out.push([k, v as Record<string, any>]);
+        }
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * Build a `steps` context schema from `x-telo-step-context` annotation.
  * Walks each step in the manifest array, resolves the invoked resource's outputType,
@@ -142,6 +181,15 @@ function extractContextsFromSchema(
  * Layer 2 is what makes `x-telo-stream` properties on definitions actually
  * govern step-result chain validation — without it, the validator falls back
  * to permissive and the stream-opacity rule never fires.
+ *
+ * Recursion into nested step arrays is annotation-driven via
+ * `x-telo-topology-role`. The analyzer recognises three role values:
+ *   - `branch`     — value is an array of steps (e.g. then / else / do / catch).
+ *   - `branch-list`— value is an array of objects each carrying further roled
+ *                    sub-properties (e.g. elseif: [{ if, then }]).
+ *   - `case-map`   — value is an object whose values are step arrays (e.g. cases).
+ * No specific Run.Sequence field name is hardcoded; any kind that uses
+ * `x-telo-step-context` and tags its branch fields with these roles works.
  */
 function buildStepContextSchema(
   manifest: Record<string, any>,
@@ -164,8 +212,43 @@ function buildStepContextSchema(
     const steps = manifest[fieldName];
     if (!Array.isArray(steps)) continue;
 
+    const stepItemSchema = resolveLocalRef(
+      fieldSchema.items as Record<string, any> | undefined,
+      defSchema,
+    );
+
     const stepProperties: Record<string, any> = {};
-    const collectSteps = (items: unknown[]) => {
+
+    const dispatchRole = (
+      data: unknown,
+      role: string,
+      itemsSchema: Record<string, any> | undefined,
+    ): void => {
+      if (role === "branch" && Array.isArray(data)) {
+        collectSteps(data);
+      } else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+        for (const arr of Object.values(data as Record<string, unknown>)) {
+          if (Array.isArray(arr)) collectSteps(arr);
+        }
+      } else if (role === "branch-list" && Array.isArray(data)) {
+        const entrySchema = resolveLocalRef(itemsSchema, defSchema);
+        if (!entrySchema) return;
+        for (const entry of data) {
+          if (!entry || typeof entry !== "object") continue;
+          for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
+            const subRole = subSchema["x-telo-topology-role"];
+            if (typeof subRole !== "string") continue;
+            dispatchRole(
+              (entry as Record<string, any>)[subKey],
+              subRole,
+              subSchema.items as Record<string, any> | undefined,
+            );
+          }
+        }
+      }
+    };
+
+    function collectSteps(items: unknown[]): void {
       for (const step of items) {
         if (!step || typeof step !== "object") continue;
         const s = step as Record<string, any>;
@@ -207,18 +290,16 @@ function buildStepContextSchema(
             },
           };
         }
-        // Recurse into nested step arrays (then, else, do, catch, finally, try, default, cases)
-        for (const nested of ["then", "else", "do", "catch", "finally", "try", "default"]) {
-          if (Array.isArray(s[nested])) collectSteps(s[nested]);
-        }
-        // cases is an object map of arrays
-        if (s.cases && typeof s.cases === "object") {
-          for (const arr of Object.values(s.cases)) {
-            if (Array.isArray(arr)) collectSteps(arr);
+        if (stepItemSchema) {
+          for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
+            const role = propSchema["x-telo-topology-role"];
+            if (typeof role !== "string") continue;
+            dispatchRole(s[propKey], role, propSchema.items as Record<string, any> | undefined);
           }
         }
       }
-    };
+    }
+
     collectSteps(steps);
 
     if (Object.keys(stepProperties).length > 0) {

package/src/cel-environment.ts

@@ -4,6 +4,7 @@ import { jsonSchemaToCelType } from "./schema-compat.js";
 
 export interface CelHandlers {
   sha256: (s: string) => string;
+  json: (value: unknown) => string;
 }
 
 const stub = (name: string) => () => {
@@ -15,6 +16,7 @@ const stub = (name: string) => () => {
 
 const STUB_HANDLERS: CelHandlers = {
   sha256: stub("sha256"),
+  json: stub("json"),
 };
 
 /** Build a CEL `Environment` with Telo's stdlib of functions. Always registers the
@@ -31,7 +33,7 @@ const STUB_HANDLERS: CelHandlers = {
  *  member access raises a CEL error at runtime — matching the analyzer's
  *  static check on `x-telo-stream`-marked properties. */
 export function buildCelEnvironment(handlers: CelHandlers = STUB_HANDLERS): Environment {
-  return new Environment({ unlistedVariablesAreDyn: true })
+  return new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
     .registerFunction("join(list, string): string", (list: unknown[], sep: string) =>
       list.map(String).join(sep),
     )
@@ -44,6 +46,7 @@ export function buildCelEnvironment(handlers: CelHandlers = STUB_HANDLERS): Envi
       return Object.values(map as Record<string, unknown>);
     })
     .registerFunction("sha256(string): string", (s: string) => handlers.sha256(s))
+    .registerFunction("json(dyn): string", (value: unknown) => handlers.json(value))
     .registerType("Stream", Stream as unknown as new (...args: unknown[]) => unknown);
 }
 

package/src/manifest-loader.ts

@@ -398,6 +398,26 @@ export class Loader {
           (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
           throw e;
         }
+        if (!importedLibrary) {
+          const kinds = imported
+            .map((im) => im.kind)
+            .filter((k): k is string => typeof k === "string");
+          // Prefer the URL the source layer actually fetched (stamped onto every
+          // loaded manifest's metadata.source) over the raw input — for registry
+          // refs the input is e.g. "std/foo@1.0.0", not a URL.
+          const fetchedFrom =
+            ((imported[0]?.metadata as { source?: string } | undefined)?.source) ?? importUrl;
+          const detail = kinds.length
+            ? `Fetched ${imported.length} document(s) with kinds [${kinds.join(", ")}].`
+            : `Fetched manifest contained no recognizable Telo documents — check that the source ` +
+              `serves a Telo.Library manifest and not an upstream error page.`;
+          const e = new Error(
+            `Telo.Import target '${importSource}' did not resolve to a Telo.Library. ` +
+              `Fetched from: ${fetchedFrom}. ${detail}`,
+          );
+          (e as any).sourceLine = (m.metadata as any)?.sourceLine ?? 0;
+          throw e;
+        }
         if (importedLibrary?.metadata?.name) {
           libraryIdentityByUrl.set(importUrl, {
             name: importedLibrary.metadata.name as string,

package/src/sources/registry-source.ts

@@ -24,7 +24,24 @@ export class RegistrySource implements ManifestSource {
         `Failed to fetch manifest ${moduleRef}: ${response.status} ${response.statusText}`,
       );
     }
-    return { text: await response.text(), source: fetchUrl };
+    const text = await response.text();
+    // Some object-storage backends (e.g. Cloudflare R2 / S3) surface auth or
+    // permission failures by returning a 200 status with an XML error body.
+    // Catch this here so the loader produces a precise error rather than
+    // silently parsing the XML as YAML and reporting a downstream UNDEFINED_KIND.
+    if (text.trimStart().startsWith("<?xml") || text.trimStart().startsWith("<Error")) {
+      const codeMatch = text.match(/<Code>([^<]+)<\/Code>/);
+      const messageMatch = text.match(/<Message>([^<]+)<\/Message>/);
+      const detail =
+        codeMatch && messageMatch
+          ? `${codeMatch[1]}: ${messageMatch[1]}`
+          : text.slice(0, 200);
+      throw new Error(
+        `Registry returned a non-manifest response for ${moduleRef} ` +
+          `(URL: ${fetchUrl}): ${detail}`,
+      );
+    }
+    return { text, source: fetchUrl };
   }
 
   resolveRelative(base: string, relative: string): string {