@supacloud/elysia 0.14.1 → 0.16.0

package/README.md

@@ -1,5 +1,94 @@
 # @supacloud/elysia
 
+## Compatibility and Acceptance Boundary
+
+The dependency range is not a claim that every allowed version has been tested.
+The focused conformance suite was verified with Bun 1.4.2 and Elysia 1.4.30.
+The package declares Elysia `^1.4.30` as a peer and TypeScript `^7.0.2` as a
+development dependency. `compatibility.json` records the exact exercised tuple,
+including the compiler's separate TypeScript 6 semantic API. The contract-upgrade
+gate checks both that semantic API and the TypeScript 7 CLI. These tests do not
+establish a wider version matrix or Node.js runtime compatibility.
+
+Run `bun run test:conformance` in this package after building the local
+`@supacloud/contracts` and `@supacloud/app` dependencies and installing this
+package's dependencies. The suite runs through `app.handle(Request)` without a
+network listener. It is included in the normal `bun test` discovery.
+
+| Boundary | Acceptance evidence in `src/conformance.test.ts` |
+| --- | --- |
+| Decoded body, params, query, headers and cookies | Native/adapter response comparison, with explicit decoded-value assertions |
+| Response normalization and declared status maps | Native/adapter comparison, including a 409 response |
+| Native `Response` transport | Status, body, content type, custom header and outgoing cookie preserved |
+| Parent lifecycle hooks | Request, before-handler, handler and after-handler order compared |
+| Parent early return | 403 response compared; controller must not run |
+| Local sibling hooks | Local hook cannot intercept compiled routes |
+| Request schema failure | Native 422 status retained; controller must not run |
+| Malformed JSON | Native 400 status retained for multiple malformed bodies; controller must not run |
+| Error mapper precedence | Custom mapper handles parse failure before request context resolution |
+| Module error isolation | Internal exception redacted; sibling native error handling remains unchanged |
+| Invalid handler output | Intentional 500 response with `RESPONSE_VALIDATION_ERROR` |
+| Unsupported route descriptors | Unsupported methods/native hooks rejected before registration |
+| Duplicate protocol package copies | Known command errors retain their status; unknown codes remain internal |
+
+### Intentional Adapter Semantics
+
+- Default parse failures return HTTP 400 with `PARSE_ERROR`; request schema
+  failures return HTTP 422 with `VALIDATION_ERROR`. Their public messages do not
+  include parser details, submitted values or schema internals.
+- Invalid handler output returns HTTP 500, not a client-input error. It may occur
+  after business work has completed and must not be interpreted as a rollback.
+- Unknown handler exceptions are redacted. Known `CommandError` instances are
+  recognized by their Error identity, name and allowlisted code across separate
+  protocol package copies, never by exposing their message. A configured `errorMapper` can
+  override these defaults and owns the safety of its response.
+- Cookie input passed to a compiled controller contains decoded values, not
+  Elysia's mutable cookie wrappers. Native `Response` headers can carry outgoing
+  cookies.
+- Errors before context resolution have no request context. Error mappers must
+  not assume identity or request-scoped services are available.
+
+### Not Yet Proven by This Suite
+
+WebSockets, streaming and disconnect behavior, multipart uploads, signed-cookie
+mutation, arbitrary third-party plugins, alternate runtime/version combinations,
+concurrent tenant isolation, database transaction/idempotency guarantees and
+published-package installation are not covered by the conformance suite alone.
+Runtime safety is covered separately below. This list records
+an evidence gap, not a declaration that all these features are unsupported.
+Do not claim complete Elysia compatibility from this gate.
+
+Compiled routes accept only the HTTP methods and schema fields declared by
+`CompiledRoute`, plus compiler-emitted parameter transformation/default and
+descriptive metadata. This metadata does not install native Elysia hooks.
+Other descriptor fields (including browser guards/resolvers and native
+`beforeHandle`) or unsupported methods throw `ROUTE_DESCRIPTOR_UNSUPPORTED`
+at registration. It is not an arbitrary Elysia route-options passthrough.
+TypeScript/decorator inference, compiler migrations and generated client parity
+require their own acceptance gates.
+
+### Runtime and Upgrade Gates
+
+`bun run test:runtime-safety` requires `SUPACLOUD_COMMAND_TEST_URL` and fails
+instead of skipping when it is missing. Use a dedicated loopback database named
+`supacloud_commands_test`, with PostgreSQL 18 and PGMQ 1.10.0; initialize it using
+`scripts/prepare-command-test-database.ts`. The gate opens real loopback HTTP
+listeners and exercises compiler-generated request-scoped controllers. It proves
+overlapping tenant/actor requests, duplicate-key concurrency, authorization
+revocation, audit rollback, same-key retry and per-request provider teardown.
+Its authentication uses a fixed test token map, not a production JWT provider.
+
+`bun run test:contract-upgrade` copies a fixed legacy source fixture, previews and
+applies its versioned migration, compiles factories/client/OpenAPI, checks positive
+and negative types with both TypeScript engines, and calls the generated client
+over real HTTP. It restores the old source checkpoint, regenerates artifacts and
+executes the restored application. Build local contracts, app and compiler
+(including declarations) before installing this package's copied file dependencies.
+
+These gates prove the stated scenarios, not a full historical npm upgrade matrix
+or all business-domain isolation. See [framework acceptance](../../docs/framework-acceptance.md)
+for the evidence boundaries and upgrade policy.
+
 ## Persistent Command Adapters
 
 `createPersistentCommandAdapter(command, { identity, input })` binds a

