@telorun/http-server 0.1.8 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @telorun/http-server
 
+## 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.
+
+### Patch Changes
+
+- Updated dependencies [353d7e5]
+  - @telorun/sdk@0.3.0
+
 ## 0.1.8
 
 ### Patch Changes

package/dist/http-api-controller.d.ts

@@ -1,33 +1,30 @@
 import { Static } from "@sinclair/typebox";
 import { ControllerContext, Invocable, KindRef, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { FastifyInstance, FastifyReply } from "fastify";
-declare const HttpApiRouteManifest: import("@sinclair/typebox").TObject<{
-    request: import("@sinclair/typebox").TObject<{
-        path: import("@sinclair/typebox").TString;
-        method: import("@sinclair/typebox").TString;
-        schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-        }>>;
-    }>;
-    handler: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<KindRef<Invocable<Record<string, any>, any>>>>;
-    inputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>>;
-    response: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
-        status: import("@sinclair/typebox").TInteger;
-        when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
-        mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"buffer">, import("@sinclair/typebox").TLiteral<"stream">]>>;
-        schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-            query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-            headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
-        }>>;
-        headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+declare const ReturnEntry: import("@sinclair/typebox").TObject<{
+    status: import("@sinclair/typebox").TInteger;
+    when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"buffer">, import("@sinclair/typebox").TLiteral<"stream">]>>;
+    schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        query: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
         body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+        headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
     }>>;
+    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
 }>;
-type HttpApiRouteManifest = Static<typeof HttpApiRouteManifest>;
+type ReturnEntry = Static<typeof ReturnEntry>;
+declare const CatchEntry: import("@sinclair/typebox").TObject<{
+    status: import("@sinclair/typebox").TInteger;
+    when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+        headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+    }>>;
+    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+}>;
+type CatchEntry = Static<typeof CatchEntry>;
 declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
     routes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         request: import("@sinclair/typebox").TObject<{
@@ -42,7 +39,7 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
         }>;
         handler: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<KindRef<Invocable<Record<string, any>, any>>>>;
         inputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TAny>>;
-        response: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        returns: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
             status: import("@sinclair/typebox").TInteger;
             when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"buffer">, import("@sinclair/typebox").TLiteral<"stream">]>>;
@@ -54,22 +51,46 @@ declare const HttpApiManifest: import("@sinclair/typebox").TObject<{
             headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
             body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
         }>>;
+        catches: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            status: import("@sinclair/typebox").TInteger;
+            when: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            schema: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+                body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+                headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+            }>>;
+            headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+            body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+        }>>>;
     }>>;
 }>;
 type HttpApiManifest = Static<typeof HttpApiManifest>;
 export declare function register(_ctx: ControllerContext): Promise<void>;
-export type ResponseEntry = Static<(typeof HttpApiRouteManifest)["properties"]["response"]["items"]>;
-export declare function dispatchResponse(response: ResponseEntry[], result: unknown, requestContext: Record<string, unknown>, moduleContext: {
+export type { ReturnEntry, CatchEntry };
+type ModuleLikeContext = {
     expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
-}, validateSchema: (value: unknown, schema: unknown) => void, reply: FastifyReply): Promise<void>;
+};
+type ValidateSchema = (value: unknown, schema: unknown) => void;
+type HandlerRef = {
+    kind: string;
+    name: string;
+};
+export declare function dispatchReturns(returns: ReturnEntry[], result: unknown, requestContext: Record<string, unknown>, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply): Promise<void>;
+/** Render an InvokeError through a `catches:` list. Falls back to a structured
+ *  500 when no entry matches. Plain (non-InvokeError) throws never reach this
+ *  function — the caller re-throws them to Fastify. */
+export declare function dispatchCatches(catches: CatchEntry[] | undefined, error: {
+    code: string;
+    message: string;
+    data?: unknown;
+}, requestContext: Record<string, unknown>, moduleContext: ModuleLikeContext, validateSchema: ValidateSchema, reply: FastifyReply): Promise<void>;
 export declare class HttpServerApi implements ResourceInstance {
     private readonly ctx;
     readonly manifest: HttpApiManifest;
-    constructor(ctx: ResourceContext, manifest: HttpApiManifest);
+    private readonly handlerRefs;
+    constructor(ctx: ResourceContext, manifest: HttpApiManifest, handlerRefs: WeakMap<object, HandlerRef>);
     init(): Promise<void>;
     register(app: FastifyInstance, prefix?: string): void;
     private registerRoutes;
     private registerRoute;
 }
 export declare function create(resource: any, ctx: ResourceContext): Promise<HttpServerApi>;
-export {};

package/dist/http-api-controller.js

@@ -1,6 +1,28 @@
 import { Type } from "@sinclair/typebox";
-import { Ref, } from "@telorun/sdk";
+import { isInvokeError, Ref, } from "@telorun/sdk";
 import { pipeline } from "stream/promises";
