@palbase/backend 17.4.0 → 18.0.0

package/dist/test/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/test/api.ts"],"sourcesContent":["/** The client a tenant's tests use to call their own backend.\n *\n * These tests run against a REAL deployment — the release the deploy just built,\n * serving from the same Environment as production, with the same database, the\n * same secrets and the same gateway in front of it. So this client is a plain\n * HTTP client, not a simulation: every call crosses Kong, the API key check, the\n * auth rail, the zod validation at the boundary, and row-level security, exactly\n * as a shipped app's call does.\n *\n * There is deliberately no schema knowledge here. The tenant already wrote their\n * types — `import type { TodoSchema } from \"../models/todos/shared.js\"` — so a\n * test types its own call (`api.get<TodoSchema[]>(\"/todos\")`) and can validate it\n * with the same zod schema the endpoint declares. A second generated client would\n * be a second thing to keep in step.\n */\n\n/** How to reach the release under test. Supplied by the deploy, never guessed. */\nexport interface TestApiConfig {\n  baseUrl: string;\n  apiKey: string;\n  /** This deploy's secret. Without it the request is served the LIVE release. */\n  candidateToken: string;\n  /** The run's minted logins, keyed by the name declared in config/test-users.ts. */\n  identities?: Record<string, TestIdentity>;\n}\n\n/** One login the deploy minted for this run.\n *\n * `accessToken` is the session issued when the identity was created, and is what\n * `signInAs` uses. The credentials come along for a test that wants to exercise\n * the login rail itself — but a suite that switches users repeatedly must not be\n * signing in each time: those calls come from one address and trip the login rate\n * limiter, failing tests for a reason that has nothing to do with the code\n * under test.\n */\nexport interface TestIdentity {\n  id?: string;\n  email: string;\n  password: string;\n  accessToken?: string;\n}\n\n/** One call the suite made, in the order it was made. */\nexport interface RecordedRequest {\n  method: string;\n  path: string;\n  status: number;\n  ms: number;\n}\n\n/** A non-2xx answer, carrying the platform's error envelope.\n *\n * The envelope is the contract every Palbase endpoint answers with, so a test\n * asserts on `status`/`error`/`data` rather than parsing a message. The message\n * exists for the human reading a failed deploy.\n */\nexport class TestApiError extends Error {\n  readonly status: number;\n  readonly error: string;\n  /** Payload of an error your code threw — `new BadRequest({ fields })` arrives here. */\n  readonly data: unknown;\n  /** The whole envelope, exactly as the server sent it. */\n  readonly body: ErrorEnvelope;\n\n  constructor(method: string, path: string, status: number, body: unknown) {\n    const envelope = (body ?? {}) as ErrorEnvelope;\n    const code = envelope.error ?? String(status);\n    super(`${method} ${path} → ${status} ${code}${envelope.error_description ? `: ${envelope.error_description}` : \"\"}`);\n    this.name = \"TestApiError\";\n    this.status = status;\n    this.error = code;\n    this.data = envelope.data;\n    this.body = envelope;\n  }\n}\n\n/** A Palbase error response.\n *\n * `data` carries the payload of an error your code threw. Validation refused at\n * the boundary — before your handler runs — answers with `details` instead, one\n * entry per field. The index signature is deliberate: whatever the server sends\n * is readable from a test, so no assertion is ever blocked on this type being\n * exhaustive.\n */\nexport interface ErrorEnvelope {\n  error?: string;\n  error_description?: string;\n  status?: number;\n  request_id?: string;\n  data?: unknown;\n  details?: Array<{ field: string; message: string }>;\n  [key: string]: unknown;\n}\n\nexport interface CallOptions {\n  headers?: Record<string, string>;\n}\n\nexport interface TestApi {\n  get<T = unknown>(path: string, opts?: CallOptions): Promise<T>;\n  post<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  patch<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  put<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  delete<T = unknown>(path: string, opts?: CallOptions): Promise<T>;\n  /** HTTP QUERY (RFC 10008): a safe, idempotent read whose filter travels in the body. */\n  query<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  /** Sign in with credentials you supply. */\n  signIn(credentials: { email: string; password: string }): Promise<{ id: string; email?: string }>;\n  /**\n   * Sign in as one of the identities this run was given, by the name you\n   * declared it under in `config/test-users.ts`.\n   *\n   * Each is minted by the platform for the length of ONE deploy, seeded with the\n   * data that declaration describes, and retired after — which is why this works\n   * on every Environment including production, where a committed fixture password\n   * is refused on purpose.\n   */\n  signInAs(name: string): Promise<{ id: string; email?: string }>;\n  signOut(): Promise<void>;\n  /** Drop the bearer without calling the server — the anonymous caller. */\n  asAnonymous(): void;\n  /** Every call made, in order. Printed for the failing test in a red deploy. */\n  readonly requests: readonly RecordedRequest[];\n}\n\nfunction required(value: string, envName: string): string {\n  if (!value) {\n    throw new Error(\n      `${envName} is not set — the test client has nowhere to send requests. ` +\n        `This is set by the deploy that runs your tests; if you are running them by hand, set it yourself.`,\n    );\n  }\n  return value;\n}\n\nexport function createTestApi(config: TestApiConfig): TestApi {\n  const baseUrl = required(config.baseUrl, \"PALBASE_TEST_BASE_URL\").replace(/\\/$/, \"\");\n  const apiKey = required(config.apiKey, \"PALBASE_TEST_API_KEY\");\n  const candidateToken = required(config.candidateToken, \"PALBASE_TEST_CANDIDATE\");\n\n  const requests: RecordedRequest[] = [];\n  let bearer: string | null = null;\n\n  async function call<T>(method: string, path: string, body: unknown, opts: CallOptions = {}): Promise<T> {\n    const headers: Record<string, string> = {\n      apikey: apiKey,\n      // Selects the release under test. Omit it and the gateway serves the LIVE\n      // one, which would make the whole suite grade the wrong code.\n      \"x-palbase-candidate\": candidateToken,\n      ...opts.headers,\n    };\n    if (bearer) headers.authorization = `Bearer ${bearer}`;\n    if (body !== undefined) headers[\"content-type\"] = \"application/json\";\n\n    const startedAt = Date.now();\n    const res = await fetch(`${baseUrl}${path}`, {\n      method,\n      headers,\n      body: body === undefined ? undefined : JSON.stringify(body),\n    });\n    const text = await res.text();\n    const parsed: unknown = text ? safeParse(text) : undefined;\n\n    requests.push({ method, path, status: res.status, ms: Date.now() - startedAt });\n\n    if (!res.ok) throw new TestApiError(method, path, res.status, parsed);\n    return parsed as T;\n  }\n\n  return {\n    requests,\n    get: (path, opts) => call(\"GET\", path, undefined, opts),\n    post: (path, body, opts) => call(\"POST\", path, body, opts),\n    patch: (path, body, opts) => call(\"PATCH\", path, body, opts),\n    put: (path, body, opts) => call(\"PUT\", path, body, opts),\n    delete: (path, opts) => call(\"DELETE\", path, undefined, opts),\n    query: (path, body, opts) => call(\"QUERY\", path, body, opts),\n\n    async signInAs(name) {\n      const identity = (config.identities ?? {})[name];\n      if (!identity) {\n        const declared = Object.keys(config.identities ?? {});\n        throw new Error(\n          `no test identity named ${JSON.stringify(name)} — the deploy mints one per user declared in ` +\n            `config/test-users.ts` +\n            (declared.length\n              ? `; this run has: ${declared.join(\", \")}`\n              : // Not \"you declared none\": from here the two causes are\n                // indistinguishable, and blaming the customer's config for a\n                // platform failure sends them to look in the wrong file. The\n                // deploy log names which one it was.\n                \", and this run has none — either your config declares no users \" +\n                \"or the deploy could not mint them; the deploy log says which\"),\n        );\n      }\n      // The session the mint already issued — no network call, so switching\n      // users is free and the login rail never sees this run.\n      if (identity.accessToken) {\n        bearer = identity.accessToken;\n        return { id: identity.id ?? \"\", email: identity.email };\n      }\n      return this.signIn(identity);\n    },\n\n    async signIn(credentials) {\n      const result = await call<{ access_token: string; user?: { id: string; email?: string } }>(\n        \"POST\",\n        \"/auth/login\",\n        credentials,\n      );\n      bearer = result.access_token;\n      return result.user ?? { id: \"\" };\n    },\n    async signOut() {\n      await call(\"POST\", \"/auth/logout\", undefined);\n      bearer = null;\n    },\n    asAnonymous() {\n      bearer = null;\n    },\n  };\n}\n\n/** The run's identities, as the deploy passed them. Absent is not an error: a\n * project that declares none still runs every test that needs no login. */\nfunction parseIdentities(raw: string | undefined): Record<string, TestIdentity> {\n  if (!raw) return {};\n  try {\n    return JSON.parse(raw) as Record<string, TestIdentity>;\n  } catch {\n    return {};\n  }\n}\n\nfunction safeParse(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\n/** The client the deploy configured, from the environment it set.\n *\n * Constructed lazily so importing this module outside a test run — a typecheck,\n * an editor — does not fail on absent configuration.\n */\nlet configured: TestApi | null = null;\n\nexport const api: TestApi = new Proxy({} as TestApi, {\n  get(_target, prop) {\n    configured ??= createTestApi({\n      baseUrl: process.env.PALBASE_TEST_BASE_URL ?? \"\",\n      apiKey: process.env.PALBASE_TEST_API_KEY ?? \"\",\n      candidateToken: process.env.PALBASE_TEST_CANDIDATE ?? \"\",\n      identities: parseIdentities(process.env.PALBASE_TEST_IDENTITIES),\n    });\n    return Reflect.get(configured, prop, configured);\n  },\n});\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/test/api.ts"],"sourcesContent":["/** The client a tenant's tests use to call their own backend.\n *\n * These tests run against a REAL deployment — the release the deploy just built,\n * serving from the same Environment as production, with the same database, the\n * same secrets and the same gateway in front of it. So this client is a plain\n * HTTP client, not a simulation: every call crosses Kong, the API key check, the\n * auth rail, the zod validation at the boundary, and row-level security, exactly\n * as a shipped app's call does.\n *\n * There is deliberately no schema knowledge here. The tenant already wrote their\n * types — `import type { TodoSchema } from \"../models/todos/shared.js\"` — so a\n * test types its own call (`api.get<TodoSchema[]>(\"/todos\")`) and can validate it\n * with the same zod schema the endpoint declares. A second generated client would\n * be a second thing to keep in step.\n */\n\n/** How to reach the release under test. Supplied by the deploy, never guessed. */\nexport interface TestApiConfig {\n  baseUrl: string;\n  apiKey: string;\n  /** This deploy's secret. Without it the request is served the LIVE release. */\n  candidateToken: string;\n  /** The run's minted logins, keyed by the name declared in config/test-users.ts. */\n  identities?: Record<string, TestIdentity>;\n}\n\n/** One login the deploy minted for this run.\n *\n * `accessToken` is the session issued when the identity was created, and is what\n * `signInAs` uses. The credentials come along for a test that wants to exercise\n * the login rail itself — but a suite that switches users repeatedly must not be\n * signing in each time: those calls come from one address and trip the login rate\n * limiter, failing tests for a reason that has nothing to do with the code\n * under test.\n */\nexport interface TestIdentity {\n  id?: string;\n  email: string;\n  password: string;\n  accessToken?: string;\n}\n\n/** One call the suite made, in the order it was made. */\nexport interface RecordedRequest {\n  method: string;\n  path: string;\n  status: number;\n  ms: number;\n}\n\n/** A non-2xx answer, carrying the platform's error envelope.\n *\n * The envelope is the contract every Palbase endpoint answers with, so a test\n * asserts on `status`/`error`/`data` rather than parsing a message. The message\n * exists for the human reading a failed deploy.\n */\nexport class TestApiError extends Error {\n  readonly status: number;\n  readonly error: string;\n  /** Payload of an error your code threw — `new BadRequest({ fields })` arrives here. */\n  readonly data: unknown;\n  /** The whole envelope, exactly as the server sent it. */\n  readonly body: ErrorEnvelope;\n\n  constructor(method: string, path: string, status: number, body: unknown) {\n    const envelope = (body ?? {}) as ErrorEnvelope;\n    const code = envelope.error ?? String(status);\n    super(`${method} ${path} → ${status} ${code}${envelope.error_description ? `: ${envelope.error_description}` : \"\"}`);\n    this.name = \"TestApiError\";\n    this.status = status;\n    this.error = code;\n    this.data = envelope.data;\n    this.body = envelope;\n  }\n}\n\n/** A Palbase error response.\n *\n * `data` carries the payload of an error your code threw. Validation refused at\n * the boundary — before your handler runs — answers with `details` instead, one\n * entry per field. The index signature is deliberate: whatever the server sends\n * is readable from a test, so no assertion is ever blocked on this type being\n * exhaustive.\n */\nexport interface ErrorEnvelope {\n  error?: string;\n  error_description?: string;\n  status?: number;\n  request_id?: string;\n  data?: unknown;\n  details?: Array<{ field: string; message: string }>;\n  [key: string]: unknown;\n}\n\nexport interface CallOptions {\n  headers?: Record<string, string>;\n}\n\nexport interface TestApi {\n  get<T = unknown>(path: string, opts?: CallOptions): Promise<T>;\n  post<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  patch<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  put<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  delete<T = unknown>(path: string, opts?: CallOptions): Promise<T>;\n  /** HTTP QUERY (RFC 10008): a safe, idempotent read whose filter travels in the body. */\n  query<T = unknown>(path: string, body?: unknown, opts?: CallOptions): Promise<T>;\n  /** Sign in with credentials you supply. */\n  signIn(credentials: { email: string; password: string }): Promise<{ id: string; email?: string }>;\n  /**\n   * Sign in as one of the identities this run was given, by the name you\n   * declared it under in `config/test-users.ts`.\n   *\n   * Each is minted by the platform for the length of ONE deploy, seeded with the\n   * data that declaration describes, and retired after — which is why this works\n   * on every Environment including production, where a committed fixture password\n   * is refused on purpose.\n   */\n  signInAs(name: string): Promise<{ id: string; email?: string }>;\n  signOut(): Promise<void>;\n  /** Drop the bearer without calling the server — the anonymous caller. */\n  asAnonymous(): void;\n  /** Every call made, in order. Printed for the failing test in a red deploy. */\n  readonly requests: readonly RecordedRequest[];\n}\n\nfunction required(value: string, envName: string): string {\n  if (!value) {\n    throw new Error(\n      `${envName} is not set — the test client has nowhere to send requests. ` +\n        `This is set by the deploy that runs your tests; if you are running them by hand, set it yourself.`,\n    );\n  }\n  return value;\n}\n\nexport function createTestApi(config: TestApiConfig): TestApi {\n  const baseUrl = required(config.baseUrl, \"PALBASE_TEST_BASE_URL\").replace(/\\/$/, \"\");\n  const apiKey = required(config.apiKey, \"PALBASE_TEST_API_KEY\");\n  const candidateToken = required(config.candidateToken, \"PALBASE_TEST_CANDIDATE\");\n\n  const requests: RecordedRequest[] = [];\n  let bearer: string | null = null;\n\n  async function call<T>(method: string, path: string, body: unknown, opts: CallOptions = {}): Promise<T> {\n    const headers: Record<string, string> = {\n      apikey: apiKey,\n      // Selects the release under test. Omit it and the gateway serves the LIVE\n      // one, which would make the whole suite grade the wrong code.\n      \"x-palbase-candidate\": candidateToken,\n      ...opts.headers,\n    };\n    if (bearer) headers.authorization = `Bearer ${bearer}`;\n    if (body !== undefined) headers[\"content-type\"] = \"application/json\";\n\n    const startedAt = Date.now();\n    const res = await fetch(`${baseUrl}${path}`, {\n      method,\n      headers,\n      body: body === undefined ? undefined : JSON.stringify(body),\n    });\n    const text = await res.text();\n    const parsed: unknown = text ? safeParse(text) : undefined;\n\n    requests.push({ method, path, status: res.status, ms: Date.now() - startedAt });\n\n    if (!res.ok) throw new TestApiError(method, path, res.status, parsed);\n    return parsed as T;\n  }\n\n  return {\n    requests,\n    get: (path, opts) => call(\"GET\", path, undefined, opts),\n    post: (path, body, opts) => call(\"POST\", path, body, opts),\n    patch: (path, body, opts) => call(\"PATCH\", path, body, opts),\n    put: (path, body, opts) => call(\"PUT\", path, body, opts),\n    delete: (path, opts) => call(\"DELETE\", path, undefined, opts),\n    query: (path, body, opts) => call(\"QUERY\", path, body, opts),\n\n    async signInAs(name) {\n      const identity = (config.identities ?? {})[name];\n      if (!identity) {\n        const declared = Object.keys(config.identities ?? {});\n        throw new Error(\n          `no test identity named ${JSON.stringify(name)} — the deploy mints one per user declared in ` +\n            `config/test-users.ts` +\n            (declared.length\n              ? `; this run has: ${declared.join(\", \")}`\n              : // Not \"you declared none\": from here the two causes are\n                // indistinguishable, and blaming the customer's config for a\n                // platform failure sends them to look in the wrong file. The\n                // deploy log names which one it was.\n                \", and this run has none — either your config declares no users \" +\n                \"or the deploy could not mint them; the deploy log says which\"),\n        );\n      }\n      // The session the mint already issued — no network call, so switching\n      // users is free and the login rail never sees this run.\n      if (identity.accessToken) {\n        bearer = identity.accessToken;\n        return { id: identity.id ?? \"\", email: identity.email };\n      }\n      return this.signIn(identity);\n    },\n\n    async signIn(credentials) {\n      const result = await call<{ access_token: string; user?: { id: string; email?: string } }>(\n        \"POST\",\n        \"/auth/login\",\n        credentials,\n      );\n      bearer = result.access_token;\n      return result.user ?? { id: \"\" };\n    },\n    async signOut() {\n      await call(\"POST\", \"/auth/logout\", undefined);\n      bearer = null;\n    },\n    asAnonymous() {\n      bearer = null;\n    },\n  };\n}\n\n/** The run's identities, as the deploy passed them. Absent is not an error: a\n * project that declares none still runs every test that needs no login. */\nfunction parseIdentities(raw: string | undefined): Record<string, TestIdentity> {\n  if (!raw) return {};\n  try {\n    return JSON.parse(raw) as Record<string, TestIdentity>;\n  } catch {\n    return {};\n  }\n}\n\nfunction safeParse(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\n/** The client the deploy configured, from the environment it set.\n *\n * Constructed lazily so importing this module outside a test run — a typecheck,\n * an editor — does not fail on absent configuration.\n */\nlet configured: TestApi | null = null;\n\nexport const api: TestApi = new Proxy({} as TestApi, {\n  get(_target, prop) {\n    configured ??= createTestApi({\n      baseUrl: process.env.PALBASE_TEST_BASE_URL ?? \"\",\n      apiKey: process.env.PALBASE_TEST_API_KEY ?? \"\",\n      candidateToken: process.env.PALBASE_TEST_CANDIDATE ?? \"\",\n      identities: parseIdentities(process.env.PALBASE_TEST_IDENTITIES),\n    });\n    return Reflect.get(configured, prop, configured);\n  },\n});\n"],"mappings":"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","names":[]}

