@telorun/run 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @telorun/run
 
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [3c4ac58]
+  - @telorun/sdk@0.3.2
+
+## 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

package/README.md

@@ -34,7 +34,7 @@ Manifests also support directives for dynamic generation: `$let`, `$if`, `$for`,
 Here is an example Telo application that defines a simple HTTP API:
 
 ```yaml
-kind: Kernel.Module
+kind: Telo.Application
 metadata:
   name: feedback
   version: 1.0.0
@@ -45,12 +45,12 @@ targets:
   - Migrations
   - Server
 ---
-kind: Kernel.Import
+kind: Telo.Import
 metadata:
   name: Http
 source: ../modules/http-server
 ---
-kind: Kernel.Import
+kind: Telo.Import
 metadata:
   name: Sql
 source: ../modules/sql

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;
@@ -38,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;
@@ -64,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;
@@ -120,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`);
     }
@@ -136,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 });
@@ -178,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;
@@ -225,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,6 @@
 {
   "name": "@telorun/run",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Telo Run module - Sequence execution for Telo manifests.",
   "keywords": [
     "telo",
@@ -29,7 +29,7 @@
     }
   },
   "dependencies": {
-    "@telorun/sdk": "0.2.8"
+    "@telorun/sdk": "0.3.2"
   },
   "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;
@@ -45,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>;
@@ -59,6 +77,7 @@ interface RunSequenceManifest {
 interface SequenceError {
   message: string;
   code: string | null;
+  data?: unknown;
   step: string;
 }
 
@@ -77,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(
@@ -196,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`);
   }
 
@@ -217,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 });
       }
@@ -278,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>,
@@ -329,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 {}