+const ReturnEntry = Type.Object({
+    status: Type.Integer({ minimum: 100, maximum: 599 }),
+    when: Type.Optional(Type.String()),
+    mode: Type.Optional(Type.Union([Type.Literal("buffer"), Type.Literal("stream")])),
+    schema: Type.Optional(Type.Object({
+        query: Type.Optional(Type.Any()),
+        body: Type.Optional(Type.Any()),
+        headers: Type.Optional(Type.Any()),
+    })),
+    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+    body: Type.Optional(Type.Any()),
+});
+const CatchEntry = Type.Object({
+    status: Type.Integer({ minimum: 100, maximum: 599 }),
+    when: Type.Optional(Type.String()),
+    schema: Type.Optional(Type.Object({
+        body: Type.Optional(Type.Any()),
+        headers: Type.Optional(Type.Any()),
+    })),
+    headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+    body: Type.Optional(Type.Any()),
+});
 const HttpApiRouteManifest = Type.Object({
     request: Type.Object({
         path: Type.String(),
@@ -12,79 +34,98 @@ const HttpApiRouteManifest = Type.Object({
             headers: Type.Optional(Type.Any()),
         })),
     }),
-    handler: Type.Optional(Type.Unsafe(Ref("kernel#Invocable"))),
+    handler: Type.Optional(Type.Unsafe(Ref("telo#Invocable"))),
     inputs: Type.Optional(Type.Record(Type.String(), Type.Any())),
-    response: Type.Array(Type.Object({
-        status: Type.Integer({ minimum: 100, maximum: 599 }),
-        when: Type.Optional(Type.String()),
-        mode: Type.Optional(Type.Union([Type.Literal("buffer"), Type.Literal("stream")])),
-        schema: Type.Optional(Type.Object({
-            query: Type.Optional(Type.Any()),
-            body: Type.Optional(Type.Any()),
-            headers: Type.Optional(Type.Any()),
-        })),
-        headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-        body: Type.Optional(Type.Any()),
-    })),
+    returns: Type.Array(ReturnEntry),
+    catches: Type.Optional(Type.Array(CatchEntry)),
 });
 const HttpApiManifest = Type.Object({
     routes: Type.Array(HttpApiRouteManifest),
 });
 export async function register(_ctx) { }