package/docs/database.md

@@ -178,9 +178,9 @@ nothing your code does. See
 
 Sometimes you need to read or write **across all users** — an admin endpoint, a
 background job that fans out notifications, a cleanup task. For that, call
-`Database.asService()`. It returns a sibling client that runs as the
-`service_role` (which has `BYPASSRLS`), exposing the exact same surface —
-`tables`, the raw string ops, and `transaction`:
+`Database.asService()`. It returns a sibling client that runs as
+**`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
+exact same surface — `tables`, the raw string ops, and `transaction`:
 
 ```ts
 import { Database } from "@palbase/backend";
@@ -209,3 +209,16 @@ Guidelines:
   transaction. Use `Database.transaction(...)` for an authenticated one and
   `Database.asService().transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
+- **It is a second transaction, on a second connection.** It has to be: the
+  Postgres role is bound once, when the transaction opens, so a sibling sharing
+  the request's transaction would run as `backend_authenticated` and silently
+  keep filtering. Three consequences worth knowing:
+  - The request opens it at most once, however many times you call
+    `asService()`, and never at all if you don't use it.
+  - Both settle with the request — commit when your handler returns, roll back
+    when it throws — but they settle as two transactions. A row written through
+    one surface is **not visible** to the other until the request commits.
+  - So don't touch the **same row** from both surfaces in one request: the
+    second surface waits for a lock the first cannot release until the handler
+    returns. The service side gives up after five seconds and tells you this;
+    the default side would wait until the edge cuts the request.

package/docs/llms-full.txt

@@ -1006,9 +1006,9 @@ nothing your code does. See
 
 Sometimes you need to read or write **across all users** — an admin endpoint, a
 background job that fans out notifications, a cleanup task. For that, call
-`Database.asService()`. It returns a sibling client that runs as the
-`service_role` (which has `BYPASSRLS`), exposing the exact same surface —
-`tables`, the raw string ops, and `transaction`:
+`Database.asService()`. It returns a sibling client that runs as
+**`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
+exact same surface — `tables`, the raw string ops, and `transaction`:
 
 ```ts
 import { Database } from "@palbase/backend";
@@ -1037,6 +1037,19 @@ Guidelines:
   transaction. Use `Database.transaction(...)` for an authenticated one and
   `Database.asService().transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
