@palbase/backend 35.0.0 → 35.0.1

package/docs/README.md

@@ -82,7 +82,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 34.
+> and will not compile against `@palbase/backend` 35.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/database.md

@@ -825,7 +825,56 @@ continue to return their rows. Custom SQL drivers must expose an integer `count`
 on a non-returning result. Empty input opens no connection. The batch remains one
 statement and participates in its enclosing transaction's rollback.
 
-## Reusable queries and response contracts
+## Query results and response contracts
+
+Use the ordinary CRUD expression. A controller without a return annotation gets
+its response validator, OpenAPI response and generated client type from the
+TypeScript return type, following calls through injected services:
+
+```ts
+// Store/service
+list(prefix: string) {
+  return Database.public.todos.findMany({
+    where: { title: { startsWith: prefix } },
+    select: ["id", "title"],
+    limit: 50,
+  });
+}
+
+// Controller
+@Get("/")
+list(@QueryParams(ListInput) input: ListInput) {
+  return this.todos.list(input.prefix);
+}
+```
+
+The generated contract contains only `id` and `title`. `findUnique` retains
+nullability, `page` retains its rows/pageInfo shape, and `insertMany` with
+`returning: false` returns a count. Use `updateMany` for one bulk UPDATE; a
+command plan is useful when several dependent operations actually belong together.
+
+Inference does not execute application code or capture a Database/transaction
+handle. Reuse a normal service method; inside an atomic callback, use its `tx`
+argument. A service-role handle still owns a separate transaction and identity.
+
+The build refuses `any`, `unknown`, unresolved imports, recursive/class/tuple
+responses and unsupported JSON shapes. Supply a named Zod response schema when
+needed. Existing named Zod annotations remain supported. Inference describes
+the static JSON shape; an explicit schema remains useful for semantic constraints
+such as UUID formats or a domain-specific numeric range. Input validation still
+uses the existing `@Body`/`@QueryParams` schema.
+
+Invalid response values and serialization failures roll the request transaction
+back before COMMIT. A committed independent `$atomic` call retains its existing
+independent commit semantics; response validation cannot undo an earlier commit.
+An explicit nullable response returns HTTP 200 with JSON `null`; a response with
+no body remains 204. This fixes nullable client contracts previously receiving an
+empty body.
+
+### Existing query definitions
+
+`defineQuery` is deprecated for normal application work. Its existing `run`,
+SQL inspection, manifests and validation remain supported for compatibility.
 
 `defineQuery` combines an explicit selection with a reusable input/filter. The
 result is also a Zod array schema: a controller can return
@@ -934,35 +983,60 @@ one invoker helper call with sequential statements inside PostgreSQL. The helper
 adds JSON/dynamic-SQL processing; measure the actual plan and network before
 selecting it for throughput. Fewer round trips alone do not guarantee a speedup.
 
-For contention on the same accounts/resources, declare a workload once:
+Core owns admission for ordinary CRUD, raw queries, request transactions,
+`$atomic`, service-role operations, upload authorization and scheduled database
+work. Nested savepoints reuse their parent's admitted connection. Application
+code does not declare concurrency or queue capacities:
 
 ```ts
-const transfers = defineWorkload("transfers", {
-  concurrency: 16, queueLimit: 128,
-  tenantConcurrency: 8, tenantQueueLimit: 32, queueTimeoutMs: 1000,
-});
-
 await Database.$atomic(async tx => {
   // Decision reads, idempotency claim, writes, ledger and outbox belong here.
 }, {
-  workload: transfers,
-  conflictKeys: [fromAccountId, toAccountId],
   timeoutMs: 3000, signal, retry: 2,
 });
 ```
 