-export async function dispatchResponse(response, result, requestContext, moduleContext, validateSchema, reply) {
-    let matched;
+/** Pick the first entry whose `when:` evaluates truthy, falling back to the
+ *  first entry with no `when:` (the list's catch-all). */
+function matchEntry(entries, celCtx, moduleContext) {
     let fallback;
-    for (const entry of response) {
+    for (const entry of entries) {
         if (!entry.when) {
             fallback ??= entry;
             continue;
         }
-        const condition = moduleContext.expandWith(entry.when, { result, ...requestContext });
-        if (condition === true) {
-            matched = entry;
-            break;
-        }
+        if (moduleContext.expandWith(entry.when, celCtx) === true)
+            return entry;
     }
-    const statusEntry = matched ?? fallback;
-    if (!statusEntry) {
-        reply.code(500);
-        reply.send({
-            error: "InternalServerError",
-            message: "No matching response status entry",
-            status: 500,
-        });
-        return;
+    return fallback;
+}
+export async function dispatchReturns(returns, result, requestContext, moduleContext, validateSchema, reply) {
+    const celCtx = { result, ...requestContext };
+    const entry = matchEntry(returns, celCtx, moduleContext);
+    if (!entry) {
+        // Unreachable when the analyzer has run — every route's returns: list must
+        // cover its handler's return values (explicit when: or catch-all). Hitting
+        // this at runtime means something bypassed analysis; surface it loudly
+        // via Fastify's error handler rather than quietly render a 500.
+        throw new Error("No matching returns entry for handler result — the route's returns: list must cover every return value (add a catch-all entry or widen a when: clause)");
     }
-    reply.code(statusEntry.status);
-    if (statusEntry.headers) {
-        const mappedHeaders = moduleContext.expandWith(statusEntry.headers, {
-            result,
-            ...requestContext,
-        });
-        Object.entries(mappedHeaders).forEach(([key, value]) => reply.header(key, value));
+    reply.code(entry.status);
+    if (entry.headers) {
+        const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx);
+        for (const [key, value] of Object.entries(mappedHeaders)) {
+            reply.header(key, value);
+        }
     }
-    if (statusEntry.mode === "stream") {
+    if (entry.mode === "stream") {
         reply.hijack();
-        reply.raw.writeHead(statusEntry.status, reply.getHeaders());
+        reply.raw.writeHead(entry.status, reply.getHeaders());
         await pipeline(result, reply.raw);
         return;
     }
-    if (statusEntry.body !== undefined) {
-        const mappedBody = moduleContext.expandWith(statusEntry.body, { result, ...requestContext });
-        if (statusEntry.schema?.body) {
-            validateSchema(mappedBody, statusEntry.schema.body);
-        }
+    if (entry.body !== undefined) {
+        const mappedBody = moduleContext.expandWith(entry.body, celCtx);
+        if (entry.schema?.body)
+            validateSchema(mappedBody, entry.schema.body);
         reply.send(mappedBody);
         return;
     }
     reply.send(result);
 }
+/** Render an InvokeError through a `catches:` list. Falls back to a structured
+ *  500 when no entry matches. Plain (non-InvokeError) throws never reach this
+ *  function — the caller re-throws them to Fastify. */
+export async function dispatchCatches(catches, error, requestContext, moduleContext, validateSchema, reply) {
+    const celCtx = { error, ...requestContext };
+    const entry = catches ? matchEntry(catches, celCtx, moduleContext) : undefined;
+    if (!entry) {
+        reply.code(500);
+        reply.send({
+            error: { code: error.code, message: error.message, data: error.data },
+        });
+        return;
+    }
+    reply.code(entry.status);
+    if (entry.headers) {
+        const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx);
+        for (const [key, value] of Object.entries(mappedHeaders)) {
+            reply.header(key, value);
+        }
+    }
+    if (entry.body !== undefined) {
+        const mappedBody = moduleContext.expandWith(entry.body, celCtx);
+        if (entry.schema?.body)
+            validateSchema(mappedBody, entry.schema.body);
+        reply.send(mappedBody);
+        return;
+    }
+    reply.send({ error: { code: error.code, message: error.message, data: error.data } });
+}
 export class HttpServerApi {
     ctx;
     manifest;
-    constructor(ctx, manifest) {
+    handlerRefs;
+    constructor(ctx, manifest, handlerRefs) {
         this.ctx = ctx;
         this.manifest = manifest;
+        this.handlerRefs = handlerRefs;
     }
     async init() { }
     register(app, prefix = "") {
@@ -106,68 +147,84 @@ export class HttpServerApi {
     registerRoute(app, route) {
         // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
         const handler = route.handler;
+        const handlerRef = this.handlerRefs.get(route);
+        const handlerKind = handlerRef?.kind ?? "";
+        const handlerName = handlerRef?.name ?? "";
         const translatedPath = translateOpenApiPath(route.request.path);
-        const schema = {
-            response: {},
-        };
-        if (route.request.schema?.query) {
-            schema.querystring = route.request.schema?.query;
-        }
-        if (route.request.schema?.params) {
-            schema.params = route.request.schema?.params;
-        }
-        if (route.request.schema?.body) {
-            schema.body = route.request.schema?.body;
+        const schema = { response: {} };
+        if (route.request.schema?.query)
+            schema.querystring = route.request.schema.query;
+        if (route.request.schema?.params)
+            schema.params = route.request.schema.params;
+        if (route.request.schema?.body)
+            schema.body = route.request.schema.body;
+        if (route.request.schema?.headers)
+            schema.headers = route.request.schema.headers;
+        for (const entry of route.returns) {
+            if (entry.schema?.body)
+                schema.response[entry.status] = entry.schema.body;
+            else if (entry.schema)
+                schema.response[entry.status] = {};
         }
-        if (route.request.schema?.headers) {
-            schema.headers = route.request.schema?.headers;
-        }
-        schema.response = route.response.reduce((acc, entry) => {
-            if (entry.schema?.body) {
-                acc[entry.status] = entry.schema.body;
-            }
-            else if (entry.schema) {
-                acc[entry.status] = {};
-            }
-            return acc;
-        }, {});
         app.route({
             method: route.request.method,
             url: translatedPath,
             schema,
             handler: async (request, reply) => {
+                const requestContext = {
+                    request: {
+                        method: request.method,
+                        path: request.url,
+                        params: request.params || {},
+                        query: request.query || {},
+                        headers: normalizeHeaders(request.headers),
+                        body: request.body,
+                    },
+                };
+                const resolvedInputs = route.inputs
+                    ? (this.ctx.moduleContext.expandWith(route.inputs, requestContext) ?? {})
+                    : requestContext;
+                const invokeInput = {
+                    ...resolvedInputs,
+                    inputs: resolvedInputs,
+                };
+                let result;
                 try {
-                    const requestContext = {
-                        request: {
-                            method: request.method,
-                            path: request.url,
-                            params: request.params || {},
-                            query: request.query || {},
-                            headers: normalizeHeaders(request.headers),
-                            body: request.body,
-                        },
-                    };
-                    const resolvedInputs = route.inputs
-                        ? (this.ctx.moduleContext.expandWith(route.inputs, requestContext) ?? {})
-                        : requestContext;
-                    const invokeInput = {
-                        ...resolvedInputs,
-                        inputs: resolvedInputs,
-                    };
-                    const result = handler ? await handler.invoke(invokeInput) : undefined;
-                    return dispatchResponse(route.response, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                    result = handler
+                        ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput)
+                        : undefined;
                 }
-                catch (error) {
-                    // Let the error handler deal with all errors
-                    throw error;
+                catch (err) {
+                    if (!isInvokeError(err))
+                        throw err;
+                    return dispatchCatches(route.catches, { code: err.code, message: err.message, data: err.data }, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
                 }
+                return dispatchReturns(route.returns, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
             },
         });
     }
 }
 export async function create(resource, ctx) {
     ctx.validateSchema(resource, HttpApiManifest);
-    return new HttpServerApi(ctx, resource);
+    // Capture handler {kind, name} before Phase 5 injection overwrites the ref
+    // with a live Invocable instance. invokeResolved() needs the kind/name to
+    // emit properly-scoped Invoked / InvokeRejected events.
+    const handlerRefs = new WeakMap();
+    for (const route of resource.routes ?? []) {
+        const h = route.handler;
+        if (!h)
+            continue;
+        if (typeof h === "object") {
+            handlerRefs.set(route, ctx.resolveChildren(h));
+        }
+        else if (typeof h === "string") {
+            // String form (schema oneOf: string | object) — only the resource name
+            // is given, not the kind. Phase 5 injects the live instance either way;
+            // invoke events on this route just emit with an empty kind.
+            handlerRefs.set(route, { kind: "", name: h });
+        }
+    }
+    return new HttpServerApi(ctx, resource, handlerRefs);
 }
 /**
  * Translates OpenAPI path format {paramName} to Fastify format :paramName

package/dist/http-server-controller.d.ts

@@ -1,5 +1,5 @@
-import type { Invocable, KindRef, ResourceContext, ResourceInstance, RuntimeResource } from "@telorun/sdk";
-import { ResponseEntry } from "./http-api-controller.js";
+import { type Invocable, type KindRef, type ResourceContext, type ResourceInstance, type RuntimeResource } from "@telorun/sdk";
+import { CatchEntry, ReturnEntry } from "./http-api-controller.js";
 type CorsOptions = {
     origin?: string | boolean | string[];
     methods?: string | string[];
@@ -36,7 +36,8 @@ type HttpServerResource = RuntimeResource & {
     }>;
     notFoundHandler?: {
         invoke: KindRef<Invocable>;
-        response?: ResponseEntry[];
+        returns?: ReturnEntry[];
+        catches?: CatchEntry[];
     };
 };
 export declare function create(resource: HttpServerResource, ctx: ResourceContext): Promise<ResourceInstance | null>;

package/dist/http-server-controller.js

@@ -1,9 +1,10 @@
 import cors from "@fastify/cors";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
+import { isInvokeError, } from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify from "fastify";
-import { dispatchResponse } from "./http-api-controller.js";
+import { dispatchCatches, dispatchReturns, } from "./http-api-controller.js";
 class HttpServer {
     releaseHold = null;
     pluginsInitialized = false;
@@ -111,7 +112,7 @@ class HttpServer {
             const type = mount.type || "";
             const { kind, name } = parseType(type);
             const prefix = mount.path || "";
-            const api = this.ctx.moduleContext.getInvocable(name);
+            const api = this.ctx.moduleContext.getInstance(name);
             if (!api) {
                 throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
             }
@@ -134,9 +135,17 @@ class HttpServer {
                         body: request.body,
                     },
                 };
-                const result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
-                if (handler.response) {
-                    return dispatchResponse(handler.response, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                let result;
+                try {
+                    result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
+                }
+                catch (err) {
+                    if (!isInvokeError(err))
+                        throw err;
+                    return dispatchCatches(handler.catches, { code: err.code, message: err.message, data: err.data }, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
+                }
+                if (handler.returns) {
+                    return dispatchReturns(handler.returns, result, requestContext, this.ctx.moduleContext, this.ctx.validateSchema.bind(this.ctx), reply);
                 }
                 const status = result?.status ?? 200;
                 reply.code(status);
@@ -179,12 +188,24 @@ class HttpServer {
 export async function create(resource, ctx) {
     let resolvedNotFoundHandler = null;
     if (resource.notFoundHandler) {
-        const resolved = ctx.resolveChildren(resource.notFoundHandler.invoke);
+        const invoke = resource.notFoundHandler.invoke;
+        let kind = "";
+        let name = "";
+        if (typeof invoke === "object" && invoke !== null) {
+            const resolved = ctx.resolveChildren(invoke);
+            kind = resolved.kind;
+            name = resolved.name;
+        }
+        else if (typeof invoke === "string") {
+            // String form (schema oneOf: string | object) — resource name only.
+            name = invoke;
+        }
         resolvedNotFoundHandler = {
-            kind: resolved.kind,
-            name: resolved.name,
-            inputs: resource.notFoundHandler.invoke.inputs ?? {},
-            response: resource.notFoundHandler.response,
+            kind,
+            name,
+            inputs: invoke?.inputs ?? {},
+            returns: resource.notFoundHandler.returns,
+            catches: resource.notFoundHandler.catches,
         };
     }
     return new HttpServer(resource, ctx, resolvedNotFoundHandler);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/http-server",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Telo HTTP Server module - HTTP server and API resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,7 +43,7 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "fastify": "^5.7.2",
-    "@telorun/sdk": "0.2.8"
+    "@telorun/sdk": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/http-api-controller.ts

@@ -2,6 +2,7 @@ import { Static, Type } from "@sinclair/typebox";
 import {
   ControllerContext,
   Invocable,
+  isInvokeError,
   KindRef,
   Ref,
   ResourceContext,
@@ -11,6 +12,36 @@ import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { type Readable } from "stream";
 import { pipeline } from "stream/promises";
 
+const ReturnEntry = Type.Object({
+  status: Type.Integer({ minimum: 100, maximum: 599 }),
+  when: Type.Optional(Type.String()),
+  mode: Type.Optional(Type.Union([Type.Literal("buffer"), Type.Literal("stream")])),
+  schema: Type.Optional(
+    Type.Object({
+      query: Type.Optional(Type.Any()),
+      body: Type.Optional(Type.Any()),
+      headers: Type.Optional(Type.Any()),
+    }),
+  ),
+  headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+  body: Type.Optional(Type.Any()),
+});
+type ReturnEntry = Static<typeof ReturnEntry>;
+
+const CatchEntry = Type.Object({
+  status: Type.Integer({ minimum: 100, maximum: 599 }),
+  when: Type.Optional(Type.String()),
+  schema: Type.Optional(
+    Type.Object({
+      body: Type.Optional(Type.Any()),
+      headers: Type.Optional(Type.Any()),
+    }),
+  ),
+  headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+  body: Type.Optional(Type.Any()),
+});
+type CatchEntry = Static<typeof CatchEntry>;
+
 const HttpApiRouteManifest = Type.Object({
   request: Type.Object({
     path: Type.String(),
@@ -24,24 +55,10 @@ const HttpApiRouteManifest = Type.Object({
       }),
     ),
   }),
-  handler: Type.Optional(Type.Unsafe<KindRef<Invocable>>(Ref("kernel#Invocable"))),
+  handler: Type.Optional(Type.Unsafe<KindRef<Invocable>>(Ref("telo#Invocable"))),
   inputs: Type.Optional(Type.Record(Type.String(), Type.Any())),
-  response: Type.Array(
-    Type.Object({
-      status: Type.Integer({ minimum: 100, maximum: 599 }),
-      when: Type.Optional(Type.String()),
-      mode: Type.Optional(Type.Union([Type.Literal("buffer"), Type.Literal("stream")])),
-      schema: Type.Optional(
-        Type.Object({
-          query: Type.Optional(Type.Any()),
-          body: Type.Optional(Type.Any()),
-          headers: Type.Optional(Type.Any()),
-        }),
-      ),
-      headers: Type.Optional(Type.Record(Type.String(), Type.String())),
-      body: Type.Optional(Type.Any()),
-    }),
-  ),
+  returns: Type.Array(ReturnEntry),
+  catches: Type.Optional(Type.Array(CatchEntry)),
 });
 type HttpApiRouteManifest = Static<typeof HttpApiRouteManifest>;
 
@@ -52,66 +69,77 @@ type HttpApiManifest = Static<typeof HttpApiManifest>;
 
 export async function register(_ctx: ControllerContext): Promise<void> {}
 
-export type ResponseEntry = Static<
-  (typeof HttpApiRouteManifest)["properties"]["response"]["items"]
->;
+export type { ReturnEntry, CatchEntry };
 
-export async function dispatchResponse(
-  response: ResponseEntry[],
-  result: unknown,
-  requestContext: Record<string, unknown>,
-  moduleContext: { expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown },
-  validateSchema: (value: unknown, schema: unknown) => void,
-  reply: FastifyReply,
-): Promise<void> {
-  let matched: ResponseEntry | undefined;
-  let fallback: ResponseEntry | undefined;
+type ModuleLikeContext = {
+  expandWith: (v: unknown, ctx: Record<string, unknown>) => unknown;
+};
+
+type ValidateSchema = (value: unknown, schema: unknown) => void;
+
+type HandlerRef = { kind: string; name: string };
 
-  for (const entry of response) {
+/** Pick the first entry whose `when:` evaluates truthy, falling back to the
+ *  first entry with no `when:` (the list's catch-all). */
+function matchEntry<T extends { when?: string }>(
+  entries: T[],
+  celCtx: Record<string, unknown>,
+  moduleContext: ModuleLikeContext,
+): T | undefined {
+  let fallback: T | undefined;
+  for (const entry of entries) {
     if (!entry.when) {
       fallback ??= entry;
       continue;
     }
-    const condition = moduleContext.expandWith(entry.when, { result, ...requestContext });
-    if (condition === true) {
-      matched = entry;
-      break;
-    }
+    if (moduleContext.expandWith(entry.when, celCtx) === true) return entry;
   }
+  return fallback;
+}
 
-  const statusEntry = matched ?? fallback;
-  if (!statusEntry) {
-    reply.code(500);
-    reply.send({
-      error: "InternalServerError",
-      message: "No matching response status entry",
-      status: 500,
-    });
-    return;
+export async function dispatchReturns(
+  returns: ReturnEntry[],
+  result: unknown,
+  requestContext: Record<string, unknown>,
+  moduleContext: ModuleLikeContext,
+  validateSchema: ValidateSchema,
+  reply: FastifyReply,
+): Promise<void> {
+  const celCtx = { result, ...requestContext };
+  const entry = matchEntry(returns, celCtx, moduleContext);
+
+  if (!entry) {
+    // Unreachable when the analyzer has run — every route's returns: list must
+    // cover its handler's return values (explicit when: or catch-all). Hitting
+    // this at runtime means something bypassed analysis; surface it loudly
+    // via Fastify's error handler rather than quietly render a 500.
+    throw new Error(
+      "No matching returns entry for handler result — the route's returns: list must cover every return value (add a catch-all entry or widen a when: clause)",
+    );
   }
 
-  reply.code(statusEntry.status);
+  reply.code(entry.status);
 
-  if (statusEntry.headers) {
-    const mappedHeaders = moduleContext.expandWith(statusEntry.headers, {
-      result,
-      ...requestContext,
-    }) as Record<string, unknown>;
-    Object.entries(mappedHeaders).forEach(([key, value]) => reply.header(key, value as string));
+  if (entry.headers) {
+    const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx) as Record<
+      string,
+      unknown
+    >;
+    for (const [key, value] of Object.entries(mappedHeaders)) {
+      reply.header(key, value as string);
+    }
   }
 
-  if (statusEntry.mode === "stream") {
+  if (entry.mode === "stream") {
     reply.hijack();
-    reply.raw.writeHead(statusEntry.status, reply.getHeaders() as Record<string, string>);
+    reply.raw.writeHead(entry.status, reply.getHeaders() as Record<string, string>);
     await pipeline(result as Readable, reply.raw);
     return;
   }
 
-  if (statusEntry.body !== undefined) {
-    const mappedBody = moduleContext.expandWith(statusEntry.body, { result, ...requestContext });
-    if (statusEntry.schema?.body) {
-      validateSchema(mappedBody, statusEntry.schema.body);
-    }
+  if (entry.body !== undefined) {
+    const mappedBody = moduleContext.expandWith(entry.body, celCtx);
+    if (entry.schema?.body) validateSchema(mappedBody, entry.schema.body);
     reply.send(mappedBody);
     return;
   }
@@ -119,10 +147,55 @@ export async function dispatchResponse(
   reply.send(result);
 }
 
+/** Render an InvokeError through a `catches:` list. Falls back to a structured
+ *  500 when no entry matches. Plain (non-InvokeError) throws never reach this
+ *  function — the caller re-throws them to Fastify. */
+export async function dispatchCatches(
+  catches: CatchEntry[] | undefined,
+  error: { code: string; message: string; data?: unknown },
+  requestContext: Record<string, unknown>,
+  moduleContext: ModuleLikeContext,
+  validateSchema: ValidateSchema,
+  reply: FastifyReply,
+): Promise<void> {
+  const celCtx = { error, ...requestContext };
+  const entry = catches ? matchEntry(catches, celCtx, moduleContext) : undefined;
+
+  if (!entry) {
+    reply.code(500);
+    reply.send({
+      error: { code: error.code, message: error.message, data: error.data },
+    });
+    return;
+  }
+
+  reply.code(entry.status);
+
+  if (entry.headers) {
+    const mappedHeaders = moduleContext.expandWith(entry.headers, celCtx) as Record<
+      string,
+      unknown
+    >;
+    for (const [key, value] of Object.entries(mappedHeaders)) {
+      reply.header(key, value as string);
+    }
+  }
+
+  if (entry.body !== undefined) {
+    const mappedBody = moduleContext.expandWith(entry.body, celCtx);
+    if (entry.schema?.body) validateSchema(mappedBody, entry.schema.body);
+    reply.send(mappedBody);
+    return;
+  }
+
+  reply.send({ error: { code: error.code, message: error.message, data: error.data } });
+}
+
 export class HttpServerApi implements ResourceInstance {
   constructor(
     private readonly ctx: ResourceContext,
     readonly manifest: HttpApiManifest,
+    private readonly handlerRefs: WeakMap<object, HandlerRef>,
   ) {}
 
   async init() {}
@@ -149,75 +222,72 @@ export class HttpServerApi implements ResourceInstance {
 
   private registerRoute(app: FastifyInstance, route: HttpApiRouteManifest) {
     // After Phase 5 injection, KindRef<Invocable> is replaced with the live Invocable instance.
-    const handler = route.handler as unknown as Invocable | undefined;
+    const handler = route.handler as unknown as ResourceInstance | undefined;
+    const handlerRef = this.handlerRefs.get(route as unknown as object);
+    const handlerKind = handlerRef?.kind ?? "";
+    const handlerName = handlerRef?.name ?? "";
     const translatedPath = translateOpenApiPath(route.request.path);
 
-    const schema: any = {
-      response: {},
-    };
+    const schema: any = { response: {} };
 
-    if (route.request.schema?.query) {
-      schema.querystring = route.request.schema?.query;
-    }
-    if (route.request.schema?.params) {
-      schema.params = route.request.schema?.params;
-    }
-    if (route.request.schema?.body) {
-      schema.body = route.request.schema?.body;
-    }
-    if (route.request.schema?.headers) {
-      schema.headers = route.request.schema?.headers;
-    }
+    if (route.request.schema?.query) schema.querystring = route.request.schema.query;
+    if (route.request.schema?.params) schema.params = route.request.schema.params;
+    if (route.request.schema?.body) schema.body = route.request.schema.body;
+    if (route.request.schema?.headers) schema.headers = route.request.schema.headers;
 
-    schema.response = route.response.reduce(
-      (acc, entry) => {
-        if (entry.schema?.body) {
-          acc[entry.status] = entry.schema.body;
-        } else if (entry.schema) {
-          acc[entry.status] = {};
-        }
-        return acc;
-      },
-      {} as Record<number, any>,
-    );
+    for (const entry of route.returns) {
+      if (entry.schema?.body) schema.response[entry.status] = entry.schema.body;
+      else if (entry.schema) schema.response[entry.status] = {};
+    }
 
     app.route({
       method: route.request.method as any,
       url: translatedPath,
       schema,
       handler: async (request: FastifyRequest, reply: FastifyReply) => {
+        const requestContext = {
+          request: {
+            method: request.method,
+            path: request.url,
+            params: request.params || {},
+            query: request.query || {},
+            headers: normalizeHeaders(request.headers),
+            body: request.body,
+          },
+        };
+        const resolvedInputs: Record<string, any> = route.inputs
+          ? ((this.ctx.moduleContext.expandWith(route.inputs, requestContext) as any) ?? {})
+          : requestContext;
+        const invokeInput: Record<string, any> = {
+          ...resolvedInputs,
+          inputs: resolvedInputs,
+        };
+
+        let result: unknown;
         try {
-          const requestContext = {
-            request: {
-              method: request.method,
-              path: request.url,
-              params: request.params || {},
-              query: request.query || {},
-              headers: normalizeHeaders(request.headers),
-              body: request.body,
-            },
-          };
-          const resolvedInputs: Record<string, any> = route.inputs
-            ? ((this.ctx.moduleContext.expandWith(route.inputs, requestContext) as any) ?? {})
-            : requestContext;
-          const invokeInput: Record<string, any> = {
-            ...resolvedInputs,
-            inputs: resolvedInputs,
-          };
-          const result = handler ? await handler.invoke(invokeInput) : undefined;
-
-          return dispatchResponse(
-            route.response,
-            result,
+          result = handler
+            ? await this.ctx.invokeResolved(handlerKind, handlerName, handler, invokeInput)
+            : undefined;
+        } catch (err) {
+          if (!isInvokeError(err)) throw err;
+          return dispatchCatches(
+            route.catches,
+            { code: err.code, message: err.message, data: err.data },
             requestContext,
             this.ctx.moduleContext,
             this.ctx.validateSchema.bind(this.ctx),
             reply,
           );
-        } catch (error) {
-          // Let the error handler deal with all errors
-          throw error;
         }
+
+        return dispatchReturns(
+          route.returns,
+          result,
+          requestContext,
+          this.ctx.moduleContext,
+          this.ctx.validateSchema.bind(this.ctx),
+          reply,
+        );
       },
     });
   }
@@ -225,7 +295,23 @@ export class HttpServerApi implements ResourceInstance {
 
 export async function create(resource: any, ctx: ResourceContext): Promise<HttpServerApi> {
   ctx.validateSchema(resource, HttpApiManifest);
-  return new HttpServerApi(ctx, resource);
+  // Capture handler {kind, name} before Phase 5 injection overwrites the ref
+  // with a live Invocable instance. invokeResolved() needs the kind/name to
+  // emit properly-scoped Invoked / InvokeRejected events.
+  const handlerRefs = new WeakMap<object, HandlerRef>();
+  for (const route of resource.routes ?? []) {
+    const h = route.handler;
+    if (!h) continue;
+    if (typeof h === "object") {
+      handlerRefs.set(route, ctx.resolveChildren(h));
+    } else if (typeof h === "string") {
+      // String form (schema oneOf: string | object) — only the resource name
+      // is given, not the kind. Phase 5 injects the live instance either way;
+      // invoke events on this route just emit with an empty kind.
+      handlerRefs.set(route, { kind: "", name: h });
+    }
+  }
+  return new HttpServerApi(ctx, resource, handlerRefs);
 }
 
 /**

package/src/http-server-controller.ts

@@ -1,16 +1,23 @@
 import cors from "@fastify/cors";
 import swagger from "@fastify/swagger";
 import apiReference from "@scalar/fastify-api-reference";
-import type {
-  Invocable,
-  KindRef,
-  ResourceContext,
-  ResourceInstance,
-  RuntimeResource,
+import {
+  isInvokeError,
+  type Invocable,
+  type KindRef,
+  type ResourceContext,
+  type ResourceInstance,
+  type RuntimeResource,
 } from "@telorun/sdk";
 import addFormats from "ajv-formats";
 import Fastify, { FastifyInstance } from "fastify";
-import { dispatchResponse, HttpServerApi, ResponseEntry } from "./http-api-controller.js";
+import {
+  CatchEntry,
+  dispatchCatches,
+  dispatchReturns,
+  HttpServerApi,
+  ReturnEntry,
+} from "./http-api-controller.js";
 
 type CorsOptions = {
   origin?: string | boolean | string[];
@@ -46,7 +53,8 @@ type HttpServerResource = RuntimeResource & {
   }>;
   notFoundHandler?: {
     invoke: KindRef<Invocable>;
-    response?: ResponseEntry[];
+    returns?: ReturnEntry[];
+    catches?: CatchEntry[];
   };
 };
 
@@ -54,7 +62,8 @@ type ResolvedHandler = {
   kind: string;
   name: string;
   inputs: Record<string, any>;
-  response?: ResponseEntry[];
+  returns?: ReturnEntry[];
+  catches?: CatchEntry[];
 };
 
 class HttpServer implements ResourceInstance {
@@ -178,7 +187,7 @@ class HttpServer implements ResourceInstance {
       const { kind, name } = parseType(type);
       const prefix = mount.path || "";
 
-      const api = this.ctx.moduleContext.getInvocable(name) as unknown as HttpServerApi;
+      const api = this.ctx.moduleContext.getInstance(name) as unknown as HttpServerApi;
 
       if (!api) {
         throw new Error(`Failed to mount Http.Api at "${prefix}": ${type} not found`);
@@ -203,10 +212,25 @@ class HttpServer implements ResourceInstance {
             body: request.body,
           },
         };
-        const result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
-        if (handler.response) {
-          return dispatchResponse(
-            handler.response,
+
+        let result: any;
+        try {
+          result = await this.ctx.invoke(handler.kind, handler.name, requestContext);
+        } catch (err) {
+          if (!isInvokeError(err)) throw err;
+          return dispatchCatches(
+            handler.catches,
+            { code: err.code, message: err.message, data: err.data },
+            requestContext,
+            this.ctx.moduleContext,
+            this.ctx.validateSchema.bind(this.ctx),
+            reply,
+          );
+        }
+
+        if (handler.returns) {
+          return dispatchReturns(
+            handler.returns,
             result,
             requestContext,
             this.ctx.moduleContext,
@@ -262,12 +286,23 @@ export async function create(
 ): Promise<ResourceInstance | null> {
   let resolvedNotFoundHandler: ResolvedHandler | null = null;
   if (resource.notFoundHandler) {
-    const resolved = ctx.resolveChildren(resource.notFoundHandler.invoke);
+    const invoke = resource.notFoundHandler.invoke as unknown;
+    let kind = "";
+    let name = "";
+    if (typeof invoke === "object" && invoke !== null) {
+      const resolved = ctx.resolveChildren(invoke);
+      kind = resolved.kind;
+      name = resolved.name;
+    } else if (typeof invoke === "string") {
+      // String form (schema oneOf: string | object) — resource name only.
+      name = invoke;
+    }
     resolvedNotFoundHandler = {
-      kind: resolved.kind,
-      name: resolved.name,
-      inputs: (resource.notFoundHandler.invoke as any).inputs ?? {},
-      response: resource.notFoundHandler.response,
+      kind,
+      name,
+      inputs: (invoke as any)?.inputs ?? {},
+      returns: resource.notFoundHandler.returns,
+      catches: resource.notFoundHandler.catches,
     };
   }
   return new HttpServer(resource, ctx, resolvedNotFoundHandler);