@supacloud/elysia 0.10.0 → 0.14.1

package/README.md

@@ -1,5 +1,28 @@
 # @supacloud/elysia
 
+## Persistent Command Adapters
+
+`createPersistentCommandAdapter(command, { identity, input })` binds a
+`createTransactionalCommand` or `createExternalCommand` from `@supacloud/commands`
+to `commandGovernance.rpc`.
+Its capabilities distinguish `database` from `external` boundaries. It owns the
+single write entry point and never invokes a second route handler or audit.
+Resolve identity from a verified host context; all durable receipt reads and replays
+must still pass domain authorization.
+
+`createApplication({ normalize: false, ... })` rejects extra schema properties rather
+than silently stripping them. Use shared schemas at domain and HTTP boundaries.
+
+Alternatively, a meaningful Controller can call its injected Command directly,
+with no route-level `command:` binding. `src/fixtures/webhook` follows this pattern.
+`bun run generate:example` generates its factories; `src/webhook-migration-example.ts`
+loads those artifacts for native HTTP/PostgreSQL acceptance. Tests reject stale
+artifacts and cover writes, authorization, audit rollback and receipt recovery.
+The runtime maps protocol errors without importing DB: explicit denial is 403,
+authorization infrastructure failure is 503, and redacted-input lookup is 410.
+See [the migration plan](../../docs/command-migration.md) for compiler policy,
+authentication replay changes, deployment order and rollback limitations.
+
 Runtime adapter that turns `@supacloud/compiler` output into a production-ready
 [Elysia](https://elysiajs.com/) application.
 
@@ -13,8 +36,15 @@ Runtime adapter that turns `@supacloud/compiler` output into a production-ready
   controllers and services.
 - **Request-scope teardown**: invokes the compiler-generated
   `destroyRequestScope` after the response, including when the handler fails.
-- **TypeBox schema binding**: attaches compiled parameter, query, body, and
-  response TypeBox schemas directly to Elysia route definitions.
+- **Angular-backed async DI**: when `createApplication({ injector })` receives
+  an `@supacloud/app` root injector, each request gets an isolated child
+  injector with `REQUEST_CONTEXT`, including across `await` boundaries.
+- **TypeBox schema binding**: attaches compiled parameter, query, body, headers,
+  cookie, single-response and status-map TypeBox schemas directly to Elysia
+  route definitions; Elysia performs request validation and normalization.
+- **Schema-first client decoding**: generated clients select the declared
+  response schema by HTTP status and validate/normalize it before returning;
+  an explicit decoder receives that checked value for custom transforms.
 - **Compiler invoker execution**: uses the compiler-emitted positional invoker
   after Elysia has decoded route input, while retaining the legacy input-object
   handler path for hand-written compiled fixtures.
@@ -24,10 +54,15 @@ Runtime adapter that turns `@supacloud/compiler` output into a production-ready
 - **Static AOP pipeline**: executes compiler-emitted module, route, command, and
   job aspects with `composeAspects`; no runtime discovery or registration is
   performed.
+- **Worker registration**: registers compiler-emitted Jobs, initializes their
+  application services once, and provides polling plus graceful shutdown around
+  a host-owned claim/receipt transport.
 - **Public error mapping**: transforms framework / application errors via
   `errorMapper` with standard `ApplicationError` envelope support, preserving
   HTTP 422 for request validation and HTTP 500 / `RESPONSE_VALIDATION_ERROR`
   for invalid handler output, without exposing payloads or schema internals.
+- **Opt-in API documentation**: serves a generated OpenAPI JSON document and a
+  dependency-free viewer, plus a role-scoped GraphQL SDL snapshot viewer.
 
 ## Installation
 
@@ -41,11 +76,24 @@ bun add @supacloud/elysia elysia
 import { composeCommandExecutors, createApplication, requireIdempotencyKey } from "@supacloud/elysia";
 import AuditModule from "./.generated/audit.module";
 import CaseModule from "./.generated/case.module";
+import { OPENAPI_DOCUMENT } from "./generated/openapi";
 
 const app = createApplication({
   name: "case-service",
   modules: [AuditModule, CaseModule], // topological import order
   deps: { db: createDbClient() },     // platform deps, passed to createServices
+  documentation: {
+    openApi: {
+      document: OPENAPI_DOCUMENT,
+      specPath: "/openapi.json",
+      uiPath: "/docs",
+    },
+    graphql: {
+      schema: () => Bun.file("./graphql/schema.graphql").text(),
+      schemaPath: "/graphql/schema.graphql",
+      uiPath: "/graphql/docs",
+    },
+  },
   commandGovernance: {
     authorize: (invocation) => authorize(invocation.requestContext, invocation.command.permission),
     idempotency: (invocation, next) => idempotencyStore.run(requireIdempotencyKey(invocation), next),
@@ -62,6 +110,17 @@ const app = createApplication({
 export default app;
 ```
 
+Documentation is disabled unless `documentation` is provided. The OpenAPI
+document can be imported from the compiler-generated `openapi.ts` module. The
+GraphQL endpoint serves a local, role-scoped snapshot only; it does not enable
+server introspection or create a GraphQL resolver layer. Protect or omit these
+routes in production when the schema is not public.
+
+The root injector is normally created and owned by `bootstrapBun`. The Elysia
+adapter does not take ownership of an injected root injector; stop it from the
+same Bun bootstrap that created it. Existing applications may omit `injector`
+and continue using compiler-generated request scopes unchanged.
+
 For deterministic local verification, use the in-memory sandbox. It supplies
 stable request identity, an isolated key-value database with optimistic
 transaction rollback, and an in-memory object store without requiring
@@ -100,6 +159,72 @@ input, requestContext)`. The asynchronous compiler-generated job scope is
 destroyed after execution, including when the job throws or scope construction
 fails partway through.
 
+### Worker Registration
+
+`createWorker` registers compiled modules and drives a host-provided claim,
+acknowledge and fail transport. The worker owns Job lookup, application-service
+initialization, concurrency and graceful shutdown. The platform adapter remains
+the owner of leases, retries, DLQ policy and receipt semantics; its receipt type
+is preserved as `TReceipt`. `createQueueWorkerTransport` adapts the structural
+API of the existing `client.queue(name)` without making Elysia depend on the SDK.
+
+```ts
+import {
+  createQueueWorkerTransport,
+  createWorker,
+  type WorkerClaim,
+} from "@supacloud/elysia";
+import type { SupaCloudQueueMutationResult } from "@supacloud/js";
+import { createCompiledModules } from "./generated/application";
+
+type QueueClaim = WorkerClaim & { queueMessageId: string };
+type PlatformReceipt = SupaCloudQueueMutationResult;
+
+// `supacloud` is a configured createSupaCloudClient(...) instance.
+
+const transport = createQueueWorkerTransport({
+  queue: supacloud.queue("jobs"),
+  receive: { visibilityTimeoutSec: 60 },
+  decodeClaim: (message): QueueClaim => {
+    const payload = message.payload;
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("Invalid job envelope");
+    }
+    const envelope = payload as Record<string, unknown>;
+    if (typeof envelope.jobName !== "string" || !("input" in envelope)) {
+      throw new Error("Invalid job envelope");
+    }
+    return {
+      id: message.id,
+      queueMessageId: message.id,
+      jobName: envelope.jobName,
+      input: envelope.input,
+      attempt: message.read_ct ?? 1,
+    };
+  },
+  messageId: (claim) => claim.queueMessageId,
+});
+
+const worker = createWorker<QueueClaim, PlatformReceipt>({
+  modules: createCompiledModules(),
+  deps: { supacloud },
+  concurrency: 4,
+  transport,
+});
+
+await worker.start();
+// The host owns process signals and calls this during shutdown.
+await worker.stop();
+```
+
+Use `mapClaim` when a platform claim has a different wire shape. Duplicate module
+or Job names are rejected before registration is committed. A Job failure is
+reported through `fail`; an unconfirmed `ack` is surfaced as
+`WorkerReceiptUnconfirmedError` and is never followed by a blind `fail`. The
+queue adapter preserves the queue client's mutation receipt type. With PGMQ,
+the SDK's `fail` compatibility method archives the message; use a custom
+transport when the platform needs a distinct retry or dead-letter transition.
+
 ## API
 
 ### External SupAuth Identity
@@ -252,3 +377,62 @@ HTTP receipt fingerprints include route, body, params, query and business
 headers, not mutable request scopes/services or identity/tracing transport.
 Authorization runs again on a replay. Use durable application-owned adapters
 for production receipts, transactions and audits.
+
+### Shared Schema Decoders
+
+`createSchemaDecoder(schema)` derives a decoder's output type from a TypeBox
+schema, including transforms. Invalid values throw a sanitized
+`SchemaContractError`. `defineJsonContract({ body, response }, request)` creates
+decoders compatible with `HttpClient.execute` while retaining the same schemas
+for route registration. Keep schemas independently importable and reference
+their identifiers explicitly in compiler-analyzed route decorators.
+
+For hand-written Elysia routes, `defineRouteContract` and
+`defineElysiaRoute` provide contextual handler types from the same schema value.
+`registerElysiaRoute` maps the contract's `responses` status map to Elysia's
+`response` option and registers the route:
+
+```ts
+import { Elysia, t } from "elysia";
+import {
+  defineElysiaRoute,
+  defineRouteContract,
+  registerElysiaRoute,
+} from "@supacloud/elysia";
+
+const itemRoute = defineRouteContract({
+  body: t.Object({ name: t.String() }),
+  params: t.Object({ id: t.String() }),
+  responses: {
+    200: t.Object({ id: t.String(), name: t.String() }),
+    409: t.Object({ conflict: t.Literal(true) }),
+  },
+});
+
+const route = defineElysiaRoute("POST", "/items/:id", itemRoute, ({ body, params, status }) =>
+  body.name === "existing"
+    ? status(409, { conflict: true })
+    : { id: params.id, name: body.name },
+);
+
+const app = registerElysiaRoute(new Elysia(), route);
+```
+
+The callback is typed from the contract (including decoded transforms and
+declared response statuses). Cookie values retain Elysia's native shape, so a
+declared `session: t.String()` is read as `cookie.session.value`. This helper
+does not add Eden-style client inference to an existing Elysia instance; the
+compiler-generated client remains the source of transport types.
+
+Response maps may use concrete statuses, `1XX`-`5XX` families, and `default`.
+Because Elysia 1.4 only compiles numeric response keys, the adapter expands
+family/default entries to concrete validators before registration. Exact
+statuses take precedence over families, which take precedence over `default`.
+An actual status absent from a structured response map fails the route contract
+before Elysia can silently accept a default `200`; binary/stream routes may
+intentionally leave successful transport statuses unschematized when only their
+JSON error responses are declared. Unsupported selectors fail during
+registration instead of silently disabling response validation.
+
+See [type safety and migration](../../docs/type-safety.md) and [command migration](../../docs/command-migration.md) for examples and
+the distinction between contract declarations and runtime verification.

package/dist/command-errors.d.ts

@@ -0,0 +1,2 @@
+import type { CommandErrorCode } from "@supacloud/contracts";
+export declare function commandErrorStatus(code: CommandErrorCode): number;

package/dist/documentation.d.ts

@@ -0,0 +1,29 @@
+import { Elysia } from "elysia";
+export type DocumentationSource<T> = T | (() => T | Promise<T>);
+export interface OpenApiDocumentationOptions {
+    /** Generated OpenAPI document, usually imported from generated/openapi.ts. */
+    document: DocumentationSource<unknown>;
+    /** JSON specification endpoint. */
+    specPath?: string;
+    /** Human-readable documentation page. */
+    uiPath?: string;
+    title?: string;
+}
+export interface GraphqlDocumentationOptions {
+    /** Role-scoped SDL snapshot, usually loaded from graphql/schema.graphql. */
+    schema: DocumentationSource<string>;
+    /** SDL endpoint. */
+    schemaPath?: string;
+    /** Human-readable schema page. */
+    uiPath?: string;
+    title?: string;
+}
+export interface ApplicationDocumentationOptions {
+    openApi?: OpenApiDocumentationOptions;
+    graphql?: GraphqlDocumentationOptions;
+}
+/**
+ * Mount opt-in, read-only documentation endpoints for a compiled application.
+ * The plugin has no external UI dependency and does not enable GraphQL introspection.
+ */
+export declare function createDocumentationPlugin(options?: ApplicationDocumentationOptions): Elysia;

package/dist/execution.d.ts

@@ -10,3 +10,4 @@ export interface ExecutionEvent {
 export type ExecutionObserver = (event: Readonly<ExecutionEvent>) => void | Promise<void>;
 export declare function observeExecution<T>(observer: ExecutionObserver | undefined, event: Pick<ExecutionEvent, "kind" | "operation" | "stage" | "requestId">, next: () => T | Promise<T>): Promise<T>;
 export declare function executionRequestId(context: unknown): string | undefined;
+export declare function executionTrace(context: unknown): Pick<ExecutionEvent, "requestId">;

package/dist/fixtures/webhook/contracts.d.ts

@@ -0,0 +1,42 @@
+export declare const WebhookInputSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    enabled: import("@sinclair/typebox").TBoolean;
+}>;
+export declare const WebhookHeadersSchema: import("@sinclair/typebox").TObject<{
+    "idempotency-key": import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare const decodeWebhookInput: (value: unknown) => {
+    id: string;
+    enabled: boolean;
+};
+export declare const WebhookReceiptSchema: import("@sinclair/typebox").TObject<{
+    tenantId: import("@sinclair/typebox").TString;
+    actorId: import("@sinclair/typebox").TString;
+    command: import("@sinclair/typebox").TLiteral<"webhook.update.v1">;
+    operationId: import("@sinclair/typebox").TString;
+    dispatchKey: import("@sinclair/typebox").TString;
+    status: import("@sinclair/typebox").TLiteral<"confirmed">;
+    audit: import("@sinclair/typebox").TLiteral<"complete">;
+    result: import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        enabled: import("@sinclair/typebox").TBoolean;
+    }>;
+}>;
+export declare const WebhookKeySchema: import("@sinclair/typebox").TObject<{
+    key: import("@sinclair/typebox").TString;
+}>;
+export declare const WebhookLookupSchema: import("@sinclair/typebox").TObject<{
+    receipt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+        tenantId: import("@sinclair/typebox").TString;
+        actorId: import("@sinclair/typebox").TString;
+        command: import("@sinclair/typebox").TLiteral<"webhook.update.v1">;
+        operationId: import("@sinclair/typebox").TString;
+        dispatchKey: import("@sinclair/typebox").TString;
+        status: import("@sinclair/typebox").TLiteral<"confirmed">;
+        audit: import("@sinclair/typebox").TLiteral<"complete">;
+        result: import("@sinclair/typebox").TObject<{
+            id: import("@sinclair/typebox").TString;
+            enabled: import("@sinclair/typebox").TBoolean;
+        }>;
+    }>, import("@sinclair/typebox").TNull]>;
+}>;

package/dist/fixtures/webhook/environment.d.ts

@@ -0,0 +1,11 @@
+import { InjectionToken } from "@supacloud/app";
+import type { CommandAuthorization, CommandIdentity } from "@supacloud/contracts";
+import type { CommandStore } from "@supacloud/commands";
+import type { CommandTransaction } from "@supacloud/db";
+export declare class WebhookEnvironment {
+    readonly store: CommandStore<CommandTransaction>;
+    readonly authorize: (identity: CommandIdentity, tx: CommandTransaction) => Promise<CommandAuthorization>;
+    readonly writeAudit: (tx: CommandTransaction) => Promise<void>;
+    constructor(store: CommandStore<CommandTransaction>, authorize: (identity: CommandIdentity, tx: CommandTransaction) => Promise<CommandAuthorization>, writeAudit: (tx: CommandTransaction) => Promise<void>);
+}
+export declare const WEBHOOK_ENVIRONMENT: InjectionToken<WebhookEnvironment>;

package/dist/fixtures/webhook/update.command.d.ts

@@ -0,0 +1,13 @@
+import { type CommandIdentity } from "@supacloud/contracts";
+export declare class UpdateWebhook {
+    private readonly executor;
+    constructor(environment: unknown);
+    execute(identity: CommandIdentity, key: string, input: unknown): Promise<import("@supacloud/contracts").DurableCommandReceipt<{
+        id: string;
+        enabled: boolean;
+    }>>;
+    receipt(identity: CommandIdentity, key: string): Promise<import("@supacloud/contracts").DurableCommandReceipt<{
+        id: string;
+        enabled: boolean;
+    }> | null>;
+}

package/dist/fixtures/webhook/webhook.controller.d.ts

@@ -0,0 +1,15 @@
+export declare class WebhookController {
+    private readonly context;
+    private readonly command;
+    constructor(command: unknown, context: unknown);
+    update(input: unknown, key: unknown): Promise<import("@supacloud/contracts").DurableCommandReceipt<{
+        id: string;
+        enabled: boolean;
+    }>>;
+    receipt(key: unknown): Promise<{
+        receipt: import("@supacloud/contracts").DurableCommandReceipt<{
+            id: string;
+            enabled: boolean;
+        }> | null;
+    }>;
+}

package/dist/fixtures/webhook/webhook.module.d.ts

@@ -0,0 +1,2 @@
+export declare class WebhookModule {
+}

package/dist/fixtures/webhook-generated/application.d.ts

@@ -0,0 +1,100 @@
+export interface CompiledRoute {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    path: string;
+    handler: string;
+    body?: unknown;
+    params?: unknown;
+    query?: unknown;
+    headers?: unknown;
+    cookie?: unknown;
+    response?: unknown;
+    responses?: Record<string | number, unknown>;
+    /** Compile-time ownership and transport classification for the route boundary. */
+    contract?: {
+        body?: "framework" | "domain";
+        response?: "framework" | "native-json" | "binary" | "stream";
+        evidence?: string;
+    };
+    /** Whether each declared schema is concrete or intentionally opaque. */
+    schemaKinds?: Partial<Record<"body" | "params" | "query" | "headers" | "cookie" | "response", "opaque" | "declared">>;
+    /** True when the handler returns a native Response rather than a framework value. */
+    nativeResponse?: boolean;
+    command?: string;
+    guards?: string[];
+    canMatch?: string[];
+    canDeactivate?: string[];
+    resolvers?: Record<string, string>;
+    redirectTo?: string;
+    pathMatch?: "full" | "prefix";
+    paramTransforms?: Record<string, "number" | "boolean" | "string">;
+    paramDefaults?: Record<string, unknown>;
+    queryTransforms?: Record<string, "number" | "boolean" | "string">;
+    queryDefaults?: Record<string, unknown>;
+    title?: string;
+    data?: Record<string, unknown>;
+    aspects?: CompiledAspect[];
+    invoker?: (controller: unknown, request: {
+        params?: Record<string, unknown>;
+        query?: Record<string, unknown>;
+        body?: unknown;
+        headers?: Record<string, unknown>;
+        cookie?: Record<string, unknown>;
+        context?: unknown;
+    }) => Promise<unknown> | unknown;
+}
+export interface CompiledCommand {
+    rpc?: string;
+    className: string;
+    name: string;
+    permission: string;
+    transaction: "required" | "none";
+    audit?: string;
+    idempotency: "required" | "none";
+    standalone?: boolean;
+    aspects?: CompiledAspect[];
+}
+export interface CompiledJob {
+    className: string;
+    name: string;
+    serviceKey: string;
+    scope: "application" | "request" | "job";
+    input?: unknown;
+    output?: unknown;
+    mode?: "task" | "workflow";
+    timeoutSec?: number;
+    maxAttempts?: number;
+    idempotency?: "required" | "none";
+    aspects?: CompiledAspect[];
+}
+export interface CompiledAspectContext {
+    kind: "route" | "command" | "job";
+    name: string;
+    input: unknown;
+    request?: Request;
+    requestContext?: unknown;
+    scope?: Record<string, unknown>;
+    services?: Record<string, unknown>;
+    metadata?: unknown;
+}
+export type CompiledAspect = (context: CompiledAspectContext, next: () => unknown | Promise<unknown>) => unknown | Promise<unknown>;
+export interface CompiledController {
+    path: string;
+    serviceKey: string;
+    scope: "application" | "request" | "job";
+    routes: CompiledRoute[];
+}
+export interface CompiledModule {
+    name: string;
+    createServices(deps: Record<string, unknown>, imported: Record<string, Record<string, unknown>>): Record<string, unknown>;
+    createRequestScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Promise<Record<string, unknown>>;
+    destroyRequestScope?(scope: Record<string, unknown>): Promise<void>;
+    createJobScope?(services: Record<string, unknown>, ctx: unknown, imported?: Record<string, Record<string, unknown>>): Promise<Record<string, unknown>>;
+    destroyJobScope?(scope: Record<string, unknown>): Promise<void>;
+    controllers: CompiledController[];
+    commands: CompiledCommand[];
+    jobs: CompiledJob[];
+    aspects?: CompiledAspect[];
+}
+export declare function createCompiledModules(): CompiledModule[];
+export declare function initializeApplication(services: Record<string, unknown>): Promise<void>;
+export declare function destroyApplication(services: Record<string, unknown>): Promise<void>;

package/dist/generate-webhook-example.d.ts

@@ -0,0 +1,19 @@
+export declare const webhookCompileOptions: {
+    rootDir: string;
+    outDir: string;
+    strict: true;
+    requireRouteContracts: true;
+    allowRouteCommandBindings: false;
+    commandCapabilities: {
+        requirePersistentAdapters: true;
+        permission: true;
+        rpc: {
+            webhookUpdate: {
+                boundary: "database";
+                audit: true;
+                transaction: true;
+                idempotency: true;
+            };
+        };
+    };
+};

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 import { Elysia } from "elysia";
+import { type CommandPreview } from "@supacloud/contracts";
+import { type EnvironmentInjector } from "@supacloud/app";
 import { type ExecutionObserver } from "./execution";
+import { type ApplicationDocumentationOptions } from "./documentation";
 export type { ExecutionEvent, ExecutionObserver } from "./execution";
+export { createSchemaDecoder, assertResponseStatusDeclared, defineElysiaRoute, defineJsonContract, defineRouteContract, registerElysiaRoute, responseSchemaForStatus, responseStatusDeclared, responseStatusOf, SchemaContractError, toElysiaRouteSchema, } from "./schema_contract";
+export type { ElysiaRouteContext, ElysiaRouteDefinition, ElysiaRouteHandler, ElysiaRouteSchema, ResponseMapSelector, RouteContractSchemas, SchemaDecoderOptions, SchemaNormalizeMode, } from "./schema_contract";
+export { createPersistentCommandAdapter, type PersistentCommandHandler } from "./persistent-command";
+export { createDocumentationPlugin } from "./documentation";
+export type { ApplicationDocumentationOptions, DocumentationSource, GraphqlDocumentationOptions, OpenApiDocumentationOptions, } from "./documentation";
 export interface CompiledRoute {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     path: string;
@@ -10,13 +18,28 @@ export interface CompiledRoute {
     body?: unknown;
     params?: unknown;
     query?: unknown;
+    headers?: unknown;
+    cookie?: unknown;
+    /** @deprecated Use `responses` with an explicit HTTP status map. */
     response?: unknown;
+    responses?: Record<string | number, unknown>;
+    /** Compile-time ownership and transport classification for the route boundary. */
+    contract?: {
+        body?: "framework" | "domain";
+        response?: "framework" | "native-json" | "binary" | "stream";
+        evidence?: string;
+    };
+    /** Whether each declared schema is concrete or intentionally opaque. */
+    schemaKinds?: Partial<Record<"body" | "params" | "query" | "headers" | "cookie" | "response", "opaque" | "declared">>;
+    /** True when the handler returns a native Response rather than a framework value. */
+    nativeResponse?: boolean;
     /** Compiler-emitted positional invoker; used when available. */
     invoker?: (controller: unknown, request: {
         params?: Record<string, unknown>;
         query?: Record<string, unknown>;
         body?: unknown;
         headers?: Record<string, unknown>;
+        cookie?: Record<string, unknown>;
         context?: unknown;
     }) => Promise<unknown> | unknown;
     /** Class name of the @Command explicitly bound to this route. */
@@ -40,6 +63,14 @@ export interface CompiledJob {
     name: string;
     serviceKey: string;
     scope: "application" | "request" | "job";
+    /** TypeBox input schema emitted by the compiler. */
+    input?: unknown;
+    /** TypeBox output schema emitted by the compiler. */
+    output?: unknown;
+    mode?: "task" | "workflow";
+    timeoutSec?: number;
+    maxAttempts?: number;
+    idempotency?: "required" | "none";
     aspects?: ApplicationAspect[];
 }
 export interface CompiledController {
@@ -127,6 +158,7 @@ export interface CommandGovernance {
             audit?: boolean;
             transaction?: boolean;
             idempotency?: boolean;
+            boundary?: "database" | "external";
         };
         execute: CommandMiddleware;
     }>;
@@ -173,10 +205,14 @@ export interface ErrorContext {
 export type ErrorMapper = (error: unknown, context: ErrorContext) => Response | undefined | Promise<Response | undefined>;
 export interface ApplicationOptions {
     name?: string;
+    /** false rejects extra schema properties instead of silently removing them. */
+    normalize?: boolean;
     /** Modules in topological import order. */
     modules?: CompiledModule[];
     /** Platform-level dependencies (db client etc.), passed to createServices. */
     deps?: Record<string, unknown>;
+    /** Optional Angular-backed root injector used for async request contexts. */
+    injector?: EnvironmentInjector;
     /** Builds the per-request context object. Defaults to { requestId, request }. */
     requestContext?: RequestContextFactory;
     /** Enforces permission/audit/idempotency policy for command-bound routes. */
@@ -187,6 +223,8 @@ export interface ApplicationOptions {
     errorMapper?: ErrorMapper;
     /** Best-effort execution metadata only; durable audit belongs to governance. */
     onExecution?: ExecutionObserver;
+    /** Optional read-only OpenAPI and GraphQL documentation endpoints. */
+    documentation?: ApplicationDocumentationOptions;
 }
 export interface JobInvocation {
     job: CompiledJob;
@@ -222,6 +260,18 @@ export declare function executeCompiledCommand<Input, Result>(options: {
     handler: (input: Input) => Result | Promise<Result>;
     decode: (value: unknown) => Result;
 }): Promise<Result>;
+/** Read-only actionability. Accepts the same governance object as execute, but only runs authorize. */
+export declare function previewCompiledCommand<Input>(options: {
+    module: Pick<CompiledModule, "name" | "commands">;
+    command: string;
+    input: Input;
+    request: Request;
+    requestContext: unknown;
+    services?: Record<string, unknown>;
+    scope?: Record<string, unknown>;
+    governance: CommandGovernance;
+    preview: (input: Input) => unknown;
+}): Promise<CommandPreview>;
 export declare function requireTrustedIdentity(requestContext: unknown): Required<Pick<TrustedRequestIdentity, "subject" | "accessToken">> & TrustedRequestIdentity;
 export declare function requireIdempotencyKey(invocation: CommandInvocation): string;
 /**
@@ -232,7 +282,7 @@ export declare function requireIdempotencyKey(invocation: CommandInvocation): st
  * exposed on the `scope` context key. Request-scoped controller instances are
  * looked up on `scope`, everything else on `services`.
  */
-export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory, options?: Pick<ApplicationOptions, "commandGovernance" | "commandExecutor" | "errorMapper" | "onExecution">, imported?: Record<string, Record<string, unknown>>): Elysia;
+export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory, options?: Pick<ApplicationOptions, "commandGovernance" | "commandExecutor" | "errorMapper" | "onExecution" | "normalize" | "injector">, imported?: Record<string, Record<string, unknown>>): Elysia;
 /**
  * Execute one compiler-emitted Job descriptor.
  *
@@ -256,3 +306,5 @@ export { createMemorySandbox, } from "./memory";
 export type { HandleLike as MemoryHandleLike, MemoryDatabase, MemorySandbox, MemorySandboxOptions, MemoryStorage, MemoryStorageObject, } from "./memory";
 export { createMemoryPolicy } from "./memory_policy";
 export type { MemoryPolicy } from "./memory_policy";
+export { createQueueWorkerTransport, createWorker, SupaCloudWorker, WorkerRegistrationError, WorkerReceiptUnconfirmedError, } from "./worker";
+export type { WorkerAcknowledge, WorkerClaim, WorkerFail, WorkerOptions, QueueWorkerTransportOptions, WorkerQueueFailureOptions, WorkerQueueMessage, WorkerQueuePort, WorkerQueueReceiveOptions, WorkerReceiptContext, WorkerReceiptOperation, WorkerRunResult, WorkerState, WorkerTransport, } from "./worker";