@velajs/vela 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.19.0 (2026-07-11)
+
+Exception-handler layer (roadmap phase 3): a single branded error concept, one
+wire-redaction seam, and a Laravel-style reporting contract layered above the
+NestJS-style exception filters. Design spec:
+`docs/superpowers/specs/2026-07-11-errors-package-and-exception-layer-design.md`.
+
+### Added
+
+- **`@velajs/errors` dependency** — the new sibling package vela now builds on:
+  the branded `VelaError` (own+enumerable fields so it rides any wire codec /
+  `structuredClone` / DO-RPC prop copy), error catalogs
+  (`defineErrorCatalog`/`composeCatalogs`/`CORE_CATALOG`), and the single
+  `toErrorBody` wire-redaction seam (unbranded or `internal`-coded errors never
+  echo their message). Its core surface is re-exported from `@velajs/vela` so
+  app authors need one import to throw branded errors, author handlers, and
+  define/compose catalogs.
+- **`ExceptionHandler` contract + `resolveErrorReporter`** — an optional
+  application-wide handler (`report` / `dontReport` / `context` / `render`)
+  consulted at every transport edge (HTTP, WS, live, queue, schedule). Reporting
+  is fire-and-forget and fully contained: a broken or throwing handler (or
+  `dontReport` matcher) can never mask the original error.
+- **`APP_EXCEPTION_HANDLER` / `ERROR_CATALOG` tokens** — provide the handler and
+  the composed catalog via module providers.
+- **`ErrorsModule.forRoot({ catalogs?, handler? })`** — composes
+  `[CORE_CATALOG, ...catalogs]` (eager; a duplicate code across catalogs fails
+  fast with `duplicate error code`) into `ERROR_CATALOG`, and — when given —
+  registers `APP_EXCEPTION_HANDLER` (`useClass` for a handler class, `useValue`
+  for a handler object).
+- **`app.useGlobalExceptionHandler(handler)`** — the imperative sibling of
+  `ErrorsModule.forRoot({ handler })`; registers `APP_EXCEPTION_HANDLER` on the
+  root container, taking effect on the next request without a rebuild.
+
+### Changed
+
+- **BREAKING (sanctioned wire break): the HTTP error body is now the canonical
+  error object.** Uncaught controller/handler errors render as
+  `{ error: { code, message, hint?, docsUrl?, details? } }` with the code's
+  catalog status, replacing the prior `{ statusCode, message }` shape.
+  `HttpException` object responses still ship verbatim (crud-envelope compat).
+  Error reporting is now **report-first**: the reporter runs before any
+  exception filter, so a filter claiming an error can no longer make it
+  invisible to logging/Sentry. A new `app.onError` fallback funnels raw
+  hono-middleware throws (which previously bypassed the filter tier entirely)
+  through the same report + redaction path; hono's own `HTTPException`
+  responses are still honored verbatim. Per the compat policy, shipped under a
+  minor with no deprecation shim.
+
+### Fixed
+
+- **Live engine raw-message leak** — initial-subscribe resolver errors were sent
+  to the browser as raw `err.message` (`src/live/live.engine.ts`); they now flow
+  through `toErrorBody`, so unbranded/internal errors are redacted like every
+  other edge. The WS exception frame and the report-then-rethrow queue/schedule
+  dispatch paths were aligned to the same report-first + redacted-body invariant.
+
 ## 1.15.0 (2026-07-04)
 
 Introspection seams for `@velajs/cli` (roadmap phase 3, CLI introspection):

package/dist/application.d.ts

@@ -1,6 +1,7 @@
 import type { Hono } from 'hono';
 import type { Container } from './container/container';
-import type { Token } from './container/types';
+import type { Token, Type } from './container/types';
+import type { ExceptionHandler } from './exceptions/exception-handler';
 import { EntrypointRegistry } from './entrypoint/entrypoint.registry';
 import type { RouteDescription, RouteManager } from './http/route.manager';
 import type { MountOpenApiOptions } from './openapi/types';