+- **It is a second transaction, on a second connection.** It has to be: the
+  Postgres role is bound once, when the transaction opens, so a sibling sharing
+  the request's transaction would run as `backend_authenticated` and silently
+  keep filtering. Three consequences worth knowing:
+  - The request opens it at most once, however many times you call
+    `asService()`, and never at all if you don't use it.
+  - Both settle with the request — commit when your handler returns, roll back
+    when it throws — but they settle as two transactions. A row written through
+    one surface is **not visible** to the other until the request commits.
+  - So don't touch the **same row** from both surfaces in one request: the
+    second surface waits for a lock the first cannot release until the handler
+    returns. The service side gives up after five seconds and tells you this;
+    the default side would wait until the edge cuts the request.
 
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@palbase/backend",
-  "version": "17.4.0",
-  "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
+  "version": "18.0.0",
+  "description": "Palbase Backend SDK \u2014 class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -62,12 +62,49 @@
         "types": "./dist/purchases/keys.d.cts",
         "default": "./dist/purchases/keys.cjs"
       }
+    },
+    "./engine": {
+      "import": {
+        "types": "./dist/engine/index.d.ts",
+        "default": "./dist/engine/index.js"
+      },
+      "require": {
+        "types": "./dist/engine/index.d.cts",
+        "default": "./dist/engine/index.cjs"
+      }
+    },
+    "./openapi": {
+      "import": {
+        "types": "./dist/openapi/index.d.ts",
+        "default": "./dist/openapi/index.js"
+      },
+      "require": {
+        "types": "./dist/openapi/index.d.cts",
+        "default": "./dist/openapi/index.cjs"
+      }
+    },
+    "./stager": {
+      "require": "./stager/stage.js",
+      "default": "./stager/stage.js"
     }
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "stager",
+    "template"
   ],
