@supacloud/elysia 0.9.0 → 0.14.1

package/dist/index.js

@@ -1,6 +1,503 @@
 // src/index.ts
-import { Elysia } from "elysia";
+import { Elysia as Elysia2 } from "elysia";
+import { CommandError as CommandError2, decodeCommandPreview } from "@supacloud/contracts";
+import {
+  provideToken,
+  runInRequestContext
+} from "@supacloud/app";
+import { REQUEST_CONTEXT } from "@supacloud/app";
+
+// src/command-errors.ts
+function commandErrorStatus(code) {
+  switch (code) {
+    case "COMMAND_INPUT_INVALID":
+      return 400;
+    case "COMMAND_REJECTED":
+      return 403;
+    case "COMMAND_IDEMPOTENCY_CONFLICT":
+      return 409;
+    case "COMMAND_INPUT_EXPIRED":
+      return 410;
+    case "COMMAND_UNAVAILABLE":
+    case "COMMAND_RECEIPT_INVALID":
+    case "COMMAND_OUTCOME_UNKNOWN":
+      return 503;
+  }
+}
+
+// src/execution.ts
+async function observeExecution(observer, event, next) {
+  const emit = (phase, durationMs) => {
+    if (!observer)
+      return;
+    try {
+      Promise.resolve(observer(Object.freeze({
+        ...event,
+        phase,
+        ...durationMs === undefined ? {} : { durationMs }
+      }))).catch(() => {});
+    } catch {}
+  };
+  const started = performance.now();
+  emit("started");
+  try {
+    const result = await next();
+    emit("succeeded", performance.now() - started);
+    return result;
+  } catch (error) {
+    emit("failed", performance.now() - started);
+    throw error;
+  }
+}
+function executionRequestId(context) {
+  if (!context || typeof context !== "object" || !("requestId" in context))
+    return;
+  const value = context.requestId;
+  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
+}
+function executionTrace(context) {
+  const requestId = executionRequestId(context);
+  return requestId === undefined ? {} : { requestId };
+}
 