-Overlapping resource keys are admitted in order. Independent keys and tenants
-can proceed while those requests wait. Queue size and per-tenant budgets are
-bounded; full/expired queues return 429 before opening a transaction. Tenant
-identity comes from the configured verified claim (`tenant_id`, then `sub`, then
-one anonymous bucket). Keys are shared within a workload; include the tenant in
-a key if resource IDs are only tenant-unique. Rejected/cancelled waiters leave the
-queue. The lease spans every retry and transaction settlement.
-
-These limits apply per engine/driver instance. Divide pool/admission budgets
-across replicas; PostgreSQL locks and constraints remain authoritative across
-instances. Admission is optional because independent work also pays its cost.
-Each driver supports at most 64 named workloads.
+The core process shares one physical pool across live and candidate applications.
+Reloading or discarding an application does not create another pool. A retiring
+application drains its requests/jobs through transaction settlement before
+closing its own resources.
+
+Before independent `$atomic` work, core releases an implicit transaction that
+contains only its authorization reads. This prevents requests holding the whole
+pool while each waits for a second connection. Role/permission decisions still
+come from verified identity and current database state, once per request. Once
+application SQL runs, its enclosing transaction is retained; atomic work never
+silently commits an application's earlier write or changes its identity.
+
+Admission happens before BEGIN and its lease lasts through COMMIT/ROLLBACK.
+Full/expired queues return an explicit 429; cancellation removes queued work.
+The private runtime `/_internal/database` probe exposes current admission counts,
+rejection reasons and PostgreSQL connection groups. It is on the internal probe
+port, not the public edge.
+
+These are resource protections, not product quotas or a transactions-per-second
+limit. `DB_POOL_MAX` remains a deployment setting, not a business-code parameter.
+It is a per-process maximum; PostgreSQL's server limit is shared by every
+process. Operators must account for every runtime application pool, control
+pool, palsvc pool, migration/admin connection and replication connection in
+their server resource plan. An instance-local queue is not a cluster-wide
+admission guarantee. Core contains no Free/Pro tier logic.
+
+Optional deployment settings are `PALBASE_DB_QUEUE_LIMIT` (default: eight times
+the application pool size, bounded to 32–512), `PALBASE_DB_QUEUE_TIMEOUT_MS`
+(default: 1000), and `PALBASE_DB_TENANT_CLAIM`. These defaults bound transient
+memory/waiting; they are not a measured optimum for every installation. Fairness
+uses verified `sub` by default, with round robin under contention. One identity
+can use the entire available pool. A custom tenant claim must be signed and
+issuer-controlled; do not use editable user metadata. Missing metadata does not
+reduce an installation to a fraction of its pool.
+
+Existing `defineWorkload` options retain their old behavior, including conflict
+ordering and any explicit tenant cap. They are deprecated, not silently ignored.
+Removing them removes that application-local scheduling policy; sorted database
+row locks and constraints remain the authority across all runtime instances.
+Do not place external service calls in a retryable callback. Use an idempotency
+claim and transactional outbox for effects that must survive retries.
 
 `timeoutMs` includes queueing, callback work and retries. The default driver uses
 a separate control pool of at most two connections to cancel active PostgreSQL
@@ -1002,8 +1076,9 @@ disabled; the completion callback includes settlement timings. Only the first
 
 | Metric | Meaning |
 | --- | --- |
-| `queueMs` | Workload admission wait, including refused waits |
+| `queueMs` | Core admission and legacy workload wait, including refused waits |
 | `poolMs` | Driver acquisition through transaction callback entry, including BEGIN |
+| `connectionMs` | Connection held from transaction callback entry through COMMIT/ROLLBACK settlement |
 | `setupMs` | Isolation, cancellation ticket and role/claims setup |
 | `sqlMs` | Awaited driver time, including execution, lock and network waits |
 | `commitMs` / `rollbackMs` | Observed settlement waits |

package/docs/llms-full.txt

@@ -90,7 +90,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 34.
+> and will not compile against `@palbase/backend` 35.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -1929,7 +1929,56 @@ continue to return their rows. Custom SQL drivers must expose an integer `count`
 on a non-returning result. Empty input opens no connection. The batch remains one
 statement and participates in its enclosing transaction's rollback.
 