+  "scripts": {
+    "build": "tsup && npm run build:stager",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "docs:build": "node scripts/build-llms.mjs",
+    "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs",
+    "check:api": "node scripts/api-surface.mjs",
+    "api:update": "node scripts/api-surface.mjs --update",
+    "build:stager": "mkdir -p stager && cp src/stager/*.js src/stager/package.json stager/"
+  },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^7.3.4",
     "zod": "^3.24.0"
@@ -84,14 +121,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "docs:build": "node scripts/build-llms.mjs",
-    "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs",
-    "check:api": "node scripts/api-surface.mjs",
-    "api:update": "node scripts/api-surface.mjs --update"
+  "bin": {
+    "palbase-backend": "./dist/bin/palbase-backend.js"
   }
-}
+}

package/stager/package.json

@@ -0,0 +1,4 @@
+{
+  "//": "The stager is CommonJS: it is a BUILD-time script driven by node, sharing its two analyzers verbatim with the CLI and the cloud's deploy stager, where they are CommonJS too. The SDK itself is ESM (\"type\": \"module\" one level up), and without this file node reads these .js files as ES modules and refuses their first require().",
+  "type": "commonjs"
+}

package/stager/return_types.js

@@ -0,0 +1,338 @@
+'use strict';
+
+/**
+ * Palbase Backend Runtime — Return-Type Schema Binder (source-`.ts` name reader)
+ *
+ * The response schema of a route is the method's RETURN TYPE, not a separate
+ * `@Returns(...)` decorator (which was removed — clean cutover). For each route
+ * method this reads the WRITTEN return-type annotation from the controller's
+ * SOURCE `.ts` (types are erased by esbuild, so they only exist in source),
+ * resolves the same-named exported zod const, and emits an injection snippet that
+ * binds it onto the controller's route registry at module-eval time — so BOTH the
+ * OpenAPI/codegen extractor AND the deployed pod's runtime output-validation see
+ * the live zod (no esbuild plugin needed; the bind is plain top-level code in the
+ * bundle).
+ *
+ * Convention (enforced — a violation is a HARD build error, never silent):
+ *   - a body-returning route MUST return a NAMED zod-inferred type:
+ *       foo(): Promise<TodoSchema>           → schema = TodoSchema
+ *       foo(): Promise<TodoSchema[]>         → schema = z.array(TodoSchema)
+ *       foo(): TodoSchema / TodoSchema[]     → (Promise optional)
+ *   - `void` / `Promise<void>` / no annotation → no 200 body (allowed)
+ *   - anything else (inline object, union, intersection, a type with no
+ *     same-named exported zod) → HARD error naming <Controller>.<method>.
+ *
+ * This module is SHARED VERBATIM by the deploy extractor and `palbase build`
+ * (the load-bearing serve==deploy parity rule). It uses the `typescript` PARSER
+ * only (ts.createSourceFile) — no type-checker, no Program — so it's cheap and
+ * needs only `typescript` on NODE_PATH.
+ */
+
+let ts = null;
+function loadTS() {
+  if (ts) return ts;
+  let mod;
+  try {
+    mod = require('typescript');
+  } catch (e) {
+    throw new Error(TS_PARSER_HELP('the `typescript` package could not be loaded (' + e.message + ')'));
+  }
+  // TypeScript 7 is the Go-native compiler: its CommonJS entry exports only
+  // { version, versionMajorMinor } — no createSourceFile, no ScriptTarget. Reading
+  // `ts.ScriptTarget.ES2022` off it threw "Cannot read properties of undefined",
+  // which told the user nothing. Check the surface we need and SAY what's wrong.
+  if (typeof mod.createSourceFile !== 'function' || !mod.ScriptTarget) {
+    throw new Error(TS_PARSER_HELP(
+      'the resolved `typescript` (v' + (mod.version || 'unknown') + ') has no compiler API — ' +
+        'TypeScript 7 ships the Go-native compiler, whose CommonJS build exposes version metadata only',
+    ));
+  }
+  ts = mod;
+  return ts;
+}
+
+// One actionable message for both parser-load failures. The CLI/pod normally puts
+// its OWN pinned TypeScript 5 ahead of the project on NODE_PATH, so reaching this
+// means that provisioning was skipped (offline first run) and the fallback — the
+// project's typescript — is unusable.
+function TS_PARSER_HELP(reason) {
+  return (
+    'palbase needs the TypeScript 5 compiler API to read controller return types, but ' +
+    reason +
+    '.\n  fix: npm install --save-dev typescript@5   (or re-run once online: the CLI installs its own pinned parser)'
+  );
+}
+
+class ReturnTypeError extends Error {}
+
+// Symbols MUST match the SDK (@palbase/backend src/decorators/registry.ts).
+const ROUTES_SYMBOL_KEY = 'palbase.backend.routes';
+const RETURN_BUFFER_SYMBOL_KEY = 'palbase.backend.returnBuffer';
+
+/**
+ * Parse one controller source file and return, per method, the resolved
+ * return-type binding the injector needs.
+ *
+ * @param {string} sourceText  the controller's .ts source
+ * @param {string} fileLabel   path/name for error messages
+ * @returns {{ className: string, methods: Array<{ fnName, typeName, isArray }>, imports: Record<string,string> }}
+ *   - methods: only routes that HAVE a resolvable named return type (void/none omitted)
+ *   - imports: local-binding-name → module-specifier (for the injector's import)
+ *   Throws ReturnTypeError on an un-resolvable/disallowed return type.
+ */
+function readReturnTypes(sourceText, fileLabel) {
+  const tsapi = loadTS();
+  const sf = tsapi.createSourceFile(
+    fileLabel || 'controller.ts',
+    sourceText,
+    tsapi.ScriptTarget.ES2022,
+    /* setParentNodes */ true,
+  );
+
+  // Map local binding name → module specifier, for named imports only.
+  // `import { TodoSchema } from "../models/todo"`         → TodoSchema:"../models/todo"
+  // `import { TodoSchema as T } from "../models/todo"`    → T:"../models/todo" (+ original)
+  const imports = {};        // localName → specifier
+  const importOriginal = {}; // localName → originalExportedName (for aliases)
+  for (const stmt of sf.statements) {
+    if (!tsapi.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    const spec = stmt.moduleSpecifier.text;
+    const named = stmt.importClause.namedBindings;
+    if (named && tsapi.isNamedImports(named)) {
+      for (const el of named.elements) {
+        const local = el.name.text;
+        const original = el.propertyName ? el.propertyName.text : local;
+        imports[local] = spec;
+        importOriginal[local] = original;
+      }
+    }
+  }
+
+  let className = null;
+  const methods = [];
+
+  function err(method, msg) {
+    return new ReturnTypeError(
+      `${fileLabel || 'controller'} — ${className || '?'}.${method}: ${msg}`,
+    );
+  }
+
+  // Unwrap Promise<T>, detect arrays, and require a single named type reference.
+  // Returns { typeName, isArray } or null for void/undefined/no-annotation.
+  function resolveType(typeNode, method) {
+    if (!typeNode) return null; // no annotation → allowed (void-ish)
+
+    // Promise<X> → unwrap
+    if (
+      tsapi.isTypeReferenceNode(typeNode) &&
+      typeNode.typeName.getText(sf) === 'Promise' &&
+      typeNode.typeArguments &&
+      typeNode.typeArguments.length === 1
+    ) {
+      return resolveType(typeNode.typeArguments[0], method);
+    }
+
+    // void / undefined → no body
+    if (
+      typeNode.kind === tsapi.SyntaxKind.VoidKeyword ||
+      typeNode.kind === tsapi.SyntaxKind.UndefinedKeyword
+    ) {
+      return null;
+    }
+
+    // X[]  → array of element
+    if (tsapi.isArrayTypeNode(typeNode)) {
+      const inner = resolveNamed(typeNode.elementType, method);
+      return { typeName: inner, isArray: true };
+    }
+
+    // Array<X> → array of element
+    if (
+      tsapi.isTypeReferenceNode(typeNode) &&
+      typeNode.typeName.getText(sf) === 'Array' &&
+      typeNode.typeArguments &&
+      typeNode.typeArguments.length === 1
+    ) {
+      const inner = resolveNamed(typeNode.typeArguments[0], method);
+      return { typeName: inner, isArray: true };
+    }
+
+    // A single named type reference (no type args) → the schema name
+    return { typeName: resolveNamed(typeNode, method), isArray: false };
+  }
+
+  // A node that resolves to a single schema NAME. Accepts either form (so the
+  // author never has to write a separate `export type X` line):
+  //   - a bare reference to the schema:        `TodoSchema`
+  //   - the zod-inferred type of the schema:   `z.infer<typeof TodoSchema>`
+  //     (and the std `z.output<...>` / `z.input<...>` aliases)
+  // Anything else — inline object, union, intersection, literal, other generic —
+  // is a hard error (name the schema in a model file).
+  function resolveNamed(node, method) {
+    // bare `TodoSchema`
+    if (tsapi.isTypeReferenceNode(node) && !node.typeArguments) {
+      return node.typeName.getText(sf);
+    }
+    // `z.infer<typeof TodoSchema>` (or z.output / z.input) → unwrap to TodoSchema
+    if (tsapi.isTypeReferenceNode(node) && node.typeArguments && node.typeArguments.length === 1) {
+      const head = node.typeName.getText(sf); // e.g. "z.infer" / "infer"
+      if (/^(z\.)?(infer|output|input)$/.test(head)) {
+        const arg = node.typeArguments[0];
+        // arg is `typeof TodoSchema` — a TypeQuery whose exprName is the schema.
+        if (tsapi.isTypeQueryNode(arg)) {
+          return arg.exprName.getText(sf);
+        }
+        // tolerate a plain reference inside (rare): z.infer<TodoSchema>
+        if (tsapi.isTypeReferenceNode(arg) && !arg.typeArguments) {
+          return arg.typeName.getText(sf);
+        }
+      }
+    }
+    if (node.kind === tsapi.SyntaxKind.VoidKeyword) {
+      throw err(method, 'void cannot appear inside an array/Promise here');
+    }
+    throw err(
+      method,
+      'return type must be a NAMED zod schema — write `Promise<z.infer<typeof TodoSchema>>` ' +
+        '(or `TodoSchema` / `TodoSchema[]`); inline objects, unions, literals, and other ' +
+        'generics are not allowed — name the schema in a model file',
+    );
+  }
+
+  for (const stmt of sf.statements) {
+    if (!tsapi.isClassDeclaration(stmt)) continue;
+    // Only consider a class decorated with @Controller (the routing surface).
+    const decos = tsapi.getDecorators ? tsapi.getDecorators(stmt) || [] : [];
+    const isController = decos.some((d) => {
+      const ex = d.expression;
+      const callee = tsapi.isCallExpression(ex) ? ex.expression : ex;
+      return callee && callee.getText(sf) === 'Controller';
+    });
+    if (!isController) continue;
+    className = stmt.name ? stmt.name.text : null;
+
+    for (const m of stmt.members) {
+      if (!tsapi.isMethodDeclaration(m)) continue;
+      const mdecos = tsapi.getDecorators ? tsapi.getDecorators(m) || [] : [];
+      const isRoute = mdecos.some((d) => {
+        const ex = d.expression;
+        const callee = tsapi.isCallExpression(ex) ? ex.expression : ex;
+        const n = callee && callee.getText(sf);
+        return n === 'Get' || n === 'Post' || n === 'Put' || n === 'Patch' || n === 'Delete' || n === 'Query'
+          // @Upload is a route like any other: on the wire it is a POST, and its
+          // RETURN TYPE is the completion's response contract. Leaving it out here
+          // meant an @Upload method's return type was never read, so the operation
+          // shipped with NO 200 schema and every generated client got an EMPTY
+          // response struct — the upload worked and the document it returns
+          // (url, variants, caption) was untyped and unreachable from the app.
+          || n === 'Upload';
+      });
+      if (!isRoute) continue;
+
+      const fnName = m.name.getText(sf);
+      // A route method MUST declare its return type explicitly — either a named
+      // zod schema or `void`/`Promise<void>`. A missing annotation is the SAME
+      // silent gap @Returns had (codegen would emit an untyped struct), so it's a
+      // HARD error: the author must say what the route returns.
+      if (!m.type) {
+        throw err(
+          fnName,
+          'route method has no return type — annotate it (e.g. `: Promise<TodoSchema>`, ' +
+            '`: TodoSchema[]`, or `: void` for no body)',
+        );
+      }
+      const resolved = resolveType(m.type, fnName);
+      if (!resolved) continue; // explicit void/Promise<void> — no 200 body, allowed
+
+      const { typeName, isArray } = resolved;
+      // The schema name must be an imported (or locally-defined) value. If it's
+      // not imported, we can't bind it from the bundle — hard error.
+      if (!(typeName in imports) && !localValueExists(sf, typeName, tsapi)) {
+        throw err(
+          fnName,
+          `return type \`${typeName}\` has no matching imported/exported zod schema in scope — ` +
+            `export \`const ${typeName} = z.object(...)\` and import it`,
+        );
+      }
+      methods.push({ fnName, typeName, isArray });
+    }
+  }
+
+  return { className, methods, imports, importOriginal };
+}
+
+// A schema declared in the controller file itself (rare) — `const X = z...`.
+function localValueExists(sf, name, tsapi) {
+  for (const stmt of sf.statements) {
+    if (tsapi.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (d.name.getText(sf) === name) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Build the JS injection snippet appended to a controller's source (or its
+ * generated sibling) BEFORE esbuild bundles it. It writes each method's
+ * return-schema onto the controller class's route registry (the same
+ * ROUTES/returnBuffer symbols the SDK uses), wrapping arrays in z.array.
+ *
+ * The snippet imports nothing new beyond `z` and the schema consts (which the
+ * controller already imports, so they're already in the bundle — referencing
+ * them here keeps esbuild from tree-shaking them).
+ *
+ * @returns {string} the snippet, or '' when there's nothing to bind.
+ */
+function buildInjection(parsed) {
+  if (!parsed.className || parsed.methods.length === 0) return '';
+  const cls = parsed.className;
+  const lines = [];
+  lines.push('');
+  lines.push('// --- AUTO-GENERATED: route return-schema bindings (from return types) ---');
+  lines.push('(() => {');
+  lines.push(`  const __ROUTES = Symbol.for(${JSON.stringify(ROUTES_SYMBOL_KEY)});`);
+  lines.push(`  const __RBUF = Symbol.for(${JSON.stringify(RETURN_BUFFER_SYMBOL_KEY)});`);
+  lines.push(`  const __ctor = ${cls};`);
+  lines.push('  const __bind = (fn, schema) => {');
+  lines.push('    const routes = __ctor[__ROUTES];');
+  lines.push('    const r = routes && routes.find((x) => x.fnName === fn);');
+  lines.push('    if (r) { r.returnSchema = schema; return; }');
+  lines.push('    if (!__ctor[__RBUF]) __ctor[__RBUF] = {};');
+  lines.push('    __ctor[__RBUF][fn] = schema;');
+  lines.push('  };');
+  for (const m of parsed.methods) {
+    const expr = m.isArray ? `z.array(${m.typeName})` : m.typeName;
+    lines.push(`  __bind(${JSON.stringify(m.fnName)}, ${expr});`);
+  }
+  lines.push('})();');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Append the return-schema injection to a controller's source text. Ensures `z`
+ * is in scope (controllers already import it from @palbase/backend; if not, we
+ * add the import). Pure string transform — the caller writes the result to the
+ * file esbuild will bundle.
+ */
+function injectReturnBindings(sourceText, fileLabel) {
+  const parsed = readReturnTypes(sourceText, fileLabel);
+  const snippet = buildInjection(parsed);
+  if (!snippet) return sourceText;
+  let out = sourceText;
+  // Ensure `z` is importable for z.array(...) wrapping.
+  if (!/\bimport\b[^\n]*\bz\b[^\n]*@palbase\/backend/.test(sourceText) &&
+      !/\bimport\b[^\n]*\{[^}]*\bz\b[^}]*\}/.test(sourceText)) {
+    out = `import { z } from "@palbase/backend";\n` + out;
+  }
+  return out + '\n' + snippet + '\n';
+}
+
+module.exports = {
+  ReturnTypeError,
+  readReturnTypes,
+  buildInjection,
+  injectReturnBindings,
+};

package/stager/stage.js

@@ -0,0 +1,78 @@
+/**
+ * Staging a project's controllers so their RETURN TYPES become response schemas.
+ *
+ * WHY THIS LIVES IN THE SDK. The two analyzers beside this file read THIS
+ * package's decorators and write THIS package's `recordReturn` / `recordThrows`
+ * calls — so the code that reads a return type and the code that defines what a
+ * return type means are versioned together, and cannot drift apart. They used to
+ * live in the CLI and in the cloud's deploy stager as verbatim copies kept
+ * honest by a workflow; a third copy was about to be written for the container
+ * push, which is the point at which copies stop being kept honest.
+ *
+ *   node stage.js <controllers-dir> <staging-dir> <project-root>
+ *
+ * The staging directory must be a SIBLING of controllers/: module resolution
+ * walks up from the file being bundled, so a directory outside the project
+ * cannot see node_modules, and one nested a level deeper turns every
+ * `../services` into a path outside the project.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+
+const returnTypes = require("./return_types.js");
+const throwAnalysis = require("./throw_analysis.js");
+
+function walk(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Copy `srcDir` into `stageDir`, injecting into controllers and copying
+ * everything else verbatim — services and models are imported from the staged
+ * tree and must still resolve.
+ */
+function stageControllers(srcDir, stageDir, projectRoot) {
+  let injected = 0;
+  for (const file of walk(srcDir)) {
+    const rel = path.relative(srcDir, file);
+    const dest = path.join(stageDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (/\.controller\.(c?ts|tsx)$/i.test(path.basename(file))) {
+      let out = returnTypes.injectReturnBindings(fs.readFileSync(file, "utf8"), rel);
+      out = throwAnalysis.injectThrowBindings(out, file, {
+        readFile: (p) => {
+          try {
+            return fs.readFileSync(p, "utf8");
+          } catch {
+            return null;
+          }
+        },
+        fileExists: (p) => fs.existsSync(p),
+        projectRoot,
+      });
+      fs.writeFileSync(dest, out);
+      injected += 1;
+    } else {
+      fs.copyFileSync(file, dest);
+    }
+  }
+  return injected;
+}
+
+module.exports = { stageControllers };
+
+if (require.main === module) {
+  const [srcDir, stageDir, projectRoot] = process.argv.slice(2);
+  if (!srcDir || !stageDir || !projectRoot) {
+    console.error("usage: stage.js <controllers-dir> <staging-dir> <project-root>");
+    process.exit(2);
+  }
+  const injected = stageControllers(srcDir, stageDir, projectRoot);
+  console.log(`typed ${injected} controller file(s) from their return types`);
+}