@telorun/run 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @telorun/run
 
+## 0.2.0
+
+### Minor Changes
+
+- 353d7e5: feat: invocable errors — structured error channel end-to-end
+
+  Invocables and runnables now have a first-class structured-error channel for domain failures (`InvokeError`), distinct from operational failures (plain `Error` / `RuntimeError`). Route handlers branch on named codes via `catches:`; sequences catch with `error.code` / `error.message` / `error.data` / `error.step` context.
+
+  **SDK** (`@telorun/sdk`)
+
+  - New `InvokeError` class + `isInvokeError` guard. Symbol-based discrimination (`Symbol.for("telo.InvokeError")`) is dual-realm-safe across pnpm hoist splits, registry modules, and future sandbox isolation.
+  - `ResourceDefinition.throws`: declared-throw contract (`codes` map, `inherit: true`, `passthrough: true`).
+  - `ResourceContext` / `EvaluationContext` gain `invokeResolved(kind, name, instance, inputs)` for callers that already hold a resolved instance.
+
+  **Kernel** (`@telorun/kernel`)
+
+  - Single emission point for invoke-level events: `Invoked` / `InvokeRejected` / `InvokeFailed` / `InvokeRejected.Undeclared`. All call paths (direct invoke, sequence scope path, HTTP route handler) route through the same wrapper.
+  - `Telo.Definition.throws:` schema with per-capability restrictions (rule 8: only on Invocable / Runnable).
+  - `resolveChildren` now auto-registers bare-kind inline refs when a resource name is supplied without an explicit name on the ref — lets stateless invocables like `Run.Throw` be used inline via `invoke: {kind: Run.Throw}`.
+
+  **Analyzer** (`@telorun/analyzer`)
+
+  - New dataflow resolver (`resolve-throws-union.ts`) for `inherit: true` / `passthrough: true` declarations. Walks `x-telo-step-context` arrays generically, applies `try`/`catch` subtraction, detects cycles, memoises per manifest.
+  - New coverage validator (`validate-throws-coverage.ts`) — rules 1/2/4/7 for `catches:` lists. Coverage-proving CEL parser recognises `error.code == 'X'`, disjunctions, and `error.code in [...]`. Typed `error.data.<field>` access against per-code `data:` schemas, with intersection narrowing for disjunctive `when:` clauses.
+  - New error codes: `UNDECLARED_THROW_CODE`, `UNCOVERED_THROW_CODE`, `UNBOUNDED_UNION_NEEDS_CATCHALL`, `CATCHALL_NOT_LAST`, `INHERIT_WITHOUT_STEP_CONTEXT`.
+
+  **Run module** (`@telorun/run`)
+
+  - `Run.Sequence` declares `throws: { inherit: true }`. Its effective union is resolved from step invocables at analysis time.
+  - New `Run.Throw` invocable: takes `{code, message, data?}` and throws `InvokeError`. Declared with `throws: { passthrough: true }`; the analyzer resolves constant / `error.code`-inside-catch forms at each call site.
+  - Sequence `try`/`catch` `error` context gains `data?: unknown` and now branches on `isInvokeError`.
+
+  **HTTP server module** (`@telorun/http-server`) — **breaking**
+
+  - Route-level `response:` is replaced by two channel lists: `returns:` (how to render handler results) and `catches:` (how to render `InvokeError` throws). Applies to both `Http.Api` routes and `Http.Server.notFoundHandler`.
+  - Plain `Error` / `RuntimeError` throws skip `catches:` and fall through to Fastify's default 5xx renderer — operational vs. domain failures are now distinct on the wire.
+  - `catches:` entries reject `mode: stream` at schema validation (structured errors always render as JSON).
+  - Unmatched `returns:` dispatch now throws (surfaces via Fastify's error handler) instead of rendering a silent 500.
+  - Every `response:` occurrence across the repo (apps, benchmarks, examples, tests) migrated to `returns:` — no manifest carries the old shape.
+
+  See `sdk/nodejs/plans/invocable-errors.md` for the full design and rollout phasing.
+
+- 31d721e: feat: bearer-token auth for the Telo module registry publish endpoint
+
+  The registry's `PUT /{namespace}/{name}/{version}` now requires an `Authorization: Bearer <token>` header. Reads stay anonymous. Tokens are provisioned declaratively at boot via `TELO_PUBLISH_TOKEN` and stored as SHA-256 hashes in a `tokens` table joined to `users` and `namespaces`.
+
+  **Analyzer** (`@telorun/analyzer`) — **breaking for direct API consumers**
+
+  - `StaticAnalyzer` and `Loader` now accept an optional `{ celHandlers }` in their constructors. Analyzer-only callers (VS Code extension, Docusaurus preview, CLI `check`/`publish`) can omit it and get throwing stubs. Runtime callers (kernel) must supply real handlers.
+  - The module-level `celEnvironment` singleton is removed — `precompile.ts` now takes the `Environment` as a parameter.
+  - New CEL stdlib function: `sha256(string): string`. Always registered with the correct signature so `env.check()` type-checks; behaviour depends on the supplied handler.
+  - The throws-union resolver recognises the new `throw:` step shape (see Run module) and resolves its code at the call site using the same rules as passthrough invocables (literal / `${{ 'LIT' }}` / `${{ error.code }}` in catch).
+  - CEL type-check failures now surface as diagnostics. Previously the analyzer only reported schema/type mismatches on valid expressions; `env.check(...)` returning `{ valid: false }` (wrong method, wrong operand types, wrong overload — e.g. `s.slice(7)` on a dyn) was silently dropped. Now surfaces as `SCHEMA_VIOLATION` with a `CEL type error:` message.
+
+  **Kernel** (`@telorun/kernel`)
+
+  - Constructs `StaticAnalyzer` and `Loader` with a `node:crypto`-backed `sha256` handler, so CEL templates invoking `sha256()` evaluate at runtime.
+
+  **Run module** (`@telorun/run`) — **breaking**
+
+  - `Run.Sequence` gains a first-class `throw:` step variant: `- name: X; throw: { code, message?, data? }` — throws `InvokeError` directly from inside the sequence. Works inside `catch:` blocks via `code: "${{ error.code }}"` for re-raise. A malformed `throw.code` (non-string or empty after expansion) is itself reported as `InvokeError("INVALID_THROW_STEP", …)` rather than a plain Error, so the failure stays in the structured-error channel and a surrounding `catches:` can map it.
+  - The `Run.Throw` invocable is removed. Existing `invoke: { kind: Run.Throw }` call sites must migrate to `throw:` steps. The separate kind was redundant with the new step form, and the `throw:` step expresses the intent more directly inside sequences.
+  - **Event-stream change:** `throw:` steps do **not** emit a scoped `<Kind>.<name>.InvokeRejected` event the way `Run.Throw` did. The error is thrown from inside the sequence's own `invoke()`, so the enclosing kind's event is what fires (e.g. `Run.Sequence.<handlerName>.InvokeRejected` — or nothing, when an enclosing `try` absorbs the throw). Downstream observers that filtered on `Run.Throw.*.InvokeRejected` must switch filters.
+
+  **CLI** (`@telorun/cli`)
+
+  - `telo publish` reads `TELO_REGISTRY_TOKEN` and sends it as `Authorization: Bearer <token>`. Without the env var, publishes to auth-gated registries fail with 401.
+
+  See `apps/registry/plans/registry-auth.md` for the full plan.
+
+### Patch Changes
+
+- Updated dependencies [353d7e5]
+  - @telorun/sdk@0.3.0
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @telorun/sdk@0.2.8
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,233 @@
+# ⚡ Telo
+
+Runtime for declarative backends.
+
+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.
+
+Built to be language-agnostic and infinitely extensible.
+
+```bash
+# Reconcile your manifest into a running backend
+$ telo ./examples/hello-api.yaml
+
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+```
+
+## Why use Telo?
+
+- **Open Standards:** Built on YAML, JSON Schema, and CEL — no proprietary DSL.
+- **Static Analysis:** CEL type checking, reference validation, and IDE diagnostics catch errors before runtime.
+- **Micro-Kernel Architecture:** Telo itself knows nothing about HTTP or SQL. Everything is a module you import, scope, and compose with typed variable and secret contracts.
+- **Language Agnostic:** Available as a Node.js runtime today, with a shared YAML runtime contract that allows for future Rust or Go implementations without changing your manifests.
+
+## What It Does
+
+- **Loads** YAML resources and compiles CEL expressions (`${{ }}`) into an in-memory registry.
+- **Resolves** resource dependencies via a multi-pass init loop, handling ordering automatically.
+- **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:
+
+```yaml
+kind: Telo.Application
+metadata:
+  name: feedback
+  version: 1.0.0
+  description: |
+    A complete feedback collection REST API — no code, pure YAML.
+    Persists entries to SQLite and serves them over HTTP.
+targets:
+  - Migrations
+  - Server
+---
+kind: Telo.Import
+metadata:
+  name: Http
+source: ../modules/http-server
+---
+kind: Telo.Import
+metadata:
+  name: Sql
+source: ../modules/sql
+---
+# SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
+kind: Sql.Connection
+metadata:
+  name: Db
+driver: sqlite
+file: ./tmp/feedback.db
+---
+# Migrations: applied automatically before the server starts
+kind: Sql.Migrations
+metadata:
+  name: Migrations
+connection:
+  kind: Sql.Connection
+  name: Db
+---
+kind: Sql.Migration
+metadata:
+  name: Migration_20260413_182154_CreateFeedback
+sql: |
+  CREATE TABLE IF NOT EXISTS feedback (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    text      TEXT    NOT NULL,
+    source    TEXT,
+    score     INTEGER NOT NULL DEFAULT 0,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )
+---
+kind: Http.Server
+metadata:
+  name: Server
+baseUrl: http://localhost:8844
+port: 8844
+logger: true
+openapi:
+  info:
+    title: Feedback API
+    version: 1.0.0
+mounts:
+  - path: /v1
+    type: Http.Api.FeedbackRoutes
+---
+kind: Http.Api
+metadata:
+  name: FeedbackRoutes
+routes:
+  # POST /v1/feedback — insert a new entry, score derived from body length heuristic
+  - request:
+      path: /feedback
+      method: POST
+      schema:
+        body:
+          type: object
+          properties:
+            text:
+              type: string
+              minLength: 1
+            source:
+              type: string
+          required: [text]
+    handler:
+      kind: Sql.Exec
+      connection:
+        kind: Sql.Connection
+        name: Db
+    inputs:
+      sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
+      bindings:
+        - "${{ request.body.text }}"
+        - "${{ request.body.source }}"
+        - "${{ size(request.body.text) }}"
+    response:
+      - status: 201
+        headers:
+          Content-Type: application/json
+        body:
+          ok: true
+          message: Feedback received
+
+  # GET /v1/feedback — list all entries, newest first
+  - request:
+      path: /feedback
+      method: GET
+    handler:
+      kind: Sql.Select
+      connection:
+        kind: Sql.Connection
+        name: Db
+      from: feedback
+      columns: [id, text, source, score, created_at]
+      orderBy:
+        - { column: created_at, direction: desc }
+    response:
+      - status: 200
+        headers:
+          Content-Type: application/json
+        body: "${{ result.rows }}"
+
+  # GET /v1/feedback/{id} — fetch a single entry
+  - request:
+      path: /feedback/{id}
+      method: GET
+      schema:
+        params:
+          type: object
+          properties:
+            id:
+              type: integer
+          required: [id]
+    handler:
+      kind: Sql.Select
+      connection:
+        kind: Sql.Connection
+        name: Db
+      from: feedback
+      columns: [id, text, source, score, created_at]
+      where:
+        - { column: id, op: "=", value: "${{ request.params.id }}" }
+    response:
+      - status: 200
+        when: "size(result.rows) > 0"
+        headers:
+          Content-Type: application/json
+        body: "${{ result.rows[0] }}"
+      - status: 404
+        headers:
+          Content-Type: application/json
+        body:
+          ok: false
+          message: Not found
+```
+
+## Status
+
+Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
+
+## The Meaning of Telo
+
+The name Telo is derived from the Greek root Telos - meaning the "end goal", "purpose", or "final state". That is exactly the philosophy behind this runtime. In standard imperative programming, you have to write thousands of lines of code to tell a server exactly how to start. With Telo, you simply declare your desired final state.
+
+You define the end state. Telo makes it real.
+
+## Philosophy
+
+Modern platforms often spend disproportionate effort on technical mechanics-wiring frameworks, managing infrastructure, and negotiating toolchains-while the original business problem gets delayed or diluted. Telo pushes in the opposite direction: it treats kernel execution as a stable, predictable host so teams can concentrate on the **business logic and outcomes** instead of the plumbing.
+
+By separating "what the system should do" from "how it is hosted", the runtime reduces friction for domain‑level changes. Teams can move faster on product requirements, experiment more safely, and keep conversations centered on value delivered rather than implementation trivia.
+
+Telo also aims to **join forces across all programming language communities**, so the best ideas, patterns, and implementations can converge into a shared kernel truth without forcing everyone into a single stack.
+
+YAML also makes the system more **AI‑friendly** than traditional programming languages: it is explicit, structured, and easier for tools to generate, review, and transform without losing intent.
+
+## Modularity
+
+Telo is built around **modules** that own specific resource kinds. A module is loaded from a manifest, declares which kinds it implements, and then receives only the resources of those kinds. This keeps concerns isolated and lets teams compose systems from focused building blocks rather than monolithic services.
+
+At kernel execution time, execution is always routed by **Kind.Name**. The kernel resolves the Kind to its owning module and hands off execution. Modules can call back into the kernel to execute other resources, enabling composition without tight coupling.
+
+## Architecture
+
+The architecture is inspired by Kubernetes-style manifests: declarative resources, explicit kinds, and a control plane that routes work based on those definitions.
+Those manifests were taken to the next level by allowing them to run inside a standalone runtime host.
+
+## 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)
+
+## License
+
+See [LICENSE](https://github.com/telorun/telo/blob/main/LICENSE).
+
+## Contribution Note
+
+By contributing, you agree that code and examples in this repository may be translated or re‑implemented in other programming languages (including by AI systems) to support the project’s polyglot goals.

package/dist/sequence.d.ts

@@ -1,4 +1,4 @@
-import type { Invocable, KindRef, ResourceContext, ScopeHandle } from "@telorun/sdk";
+import { type Invocable, type KindRef, type ResourceContext, type ScopeHandle } from "@telorun/sdk";
 interface RetryPolicy {
     attempts?: number;
     delay?: string;
@@ -14,6 +14,10 @@ interface IfStep {
     name: string;
     if: string;
     then: Step[];
+    elseif?: Array<{
+        if: string;
+        then: Step[];
+    }>;
     else?: Step[];
 }
 interface WhileStep {
@@ -34,7 +38,15 @@ interface TryStep {
     catch?: Step[];
     finally?: Step[];
 }
-type Step = InvokeStep | IfStep | WhileStep | SwitchStep | TryStep;
+interface ThrowStep {
+    name: string;
+    throw: {
+        code: string;
+        message?: string;
+        data?: unknown;
+    };
+}
+type Step = InvokeStep | IfStep | WhileStep | SwitchStep | TryStep | ThrowStep;
 interface RunSequenceManifest {
     metadata: Record<string, string | number | boolean>;
     with?: ScopeHandle;
@@ -49,6 +61,7 @@ declare class RunSequence {
     constructor(ctx: ResourceContext, resource: RunSequenceManifest);
     init(): Promise<void>;
     private resolveInvokes;
+    private inlineInvokeResourceName;
     run(): Promise<void>;
     invoke(inputs: Record<string, unknown>): Promise<unknown>;
     private runScopeTargets;
@@ -59,6 +72,7 @@ declare class RunSequence {
     private executeIfStep;
     private executeWhileStep;
     private executeSwitchStep;
+    private executeThrowStep;
     private executeTryStep;
 }
 export declare function register(): void;

package/dist/sequence.js

@@ -1,3 +1,4 @@
+import { InvokeError, isInvokeError, } from "@telorun/sdk";
 function isInvokeStep(step) {
     return "invoke" in step;
 }
@@ -13,6 +14,9 @@ function isSwitchStep(step) {
 function isTryStep(step) {
     return "try" in step;
 }
+function isThrowStep(step) {
+    return "throw" in step;
+}
 class RunSequence {
     ctx;
     resource;
@@ -23,36 +27,47 @@ class RunSequence {
     async init() {
         this.resolveInvokes(this.resource.steps);
     }
-    resolveInvokes(stepList) {
-        for (const step of stepList) {
+    resolveInvokes(stepList, path = ["steps"]) {
+        for (const [index, step] of stepList.entries()) {
+            const stepPath = [...path, String(index)];
             if (isInvokeStep(step)) {
                 const raw = step.invoke;
                 if (!raw || typeof raw.invoke !== "function") {
-                    step.invoke = this.ctx.resolveChildren(raw, step.name);
+                    step.invoke = this.ctx.resolveChildren(raw, this.inlineInvokeResourceName(step.name, stepPath));
                 }
             }
             if (isIfStep(step)) {
-                this.resolveInvokes(step.then);
+                this.resolveInvokes(step.then, [...stepPath, "then"]);
+                if (step.elseif) {
+                    for (const [elseifIndex, branch] of step.elseif.entries()) {
+                        this.resolveInvokes(branch.then, [...stepPath, "elseif", String(elseifIndex), "then"]);
+                    }
+                }
                 if (step.else)
-                    this.resolveInvokes(step.else);
+                    this.resolveInvokes(step.else, [...stepPath, "else"]);
             }
             if (isWhileStep(step))
-                this.resolveInvokes(step.do);
+                this.resolveInvokes(step.do, [...stepPath, "do"]);
             if (isSwitchStep(step)) {
-                for (const branch of Object.values(step.cases))
-                    this.resolveInvokes(branch);
+                for (const [caseName, branch] of Object.entries(step.cases)) {
+                    this.resolveInvokes(branch, [...stepPath, "cases", caseName]);
+                }
                 if (step.default)
-                    this.resolveInvokes(step.default);
+                    this.resolveInvokes(step.default, [...stepPath, "default"]);
             }
             if (isTryStep(step)) {
-                this.resolveInvokes(step.try);
+                this.resolveInvokes(step.try, [...stepPath, "try"]);
                 if (step.catch)
-                    this.resolveInvokes(step.catch);
+                    this.resolveInvokes(step.catch, [...stepPath, "catch"]);
                 if (step.finally)
-                    this.resolveInvokes(step.finally);
+                    this.resolveInvokes(step.finally, [...stepPath, "finally"]);
             }
         }
     }
+    inlineInvokeResourceName(stepName, stepPath) {
+        const safeName = stepName.replace(/[^a-zA-Z0-9_-]+/g, "_");
+        return `__sequence_${stepPath.join("_")}__${safeName}`;
+    }
     async run() {
         if (this.resource.with) {
             await this.resource.with.run(async (scope) => {
@@ -109,6 +124,8 @@ class RunSequence {
             await this.executeSwitchStep(step, steps, scope, extraCtx);
         else if (isTryStep(step))
             await this.executeTryStep(step, steps, scope, extraCtx);
+        else if (isThrowStep(step))
+            this.executeThrowStep(step, steps, extraCtx);
         else
             throw new Error(`Step "${step.name}" has no recognized type key`);
     }
@@ -125,7 +142,8 @@ class RunSequence {
         else {
             const ref = raw;
             if (scope) {
-                result = await scope.getInstance(ref.name).invoke(inputs);
+                const instance = scope.getInstance(ref.name);
+                result = await this.ctx.invokeResolved(ref.kind, ref.name, instance, inputs);
             }
             else {
                 result = await this.ctx.invoke(ref.kind, ref.name, inputs, { retry: step.retry });
@@ -136,8 +154,17 @@ class RunSequence {
     async executeIfStep(step, steps, scope, extraCtx) {
         if (this.ctx.expandValue(step.if, { steps, ...extraCtx })) {
             await this.executeSteps(step.then, steps, scope, extraCtx);
+            return;
         }
-        else if (step.else) {
+        if (step.elseif) {
+            for (const branch of step.elseif) {
+                if (this.ctx.expandValue(branch.if, { steps, ...extraCtx })) {
+                    await this.executeSteps(branch.then, steps, scope, extraCtx);
+                    return;
+                }
+            }
+        }
+        if (step.else) {
             await this.executeSteps(step.else, steps, scope, extraCtx);
         }
     }
@@ -158,6 +185,19 @@ class RunSequence {
             throw new Error(`Switch step "${step.name}": no matching case for "${key}" and no default`);
         }
     }
+    executeThrowStep(step, steps, extraCtx) {
+        const cel = { steps, ...extraCtx };
+        const expanded = this.ctx.expandValue(step.throw, cel);
+        const code = expanded?.code;
+        if (typeof code !== "string" || code.length === 0) {
+            // Structured error (not plain Error) so the failure stays in the InvokeError
+            // channel and a route's `catches:` list can still map it. The alternative —
+            // a plain Error — would skip catches: entirely and fall through to a 500.
+            throw new InvokeError("INVALID_THROW_STEP", `Run.Sequence step "${step.name}": throw.code is required and must resolve to a non-empty string`, { step: step.name, code });
+        }
+        const message = typeof expanded.message === "string" ? expanded.message : code;
+        throw new InvokeError(code, message, expanded.data);
+    }
     async executeTryStep(step, steps, scope, extraCtx) {
         if (step.when !== undefined && !this.ctx.expandValue(step.when, { steps, ...extraCtx }))
             return;
@@ -205,11 +245,11 @@ class RunSequence {
     }
 }
 function toSequenceError(err, stepName) {
+    if (isInvokeError(err)) {
+        return { message: err.message, code: err.code, data: err.data, step: stepName };
+    }
     const message = err instanceof Error ? err.message : String(err);
-    const code = err instanceof Error && err.code != null
-        ? err.code
-        : null;
-    return { message, code, step: stepName };
+    return { message, code: null, data: undefined, step: stepName };
 }
 export function register() { }
 export async function create(resource, ctx) {

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@telorun/run",
-  "version": "0.1.2",
+  "version": "0.2.0",
+  "description": "Telo Run module - Sequence execution for Telo manifests.",
+  "keywords": [
+    "telo",
+    "run",
+    "sequence",
+    "pipeline"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "modules/run/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
   "type": "module",
   "main": "./src/sequence.ts",
   "module": "./src/sequence.ts",
@@ -11,7 +29,7 @@
     }
   },
   "dependencies": {
-    "@telorun/sdk": "0.2.7"
+    "@telorun/sdk": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/sequence.ts

@@ -1,4 +1,13 @@
-import type { Invocable, KindRef, ResourceContext, ScopeContext, ScopeHandle } from "@telorun/sdk";
+import {
+  InvokeError,
+  isInvokeError,
+  type Invocable,
+  type KindRef,
+  type ResourceContext,
+  type ResourceInstance,
+  type ScopeContext,
+  type ScopeHandle,
+} from "@telorun/sdk";
 
 interface RetryPolicy {
   attempts?: number;
@@ -17,6 +26,10 @@ interface IfStep {
   name: string;
   if: string;
   then: Step[];
+  elseif?: Array<{
+    if: string;
+    then: Step[];
+  }>;
   else?: Step[];
 }
 
@@ -41,7 +54,16 @@ interface TryStep {
   finally?: Step[];
 }
 
-type Step = InvokeStep | IfStep | WhileStep | SwitchStep | TryStep;
+interface ThrowStep {
+  name: string;
+  throw: {
+    code: string;
+    message?: string;
+    data?: unknown;
+  };
+}
+
+type Step = InvokeStep | IfStep | WhileStep | SwitchStep | TryStep | ThrowStep;
 
 interface RunSequenceManifest {
   metadata: Record<string, string | number | boolean>;
@@ -55,6 +77,7 @@ interface RunSequenceManifest {
 interface SequenceError {
   message: string;
   code: string | null;
+  data?: unknown;
   step: string;
 }
 
@@ -73,6 +96,9 @@ function isSwitchStep(step: Step): step is SwitchStep {
 function isTryStep(step: Step): step is TryStep {
   return "try" in step;
 }
+function isThrowStep(step: Step): step is ThrowStep {
+  return "throw" in step;
+}
 
 class RunSequence {
   constructor(
@@ -84,34 +110,47 @@ class RunSequence {
     this.resolveInvokes(this.resource.steps);
   }
 
-  private resolveInvokes(stepList: Step[]): void {
-    for (const step of stepList) {
+  private resolveInvokes(stepList: Step[], path: string[] = ["steps"]): void {
+    for (const [index, step] of stepList.entries()) {
+      const stepPath = [...path, String(index)];
       if (isInvokeStep(step)) {
         const raw = step.invoke as unknown;
         if (!raw || typeof (raw as Invocable).invoke !== "function") {
           (step as InvokeStep).invoke = this.ctx.resolveChildren(
             raw as any,
-            step.name,
+            this.inlineInvokeResourceName(step.name, stepPath),
           ) as KindRef<Invocable>;
         }
       }
       if (isIfStep(step)) {
-        this.resolveInvokes(step.then);
-        if (step.else) this.resolveInvokes(step.else);
+        this.resolveInvokes(step.then, [...stepPath, "then"]);
+        if (step.elseif) {
+          for (const [elseifIndex, branch] of step.elseif.entries()) {
+            this.resolveInvokes(branch.then, [...stepPath, "elseif", String(elseifIndex), "then"]);
+          }
+        }
+        if (step.else) this.resolveInvokes(step.else, [...stepPath, "else"]);
       }
-      if (isWhileStep(step)) this.resolveInvokes(step.do);
+      if (isWhileStep(step)) this.resolveInvokes(step.do, [...stepPath, "do"]);
       if (isSwitchStep(step)) {
-        for (const branch of Object.values(step.cases)) this.resolveInvokes(branch);
-        if (step.default) this.resolveInvokes(step.default);
+        for (const [caseName, branch] of Object.entries(step.cases)) {
+          this.resolveInvokes(branch, [...stepPath, "cases", caseName]);
+        }
+        if (step.default) this.resolveInvokes(step.default, [...stepPath, "default"]);
       }
       if (isTryStep(step)) {
-        this.resolveInvokes(step.try);
-        if (step.catch) this.resolveInvokes(step.catch);
-        if (step.finally) this.resolveInvokes(step.finally);
+        this.resolveInvokes(step.try, [...stepPath, "try"]);
+        if (step.catch) this.resolveInvokes(step.catch, [...stepPath, "catch"]);
+        if (step.finally) this.resolveInvokes(step.finally, [...stepPath, "finally"]);
       }
     }
   }
 
+  private inlineInvokeResourceName(stepName: string, stepPath: string[]): string {
+    const safeName = stepName.replace(/[^a-zA-Z0-9_-]+/g, "_");
+    return `__sequence_${stepPath.join("_")}__${safeName}`;
+  }
+
   async run(): Promise<void> {
     if (this.resource.with) {
       await this.resource.with.run(async (scope) => {
@@ -179,6 +218,7 @@ class RunSequence {
     else if (isWhileStep(step)) await this.executeWhileStep(step, steps, scope, extraCtx);
     else if (isSwitchStep(step)) await this.executeSwitchStep(step, steps, scope, extraCtx);
     else if (isTryStep(step)) await this.executeTryStep(step, steps, scope, extraCtx);
+    else if (isThrowStep(step)) this.executeThrowStep(step, steps, extraCtx);
     else throw new Error(`Step "${(step as Step).name}" has no recognized type key`);
   }
 
@@ -200,7 +240,8 @@ class RunSequence {
     } else {
       const ref = raw as KindRef<Invocable>;
       if (scope) {
-        result = await (scope.getInstance(ref.name) as unknown as Invocable).invoke(inputs);
+        const instance = scope.getInstance(ref.name) as unknown as ResourceInstance;
+        result = await this.ctx.invokeResolved(ref.kind, ref.name, instance, inputs);
       } else {
         result = await this.ctx.invoke(ref.kind, ref.name, inputs, { retry: step.retry });
       }
@@ -217,7 +258,19 @@ class RunSequence {
   ): Promise<void> {
     if (this.ctx.expandValue(step.if, { steps, ...extraCtx })) {
       await this.executeSteps(step.then, steps, scope, extraCtx);
-    } else if (step.else) {
+      return;
+    }
+
+    if (step.elseif) {
+      for (const branch of step.elseif) {
+        if (this.ctx.expandValue(branch.if, { steps, ...extraCtx })) {
+          await this.executeSteps(branch.then, steps, scope, extraCtx);
+          return;
+        }
+      }
+    }
+
+    if (step.else) {
       await this.executeSteps(step.else, steps, scope, extraCtx);
     }
   }
@@ -249,6 +302,32 @@ class RunSequence {
     }
   }
 
+  private executeThrowStep(
+    step: ThrowStep,
+    steps: Record<string, unknown>,
+    extraCtx: Record<string, unknown>,
+  ): never {
+    const cel = { steps, ...extraCtx };
+    const expanded = this.ctx.expandValue(step.throw, cel) as {
+      code: unknown;
+      message?: unknown;
+      data?: unknown;
+    };
+    const code = expanded?.code;
+    if (typeof code !== "string" || code.length === 0) {
+      // Structured error (not plain Error) so the failure stays in the InvokeError
+      // channel and a route's `catches:` list can still map it. The alternative —
+      // a plain Error — would skip catches: entirely and fall through to a 500.
+      throw new InvokeError(
+        "INVALID_THROW_STEP",
+        `Run.Sequence step "${step.name}": throw.code is required and must resolve to a non-empty string`,
+        { step: step.name, code },
+      );
+    }
+    const message = typeof expanded.message === "string" ? expanded.message : code;
+    throw new InvokeError(code, message, expanded.data);
+  }
+
   private async executeTryStep(
     step: TryStep,
     steps: Record<string, unknown>,
@@ -300,12 +379,11 @@ class RunSequence {
 }
 
 function toSequenceError(err: unknown, stepName: string): SequenceError {
+  if (isInvokeError(err)) {
+    return { message: err.message, code: err.code, data: err.data, step: stepName };
+  }
   const message = err instanceof Error ? err.message : String(err);
-  const code =
-    err instanceof Error && (err as Error & { code?: string }).code != null
-      ? (err as Error & { code?: string }).code!
-      : null;
-  return { message, code, step: stepName };
+  return { message, code: null, data: undefined, step: stepName };
 }
 
 export function register(): void {}