-## Reusable queries and response contracts
+## Query results and response contracts
+
+Use the ordinary CRUD expression. A controller without a return annotation gets
+its response validator, OpenAPI response and generated client type from the
+TypeScript return type, following calls through injected services:
+
+```ts
+// Store/service
+list(prefix: string) {
+  return Database.public.todos.findMany({
+    where: { title: { startsWith: prefix } },
+    select: ["id", "title"],
+    limit: 50,
+  });
+}
+
+// Controller
+@Get("/")
+list(@QueryParams(ListInput) input: ListInput) {
+  return this.todos.list(input.prefix);
+}
+```
+
+The generated contract contains only `id` and `title`. `findUnique` retains
+nullability, `page` retains its rows/pageInfo shape, and `insertMany` with
+`returning: false` returns a count. Use `updateMany` for one bulk UPDATE; a
+command plan is useful when several dependent operations actually belong together.
+
+Inference does not execute application code or capture a Database/transaction
+handle. Reuse a normal service method; inside an atomic callback, use its `tx`
+argument. A service-role handle still owns a separate transaction and identity.
+
+The build refuses `any`, `unknown`, unresolved imports, recursive/class/tuple
+responses and unsupported JSON shapes. Supply a named Zod response schema when
+needed. Existing named Zod annotations remain supported. Inference describes
+the static JSON shape; an explicit schema remains useful for semantic constraints
+such as UUID formats or a domain-specific numeric range. Input validation still
+uses the existing `@Body`/`@QueryParams` schema.
+
+Invalid response values and serialization failures roll the request transaction
+back before COMMIT. A committed independent `$atomic` call retains its existing
+independent commit semantics; response validation cannot undo an earlier commit.
+An explicit nullable response returns HTTP 200 with JSON `null`; a response with
+no body remains 204. This fixes nullable client contracts previously receiving an
+empty body.
+
+### Existing query definitions
+
+`defineQuery` is deprecated for normal application work. Its existing `run`,
+SQL inspection, manifests and validation remain supported for compatibility.
 
 `defineQuery` combines an explicit selection with a reusable input/filter. The
 result is also a Zod array schema: a controller can return
@@ -2038,35 +2087,60 @@ one invoker helper call with sequential statements inside PostgreSQL. The helper
 adds JSON/dynamic-SQL processing; measure the actual plan and network before
 selecting it for throughput. Fewer round trips alone do not guarantee a speedup.
 
-For contention on the same accounts/resources, declare a workload once:
+Core owns admission for ordinary CRUD, raw queries, request transactions,
+`$atomic`, service-role operations, upload authorization and scheduled database
+work. Nested savepoints reuse their parent's admitted connection. Application
+code does not declare concurrency or queue capacities:
 
 ```ts
-const transfers = defineWorkload("transfers", {
-  concurrency: 16, queueLimit: 128,
-  tenantConcurrency: 8, tenantQueueLimit: 32, queueTimeoutMs: 1000,
-});
-
 await Database.$atomic(async tx => {
   // Decision reads, idempotency claim, writes, ledger and outbox belong here.
 }, {
-  workload: transfers,
-  conflictKeys: [fromAccountId, toAccountId],
   timeoutMs: 3000, signal, retry: 2,
 });
 ```
 