package/compatibility.json

@@ -0,0 +1,9 @@
+{
+  "bun": "1.4.2",
+  "packages": {
+    "elysia": "1.4.30",
+    "typescript": "7.0.2",
+    "@sinclair/typebox": "0.34.52",
+    "@typescript/typescript6": "6.0.2"
+  }
+}

package/dist/command-errors.d.ts

@@ -1,2 +1,3 @@
 import type { CommandErrorCode } from "@supacloud/contracts";
+export declare function commandErrorCode(error: unknown): CommandErrorCode | undefined;
 export declare function commandErrorStatus(code: CommandErrorCode): number;

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { Elysia as Elysia2 } from "elysia";
-import { CommandError as CommandError2, decodeCommandPreview } from "@supacloud/contracts";
+import { decodeCommandPreview } from "@supacloud/contracts";
 import {
   provideToken,
   runInRequestContext
@@ -8,6 +8,22 @@ import {
 import { REQUEST_CONTEXT } from "@supacloud/app";
 
 // src/command-errors.ts
+function commandErrorCode(error) {
+  if (!(error instanceof Error) || error.name !== "CommandError" || !("code" in error))
+    return;
+  switch (error.code) {
+    case "COMMAND_INPUT_INVALID":
+    case "COMMAND_REJECTED":
+    case "COMMAND_IDEMPOTENCY_CONFLICT":
+    case "COMMAND_INPUT_EXPIRED":
+    case "COMMAND_UNAVAILABLE":
+    case "COMMAND_RECEIPT_INVALID":
+    case "COMMAND_OUTCOME_UNKNOWN":
+      return error.code;
+    default:
+      return;
+  }
+}
 function commandErrorStatus(code) {
   switch (code) {
     case "COMMAND_INPUT_INVALID":
@@ -1591,6 +1607,42 @@ function assertDeclaredResponseStatus(route, value, configuredStatus) {
   throw new ApplicationError("Response validation failed", { status: 500, code: "RESPONSE_CONTRACT_UNDECLARED" });
 }
 function createModulePlugin(compiled, services, ctxFactory = defaultRequestContext, options = {}, imported = {}) {
+  const supportedMethods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+  const supportedFields = new Set([
+    "method",
+    "path",
+    "handler",
+    "body",
+    "params",
+    "query",
+    "headers",
+    "cookie",
+    "response",
+    "responses",
+    "contract",
+    "schemaKinds",
+    "nativeResponse",
+    "invoker",
+    "command",
+    "aspects",
+    "paramTransforms",
+    "paramDefaults",
+    "queryTransforms",
+    "queryDefaults",
+    "title",
+    "data",
+    "input",
+    "result",
+    "request"
+  ]);
+  for (const controller of compiled.controllers) {
+    for (const route of controller.routes) {
+      const unsupported = Object.keys(route).filter((field) => !supportedFields.has(field));
+      if (!supportedMethods.has(route.method) || unsupported.length > 0) {
+        throw new ApplicationError(`Unsupported compiled route ${route.method} ${controller.path}${route.path}` + (unsupported.length > 0 ? `: ${unsupported.join(", ")}` : ""), { code: "ROUTE_DESCRIPTOR_UNSUPPORTED" });
+      }
+    }
+  }
   const hasCommandRoutes = compiled.controllers.some((controller) => controller.routes.some((route) => route.command !== undefined));
   if (hasCommandRoutes && !options.commandGovernance && !options.commandExecutor) {
     throw new ApplicationError(`Module "${compiled.name}" has command routes but no commandGovernance`, { code: "COMMAND_GOVERNANCE_UNCONFIGURED" });
@@ -1810,9 +1862,10 @@ 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)
+  const protocolCode = commandErrorCode(error);
+  if (protocolCode) {
+    return Response.json({ ok: false, code: protocolCode, message: protocolCode }, {
+      status: commandErrorStatus(protocolCode)
     });
   }
   if (isPublicApplicationError(error)) {
@@ -1823,6 +1876,13 @@ function defaultErrorResponse(error, frameworkCode) {
       ...error.details === undefined ? {} : { details: error.details }
     }, { status: error.status });
   }
+  if (frameworkCode === "PARSE") {
+    return Response.json({
+      ok: false,
+      code: "PARSE_ERROR",
+      message: "Request body could not be parsed"
+    }, { status: 400 });
+  }
   if (frameworkCode === "VALIDATION") {
     if (isRecord(error) && error.type === "response") {
       return Response.json({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "compatibility.json"
   ],
   "scripts": {
     "generate:example": "bun src/generate-webhook-example.ts",
@@ -25,6 +26,9 @@
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build",
     "test": "bun test",
+    "test:conformance": "bun test src/conformance.test.ts",
+    "test:runtime-safety": "SUPACLOUD_REQUIRE_RUNTIME_SAFETY=1 bun test src/runtime-safety.test.ts",
+    "test:contract-upgrade": "bun test src/contract-upgrade.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit"
   },
@@ -54,7 +58,7 @@
     "elysia": "^1.4.30"
   },
   "devDependencies": {
-    "@supacloud/compiler": "0.19.1",
+    "@supacloud/compiler": "0.21.0",
     "@supacloud/commands": "0.4.0",
     "@supacloud/db": "0.7.1",
     "@types/bun": "^1.4.2",