@palbase/backend 34.1.1 → 35.0.1

package/dist/openapi/index.d.cts

@@ -1,7 +1,7 @@
 import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
 import { ZodTypeAny } from 'zod';
-import { A as AuthSpec, R as RateLimitConfig } from '../endpoint-DqhUP7RT.cjs';
-import { P as ParamMeta, T as ThrowDescriptor, U as UploadConfig, S as SseConfig } from '../registry-BkIVHPzB.cjs';
+import { A as AuthSpec, R as RateLimitConfig } from '../endpoint-DaGnjt42.cjs';
+import { P as ParamMeta, T as ThrowDescriptor, U as UploadConfig, S as SseConfig } from '../registry-BnKvIyve.cjs';
 import '../stack.cjs';
 import '../db/env.cjs';
 import 'node:async_hooks';

package/dist/openapi/index.d.ts

@@ -1,7 +1,7 @@
 import { OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
 import { ZodTypeAny } from 'zod';
-import { A as AuthSpec, R as RateLimitConfig } from '../endpoint-BXPdsTA5.js';
-import { P as ParamMeta, T as ThrowDescriptor, U as UploadConfig, S as SseConfig } from '../registry-CvGLR5j1.js';
+import { A as AuthSpec, R as RateLimitConfig } from '../endpoint-BI0yGuEL.js';
+import { P as ParamMeta, T as ThrowDescriptor, U as UploadConfig, S as SseConfig } from '../registry-zDCj0eOU.js';
 import '../stack.js';
 import '../db/env.js';
 import 'node:async_hooks';

package/dist/{registry-BkIVHPzB.d.cts → registry-BnKvIyve.d.cts}

@@ -1,4 +1,4 @@
-import { D as DatabaseBudget, A as AuthSpec, R as RateLimitConfig } from './endpoint-DqhUP7RT.cjs';
+import { D as DatabaseBudget, A as AuthSpec, R as RateLimitConfig } from './endpoint-DaGnjt42.cjs';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.cjs';
 

package/dist/{registry-CvGLR5j1.d.ts → registry-zDCj0eOU.d.ts}

@@ -1,4 +1,4 @@
-import { D as DatabaseBudget, A as AuthSpec, R as RateLimitConfig } from './endpoint-BXPdsTA5.js';
+import { D as DatabaseBudget, A as AuthSpec, R as RateLimitConfig } from './endpoint-BI0yGuEL.js';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.js';
 

package/dist/test/index.d.cts

@@ -1,5 +1,5 @@
 import { T as Token } from '../module-Dl1KFVtc.cjs';
-import { E as EnvServiceDatabase, a as DBClient, b as RuntimeServices } from '../endpoint-DqhUP7RT.cjs';
+import { E as EnvServiceDatabase, a as DBClient, b as RuntimeServices } from '../endpoint-DaGnjt42.cjs';
 import 'zod';
 import '../stack.cjs';
 import '../db/env.cjs';

package/dist/test/index.d.ts

@@ -1,5 +1,5 @@
 import { T as Token } from '../module-Dl1KFVtc.js';
-import { E as EnvServiceDatabase, a as DBClient, b as RuntimeServices } from '../endpoint-BXPdsTA5.js';
+import { E as EnvServiceDatabase, a as DBClient, b as RuntimeServices } from '../endpoint-BI0yGuEL.js';
 import 'zod';
 import '../stack.js';
 import '../db/env.js';

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": "34.1.1",
+  "version": "35.0.1",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {

package/stager/generics.js

@@ -163,6 +163,12 @@ const SKIP = new Set([
   '.palbase',
   '.palbase-staged-controllers',
   '.palbase-build-controllers',
+  // An iOS app's build output beside the backend (stage.js SKIP, same list):
+  // not source, large, and Xcode writes symlinks into it.
+  'DerivedData',
+  '.build',
+  'Pods',
+  'xcuserdata',
 ]);
 
 function sources(dir, root, out) {
@@ -173,12 +179,14 @@ function sources(dir, root, out) {
     return out;
   }
   for (const entry of entries) {
-    if (entry.name.startsWith('.') && entry.name !== '.') {
-      if (SKIP.has(entry.name)) continue;
-    }
+    if (SKIP.has(entry.name)) continue;
+    // Symlinks are skipped here for the same reason stage.js skips them: this
+    // walk runs BEFORE staging, on the whole project root, and a dangling link
+    // whose name ends in `.ts` used to refuse the entire push with ENOENT one
+    // function before the stager's own guard could (W4 r2 C-2).
+    if (entry.isSymbolicLink()) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (SKIP.has(entry.name)) continue;
       sources(full, root, out);
     } else if (/\.(c?ts|tsx)$/i.test(entry.name) && !/\.d\.ts$/i.test(entry.name)) {
       out.push(full);

package/stager/stage.js

@@ -36,9 +36,23 @@ const throwAnalysis = require("./throw_analysis.js");
  * resolves from above the staged tree anyway, and `.palbase*` holds build output
  * including previous staging runs.
  */
-const SKIP = new Set(["node_modules", "dist", "build", ".git", ".palbase"]);
+//
+// The last four are an iOS app's build output, which lives BESIDE the backend
+// in a project that ships both (the 2026-09-06 demo did). None of it is source
+// the stager could type, all of it is large, and Xcode writes symlinks into it.
+const SKIP = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".palbase",
+  "DerivedData",
+  ".build",
+  "Pods",
+  "xcuserdata",
+]);
 
-function walk(dir) {
+function walk(dir, root = dir) {
   const out = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     // Skipped by NAME, not by type: `node_modules` is often a SYMLINK (pnpm, and
@@ -46,8 +60,29 @@ function walk(dir) {
     // for one — so a type-gated check walked straight into it and tried to
     // `copyFileSync` a symlinked directory. Measured: ENOTSUP, copyfile.
     if (SKIP.has(entry.name) || entry.name.startsWith(".palbase")) continue;
+    // And every OTHER symlink is skipped by TYPE. A staged copy is a copy of
+    // the project's source; a link is a pointer to something that is either
+    // already in the tree (staged once under its real name), outside it (not
+    // this project's source), or gone. `copyFileSync` on one is ENOENT when the
+    // target is missing and ENOTSUP on a bind mount — measured 2026-09-06 on a
+    // demo whose `ios/DerivedData/Framework/Resources` was a dangling link, and
+    // that one link refused the whole push.
     const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walk(full));
+    if (entry.isSymbolicLink()) {
+      // Said once, with the path from the project root, so a `TS2307 Cannot
+      // find module` in the staged copy has its explanation next to it: a
+      // project that symlinks a shared source directory stages a tree without
+      // it (the declared FR-037 trade-off).
+      let target = '';
+      try {
+        target = fs.readlinkSync(full);
+      } catch {
+        /* unreadable link: nothing to name */
+      }
+      process.stderr.write(`stager: skipped symlink ${path.relative(root, full)} -> ${target}\n`);
+      continue;
+    }
+    if (entry.isDirectory()) out.push(...walk(full, root));
     else out.push(full);
   }
   return out;

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": {