@@ -38,6 +39,18 @@ export declare class VelaApplication {
     useGlobalGuards(...guards: GuardType[]): this;
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;
     useGlobalFilters(...filters: FilterType[]): this;
+    /**
+     * Register the application-wide {@link ExceptionHandler} imperatively — the
+     * sibling of `ErrorsModule.forRoot({ handler })`. A class is constructed
+     * through DI (`useClass`); a plain handler object is registered verbatim
+     * (`useValue`). Consumed by `resolveErrorReporter` at every transport edge,
+     * so it takes effect on the next request without a rebuild.
+     *
+     * ```ts
+     * app.useGlobalExceptionHandler({ report: (e) => sentry.capture(e) });
+     * ```
+     */
+    useGlobalExceptionHandler(handler: Type<ExceptionHandler> | ExceptionHandler): this;
     /**
      * Serve a pre-built OpenAPI document and one or more interactive doc UIs
      * (Swagger UI, Scalar, ReDoc) on the underlying Hono app, mirroring the

package/dist/application.js

@@ -1,3 +1,7 @@
+import { HTTPException } from "hono/http-exception";
+import { toErrorBody } from "@velajs/errors";
+import { APP_EXCEPTION_HANDLER } from "./pipeline/tokens.js";
+import { resolveErrorReporter } from "./exceptions/reporter.js";
 import { DiscoveryService } from "./discovery/discovery.service.js";
 import { EntrypointRegistry } from "./entrypoint/entrypoint.registry.js";
 import { LazyModuleManager } from "./module/lazy-modules.js";
@@ -36,6 +40,38 @@ export class VelaApplication {
     }
     /** Pre-build routes (handles async CRUD imports). Called by VelaFactory. */ async initRoutes() {
         this.honoApp = await this.routeManager.build();
+        // Last line of defense for the HTTP edge. HandlerExecutor's catch tail
+        // only sees controller-handler errors; a raw Hono middleware (or any
+        // hono-level throw that bypasses route.manager's wrapMiddlewareWithFilters)
+        // would otherwise reach Hono's default error handler unreported and
+        // unredacted. `onError` funnels it through the same report-first + canonical
+        // redacted body path every other edge uses.
+        this.honoApp.onError((err, c)=>{
+            const reporter = resolveErrorReporter(this.container);
+            // Hono's own HTTPException (e.g. `bodyLimit`'s 413) carries a deliberate,
+            // author-intended client response — honor it exactly as Hono's default
+            // error handler would, without treating it as a server fault to redact.
+            // But a 5xx HTTPException is still a server fault: every other edge reports
+            // before returning, so report status>=500 here too (leaving the verbatim
+            // response — and its redaction/status — untouched).
+            if (err instanceof HTTPException) {
+                if (err.status >= 500) {
+                    reporter.report(err, {
+                        edge: 'hono',
+                        source: `${c.req.method} ${c.req.path}`
+                    });
+                }
+                return err.getResponse();
+            }
+            reporter.report(err, {
+                edge: 'hono',
+                source: `${c.req.method} ${c.req.path}`
+            });
+            const { body, status } = toErrorBody(err, {
+                catalog: reporter.catalog
+            });
+            return c.json(body, status);
+        });
     }
     getApp() {
         if (!this.honoApp) {
@@ -93,6 +129,26 @@ export class VelaApplication {
         return this;
     }
     /**
+   * Register the application-wide {@link ExceptionHandler} imperatively — the
+   * sibling of `ErrorsModule.forRoot({ handler })`. A class is constructed
+   * through DI (`useClass`); a plain handler object is registered verbatim
+   * (`useValue`). Consumed by `resolveErrorReporter` at every transport edge,
+   * so it takes effect on the next request without a rebuild.
+   *
+   * ```ts
+   * app.useGlobalExceptionHandler({ report: (e) => sentry.capture(e) });
+   * ```
+   */ useGlobalExceptionHandler(handler) {
+        this.container.register(typeof handler === 'function' ? {
+            provide: APP_EXCEPTION_HANDLER,
+            useClass: handler
+        } : {
+            provide: APP_EXCEPTION_HANDLER,
+            useValue: handler
+        });
+        return this;
+    }
+    /**
    * Serve a pre-built OpenAPI document and one or more interactive doc UIs
    * (Swagger UI, Scalar, ReDoc) on the underlying Hono app, mirroring the
    * hono-crud docs convention. Edge-safe: each UI is a tiny self-contained

package/dist/errors/http-exception.d.ts

@@ -5,6 +5,7 @@ export declare class HttpException extends Error {
     constructor(response: ExceptionResponse, statusCode: number);
     getStatus(): number;
     getResponse(): Record<string, unknown>;
+    getRawResponse(): ExceptionResponse;
 }
 export declare class BadRequestException extends HttpException {
     constructor(message?: ExceptionResponse);

package/dist/errors/http-exception.js

@@ -21,6 +21,14 @@ export class HttpException extends Error {
         }
         return this._response;
     }
+    // The constructor's original argument, untransformed — a string message or a
+    // caller-supplied object. The canonical HTTP edge branches on this: string
+    // responses become `{ error: { code, message } }`, object responses ship
+    // verbatim (crud envelope compat). Distinct from `getResponse()`, which wraps
+    // strings in the legacy `{ statusCode, message }` shape.
+    getRawResponse() {
+        return this._response;
+    }
 }
 // 4xx
 export class BadRequestException extends HttpException {

package/dist/exceptions/errors.module.d.ts

@@ -0,0 +1,40 @@
+import { type Catalog } from '@velajs/errors';
+import type { Type } from '../container/types';
+import type { ExceptionHandler } from './exception-handler';
+/**
+ * Options for {@link ErrorsModule.forRoot}. Both fields are optional — an empty
+ * `forRoot()` provides just the core catalog (`CORE_CATALOG`) and no custom
+ * handler, which is the framework default anyway.
+ */
+export interface ErrorsModuleOptions {
+    /**
+     * App-specific catalogs composed **onto** `CORE_CATALOG` via
+     * {@link composeCatalogs}. Composition is eager (at `forRoot` call time), so a
+     * duplicate code across two catalogs fails fast with `duplicate error code`.
+     */
+    catalogs?: Catalog<string>[];
+    /**
+     * The application-wide {@link ExceptionHandler}. A class is wired with
+     * `useClass` (constructed through DI); a plain handler object with `useValue`.
+     */
+    handler?: Type<ExceptionHandler> | ExceptionHandler;
+}
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<ErrorsModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+/**
+ * Registers the application-wide error surface: the composed
+ * {@link ERROR_CATALOG} that every transport edge redacts against, and an
+ * optional {@link APP_EXCEPTION_HANDLER}. The imperative sibling is
+ * `app.useGlobalExceptionHandler(handler)`.
+ *
+ * ```ts
+ * @Module({
+ *   imports: [ErrorsModule.forRoot({ catalogs: [ordersCatalog], handler: SentryHandler })],
+ * })
+ * class AppModule {}
+ * ```
+ */
+export declare class ErrorsModule extends ConfigurableModuleClass {
+}
+export {};

package/dist/exceptions/errors.module.js

@@ -0,0 +1,46 @@
+import { CORE_CATALOG, composeCatalogs } from "@velajs/errors";
+import { defineModule } from "../module/define-module.js";
+import { APP_EXCEPTION_HANDLER, ERROR_CATALOG } from "../pipeline/tokens.js";
+/** Lower a `handler` option to an {@link APP_EXCEPTION_HANDLER} provider. */ const handlerProvider = (handler)=>typeof handler === 'function' ? {
+        provide: APP_EXCEPTION_HANDLER,
+        useClass: handler
+    } : {
+        provide: APP_EXCEPTION_HANDLER,
+        useValue: handler
+    };
+const { ConfigurableModuleClass } = defineModule({
+    name: 'Errors',
+    setup: ({ options })=>{
+        const providers = [
+            {
+                provide: ERROR_CATALOG,
+                useValue: composeCatalogs(CORE_CATALOG, ...options.catalogs ?? [])
+            }
+        ];
+        const exports = [
+            ERROR_CATALOG
+        ];
+        if (options.handler) {
+            providers.push(handlerProvider(options.handler));
+            exports.push(APP_EXCEPTION_HANDLER);
+        }
+        return {
+            providers,
+            exports
+        };
+    }
+});
+/**
+ * Registers the application-wide error surface: the composed
+ * {@link ERROR_CATALOG} that every transport edge redacts against, and an
+ * optional {@link APP_EXCEPTION_HANDLER}. The imperative sibling is
+ * `app.useGlobalExceptionHandler(handler)`.
+ *
+ * ```ts
+ * @Module({
+ *   imports: [ErrorsModule.forRoot({ catalogs: [ordersCatalog], handler: SentryHandler })],
+ * })
+ * class AppModule {}
+ * ```
+ */ export class ErrorsModule extends ConfigurableModuleClass {
+}

package/dist/exceptions/exception-handler.d.ts

@@ -0,0 +1,56 @@
+import { type ErrorBodyResult } from '@velajs/errors';
+/**
+ * A predicate for classifying an error, used by {@link ExceptionHandler.dontReport}.
+ *
+ * Three shapes are accepted:
+ * - `string` — a Vela error code; matches when the error is a branded
+ *   `VelaError` whose `code` equals the string.
+ * - a predicate `(error: unknown) => boolean` — **must be an arrow function**.
+ *   A class and a predicate are both `typeof 'function'`; {@link matchesAny}
+ *   discriminates on `prototype`, which arrow functions do not have.
+ * - an error class constructor — matches via `instanceof`.
+ *
+ * Bound functions (e.g. `SomeClass.bind(null)`) also lack `.prototype`, so they
+ * are treated as predicates and invoked — never as class matchers. Since a bound
+ * constructor cannot be called without `new`, using one here throws; pass the
+ * unbound class instead.
+ */
+export type ErrorMatcher = string | ((error: unknown) => boolean) | (new (...args: never[]) => Error);
+/**
+ * Ambient context handed to every reporting/rendering hook. `edge` names the
+ * transport that caught the error; open-ended extra keys (via the index
+ * signature) let a handler's `context()` enrich the payload.
+ */
+export interface ErrorReportContext {
+    edge: 'http' | 'ws' | 'live' | 'queue' | 'schedule' | 'hono';
+    /** e.g. `'CatsController.findAll'` or a query name. */
+    source?: string;
+    /** e.g. `'exception filter threw'`. */
+    note?: string;
+    [key: string]: unknown;
+}
+/**
+ * The application-wide exception handler contract. Provide an implementation
+ * under {@link APP_EXCEPTION_HANDLER} to customize how errors are reported and
+ * rendered. Every member is optional — an empty object is a valid handler.
+ */
+export interface ExceptionHandler {
+    /** Fire-and-forget reporting (logging, Sentry, …). May be async. */
+    report?(error: unknown, ctx: ErrorReportContext): void | Promise<void>;
+    /** Errors matching any of these are never reported. */
+    dontReport?: ErrorMatcher[];
+    /** Extra fields merged into the report context. Must be side-effect free. */
+    context?(error: unknown, ctx: ErrorReportContext): Record<string, unknown>;
+    /** Override the client-bound response for an error. */
+    render?(error: unknown, ctx: unknown): Response | ErrorBodyResult | undefined;
+}
+/**
+ * True when `error` matches any of `matchers`. A string matches a branded
+ * {@link VelaError} by `code`; an arrow-function predicate is called; anything
+ * else with a `prototype` is treated as an error class and matched via
+ * `instanceof`. Predicates therefore MUST be arrow functions — a regular
+ * `function` expression has a `prototype` and would be mistaken for a class.
+ * Bound functions (e.g. `SomeClass.bind(null)`) lack `.prototype` too, so they
+ * are invoked as predicates — don't pass a bound class as a class matcher.
+ */
+export declare const matchesAny: (matchers: ErrorMatcher[] | undefined, error: unknown) => boolean;

package/dist/exceptions/exception-handler.js

@@ -0,0 +1,17 @@
+import { isVelaError } from "@velajs/errors";
+/**
+ * True when `error` matches any of `matchers`. A string matches a branded
+ * {@link VelaError} by `code`; an arrow-function predicate is called; anything
+ * else with a `prototype` is treated as an error class and matched via
+ * `instanceof`. Predicates therefore MUST be arrow functions — a regular
+ * `function` expression has a `prototype` and would be mistaken for a class.
+ * Bound functions (e.g. `SomeClass.bind(null)`) lack `.prototype` too, so they
+ * are invoked as predicates — don't pass a bound class as a class matcher.
+ */ export const matchesAny = (matchers, error)=>{
+    if (!matchers?.length) return false;
+    return matchers.some((m)=>{
+        if (typeof m === 'string') return isVelaError(error) && error.code === m;
+        if (typeof m === 'function' && !m.prototype) return m(error);
+        return error instanceof m;
+    });
+};

package/dist/exceptions/index.d.ts

@@ -0,0 +1,6 @@
+export { matchesAny } from './exception-handler';
+export type { ErrorMatcher, ErrorReportContext, ExceptionHandler } from './exception-handler';
+export { ErrorsModule } from './errors.module';
+export type { ErrorsModuleOptions } from './errors.module';
+export { resolveErrorReporter } from './reporter';
+export type { ErrorReporter } from './reporter';

package/dist/exceptions/index.js

@@ -0,0 +1,3 @@
+export { matchesAny } from "./exception-handler.js";
+export { ErrorsModule } from "./errors.module.js";
+export { resolveErrorReporter } from "./reporter.js";

package/dist/exceptions/reporter.d.ts

@@ -0,0 +1,21 @@
+import { type Catalog, type ErrorBodyResult } from '@velajs/errors';
+import type { Container } from '../container/container';
+import { type ErrorReportContext } from './exception-handler';
+/**
+ * The resolved reporting facade every transport edge (HTTP, WS, live, queue,
+ * schedule) uses. `report` is fire-and-forget and fully contained — a broken
+ * or throwing handler can never mask the original error. `render` gives a
+ * handler the chance to override the client-bound response.
+ */
+export interface ErrorReporter {
+    catalog: Catalog<string>;
+    report(error: unknown, ctx: ErrorReportContext): void;
+    render(error: unknown, executionCtx: unknown): Response | ErrorBodyResult | undefined;
+}
+/**
+ * Build an {@link ErrorReporter} from a container. Reads the optional
+ * {@link APP_EXCEPTION_HANDLER} and {@link ERROR_CATALOG} providers; with
+ * neither registered the reporter logs (unless diagnostics is `'silent'`) and
+ * exposes the core catalog.
+ */
+export declare const resolveErrorReporter: (container: Container) => ErrorReporter;

package/dist/exceptions/reporter.js

@@ -0,0 +1,70 @@
+import { CORE_CATALOG, isVelaError } from "@velajs/errors";
+import { HTTPException } from "hono/http-exception";
+import { HttpException } from "../errors/http-exception.js";
+import { APP_EXCEPTION_HANDLER, ERROR_CATALOG } from "../pipeline/tokens.js";
+import { matchesAny } from "./exception-handler.js";
+/**
+ * Build an {@link ErrorReporter} from a container. Reads the optional
+ * {@link APP_EXCEPTION_HANDLER} and {@link ERROR_CATALOG} providers; with
+ * neither registered the reporter logs (unless diagnostics is `'silent'`) and
+ * exposes the core catalog.
+ */ export const resolveErrorReporter = (container)=>{
+    const handler = container.has(APP_EXCEPTION_HANDLER) ? container.resolve(APP_EXCEPTION_HANDLER) : undefined;
+    const catalog = container.has(ERROR_CATALOG) ? container.resolve(ERROR_CATALOG) : CORE_CATALOG;
+    return {
+        catalog,
+        report (error, ctx) {
+            let suppressed = false;
+            try {
+                suppressed = matchesAny(handler?.dontReport, error);
+            } catch  {
+            // A broken matcher must never mask the original error — treat as no match.
+            }
+            if (suppressed) return;
+            const merged = handler?.context ? {
+                ...ctx,
+                ...safeContext(handler, error, ctx)
+            } : ctx;
+            if (handler?.report) {
+                try {
+                    void Promise.resolve(handler.report(error, merged)).catch(()=>{});
+                } catch  {
+                // A broken reporter must never mask the original error.
+                }
+                return;
+            }
+            if (container.getDiagnostics() !== 'silent') {
+                const status = clientFaultStatus(error);
+                if (status !== undefined && status >= 400 && status < 500) return; // client fault — not server-error log noise
+                console.error(`[vela] ${merged.edge} error${merged.source ? ` in ${merged.source}` : ''}${merged.note ? ` (${merged.note})` : ''}:`, error);
+            }
+        },
+        render (error, executionCtx) {
+            try {
+                return handler?.render?.(error, executionCtx);
+            } catch  {
+                return undefined; // broken render hook falls through to default render
+            }
+        }
+    };
+};
+/**
+ * The HTTP status of a client-fault (4xx) error, read across the three shapes a
+ * caught error can take: a branded {@link VelaError} (`.status`), vela's own
+ * {@link HttpException} (`getStatus()`), or hono's {@link HTTPException}
+ * (`.status`). `undefined` for anything else — including raw/unbranded errors,
+ * which must always be logged. Only the DEFAULT console reporter uses this to
+ * mute client faults; a custom `handler.report` still receives everything.
+ */ const clientFaultStatus = (error)=>{
+    if (isVelaError(error)) return error.status;
+    if (error instanceof HttpException) return error.getStatus();
+    if (error instanceof HTTPException) return error.status; // hono
+    return undefined;
+};
+const safeContext = (handler, error, ctx)=>{
+    try {
+        return handler.context?.(error, ctx) ?? {};
+    } catch  {
+        return {};
+    }
+};

package/dist/factory/bootstrap.js

@@ -8,7 +8,7 @@ import { UrlGeneratorService } from "../http/url/url-generator.service.js";
 import { SignedUrlGuard } from "../http/url/signed-url.guard.js";
 import { ModuleLoader } from "../module/module-loader.js";
 import { bindAppProviders } from "../pipeline/app-providers.js";
-import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from "../pipeline/tokens.js";
+import { APP_EXCEPTION_HANDLER, APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE, ERROR_CATALOG } from "../pipeline/tokens.js";
 /**
  * Wire the DI graph for `rootModule` and prepare the route manager — without
  * running lifecycle hooks or building the Hono app. The single primitive
@@ -48,7 +48,9 @@ import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_MIDDLEWARE, APP_PIPE } from
         APP_PIPE,
         APP_INTERCEPTOR,
         APP_FILTER,
-        APP_MIDDLEWARE
+        APP_MIDDLEWARE,
+        APP_EXCEPTION_HANDLER,
+        ERROR_CATALOG
     ]){
         container.markGlobalToken(t);
     }

package/dist/http/handler-executor.js

@@ -1,4 +1,6 @@
+import { STATUS_TO_CODE, toErrorBody } from "@velajs/errors";
 import { HttpException } from "../errors/http-exception.js";
+import { resolveErrorReporter } from "../exceptions/reporter.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
 import { shouldFilterCatch } from "../pipeline/decorators.js";
 import { PipelineRunner } from "../pipeline/pipeline-runner.js";
@@ -80,31 +82,51 @@ export class HandlerExecutor {
                 applyResponseHeaders(response, responseHeaders);
                 return response;
             } catch (error) {
+                const reporter = resolveErrorReporter(requestContainer);
+                const source = `${controller.name}.${String(route.handlerName)}`;
+                // Report FIRST, always — rendering (filters included) is a separate
+                // concern; a filter claiming the error must not make it invisible.
+                reporter.report(error, {
+                    edge: 'http',
+                    source
+                });
                 for (const filter of filters){
                     if (shouldFilterCatch(filter, error)) {
                         try {
                             const filtered = await filter.catch(error, executionContext);
                             return mapResponse(c, filtered);
-                        } catch  {
+                        } catch (filterError) {
+                            // A broken filter is itself a bug worth logs — then fall through
+                            // to the default render instead of silently dying here.
+                            reporter.report(filterError, {
+                                edge: 'http',
+                                source,
+                                note: 'exception filter threw'
+                            });
                             break;
                         }
                     }
                 }
+                const rendered = reporter.render(error, executionContext);
+                if (rendered instanceof Response) return rendered;
+                if (rendered) return c.json(rendered.body, rendered.status);
                 if (error instanceof HttpException) {
-                    const response = error.getResponse();
                     const status = error.getStatus();
-                    return c.json(response, status);
-                }
-                // An unknown error reaching here means no filter claimed it — never
-                // swallow it silently: the response is a generic 500, but the cause
-                // must land in the logs (diagnostics 'silent' opts out).
-                if (requestContainer.getDiagnostics() !== 'silent') {
-                    console.error(`[vela] unhandled error in ${controller.name}.${String(route.handlerName)}:`, error);
+                    const raw = error.getRawResponse() ?? error.message;
+                    if (typeof raw === 'string') {
+                        return c.json({
+                            error: {
+                                code: STATUS_TO_CODE[status] ?? 'internal',
+                                message: raw
+                            }
+                        }, status);
+                    }
+                    return c.json(raw, status); // object responses ship verbatim (crud envelope compat)
                 }
-                return c.json({
-                    statusCode: 500,
-                    message: 'Internal Server Error'
-                }, 500);
+                const { body, status } = toErrorBody(error, {
+                    catalog: reporter.catalog
+                });
+                return c.json(body, status);
             }
         };
     }

package/dist/index.d.ts

@@ -51,13 +51,17 @@ export type { AdapterContext, RuntimeAdapter } from './factory/adapter';
 export type { VelaCreateOptions } from './factory';
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN, } from './plugin/plugin';
 export type { Plugin } from './plugin/plugin';
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, } from './pipeline/index';
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, APP_EXCEPTION_HANDLER, ERROR_CATALOG, } from './pipeline/index';
 export type { PipelineRunOptions, ResolvedComponentMap } from './pipeline/index';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, ReflectableDecorator, CreateDecoratorOptions, } from './pipeline/index';
 export type { Constructor, MiddlewareType, GuardType, PipeType, InterceptorType, FilterType, } from './registry/index';
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipeline/index';
 export type { ParseUUIDPipeOptions, ParseArrayPipeOptions } from './pipeline/index';
 export { HttpException, BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, GoneException, PayloadTooLargeException, UnsupportedMediaTypeException, UnprocessableEntityException, TooManyRequestsException, InternalServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, GatewayTimeoutException, } from './errors/index';
+export { ErrorsModule, matchesAny, resolveErrorReporter } from './exceptions/index';
+export type { ErrorMatcher, ErrorReportContext, ErrorsModuleOptions, ExceptionHandler, ErrorReporter, } from './exceptions/index';
+export { VelaError, isVelaError, defineErrorCatalog, composeCatalogs, toErrorBody, CORE_CATALOG, } from '@velajs/errors';
+export type { Catalog, ErrorBodyResult, ErrorCatalogEntry, VelaErrorOptions } from '@velajs/errors';
 export type { OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, OnApplicationShutdown, BeforeApplicationShutdown, } from './lifecycle/index';
 export { MetadataRegistry } from './registry/metadata.registry';
 export { createZodDto, ValidationPipe } from './validation/index';

package/dist/index.js

@@ -53,11 +53,16 @@ export { registerRouteContributor, getRouteContributors } from "./http/route-con
 // Plugin manifest + composer
 export { definePlugin, composePlugins, PluginRegistry, PluginRootModule, PLUGIN_REGISTRY_TOKEN } from "./plugin/plugin.js";
 // Pipeline Decorators
-export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";
+export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, PipelineRunner, getCatchTypes, shouldFilterCatch, resolveScopedComponents, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, APP_EXCEPTION_HANDLER, ERROR_CATALOG } from "./pipeline/index.js";
 // Built-in Pipes
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipeline/index.js";
 // Errors
 export { HttpException, BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, GoneException, PayloadTooLargeException, UnsupportedMediaTypeException, UnprocessableEntityException, TooManyRequestsException, InternalServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, GatewayTimeoutException } from "./errors/index.js";
+// Exception handling — the ExceptionHandler contract + shared error reporter.
+// Re-exports the core @velajs/errors surface so app authors need one import to
+// author handlers, throw branded errors, and define/compose catalogs.
+export { ErrorsModule, matchesAny, resolveErrorReporter } from "./exceptions/index.js";
+export { VelaError, isVelaError, defineErrorCatalog, composeCatalogs, toErrorBody, CORE_CATALOG } from "@velajs/errors";
 // MetadataRegistry — the central decoration store. Test setup typically
 // uses `MetadataRegistry.clear()` between cases. Internal primitives like
 // RouteManager/ModuleLoader/ComponentManager live only at @velajs/vela/internal.

package/dist/live/live.engine.d.ts

@@ -66,6 +66,13 @@ export declare class LiveEngine implements OnApplicationBootstrap, ContributesEn
     private runSubscribeGuards;
     private scheduleDrain;
     private drainLoop;
+    /**
+     * Map a resolver failure to its live error-frame code. A branded
+     * {@link VelaError} carries an HTTP-ish status that projects onto the live
+     * vocabulary (403 → forbidden, 400/422 → bad_args); everything else — and
+     * every unbranded error — is `internal` (the client sees a redacted message).
+     */
+    private static liveFrameCode;
     private push;
     private runQuery;
     /**

package/dist/live/live.engine.js

@@ -13,7 +13,7 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 import { LIVE_ERROR_CODES, LIVE_PROTOCOL, encodeLiveEnvelope, isClientLiveFrame } from "@velajs/live-protocol";
-import { Container, DiscoveryService, Inject, Injectable, Optional, PipelineRunner, ReservedWsEvent, buildEntrypointExecutionContext, resolveScopedComponents, runInEntrypointScope } from "../index.js";
+import { Container, DiscoveryService, Inject, Injectable, Optional, PipelineRunner, ReservedWsEvent, buildEntrypointExecutionContext, isVelaError, resolveErrorReporter, resolveScopedComponents, runInEntrypointScope, toErrorBody } from "../index.js";
 import { getLiveQueries } from "./live.decorators.js";
 import { encodeSubscriptionUpdate } from "./live.delta.js";
 import { LIVE_CURSOR_LOG, LIVE_DRIVER, LIVE_MODULE_OPTIONS, LIVE_RESOLVER_METADATA } from "./live.tokens.js";
@@ -308,6 +308,17 @@ export class LiveEngine {
             });
         }
     }
+    /**
+   * Map a resolver failure to its live error-frame code. A branded
+   * {@link VelaError} carries an HTTP-ish status that projects onto the live
+   * vocabulary (403 → forbidden, 400/422 → bad_args); everything else — and
+   * every unbranded error — is `internal` (the client sees a redacted message).
+   */ static liveFrameCode(err) {
+        if (!isVelaError(err)) return LIVE_ERROR_CODES.INTERNAL;
+        if (err.status === 403) return LIVE_ERROR_CODES.FORBIDDEN;
+        if (err.status === 400 || err.status === 422) return LIVE_ERROR_CODES.BAD_ARGS;
+        return LIVE_ERROR_CODES.INTERNAL;
+    }
     async push(conn, record, stamp, { initial }) {
         // Outbound expiry enforcement — the only place expiry CAN be enforced for
         // a passive subscriber.
@@ -331,12 +342,24 @@ export class LiveEngine {
             json = JSON.stringify(result);
         } catch (err) {
             if (initial) {
+                // Close the leak: an initial-subscribe resolver failure is REDACTED
+                // through `toErrorBody` (the single wire-redaction seam) — an unbranded
+                // error's raw message never reaches the browser, it surfaces only via
+                // the reporter. Branded VelaErrors keep their client-facing message.
                 conn.subs.delete(record.sub);
+                const reporter = resolveErrorReporter(this.container);
+                reporter.report(err, {
+                    edge: 'live',
+                    source: record.query
+                });
+                const safe = toErrorBody(err, {
+                    catalog: reporter.catalog
+                });
                 this.sendFrame(conn.client, {
                     t: 'error',
                     sub: record.sub,
-                    code: LIVE_ERROR_CODES.INTERNAL,
-                    message: err instanceof Error ? err.message : 'live query failed',
+                    code: LiveEngine.liveFrameCode(err),
+                    message: safe.body.error.message,
                     fatal: true
                 });
             } else if (this.container.getDiagnostics() !== 'silent') {

package/dist/pipeline/index.d.ts

@@ -6,7 +6,7 @@ export type { ResolvedComponentMap } from './scoped-components';
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch, } from './decorators';
 export { SetMetadata, Reflector } from './reflector';
 export type { ReflectableDecorator, CreateDecoratorOptions } from './reflector';
-export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from './tokens';
+export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, APP_EXCEPTION_HANDLER, ERROR_CATALOG, } from './tokens';
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe, } from './pipes';
 export type { ParseUUIDPipeOptions, ParseArrayPipeOptions } from './pipes';
 export type { HttpArgumentsHost, ExecutionContext, CanActivate, CallHandler, NestInterceptor, NestMiddleware, PipeTransform, ExceptionFilter, ArgumentMetadata, } from './types';

package/dist/pipeline/index.js

@@ -3,5 +3,5 @@ export { PipelineRunner } from "./pipeline-runner.js";
 export { resolveScopedComponents } from "./scoped-components.js";
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, getCatchTypes, shouldFilterCatch } from "./decorators.js";
 export { SetMetadata, Reflector } from "./reflector.js";
-export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./tokens.js";
+export { APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE, APP_EXCEPTION_HANDLER, ERROR_CATALOG } from "./tokens.js";
 export { ParseIntPipe, ParseFloatPipe, ParseBoolPipe, ParseUUIDPipe, ParseEnumPipe, ParseArrayPipe, DefaultValuePipe, RequiredPipe, ZodValidationPipe } from "./pipes.js";

package/dist/pipeline/tokens.d.ts

@@ -1,4 +1,6 @@
+import type { Catalog } from '@velajs/errors';
 import { InjectionToken } from '../container/types';
+import type { ExceptionHandler } from '../exceptions/exception-handler';
 import type { CanActivate, ExceptionFilter, NestInterceptor, NestMiddleware, PipeTransform } from './types';
 /**
  * Register global guards via module providers instead of app.useGlobalGuards().
@@ -31,3 +33,25 @@ export declare const APP_FILTER: InjectionToken<ExceptionFilter<unknown>>;
  * Register global middleware via module providers.
  */
 export declare const APP_MIDDLEWARE: InjectionToken<NestMiddleware>;
+/**
+ * Register the application-wide exception handler via module providers.
+ * Consumed by the shared error reporter (`resolveErrorReporter`) at every
+ * transport edge to customize how errors are reported and rendered.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   providers: [
+ *     { provide: APP_EXCEPTION_HANDLER, useValue: { report: (e) => sentry.capture(e) } },
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ */
+export declare const APP_EXCEPTION_HANDLER: InjectionToken<ExceptionHandler>;
+/**
+ * Provide the composed error catalog (`composeCatalogs(CORE_CATALOG, …)`)
+ * consulted when rendering wire-bound error bodies. Defaults to the core
+ * catalog when unset.
+ */
+export declare const ERROR_CATALOG: InjectionToken<Catalog<string>>;

package/dist/pipeline/tokens.js

@@ -25,3 +25,23 @@ import { InjectionToken } from "../container/types.js";
 /**
  * Register global middleware via module providers.
  */ export const APP_MIDDLEWARE = new InjectionToken('APP_MIDDLEWARE');
+/**
+ * Register the application-wide exception handler via module providers.
+ * Consumed by the shared error reporter (`resolveErrorReporter`) at every
+ * transport edge to customize how errors are reported and rendered.
+ *
+ * @example
+ * ```ts
+ * @Module({
+ *   providers: [
+ *     { provide: APP_EXCEPTION_HANDLER, useValue: { report: (e) => sentry.capture(e) } },
+ *   ],
+ * })
+ * class AppModule {}
+ * ```
+ */ export const APP_EXCEPTION_HANDLER = new InjectionToken('APP_EXCEPTION_HANDLER');
+/**
+ * Provide the composed error catalog (`composeCatalogs(CORE_CATALOG, …)`)
+ * consulted when rendering wire-bound error bodies. Defaults to the core
+ * catalog when unset.
+ */ export const ERROR_CATALOG = new InjectionToken('ERROR_CATALOG');

package/dist/queue/queue.binding.js

@@ -1,4 +1,4 @@
-import { EntrypointRegistry } from "../index.js";
+import { EntrypointRegistry, resolveErrorReporter } from "../index.js";
 import { dispatchJobToEntries } from "./queue.dispatch.js";
 import { PROCESSOR_METADATA, queueToken } from "./queue.tokens.js";
 /**
@@ -48,6 +48,13 @@ import { PROCESSOR_METADATA, queueToken } from "./queue.tokens.js";
         if (mode === 'throw') {
             throw error instanceof Error ? error : new Error(String(error));
         }
-        console.error(`[vela] unhandled error processing queue job '${job.name}' on '${job.queue}':`, error);
+        // Fire-and-forget (inline `immediate`) deliveries have no awaiter to rethrow
+        // into — route their unclaimed errors to the exception handler instead of a
+        // bare console.error.
+        resolveErrorReporter(this.container).report(error, {
+            edge: 'queue',
+            source: `${job.queue}/${job.name}`,
+            note: 'inline driver'
+        });
     }
 }

package/dist/queue/queue.dispatch.js

@@ -1,4 +1,4 @@
-import { buildEntrypointExecutionContext, PipelineRunner, resolveScopedComponents, runInEntrypointScope, shouldFilterCatch } from "../index.js";
+import { buildEntrypointExecutionContext, PipelineRunner, resolveErrorReporter, resolveScopedComponents, runInEntrypointScope, shouldFilterCatch } from "../index.js";
 import { getProcessHandlers } from "./queue.decorators.js";
 const warnedDuplicates = new WeakSet();
 function selectHandler(container, processorClass, handlers, jobName) {
@@ -90,13 +90,20 @@ async function dispatchToProcessor(container, processorClass, job) {
             });
             return true;
         } catch (error) {
+            // Report BEFORE the filter loop and BEFORE any rethrow — every dispatch
+            // error reaches the exception handler, whether a scoped filter claims it
+            // or it rethrows to preserve platform retry semantics.
+            resolveErrorReporter(scope).report(error, {
+                edge: 'queue',
+                source: `${processorClass.name}.${String(handler.methodName)}`
+            });
             for (const filter of filters){
                 if (shouldFilterCatch(filter, error)) {
                     await filter.catch(error, context);
                     return true;
                 }
             }
-            throw error;
+            throw error; // unclaimed → platform retry semantics stay intact
         }
     });
 }

package/dist/schedule-node/schedule.executor.js

@@ -14,6 +14,7 @@ function _ts_param(paramIndex, decorator) {
 }
 import { Inject, Injectable } from "../container/index.js";
 import { Container } from "../container/container.js";
+import { resolveErrorReporter } from "../exceptions/reporter.js";
 import { parseCron } from "../schedule/cron-matcher.js";
 import { ScheduleRegistry } from "../schedule/schedule.registry.js";
 export class ScheduleExecutor {
@@ -70,13 +71,17 @@ export class ScheduleExecutor {
                 await method.call(instance);
             }
         } catch (err) {
+            // Report BEFORE the rethrow below — the exception handler sees every
+            // scheduled-job error, and its default reporter logs it (unless silent),
+            // replacing the previous bare console.warn.
+            resolveErrorReporter(this.container).report(err, {
+                edge: 'schedule',
+                source: methodName
+            });
             // Runtime job error — keep the scheduler running by default. Users
             // can opt into rethrowing by setting diagnostics: 'throw'.
             const mode = this.container.getDiagnostics();
             if (mode === 'throw') throw err;
-            if (mode === 'log') {
-                console.warn(`[vela] scheduled job ${methodName} failed:`, err);
-            }
         }
     }
     getMatcher(expression) {

package/dist/websocket/ws-dispatcher.js

@@ -15,6 +15,7 @@ function _ts_param(paramIndex, decorator) {
 import { Container } from "../container/container.js";
 import { Inject, Injectable, Optional } from "../container/decorators.js";
 import { DiscoveryService } from "../discovery/discovery.service.js";
+import { resolveErrorReporter } from "../exceptions/reporter.js";
 import { instantiateMany } from "../http/instantiate.js";
 import { RouteManager } from "../http/route.manager.js";
 import { ComponentManager } from "../pipeline/component.manager.js";
@@ -127,9 +128,15 @@ export class WsDispatcher {
         }
     }
     async handleError(path, _client, err) {
-        if (this.container.getDiagnostics() !== 'silent') {
-            console.warn(`[vela] websocket error on gateway ${path}:`, err);
-        }
+        // Connection-level and reserved-frame (`$…`) throws land here. Route them
+        // through the shared reporter so a custom APP_EXCEPTION_HANDLER observes
+        // them too — the default reporter console.errors and honors `'silent'`.
+        // No client frame is sent for this path, by design: reserved frames own
+        // their own client-facing responses, and there is no envelope id to reply to.
+        resolveErrorReporter(this.container).report(err, {
+            edge: 'ws',
+            source: path ? `reserved-frame ${path}` : 'reserved-frame'
+        });
     }
     async dispatchMessage(path, client, raw) {
         const entry = this.gateways.get(path);
@@ -189,7 +196,15 @@ export class WsDispatcher {
             });
             this.reply(client, message, result);
         } catch (error) {
-            await this.runFilters(client, message, error, filters, ctx);
+            const reporter = resolveErrorReporter(this.container);
+            const source = `${entry.gatewayClass.name}.${handler.methodName}`;
+            // Report FIRST, always — before any exception filter can claim (and thus
+            // hide) the error. Rendering is a separate concern (mirrors HandlerExecutor).
+            reporter.report(error, {
+                edge: 'ws',
+                source
+            });
+            await this.runFilters(client, message, error, filters, ctx, reporter, source);
         }
     }
     /**
@@ -207,7 +222,7 @@ export class WsDispatcher {
         try {
             for (const guard of guards){
                 if (!await guard.canActivate(ctx)) {
-                    const frame = toErrorFrame(new WsException('Forbidden'));
+                    const frame = toErrorFrame(new WsException('Forbidden'), resolveErrorReporter(this.container).catalog);
                     this.trySend(client, frame.event, frame.data, message.id);
                     return;
                 }
@@ -225,7 +240,7 @@ export class WsDispatcher {
             this.trySend(client, message.event, result, message.id);
         }
     }
-    async runFilters(client, message, error, filters, ctx) {
+    async runFilters(client, message, error, filters, ctx, reporter, source) {
         for (const filter of filters){
             if (shouldFilterCatch(filter, error)) {
                 try {
@@ -233,15 +248,21 @@ export class WsDispatcher {
                     if (isWsResponse(handled)) {
                         this.trySend(client, handled.event, handled.data, message.id);
                     }
-                } catch  {
-                    // A throwing filter falls back to the default error frame (mirrors HandlerExecutor).
-                    const frame = toErrorFrame(error);
+                } catch (filterError) {
+                    // A throwing filter is itself a bug worth reporting — then fall back
+                    // to the default redacted frame (mirrors HandlerExecutor).
+                    reporter.report(filterError, {
+                        edge: 'ws',
+                        source,
+                        note: 'exception filter threw'
+                    });
+                    const frame = toErrorFrame(error, reporter.catalog);
                     this.trySend(client, frame.event, frame.data, message.id);
                 }
                 return;
             }
         }
-        const errorFrame = toErrorFrame(error);
+        const errorFrame = toErrorFrame(error, reporter.catalog);
         this.trySend(client, errorFrame.event, errorFrame.data, message.id);
     }
     // Outbound sends are best-effort: the socket may have closed mid-dispatch.

package/dist/websocket/ws-exception.d.ts

@@ -1,3 +1,4 @@
+import { type Catalog } from '@velajs/errors';
 /**
  * WebSocket analogue of `HttpException`. Thrown from guards/pipes/handlers to
  * signal a client-facing error; the dispatcher serializes it to an
@@ -9,8 +10,16 @@ export declare class WsException extends Error {
     constructor(err: string | Record<string, unknown>);
     getError(): string | Record<string, unknown>;
 }
-/** Default serialization of an uncaught error into the outbound exception frame. */
-export declare function toErrorFrame(error: unknown): {
+/**
+ * Default serialization of an uncaught error into the outbound exception frame.
+ *
+ * A `WsException` ships its own payload verbatim (string → `{ message }`,
+ * object → as-is). Every other error routes through `toErrorBody` — the single
+ * wire-redaction seam shared with the HTTP edge — so unbranded/internal errors
+ * are redacted to their catalog title and only branded `VelaError`s echo a
+ * client-safe `{ code, message, ... }`.
+ */
+export declare function toErrorFrame(error: unknown, catalog?: Catalog<string>): {
     event: 'exception';
     data: unknown;
 };

package/dist/websocket/ws-exception.js

@@ -1,3 +1,4 @@
+import { toErrorBody } from "@velajs/errors";
 /**
  * WebSocket analogue of `HttpException`. Thrown from guards/pipes/handlers to
  * signal a client-facing error; the dispatcher serializes it to an
@@ -13,7 +14,15 @@
         return this.err;
     }
 }
-/** Default serialization of an uncaught error into the outbound exception frame. */ export function toErrorFrame(error) {
+/**
+ * Default serialization of an uncaught error into the outbound exception frame.
+ *
+ * A `WsException` ships its own payload verbatim (string → `{ message }`,
+ * object → as-is). Every other error routes through `toErrorBody` — the single
+ * wire-redaction seam shared with the HTTP edge — so unbranded/internal errors
+ * are redacted to their catalog title and only branded `VelaError`s echo a
+ * client-safe `{ code, message, ... }`.
+ */ export function toErrorFrame(error, catalog) {
     if (error instanceof WsException) {
         const e = error.getError();
         return {
@@ -23,10 +32,11 @@
             } : e
         };
     }
+    const { body } = toErrorBody(error, {
+        catalog
+    });
     return {
         event: 'exception',
-        data: {
-            message: 'Internal server error'
-        }
+        data: body.error
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -88,6 +88,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@velajs/errors": "^1.0.0",
     "@velajs/live-protocol": "^1.0.0",
     "hono": "^4.12.26"
   },