-Overlapping resource keys are admitted in order. Independent keys and tenants
-can proceed while those requests wait. Queue size and per-tenant budgets are
-bounded; full/expired queues return 429 before opening a transaction. Tenant
-identity comes from the configured verified claim (`tenant_id`, then `sub`, then
-one anonymous bucket). Keys are shared within a workload; include the tenant in
-a key if resource IDs are only tenant-unique. Rejected/cancelled waiters leave the
-queue. The lease spans every retry and transaction settlement.
-
-These limits apply per engine/driver instance. Divide pool/admission budgets
-across replicas; PostgreSQL locks and constraints remain authoritative across
-instances. Admission is optional because independent work also pays its cost.
-Each driver supports at most 64 named workloads.
+The core process shares one physical pool across live and candidate applications.
+Reloading or discarding an application does not create another pool. A retiring
+application drains its requests/jobs through transaction settlement before
+closing its own resources.
+
+Before independent `$atomic` work, core releases an implicit transaction that
+contains only its authorization reads. This prevents requests holding the whole
+pool while each waits for a second connection. Role/permission decisions still
+come from verified identity and current database state, once per request. Once
+application SQL runs, its enclosing transaction is retained; atomic work never
+silently commits an application's earlier write or changes its identity.
+
+Admission happens before BEGIN and its lease lasts through COMMIT/ROLLBACK.
+Full/expired queues return an explicit 429; cancellation removes queued work.
+The private runtime `/_internal/database` probe exposes current admission counts,
+rejection reasons and PostgreSQL connection groups. It is on the internal probe
+port, not the public edge.
+
+These are resource protections, not product quotas or a transactions-per-second
+limit. `DB_POOL_MAX` remains a deployment setting, not a business-code parameter.
+It is a per-process maximum; PostgreSQL's server limit is shared by every
+process. Operators must account for every runtime application pool, control
+pool, palsvc pool, migration/admin connection and replication connection in
+their server resource plan. An instance-local queue is not a cluster-wide
+admission guarantee. Core contains no Free/Pro tier logic.
+
+Optional deployment settings are `PALBASE_DB_QUEUE_LIMIT` (default: eight times
+the application pool size, bounded to 32–512), `PALBASE_DB_QUEUE_TIMEOUT_MS`
+(default: 1000), and `PALBASE_DB_TENANT_CLAIM`. These defaults bound transient
+memory/waiting; they are not a measured optimum for every installation. Fairness
+uses verified `sub` by default, with round robin under contention. One identity
+can use the entire available pool. A custom tenant claim must be signed and
+issuer-controlled; do not use editable user metadata. Missing metadata does not
+reduce an installation to a fraction of its pool.
+
+Existing `defineWorkload` options retain their old behavior, including conflict
+ordering and any explicit tenant cap. They are deprecated, not silently ignored.
+Removing them removes that application-local scheduling policy; sorted database
+row locks and constraints remain the authority across all runtime instances.
+Do not place external service calls in a retryable callback. Use an idempotency
+claim and transactional outbox for effects that must survive retries.
 
 `timeoutMs` includes queueing, callback work and retries. The default driver uses
 a separate control pool of at most two connections to cancel active PostgreSQL
@@ -2106,8 +2180,9 @@ disabled; the completion callback includes settlement timings. Only the first
 
 | Metric | Meaning |
 | --- | --- |
-| `queueMs` | Workload admission wait, including refused waits |
+| `queueMs` | Core admission and legacy workload wait, including refused waits |
 | `poolMs` | Driver acquisition through transaction callback entry, including BEGIN |
+| `connectionMs` | Connection held from transaction callback entry through COMMIT/ROLLBACK settlement |
 | `setupMs` | Isolation, cancellation ticket and role/claims setup |
 | `sqlMs` | Awaited driver time, including execution, lock and network waits |
 | `commitMs` / `rollbackMs` | Observed settlement waits |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "35.0.0",
+  "version": "35.0.1",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {

package/template/package.json

@@ -3,13 +3,13 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "A Palbase backend — class controllers, a declared database, and the secrets it needs.",
+  "description": "A Palbase backend \u2014 class controllers, a declared database, and the secrets it needs.",
   "scripts": {
     "test": "./scripts/test.sh",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^34.0.0",
+    "@palbase/backend": "^35.0.0",
     "reflect-metadata": "^0.2.2"
   },
   "engines": {