+// src/schema_contract.ts
+import {
+  getSchemaValidator,
+  StatusMap,
+  ElysiaCustomStatusResponse
+} from "elysia";
+function defineRouteContract(schemas) {
+  return Object.freeze({ ...schemas });
+}
+var TYPEBOX_KIND = Symbol.for("TypeBox.Kind");
+var RESPONSE_STATUS_MIN = 100;
+var RESPONSE_STATUS_MAX = 599;
+var RESPONSE_FAMILY_PATTERN = /^([1-5])(?:xx|XX)$/;
+var RESPONSE_STATUS_PATTERN = /^[1-5]\d{2}$/;
+function isSchema(value) {
+  return value !== null && typeof value === "object" && ((TYPEBOX_KIND in value) || ("~standard" in value));
+}
+function isJsonSchemaObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return false;
+  return [
+    "$schema",
+    "$id",
+    "$ref",
+    "$defs",
+    "definitions",
+    "type",
+    "properties",
+    "patternProperties",
+    "required",
+    "items",
+    "prefixItems",
+    "contains",
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "not",
+    "enum",
+    "const",
+    "additionalProperties",
+    "minLength",
+    "maxLength",
+    "minimum",
+    "maximum",
+    "format",
+    "pattern"
+  ].some((key) => (key in value));
+}
+function invalidResponseSelector(selector) {
+  throw new TypeError(`Unsupported response selector "${selector}". Use an HTTP status (100-599), ` + "a status family such as 4XX/5XX, or default.");
+}
+function conflictingResponseSchemas() {
+  throw new TypeError("Route contracts cannot declare both response and responses. " + "Remove response and use responses: { 200: Schema }.");
+}
+function duplicateResponseSelector(selector, existing) {
+  throw new TypeError(`Duplicate response selectors "${existing}" and "${selector}" differ only by case. ` + `Keep one ${selector.toUpperCase()} selector.`);
+}
+function responseSchemaForStatus(responses, status) {
+  const exact = Object.hasOwn(responses, status) ? responses[status] : Object.hasOwn(responses, String(status)) ? responses[String(status)] : undefined;
+  if (exact !== undefined || Object.hasOwn(responses, status) || Object.hasOwn(responses, String(status))) {
+    return exact;
+  }
+  const family = `${Math.floor(status / 100)}XX`;
+  if (Object.hasOwn(responses, family))
+    return responses[family];
+  const lowerFamily = family.toLowerCase();
+  if (Object.hasOwn(responses, lowerFamily))
+    return responses[lowerFamily];
+  return Object.hasOwn(responses, "default") ? responses.default : undefined;
+}
+function responseStatusDeclared(responses, status) {
+  return responseSchemaForStatus(responses, status) !== undefined || Object.hasOwn(responses, status) || Object.hasOwn(responses, String(status));
+}
+function responseStatusOf(value, configuredStatus) {
+  if (value instanceof Response)
+    return value.status;
+  if (value instanceof ElysiaCustomStatusResponse) {
+    const code = value.code;
+    if (typeof code === "number" && Number.isInteger(code) && code >= RESPONSE_STATUS_MIN && code <= RESPONSE_STATUS_MAX) {
+      return code;
+    }
+  }
+  if (typeof configuredStatus === "number")
+    return configuredStatus;
+  if (typeof configuredStatus === "string") {
+    const mapped = StatusMap[configuredStatus];
+    if (typeof mapped === "number")
+      return mapped;
+  }
+  return 200;
+}
+function assertResponseStatusDeclared(responses, status) {
+  if (responseStatusDeclared(responses, status))
+    return;
+  throw new TypeError("Response validation failed");
+}
+function toElysiaResponseMap(responses) {
+  const exact = new Map;
+  const families = new Map;
+  const familySelectors = new Map;
+  let defaultSchema;
+  let hasDefault = false;
+  let requiresExpansion = false;
+  for (const [selector, schema] of Object.entries(responses)) {
+    if (RESPONSE_STATUS_PATTERN.test(selector)) {
+      exact.set(Number(selector), schema);
+      continue;
+    }
+    if (selector === "default") {
+      defaultSchema = schema;
+      hasDefault = true;
+      requiresExpansion = true;
+      continue;
+    }
+    const family = RESPONSE_FAMILY_PATTERN.exec(selector);
+    if (family) {
+      const canonicalSelector = selector.toLowerCase();
+      const existingSelector = familySelectors.get(canonicalSelector);
+      if (existingSelector !== undefined)
+        duplicateResponseSelector(selector, existingSelector);
+      familySelectors.set(canonicalSelector, selector);
+      families.set(Number(family[1]), schema);
+      requiresExpansion = true;
+      continue;
+    }
+    invalidResponseSelector(selector);
+  }
+  if (!requiresExpansion)
+    return responses;
+  const expanded = {};
+  if (hasDefault) {
+    for (let status = RESPONSE_STATUS_MIN;status <= RESPONSE_STATUS_MAX; status++) {
+      expanded[status] = defaultSchema;
+    }
+  }
+  for (const [family, schema] of families) {
+    const first = family * 100;
+    for (let status = first;status < first + 100; status++)
+      expanded[status] = schema;
+  }
+  for (const [status, schema] of exact)
+    expanded[status] = schema;
+  return expanded;
+}
+function toElysiaResponseSchema(response) {
+  if (typeof response === "string" || isSchema(response) || isJsonSchemaObject(response))
+    return response;
+  if (response === null || typeof response !== "object" || Array.isArray(response))
+    return response;
+  return toElysiaResponseMap(response);
+}
+function toElysiaRouteSchema(contract) {
+  if (contract.response !== undefined && contract.responses !== undefined) {
+    conflictingResponseSchemas();
+  }
+  const schema = {};
+  if (contract.body !== undefined)
+    schema.body = contract.body;
+  if (contract.params !== undefined)
+    schema.params = contract.params;
+  if (contract.query !== undefined)
+    schema.query = contract.query;
+  if (contract.headers !== undefined)
+    schema.headers = contract.headers;
+  if (contract.cookie !== undefined)
+    schema.cookie = contract.cookie;
+  if (contract.responses !== undefined)
+    schema.response = toElysiaResponseMap(contract.responses);
+  else if (contract.response !== undefined)
+    schema.response = toElysiaResponseSchema(contract.response);
+  return schema;
+}
+function defineElysiaRoute(method, path, contract, handler) {
+  toElysiaRouteSchema(contract);
+  const stableContract = Object.isFrozen(contract) ? contract : Object.freeze(contract);
+  return Object.freeze({
+    method,
+    path,
+    contract: stableContract,
+    handler
+  });
+}
+function registerElysiaRoute(app, route) {
+  const handler = async (context) => {
+    const value = await route.handler(context);
+    if (route.contract.responses !== undefined) {
+      const status = responseStatusOf(value, context.set.status);
+      assertResponseStatusDeclared(route.contract.responses, status);
+    }
+    return value;
+  };
+  app.route(route.method, route.path, handler, toElysiaRouteSchema(route.contract));
+  return app;
+}
+
+class SchemaContractError extends Error {
+  code = "SCHEMA_CONTRACT_INVALID";
+  constructor() {
+    super("Schema contract validation failed");
+    this.name = "SchemaContractError";
+  }
+}
+function createSchemaDecoder(schema, options = {}) {
+  const validator = getSchemaValidator(schema, {
+    coerce: options.coerce ?? false,
+    normalize: options.normalize ?? true
+  });
+  return (value) => {
+    try {
+      return validator.parse(value);
+    } catch {
+      throw new SchemaContractError;
+    }
+  };
+}
+function defineJsonContract(schemas, request, options = {}) {
+  return Object.freeze({
+    ...schemas,
+    input: createSchemaDecoder(schemas.body, options),
+    result: createSchemaDecoder(schemas.response, options),
+    request
+  });
+}
+
+// src/documentation.ts
+import { Elysia } from "elysia";
+function normalizePath(value, fallback) {
+  const path = value ?? fallback;
+  if (!path.trim() || !path.startsWith("/") || path.includes("?") || path.includes("#")) {
+    throw new Error(`Documentation path must be an absolute path without query or fragment: ${path}`);
+  }
+  return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+function resolveSource(source) {
+  if (typeof source === "function") {
+    return Promise.resolve(source());
+  }
+  return Promise.resolve(source);
+}
+function jsonResponse(document) {
+  if (document === null || typeof document !== "object" || Array.isArray(document)) {
+    throw new Error("OpenAPI documentation must be a JSON object");
+  }
+  const serialized = JSON.stringify(document);
+  if (serialized === undefined)
+    throw new Error("OpenAPI documentation must be JSON-serializable");
+  return new Response(serialized, {
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+function textResponse(schema) {
+  return new Response(schema, {
+    headers: { "content-type": "text/plain; charset=utf-8" }
+  });
+}
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;"
+  })[character] ?? character);
+}
+function scriptString(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function renderViewerPage(title, resourcePath, mode) {
+  const parse = mode === "json" ? "const value = await response.json(); output.textContent = JSON.stringify(value, null, 2);" : "output.textContent = await response.text();";
+  const safeTitle = escapeHtml(title);
+  const safeResourcePath = escapeHtml(resourcePath);
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${safeTitle}</title>
+  <style>
+    :root { color-scheme: light dark; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+    body { margin: 0; padding: 24px; background: Canvas; color: CanvasText; }
+    header { display: flex; gap: 16px; align-items: baseline; flex-wrap: wrap; }
+    h1 { font: 600 20px system-ui, sans-serif; margin: 0; }
+    a { color: LinkText; }
+    pre { white-space: pre-wrap; overflow-wrap: anywhere; line-height: 1.5; }
+  </style>
+</head>
+<body>
+  <header><h1>${safeTitle}</h1><a href="${safeResourcePath}">${safeResourcePath}</a></header>
+  <pre id="output">Loading...</pre>
+  <script>
+    const output = document.getElementById("output");
+    fetch(${scriptString(resourcePath)}, { headers: { "accept": "${mode === "json" ? "application/json" : "text/plain"}" } })
+      .then(async (response) => {
+        if (!response.ok) throw new Error("HTTP " + response.status);
+        ${parse}
+      })
+      .catch((error) => { output.textContent = "Unable to load documentation: " + error.message; });
+  </script>
+</body>
+</html>`;
+}
+function createDocumentationPlugin(options = {}) {
+  const app = new Elysia({ name: "supacloud:documentation" });
+  const paths = new Set;
+  const reserve = (path) => {
+    if (paths.has(path))
+      throw new Error(`Duplicate documentation path: ${path}`);
+    paths.add(path);
+  };
+  if (options.openApi) {
+    const specPath = normalizePath(options.openApi.specPath, "/openapi.json");
+    const uiPath = normalizePath(options.openApi.uiPath, "/docs");
+    reserve(specPath);
+    reserve(uiPath);
+    const title = options.openApi.title ?? "OpenAPI Documentation";
+    app.get(specPath, async () => jsonResponse(await resolveSource(options.openApi.document)), {
+      detail: { hide: true }
+    });
+    app.get(uiPath, () => new Response(renderViewerPage(title, specPath, "json"), {
+      headers: { "content-type": "text/html; charset=utf-8" }
+    }), { detail: { hide: true } });
+  }
+  if (options.graphql) {
+    const schemaPath = normalizePath(options.graphql.schemaPath, "/graphql/schema.graphql");
+    const uiPath = normalizePath(options.graphql.uiPath, "/graphql/docs");
+    reserve(schemaPath);
+    reserve(uiPath);
+    const title = options.graphql.title ?? "GraphQL Schema";
+    app.get(schemaPath, async () => textResponse(await resolveSource(options.graphql.schema)), {
+      detail: { hide: true }
+    });
+    app.get(uiPath, () => new Response(renderViewerPage(title, schemaPath, "text"), {
+      headers: { "content-type": "text/html; charset=utf-8" }
+    }), { detail: { hide: true } });
+  }
+  return app;
+}
+// src/persistent-command.ts
+import {
+  CommandError,
+  decodeCommandIdentity
+} from "@supacloud/contracts";
+function createPersistentCommandAdapter(command, options) {
+  return {
+    capabilities: {
+      audit: true,
+      idempotency: true,
+      transaction: command.kind === "transactional",
+      boundary: command.kind === "transactional" ? "database" : "external"
+    },
+    async execute(invocation) {
+      try {
+        const identity = decodeCommandIdentity(await options.identity(invocation));
+        return await command.execute(identity, requireIdempotencyKey(invocation), options.input(invocation));
+      } catch (error) {
+        if (!(error instanceof CommandError))
+          throw error;
+        const status = commandErrorStatus(error.code);
+        throw new ApplicationError(error.code, { code: error.code, status });
+      }
+    }
+  };
+}
+// src/identity.ts
+import { createRemoteJWKSet, jwtVerify, errors } from "jose";
+function httpsUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || url.hash) {
+    throw new TypeError("Identity endpoints must be HTTPS URLs without credentials or fragments");
+  }
+  return url;
+}
+function createSupAuthRequestContext(options) {
+  httpsUrl(options.issuer);
+  const jwksUrl = httpsUrl(options.jwksUrl);
+  if (!options.audience.trim() || !options.projectId.trim() || !options.clientId?.trim()) {
+    throw new TypeError("SupAuth audience, clientId and projectId are required");
+  }
+  const algorithms = [...options.algorithms ?? ["ES256", "RS256"]];
+  if (!algorithms.length || algorithms.some((value) => value !== "ES256" && value !== "RS256")) {
+    throw new TypeError("SupAuth requires ES256 or RS256");
+  }
+  const { issuer, audience, clientId, projectId, resolveAccess } = options;
+  const keyResolver = options.keyResolver ?? createRemoteJWKSet(jwksUrl, { timeoutDuration: 5000 });
+  return async (request) => {
+    const match = request.headers.get("authorization")?.match(/^Bearer ([^\s]+)$/i);
+    const token = match?.[1];
+    if (!token || token.length > 16384)
+      throw unauthenticated();
+    let subject;
+    try {
+      const { payload } = await jwtVerify(token, keyResolver, {
+        issuer,
+        audience,
+        algorithms,
+        requiredClaims: ["sub", "exp", "iat"]
+      });
+      if (typeof payload.sub !== "string" || !payload.sub.trim() || payload.sub.length > 1024 || /[\u0000-\u001f\u007f]/.test(payload.sub)) {
+        throw unauthenticated();
+      }
+      const application = payload.client_id ?? payload.azp;
+      if (application !== clientId || payload.role !== "authenticated" || payload.client_id !== undefined && payload.client_id !== clientId || payload.azp !== undefined && payload.azp !== clientId) {
+        throw unauthenticated();
+      }
+      subject = payload.sub;
+    } catch (error) {
+      if (error instanceof ApplicationError || error instanceof errors.JWTClaimValidationFailed || error instanceof errors.JWTExpired || error instanceof errors.JWTInvalid || error instanceof errors.JWSInvalid || error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JOSEAlgNotAllowed || error instanceof errors.JOSENotSupported || error instanceof errors.JWKSNoMatchingKey)
+        throw unauthenticated();
+      throw new ApplicationError("Identity verification service unavailable", {
+        status: 503,
+        code: "AUTHENTICATION_UNAVAILABLE"
+      });
+    }
+    const identity = { authenticated: true, subject, issuer, clientId };
+    Object.defineProperty(identity, "accessToken", { value: token, enumerable: false });
+    Object.freeze(identity);
+    const access = await resolveAccess(identity, request);
+    if (!access || access.projectId !== projectId || typeof access.tenantId !== "string" || !access.tenantId.trim() || !Array.isArray(access.permissions) || access.permissions.some((permission) => typeof permission !== "string" || !permission.trim())) {
+      throw new ApplicationError("Application access denied", { status: 403, code: "APPLICATION_ACCESS_DENIED" });
+    }
+    const context = createSupaCloudRequestContext(request);
+    return {
+      ...context,
+      identity,
+      access: Object.freeze({
+        projectId,
+        tenantId: access.tenantId,
+        permissions: Object.freeze([...new Set(access.permissions)])
+      })
+    };
+  };
+}
+function unauthenticated() {
+  return new ApplicationError("Authenticated user context is required", {
+    status: 401,
+    code: "AUTHENTICATION_REQUIRED"
+  });
+}
 // src/feature.ts
 function assertFeatureTransition(spec, state, event) {
   const transition = Object.hasOwn(spec.transitions, event) ? spec.transitions[event] : undefined;
@@ -347,6 +844,401 @@ function cloneTables(tables) {
 function cloneValue(value) {
   return structuredClone(value);
 }
+// src/worker.ts
+function workerFailureMessage(error) {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Worker job failed";
+  const normalized = message.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+  return (normalized || "Worker job failed").slice(0, 4096);
+}
+function createQueueWorkerTransport(options) {
+  if (!options.queue || typeof options.queue.receive !== "function" || typeof options.queue.ack !== "function" || typeof options.queue.fail !== "function" || typeof options.decodeClaim !== "function" || typeof options.messageId !== "function") {
+    throw new TypeError("Queue worker transport requires queue, decodeClaim and messageId");
+  }
+  const receiveOptions = options.receive === undefined ? undefined : { ...options.receive };
+  return {
+    claim: async (signal) => {
+      signal.throwIfAborted();
+      const message = await options.queue.receive(receiveOptions);
+      signal.throwIfAborted();
+      return message === null ? null : options.decodeClaim(message);
+    },
+    ack: (claim) => options.queue.ack(options.messageId(claim)),
+    fail: (claim, error) => options.queue.fail(options.messageId(claim), {
+      error: workerFailureMessage(error)
+    })
+  };
+}
+
+class WorkerRegistrationError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "WorkerRegistrationError";
+    this.code = code;
+  }
+}
+
+class WorkerReceiptUnconfirmedError extends Error {
+  operation;
+  claimId;
+  code = "WORKER_RECEIPT_UNCONFIRMED";
+  mutationMayHaveApplied = true;
+  constructor(operation, claimId) {
+    super(`Worker ${operation} receipt could not be confirmed for claim "${claimId}"`);
+    this.operation = operation;
+    this.claimId = claimId;
+    this.name = "WorkerReceiptUnconfirmedError";
+  }
+}
+function safeWorkerId(value) {
+  const workerId = value ?? `worker-${crypto.randomUUID()}`;
+  if (workerId.length === 0 || workerId.length > 256 || /[\u0000-\u001f\u007f]/.test(workerId)) {
+    throw new TypeError("Worker workerId must be a safe non-empty string");
+  }
+  return workerId;
+}
+function safeDescriptorText(value, maxLength) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maxLength && !/[\u0000-\u001f\u007f]/.test(value);
+}
+function validJobScope(value) {
+  return value === "application" || value === "request" || value === "job";
+}
+function validJobMode(value) {
+  return value === "task" || value === "workflow";
+}
+function validJobIdempotency(value) {
+  return value === "required" || value === "none";
+}
+function validPositiveInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function safeClaim(claim) {
+  if (!claim || typeof claim !== "object") {
+    throw new WorkerRegistrationError("WORKER_INVALID_JOB", "Worker claim is invalid");
+  }
+  if (typeof claim.id !== "string" || claim.id.length === 0 || claim.id.length > 512 || /[\u0000-\u001f\u007f]/.test(claim.id) || typeof claim.jobName !== "string" || claim.jobName.length === 0 || claim.jobName.length > 256 || /[\u0000-\u001f\u007f]/.test(claim.jobName)) {
+    throw new WorkerRegistrationError("WORKER_INVALID_JOB", "Worker claim identity is invalid");
+  }
+  const attempt = claim.attempt ?? 1;
+  if (!Number.isSafeInteger(attempt) || attempt < 1) {
+    throw new WorkerRegistrationError("WORKER_INVALID_JOB", "Worker claim attempt is invalid");
+  }
+  return { ...claim, attempt };
+}
+function delay(milliseconds, signal) {
+  if (milliseconds <= 0)
+    return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      callback();
+    };
+    const onAbort = () => finish(() => reject(signal.reason ?? new DOMException("Aborted", "AbortError")));
+    const timer = setTimeout(() => finish(resolve), milliseconds);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+      onAbort();
+  });
+}
+async function destroyServiceValues(services) {
+  const errors = [];
+  const seen = new Set;
+  for (const value of Object.values(services).reverse()) {
+    if (seen.has(value) || !value || typeof value !== "object")
+      continue;
+    seen.add(value);
+    const candidate = value;
+    const hook = typeof candidate.onDestroy === "function" ? candidate.onDestroy : typeof candidate.ngOnDestroy === "function" ? candidate.ngOnDestroy : undefined;
+    if (!hook)
+      continue;
+    try {
+      await Reflect.apply(hook, value, []);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length > 0)
+    throw new AggregateError(errors, "Worker service destruction failed");
+}
+
+class SupaCloudWorker {
+  registry = new Map;
+  modules = [];
+  moduleServices = new Map;
+  deps;
+  transport;
+  mapClaim;
+  requestContextFactory;
+  workerId;
+  concurrency;
+  pollIntervalMs;
+  executor;
+  observer;
+  onError;
+  destroyServices;
+  stateValue = "idle";
+  claimController;
+  loopPromise;
+  startPromise;
+  stopPromise;
+  stopRequested = false;
+  inFlight = new Set;
+  services = {};
+  imported = {};
+  constructor(options) {
+    if (!options.transport || typeof options.transport.claim !== "function" || typeof options.transport.fail !== "function" || typeof options.transport.ack !== "function" && typeof options.transport.acknowledge !== "function") {
+      throw new WorkerRegistrationError("WORKER_TRANSPORT_INVALID", "Worker transport must provide claim, ack and fail");
+    }
+    this.transport = options.transport;
+    this.deps = options.deps ?? {};
+    this.workerId = safeWorkerId(options.workerId);
+    this.mapClaim = options.mapClaim ?? ((claim) => claim);
+    this.requestContextFactory = options.requestContext ?? ((claim, signal) => ({
+      workerId: this.workerId,
+      jobId: claim.id,
+      jobName: claim.jobName,
+      attempt: claim.attempt,
+      signal
+    }));
+    this.concurrency = this.capturePositiveInteger(options.concurrency, 1, 1000, "concurrency");
+    this.pollIntervalMs = this.captureNonNegativeInteger(options.pollIntervalMs, 1000, 300000, "pollIntervalMs");
+    this.executor = options.executor;
+    this.observer = options.onExecution;
+    this.onError = options.onError;
+    this.destroyServices = options.destroyServices;
+    for (const module of options.modules ?? [])
+      this.registerModule(module);
+  }
+  get state() {
+    return this.stateValue;
+  }
+  get id() {
+    return this.workerId;
+  }
+  get jobNames() {
+    return Object.freeze([...this.registry.keys()]);
+  }
+  get jobs() {
+    return Object.freeze([...this.registry.values()].map((entry) => entry.job));
+  }
+  registerModule(module) {
+    if (this.stateValue !== "idle" && this.stateValue !== "stopped") {
+      throw new WorkerRegistrationError("WORKER_INVALID_JOB", "Jobs cannot be registered while the worker is active");
+    }
+    if (!module || typeof module !== "object" || typeof module.name !== "string" || module.name.length === 0 || module.name.length > 256 || /[\u0000-\u001f\u007f]/.test(module.name) || typeof module.createServices !== "function" || module.jobs !== undefined && !Array.isArray(module.jobs)) {
+      throw new WorkerRegistrationError("WORKER_INVALID_JOB", "A registered module is invalid");
+    }
+    if (this.modules.some((candidate) => candidate.name === module.name)) {
+      throw new WorkerRegistrationError("WORKER_DUPLICATE_MODULE", `Module "${module.name}" is registered more than once`);
+    }
+    const jobs = module.jobs ?? [];
+    const names = new Set;
+    for (const job of jobs) {
+      if (!job || typeof job !== "object" || !safeDescriptorText(job.className, 256) || !safeDescriptorText(job.name, 256) || !safeDescriptorText(job.serviceKey, 256) || !validJobScope(job.scope) || job.mode !== undefined && !validJobMode(job.mode) || job.idempotency !== undefined && !validJobIdempotency(job.idempotency) || job.timeoutSec !== undefined && !validPositiveInteger(job.timeoutSec) || job.maxAttempts !== undefined && !validPositiveInteger(job.maxAttempts)) {
+        throw new WorkerRegistrationError("WORKER_INVALID_JOB", "A registered Job has invalid identity or execution metadata");
+      }
+      if (this.registry.has(job.name) || names.has(job.name)) {
+        throw new WorkerRegistrationError("WORKER_DUPLICATE_JOB", `Job "${job.name}" is registered more than once`);
+      }
+      names.add(job.name);
+    }
+    this.modules.push(module);
+    for (const job of jobs)
+      this.registry.set(job.name, { module, job });
+  }
+  register(module) {
+    this.registerModule(module);
+  }
+  async start() {
+    if (this.stateValue === "running")
+      return;
+    if (this.stateValue === "starting" && this.startPromise)
+      return this.startPromise;
+    if (this.stateValue === "stopping" && this.stopPromise)
+      await this.stopPromise;
+    this.stopRequested = false;
+    this.stateValue = "starting";
+    const startPromise = Promise.resolve().then(() => this.initialize()).then(async () => {
+      if (this.stopRequested || this.stateValue !== "starting") {
+        await this.releaseServices();
+        return;
+      }
+      this.claimController = new AbortController;
+      this.stateValue = "running";
+      this.loopPromise = this.pollLoop(this.claimController.signal);
+    }).catch(async (error) => {
+      this.stateValue = "stopped";
+      await this.releaseServices();
+      throw error;
+    });
+    this.startPromise = startPromise;
+    return startPromise;
+  }
+  async stop() {
+    if (this.stateValue === "idle" || this.stateValue === "stopped")
+      return;
+    if (this.stopPromise)
+      return this.stopPromise;
+    this.stopRequested = true;
+    this.stateValue = "stopping";
+    this.claimController?.abort(new DOMException("Worker stopped", "AbortError"));
+    const startPromise = this.startPromise;
+    this.stopPromise = (async () => {
+      await startPromise?.catch(() => {
+        return;
+      });
+      await this.loopPromise?.catch((error) => this.reportError(error));
+      await Promise.allSettled([...this.inFlight]);
+      await this.releaseServices();
+      this.stateValue = "stopped";
+      this.claimController = undefined;
+      this.loopPromise = undefined;
+      this.startPromise = undefined;
+      this.stopPromise = undefined;
+    })();
+    return this.stopPromise;
+  }
+  async runOnce() {
+    if (this.stateValue !== "running") {
+      throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker must be started before runOnce");
+    }
+    const controller = this.claimController;
+    if (!controller)
+      throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker claim lifecycle is unavailable");
+    controller.signal.throwIfAborted();
+    const claim = await this.transport.claim(controller.signal);
+    if (claim === null)
+      return null;
+    return this.processClaim(claim);
+  }
+  async processClaim(rawClaim) {
+    const claim = safeClaim(this.mapClaim(rawClaim));
+    const entry = this.registry.get(claim.jobName);
+    const controller = new AbortController;
+    const context = Object.freeze({
+      jobId: claim.id,
+      jobName: claim.jobName,
+      attempt: claim.attempt ?? 1,
+      signal: controller.signal
+    });
+    if (!entry) {
+      const receipt = await this.failClaim(rawClaim, claim, new WorkerRegistrationError("WORKER_INVALID_JOB", `Job "${claim.jobName}" is not registered`), context);
+      return { claimId: claim.id, jobName: claim.jobName, status: "failed", receipt };
+    }
+    let output;
+    try {
+      if (this.stateValue !== "running" && this.stateValue !== "stopping") {
+        throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker is not active");
+      }
+      const requestContext = claim.requestContext ?? await this.requestContextFactory(claim, controller.signal);
+      const moduleServices = this.moduleServices.get(entry.module.name);
+      if (!moduleServices)
+        throw new WorkerRegistrationError("WORKER_NOT_STARTED", "Worker services are unavailable");
+      output = await executeJob(entry.module, moduleServices, entry.job, claim.input, requestContext, this.imported, this.executor, this.observer);
+    } catch (error) {
+      const receipt = await this.failClaim(rawClaim, claim, error, context);
+      return { claimId: claim.id, jobName: claim.jobName, status: "failed", receipt };
+    }
+    const acknowledge = this.transport.ack ?? this.transport.acknowledge;
+    if (!acknowledge)
+      throw new WorkerRegistrationError("WORKER_TRANSPORT_INVALID", "Worker acknowledgement is unavailable");
+    try {
+      const receipt = await acknowledge(rawClaim, output, context);
+      return { claimId: claim.id, jobName: claim.jobName, status: "acknowledged", receipt };
+    } catch {
+      throw new WorkerReceiptUnconfirmedError("ack", claim.id);
+    }
+  }
+  async failClaim(rawClaim, claim, error, context) {
+    try {
+      return await this.transport.fail(rawClaim, error, context);
+    } catch {
+      throw new WorkerReceiptUnconfirmedError("fail", claim.id);
+    }
+  }
+  async initialize() {
+    this.services = {};
+    this.imported = {};
+    this.moduleServices.clear();
+    for (const module of this.modules) {
+      const services = module.createServices(this.deps, this.imported);
+      this.moduleServices.set(module.name, services);
+      this.services = { ...this.services, ...services };
+      this.imported[module.name] = services;
+    }
+  }
+  async releaseServices() {
+    const services = this.services;
+    const imported = this.imported;
+    this.services = {};
+    this.imported = {};
+    this.moduleServices.clear();
+    if (Object.keys(services).length === 0)
+      return;
+    try {
+      if (this.destroyServices)
+        await this.destroyServices(services, imported);
+      else
+        await destroyServiceValues(services);
+    } catch (error) {
+      await this.reportError(error);
+    }
+  }
+  async pollLoop(signal) {
+    while (!signal.aborted && this.stateValue === "running") {
+      if (this.inFlight.size >= this.concurrency) {
+        await Promise.race(this.inFlight).catch((error) => this.reportError(error));
+        continue;
+      }
+      let claim;
+      try {
+        claim = await this.transport.claim(signal);
+      } catch (error) {
+        if (signal.aborted)
+          break;
+        await this.reportError(error);
+        await delay(this.pollIntervalMs, signal).catch(() => {
+          return;
+        });
+        continue;
+      }
+      if (claim === null) {
+        await delay(this.pollIntervalMs, signal).catch(() => {
+          return;
+        });
+        continue;
+      }
+      const execution = this.processClaim(claim).catch((error) => this.reportError(error));
+      this.inFlight.add(execution);
+      execution.finally(() => this.inFlight.delete(execution));
+    }
+  }
+  async reportError(error) {
+    try {
+      await this.onError?.(error);
+    } catch {}
+  }
+  capturePositiveInteger(value, fallback, max, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1 || result > max)
+      throw new TypeError(`Worker ${name} is invalid`);
+    return result;
+  }
+  captureNonNegativeInteger(value, fallback, max, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 0 || result > max)
+      throw new TypeError(`Worker ${name} is invalid`);
+    return result;
+  }
+}
+function createWorker(options) {
+  return new SupaCloudWorker(options);
+}
 
 // src/index.ts
 var VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
@@ -361,13 +1253,22 @@ function composeAspects(...aspects) {
         return Promise.reject(new Error("next() called multiple times"));
       }
       index = current;
-      if (current === active.length)
+      const aspect = active[current];
+      if (!aspect)
         return Promise.resolve(next());
-      return Promise.resolve(active[current](context, () => dispatch(current + 1)));
+      return Promise.resolve(aspect(context, () => dispatch(current + 1)));
     };
     return dispatch(0);
   };
 }
+function observedAspects(aspects, boundary, observer) {
+  return composeAspects(...aspects.map((aspect, index) => (context, next) => observeExecution(observer, {
+    kind: context.kind,
+    operation: context.name,
+    stage: `${boundary}.aspect[${index}]:${aspect.name || "anonymous"}`,
+    ...executionTrace(context.requestContext)
+  }, () => aspect(context, next))));
+}
 function composeCommandExecutors(...executors) {
   const active = executors.filter((e) => typeof e === "function");
   if (active.length === 0)
@@ -427,6 +1328,19 @@ function validatedJsonResponse(validate, value, init) {
     headers.set("content-type", "application/json");
   return new Response(body, { ...init, headers });
 }
+function decodeJobContract(schema, value, boundary) {
+  if (schema === undefined)
+    return value;
+  try {
+    return createSchemaDecoder(schema)(value);
+  } catch {
+    const input = boundary === "input";
+    throw new ApplicationError(input ? "Job input contract validation failed" : "Job output contract validation failed", {
+      status: input ? 422 : 500,
+      code: input ? "JOB_INPUT_VALIDATION_ERROR" : "JOB_OUTPUT_VALIDATION_ERROR"
+    });
+  }
+}
 function safeHeaderValue(value, maxLength) {
   if (!value || value.length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
     return;
@@ -445,7 +1359,7 @@ function isAuthenticatedTrustedIdentity(value) {
 function bearerToken(request) {
   const authorization = request.headers.get("authorization");
   const match = authorization?.match(/^Bearer\s+(.+)$/i);
-  return match ? safeHeaderValue(match[1], 16384) : undefined;
+  return match?.[1] ? safeHeaderValue(match[1], 16384) : undefined;
 }
 var createSupaCloudRequestContext = (request) => {
   const subject = safeHeaderValue(request.headers.get(VERIFIED_JWT_SUBJECT_HEADER), 1024);
@@ -482,9 +1396,31 @@ function missingGovernanceAdapter(command, adapter) {
     code: codes[adapter]
   });
 }
-function createCommandExecutor(governance) {
+function createCommandExecutor(governance, observer) {
   return async (invocation, next) => {
     const { command } = invocation;
+    for (const mode of [command.transaction, command.idempotency]) {
+      if (mode !== undefined && mode !== "required" && mode !== "none") {
+        throw new ApplicationError("Invalid command governance mode", { code: "COMMAND_MODE_INVALID" });
+      }
+    }
+    if (command.rpc !== undefined) {
+      const adapter = Object.hasOwn(governance.rpc ?? {}, command.rpc) ? governance.rpc?.[command.rpc] : undefined;
+      if (!adapter)
+        throw new ApplicationError("RPC governance adapter unavailable", { code: "COMMAND_RPC_UNAVAILABLE", status: 501 });
+      for (const capability of ["audit", "transaction", "idempotency"]) {
+        const required = capability === "audit" ? !!command.audit : command[capability] === "required";
+        if (required && adapter.capabilities[capability] !== true)
+          throw missingGovernanceAdapter(command, capability);
+      }
+      const event = {
+        kind: "command",
+        operation: command.name,
+        ...executionTrace(invocation.requestContext)
+      };
+      await observeExecution(observer, { ...event, stage: "authorize" }, () => governance.authorize(invocation));
+      return observeExecution(observer, { ...event, stage: `rpc:${command.rpc}` }, () => adapter.execute(invocation, once(next)));
+    }
     const audit = command.audit ? governance.audit : undefined;
     const transaction = command.transaction === "required" ? governance.transaction : undefined;
     const idempotency = command.idempotency === "required" ? governance.idempotency : undefined;
@@ -498,24 +1434,31 @@ function createCommandExecutor(governance) {
       throw missingGovernanceAdapter(command, "idempotency");
     }
     try {
-      await governance.authorize(invocation);
+      const observe = (stage, next) => observeExecution(observer, {
+        kind: "command",
+        operation: command.name,
+        stage,
+        ...executionTrace(invocation.requestContext)
+      }, next);
+      await observe("authorize", () => governance.authorize(invocation));
       let execute = async () => {
-        const result = await next();
+        const result = await observe("handler", invokeOnce);
         if (audit)
-          await audit.succeeded.call(audit, invocation, result);
+          await observe("audit", () => audit.succeeded.call(audit, invocation, result));
         return result;
       };
+      const invokeOnce = once(next);
       if (command.transaction === "required") {
         if (!transaction)
           throw missingGovernanceAdapter(command, "transaction");
         const inner = execute;
-        execute = () => Promise.resolve(transaction.call(governance, invocation, inner));
+        execute = () => observe("transaction", () => transaction.call(governance, invocation, once(inner)));
       }
       if (command.idempotency === "required") {
         if (!idempotency)
           throw missingGovernanceAdapter(command, "idempotency");
         const inner = execute;
-        execute = () => Promise.resolve(idempotency.call(governance, invocation, inner));
+        execute = () => observe("idempotency", () => idempotency.call(governance, invocation, once(inner)));
       }
       return await execute();
     } catch (error) {
@@ -525,6 +1468,79 @@ function createCommandExecutor(governance) {
     }
   };
 }
+async function executeCompiledCommand(options) {
+  const matches = options.module.commands?.filter((item) => item.className === options.command) ?? [];
+  if (matches.length !== 1)
+    throw new ApplicationError("Command descriptor missing or ambiguous", { code: "COMMAND_NOT_REGISTERED" });
+  const command = matches[0];
+  if (!command)
+    throw new Error(`Command not found: ${options.command}`);
+  const invocation = {
+    command,
+    input: { body: options.input, params: {}, query: {} },
+    request: options.request,
+    requestContext: options.requestContext,
+    services: options.services ?? {},
+    ...options.scope ? { scope: options.scope } : {}
+  };
+  const aspects = composeAspects(observedAspects(options.module.aspects ?? [], `module:${options.module.name}`, options.observer), observedAspects(command.aspects ?? [], "command", options.observer));
+  const value = await createCommandExecutor(options.governance, options.observer)(invocation, once(() => aspects({
+    kind: "command",
+    name: command.name,
+    input: options.input,
+    request: options.request,
+    requestContext: options.requestContext,
+    services: invocation.services,
+    ...invocation.scope ? { scope: invocation.scope } : {},
+    metadata: command
+  }, once(() => options.handler(options.input)))));
+  return options.decode(value);
+}
+async function previewCompiledCommand(options) {
+  const matches = options.module.commands?.filter((item) => item.className === options.command) ?? [];
+  if (matches.length !== 1)
+    throw new ApplicationError("Command descriptor missing or ambiguous", { code: "COMMAND_NOT_REGISTERED" });
+  const command = matches[0];
+  if (!command)
+    throw new Error(`Command not found: ${options.command}`);
+  const invocation = {
+    command,
+    input: { body: options.input, params: {}, query: {} },
+    request: options.request,
+    requestContext: options.requestContext,
+    services: options.services ?? {},
+    ...options.scope ? { scope: options.scope } : {}
+  };
+  try {
+    await options.governance.authorize(invocation);
+  } catch (error) {
+    if (error instanceof ApplicationError && (error.status === 401 || error.status === 403)) {
+      return decodeCommandPreview({
+        command: command.name,
+        allowed: false,
+        blockers: [{ code: error.code, message: error.message }]
+      });
+    }
+    throw error;
+  }
+  const preview = decodeCommandPreview(await options.preview(options.input));
+  if (preview.command !== command.name && preview.command !== command.className) {
+    throw new TypeError("Mismatched command identity");
+  }
+  return preview;
+}
+function once(next) {
+  let called = false;
+  return async () => {
+    if (called) {
+      throw new ApplicationError("Command continuation called multiple times", {
+        code: "COMMAND_CONTINUATION_REUSED"
+      });
+    }
+    called = true;
+    return await next();
+  };
+}
 function requireTrustedIdentity(requestContext) {
   const context = isRecord(requestContext) ? requestContext : {};
   const identity = isTrustedIdentity(context.identity) ? context.identity : undefined;
@@ -554,6 +1570,26 @@ function joinPaths(prefix, path) {
 function controllerInstance(value) {
   return isRecord(value) ? value : undefined;
 }
+function cookieValues(value) {
+  if (!isRecord(value))
+    return;
+  const result = {};
+  for (const [name, entry] of Object.entries(value)) {
+    result[name] = isRecord(entry) && "value" in entry ? entry.value : entry;
+  }
+  return result;
+}
+function assertDeclaredResponseStatus(route, value, configuredStatus) {
+  if (route.responses === undefined)
+    return;
+  const status = responseStatusOf(value, configuredStatus);
+  if (responseStatusDeclared(route.responses, status))
+    return;
+  const transport = route.contract?.response;
+  if ((transport === "binary" || transport === "stream") && status >= 200 && status < 300)
+    return;
+  throw new ApplicationError("Response validation failed", { status: 500, code: "RESPONSE_CONTRACT_UNDECLARED" });
+}
 function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext, options = {}, imported = {}) {
   const hasCommandRoutes = compiled.controllers.some((controller) => controller.routes.some((route) => route.command !== undefined));
   if (hasCommandRoutes && !options.commandGovernance && !options.commandExecutor) {
@@ -570,9 +1606,9 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
     }
   }
   const requestContexts = new WeakMap;
-  const governanceExecutor = options.commandGovernance ? createCommandExecutor(options.commandGovernance) : undefined;
+  const governanceExecutor = options.commandGovernance ? createCommandExecutor(options.commandGovernance, options.onExecution) : undefined;
   const commandExecutor = options.commandExecutor && governanceExecutor ? composeCommandExecutors(options.commandExecutor, governanceExecutor) : options.commandExecutor ?? governanceExecutor;
-  const plugin = new Elysia({ name: `supacloud:${compiled.name}` }).decorate("services", services);
+  const plugin = new Elysia2({ name: `supacloud:${compiled.name}`, normalize: options.normalize ?? true }).decorate("services", services);
   const createRequestScope = compiled.createRequestScope;
   const requestScopes = new WeakMap;
   if (compiled.destroyRequestScope) {
@@ -606,88 +1642,98 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
   for (const controller of compiled.controllers) {
     for (const route of controller.routes) {
       const path = joinPaths(controller.path, route.path);
-      const schema = {};
-      if (route.body !== undefined)
-        schema.body = route.body;
-      if (route.params !== undefined)
-        schema.params = route.params;
-      if (route.query !== undefined)
-        schema.query = route.query;
-      if (route.response !== undefined)
-        schema.response = route.response;
+      const schema = toElysiaRouteSchema(route);
       const handler = async (ctx) => {
         const requestContext = ctx.requestContext ?? await ctxFactory(ctx.request);
-        const requestScope = createRequestScope ? await createRequestScope(services, requestContext, imported) : undefined;
-        if (requestScope && compiled.destroyRequestScope)
-          requestScopes.set(ctx.request, requestScope);
-        const source = controller.scope === "request" ? requestScope : services;
-        const instance = controllerInstance(source?.[controller.serviceKey]);
-        const method = instance?.[route.handler];
-        if (typeof method !== "function") {
-          throw new Error(`supacloud: controller "${controller.serviceKey}" has no handler "${route.handler}" in scope "${controller.scope}"`);
-        }
-        const input = {
-          body: ctx.body,
-          params: ctx.params,
-          query: ctx.query,
-          headers: Object.fromEntries(ctx.request.headers.entries()),
-          context: requestContext,
-          request: ctx.request,
-          scope: requestScope,
-          requestContext
-        };
-        const invoke = () => route.invoker ? route.invoker(instance, input) : Reflect.apply(method, instance, [input]);
-        const routeContext = {
-          kind: "route",
-          name: `${route.method} ${path}`,
-          input,
-          request: ctx.request,
-          requestContext,
-          scope: requestScope,
-          services,
-          metadata: route
-        };
-        const command = route.command ? commandsByClassName.get(route.command) : undefined;
-        const commandContext = {
-          kind: "command",
-          name: command?.name ?? route.command ?? `${route.method} ${path}`,
-          input,
-          request: ctx.request,
-          requestContext,
-          scope: requestScope,
-          services,
-          metadata: command ?? route
-        };
-        const commandAspects = route.command ? commandsByClassName.get(route.command)?.aspects ?? [] : [];
-        const routePipeline = composeAspects(...route.aspects ?? []);
-        const commandPipeline = composeAspects(...commandAspects);
-        const modulePipeline = composeAspects(...compiled.aspects ?? []);
-        const invokeRoute = () => routePipeline(routeContext, () => route.command ? commandPipeline(commandContext, () => invokeCommand()) : invoke());
-        const invokeCommand = () => {
-          if (!route.command)
-            return invoke();
-          if (!command) {
-            throw new ApplicationError(`Command "${route.command}" is not registered`, {
-              code: "COMMAND_NOT_REGISTERED"
-            });
+        const execute = async () => {
+          const requestScope = createRequestScope ? await createRequestScope(services, requestContext, imported) : undefined;
+          if (requestScope && compiled.destroyRequestScope)
+            requestScopes.set(ctx.request, requestScope);
+          const source = controller.scope === "request" ? requestScope : services;
+          const instance = controllerInstance(source?.[controller.serviceKey]);
+          const method = instance?.[route.handler];
+          if (typeof method !== "function") {
+            throw new Error(`supacloud: controller "${controller.serviceKey}" has no handler "${route.handler}" in scope "${controller.scope}"`);
           }
-          if (!commandExecutor) {
-            throw new ApplicationError(`Command "${command.name}" has no executor`, {
-              status: 501,
-              code: "COMMAND_EXECUTOR_UNAVAILABLE"
-            });
-          }
-          const invocation = {
-            command,
+          const normalizedCookie = ctx.cookie === undefined ? undefined : cookieValues(ctx.cookie);
+          const input = {
+            body: ctx.body,
+            params: ctx.params,
+            query: ctx.query,
+            headers: ctx.headers ?? Object.fromEntries(ctx.request.headers.entries()),
+            ...normalizedCookie === undefined ? {} : { cookie: normalizedCookie },
+            context: requestContext,
+            request: ctx.request,
+            ...requestScope ? { scope: requestScope } : {},
+            requestContext
+          };
+          const handlerCall = () => route.invoker ? route.invoker(instance, input) : Reflect.apply(method, instance, [input]);
+          const invoke = once(() => route.command && options.commandGovernance ? handlerCall() : observeExecution(options.onExecution, {
+            kind: route.command ? "command" : "route",
+            operation: route.command ?? `${route.method} ${path}`,
+            stage: "handler",
+            ...executionTrace(requestContext)
+          }, handlerCall));
+          const routeContext = {
+            kind: "route",
+            name: `${route.method} ${path}`,
             input,
             request: ctx.request,
             requestContext,
-            scope: requestScope,
-            services
+            ...requestScope ? { scope: requestScope } : {},
+            services,
+            metadata: route
           };
-          return commandExecutor(invocation, invoke);
+          const command = route.command ? commandsByClassName.get(route.command) : undefined;
+          const commandContext = {
+            kind: "command",
+            name: command?.name ?? route.command ?? `${route.method} ${path}`,
+            input,
+            request: ctx.request,
+            requestContext,
+            ...requestScope ? { scope: requestScope } : {},
+            services,
+            metadata: command ?? route
+          };
+          const commandAspects = route.command ? commandsByClassName.get(route.command)?.aspects ?? [] : [];
+          const routePipeline = observedAspects(route.aspects ?? [], "route", options.onExecution);
+          const commandPipeline = observedAspects(commandAspects, "command", options.onExecution);
+          const modulePipeline = observedAspects(compiled.aspects ?? [], `module:${compiled.name}`, options.onExecution);
+          const invokeRoute = () => routePipeline(routeContext, () => route.command ? commandPipeline(commandContext, () => invokeCommand()) : invoke());
+          const invokeCommand = () => {
+            if (!route.command)
+              return invoke();
+            if (!command) {
+              throw new ApplicationError(`Command "${route.command}" is not registered`, {
+                code: "COMMAND_NOT_REGISTERED"
+              });
+            }
+            if (!commandExecutor) {
+              throw new ApplicationError(`Command "${command.name}" has no executor`, {
+                status: 501,
+                code: "COMMAND_EXECUTOR_UNAVAILABLE"
+              });
+            }
+            const invocation = {
+              command,
+              input,
+              request: ctx.request,
+              requestContext,
+              ...requestScope ? { scope: requestScope } : {},
+              services
+            };
+            return observeExecution(options.onExecution, {
+              kind: "command",
+              operation: command.name,
+              stage: "commandExecutor",
+              ...executionTrace(requestContext)
+            }, () => commandExecutor(invocation, invoke));
+          };
+          return modulePipeline(route.command ? commandContext : routeContext, invokeRoute);
         };
-        return modulePipeline(route.command ? commandContext : routeContext, invokeRoute);
+        const result = options.injector ? await runInRequestContext(options.injector, [provideToken(REQUEST_CONTEXT, requestContext)], execute) : await execute();
+        assertDeclaredResponseStatus(route, result, ctx.set.status);
+        return result;
       };
       switch (route.method) {
         case "GET":
@@ -716,7 +1762,8 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
   }
   return plugin;
 }
-async function executeJob(compiled, services, job, input, requestContext, imported = {}, executor) {
+async function executeJob(compiled, services, job, input, requestContext, imported = {}, executor, observer) {
+  const decodedInput = decodeJobContract(job.input, input, "input");
   const jobScope = job.scope === "job" && compiled.createJobScope ? await compiled.createJobScope(services, requestContext, imported) : undefined;
   try {
     const source = job.scope === "job" ? jobScope : services;
@@ -727,23 +1774,35 @@ async function executeJob(compiled, services, job, input, requestContext, import
     }
     const invocation = {
       job,
-      input,
+      input: decodedInput,
       requestContext,
-      scope: jobScope,
+      ...jobScope ? { scope: jobScope } : {},
       services
     };
     const context = {
       kind: "job",
       name: job.name,
-      input,
+      input: decodedInput,
       requestContext,
-      scope: jobScope,
+      ...jobScope ? { scope: jobScope } : {},
       services,
       metadata: job
     };
-    const invoke = () => Reflect.apply(method, instance, [input]);
-    const pipeline = composeAspects(...compiled.aspects ?? [], ...job.aspects ?? []);
-    return await pipeline(context, executor ? () => executor(invocation, invoke) : invoke);
+    const invoke = once(() => observeExecution(observer, {
+      kind: "job",
+      operation: job.name,
+      stage: "handler",
+      ...executionTrace(requestContext)
+    }, () => Reflect.apply(method, instance, [decodedInput])));
+    const pipeline = observedAspects(compiled.aspects ?? [], `module:${compiled.name}`, observer);
+    const jobPipeline = observedAspects(job.aspects ?? [], "job", observer);
+    const result = await pipeline(context, () => jobPipeline(context, () => observeExecution(observer, {
+      kind: "job",
+      operation: job.name,
+      stage: "jobExecutor",
+      ...executionTrace(requestContext)
+    }, executor ? () => executor(invocation, invoke) : invoke)));
+    return decodeJobContract(job.output, result, "output");
   } finally {
     if (jobScope && compiled.destroyJobScope) {
       await compiled.destroyJobScope(jobScope);
@@ -751,6 +1810,11 @@ async function executeJob(compiled, services, job, input, requestContext, import
   }
 }
 function defaultErrorResponse(error, frameworkCode) {
+  if (error instanceof CommandError2) {
+    return Response.json({ ok: false, code: error.code, message: error.code }, {
+      status: commandErrorStatus(error.code)
+    });
+  }
   if (isPublicApplicationError(error)) {
     return Response.json({
       ok: false,
@@ -785,7 +1849,9 @@ function isPublicApplicationError(error) {
   return error.expose === true && typeof error.status === "number" && Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 && typeof error.code === "string" && error.code.length > 0;
 }
 function createApplication(options) {
-  const app = new Elysia({ name: options.name ?? "supacloud:app" });
+  const app = new Elysia2({ name: options.name ?? "supacloud:app", normalize: options.normalize ?? true });
+  if (options.documentation)
+    app.use(createDocumentationPlugin(options.documentation));
   const configuredContextFactory = options.requestContext ?? defaultRequestContext;
   const contextCache = new WeakMap;
   const ctxFactory = (request) => {
@@ -800,11 +1866,7 @@ function createApplication(options) {
   for (const module of options.modules ?? []) {
     const services = module.createServices(options.deps ?? {}, imported);
     imported[module.name] = services;
-    app.use(createModulePlugin(module, services, ctxFactory, {
-      commandGovernance: options.commandGovernance,
-      commandExecutor: options.commandExecutor,
-      errorMapper: options.errorMapper
-    }, imported));
+    app.use(createModulePlugin(module, services, ctxFactory, options, imported));
   }
   return app;
 }
@@ -815,20 +1877,41 @@ export {
   ApplicationError,
   EXECUTION_ID_HEADER,
   IDEMPOTENCY_KEY_HEADER,
+  SchemaContractError,
+  SupaCloudWorker,
   VERIFIED_JWT_SUBJECT_HEADER,
+  WorkerReceiptUnconfirmedError,
+  WorkerRegistrationError,
   assertFeatureTransition,
+  assertResponseStatusDeclared,
   composeAspects,
   composeCommandExecutors,
   createApplication,
   createCommandExecutor,
+  createDocumentationPlugin,
   createMemoryPolicy,
   createMemorySandbox,
   createModulePlugin,
+  createPersistentCommandAdapter,
+  createQueueWorkerTransport,
+  createSchemaDecoder,
+  createSupAuthRequestContext,
   createSupaCloudRequestContext,
   createTestApp,
+  createWorker,
   defaultErrorResponse,
+  defineElysiaRoute,
+  defineJsonContract,
+  defineRouteContract,
+  executeCompiledCommand,
   executeJob,
+  previewCompiledCommand,
+  registerElysiaRoute,
   requireIdempotencyKey,
   requireTrustedIdentity,
+  responseSchemaForStatus,
+  responseStatusDeclared,
+  responseStatusOf,
+  toElysiaRouteSchema,
   validatedJsonResponse
 };