@palbase/backend 35.0.0 → 36.0.0

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` 36.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/database.md

@@ -825,58 +825,51 @@ 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
 
-`defineQuery` combines an explicit selection with a reusable input/filter. The
-result is also a Zod array schema: a controller can return
-`Promise<z.infer<typeof ListTodos>>`, and the existing build binder uses that
-same value for response validation, OpenAPI and generated clients.
+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
-export const ListTodos = defineQuery("ListTodos", {
-  table: todos, // a defineTable value already registered by defineSchema
-  input: z.object({ prefix: z.string().default("") }),
-  select: ["id", "title"],
-  where: ({ prefix }) => ({ title: { startsWith: prefix } }),
-  orderBy: { column: "id" },
-  limit: 50,
-});
-
-const rows = await ListTodos.run(Database, { prefix: "Buy" });
-const compiled = ListTodos.sql(Database, { prefix: "Buy" }); // no connection
-// compiled.sql and compiled.params describe the same statement run() executes.
-```
-
-`run` validates its input before SQL and its response before returning. SQL uses
-the same SELECT compiler as `findMany`, under the caller's transaction and RLS
-identity. Table names retain their declared schema. Selection is mandatory;
-unselected database columns cannot silently expand the API. Numeric/bigint and
-timestamp outputs retain their exact string representations, and named codecs
-determine the surfaced type. A selected `jsonb<T>()` needs a matching Zod schema
-in `fields: { payload: PayloadSchema }`, because its TypeScript payload is erased
-at runtime. Free-form column transforms require migration to a named codec.
-
-Keep a contract manifest in the application repository:
+// Store/service
+list(prefix: string) {
+  return Database.public.todos.findMany({
+    where: { title: { startsWith: prefix } },
+    select: ["id", "title"],
+    limit: 50,
+  });
+}
 
-```ts
-const generated = queryManifest([ListTodos]);
-// Write generated JSON for the initial, reviewed baseline.
-assertQueryManifest([ListTodos], committedManifest); // run in the CI/build check
+// Controller
+@Get("/")
+list(@QueryParams(ListInput) input: ListInput) {
+  return this.todos.list(input.prefix);
+}
 ```
 
-The manifest contains input/response OpenAPI components, selected storage types,
-nullability and codecs. A changed contract fails the check until its diff is
-reviewed and the committed baseline is updated. The runtime also refuses a query
-whose selected columns disagree with the installed declaration, before SQL.
-This check compares declarations; migration validation still owns drift in the
-physical PostgreSQL schema. Queries currently project one table; use `findMany`
-or `page` for nested relation reads.
-
-`await ListTodos.explain(Database, input)` executes plain `EXPLAIN (FORMAT JSON)`
-with the same role and parameters. It never enables `ANALYZE`. Plans can contain
-filter literals, so inspect them in development/operator tooling. No EXPLAIN is
-run automatically on production requests. The complete controller/schema example
-is [examples/database-dx.ts](./examples/database-dx.ts).
+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.
 
 ## Nested relations and unique lookups
 
@@ -934,35 +927,58 @@ 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.
+
+Sorted PostgreSQL row locks and constraints coordinate conflicting writes across
+all runtime instances. No application workload declaration is needed.
+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 +1018,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/examples/database-dx.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import {
-  Controller, Get, QueryParams, Module, Injectable, Database, defineQuery, defineWorkload,
+  Controller, Get, QueryParams, Module, Injectable, Database,
   defineSchema, defineTable, uuid, text, boolean, timestamp, ownedByUser,
 } from "@palbase/backend";
 
@@ -17,18 +17,16 @@ export const todos = defineTable("dx_todos", {
 });
 export const schema = defineSchema("public", { tables: [todos] });
 
-export const ListTodos = defineQuery("ListTodos", {
-  table: todos,
-  input: z.object({ prefix: z.string().default("") }),
-  select: ["id", "title", "done"],
-  where: ({ prefix }) => ({ title: { startsWith: prefix } }),
-  orderBy: { column: "id" },
-  limit: 50,
-});
+export const ListInput = z.object({ prefix: z.string().default("") });
 
 @Injectable()
 export class TodoQueries {
-  list(input: z.input<typeof ListTodos.input>) { return ListTodos.run(Database, input); }
+  list(input: z.output<typeof ListInput>) {
+    return Database.public.dx_todos.findMany({
+      select: ["id", "title", "done"], where: { title: { startsWith: input.prefix } },
+      orderBy: { column: "id" }, limit: 50,
+    });
+  }
 }
 
 @Controller("/dx-todos", { auth: true })
@@ -36,7 +34,7 @@ export class DatabaseDxController {
   constructor(private readonly todos: TodoQueries) {}
 
   @Get("/", { databaseBudget: { maxQueries: 8, maxRows: 50, maxBytes: 65536 } })
-  list(@QueryParams(ListTodos.input) input: z.input<typeof ListTodos.input>): Promise<z.infer<typeof ListTodos>> {
+  list(@QueryParams(ListInput) input: z.output<typeof ListInput>) {
     return this.todos.list(input);
   }
 }
@@ -49,12 +47,9 @@ export function findExternalTodo(ownerId: string, key: string) {
   return Database.public.dx_todos.findUnique({ where: { owner_id: ownerId, external_key: key }, select: ["id", "title"] });
 }
 
-// Optional admission for repeated writes to the same resource.
-const writes = defineWorkload("todo-writes", { concurrency: 8, queueLimit: 32, tenantConcurrency: 4, tenantQueueLimit: 8 });
-export function finishTodo(id: string, signal?: AbortSignal) {
-  return Database.$atomic(tx => tx.public.dx_todos.update({ where: { id }, set: { done: true } }), {
-    workload: writes, conflictKeys: [id], timeoutMs: 1000, signal, retry: 2,
-  });
+// One batch UPDATE uses the ordinary CRUD surface and core admission.
+export function finishTodos(ids: string[]) {
+  return Database.public.dx_todos.updateMany({ where: { id: { in: ids } }, set: { done: true }, returning: false });
 }
 
 export function readPage(after?: string) {

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` 36.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -1929,58 +1929,51 @@ 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
 
-`defineQuery` combines an explicit selection with a reusable input/filter. The
-result is also a Zod array schema: a controller can return
-`Promise<z.infer<typeof ListTodos>>`, and the existing build binder uses that
-same value for response validation, OpenAPI and generated clients.
+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
-export const ListTodos = defineQuery("ListTodos", {
-  table: todos, // a defineTable value already registered by defineSchema
-  input: z.object({ prefix: z.string().default("") }),
-  select: ["id", "title"],
-  where: ({ prefix }) => ({ title: { startsWith: prefix } }),
-  orderBy: { column: "id" },
-  limit: 50,
-});
+// Store/service
+list(prefix: string) {
+  return Database.public.todos.findMany({
+    where: { title: { startsWith: prefix } },
+    select: ["id", "title"],
+    limit: 50,
+  });
+}
 
-const rows = await ListTodos.run(Database, { prefix: "Buy" });
-const compiled = ListTodos.sql(Database, { prefix: "Buy" }); // no connection
-// compiled.sql and compiled.params describe the same statement run() executes.
+// Controller
+@Get("/")
+list(@QueryParams(ListInput) input: ListInput) {
+  return this.todos.list(input.prefix);
+}
 ```
 
-`run` validates its input before SQL and its response before returning. SQL uses
-the same SELECT compiler as `findMany`, under the caller's transaction and RLS
-identity. Table names retain their declared schema. Selection is mandatory;
-unselected database columns cannot silently expand the API. Numeric/bigint and
-timestamp outputs retain their exact string representations, and named codecs
-determine the surfaced type. A selected `jsonb<T>()` needs a matching Zod schema
-in `fields: { payload: PayloadSchema }`, because its TypeScript payload is erased
-at runtime. Free-form column transforms require migration to a named codec.
+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.
 
-Keep a contract manifest in the application repository:
+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.
 
-```ts
-const generated = queryManifest([ListTodos]);
-// Write generated JSON for the initial, reviewed baseline.
-assertQueryManifest([ListTodos], committedManifest); // run in the CI/build check
-```
-
-The manifest contains input/response OpenAPI components, selected storage types,
-nullability and codecs. A changed contract fails the check until its diff is
-reviewed and the committed baseline is updated. The runtime also refuses a query
-whose selected columns disagree with the installed declaration, before SQL.
-This check compares declarations; migration validation still owns drift in the
-physical PostgreSQL schema. Queries currently project one table; use `findMany`
-or `page` for nested relation reads.
+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.
 
-`await ListTodos.explain(Database, input)` executes plain `EXPLAIN (FORMAT JSON)`
-with the same role and parameters. It never enables `ANALYZE`. Plans can contain
-filter literals, so inspect them in development/operator tooling. No EXPLAIN is
-run automatically on production requests. The complete controller/schema example
-is [examples/database-dx.ts](./examples/database-dx.ts).
+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.
 
 ## Nested relations and unique lookups
 
@@ -2038,35 +2031,58 @@ 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.
+
+Sorted PostgreSQL row locks and constraints coordinate conflicting writes across
+all runtime instances. No application workload declaration is needed.
+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 +2122,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": "36.0.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {

package/stager/inferred_returns.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// Build-time only. The actual TypeScript return type follows calls through DI
+// services and the generated Database tables, including literal projections.
+// No application code is executed and no database/identity handle is rebound.
+const path = require('node:path');
+
+function createReturnInference(projectRoot) {
+  let program, checker, ts;
+  function initialize(file) {
+    ts = require('typescript');
+    const configFile = ts.findConfigFile(projectRoot, ts.sys.fileExists);
+    let config = { compilerOptions: {}, include: ['**/*.ts'] };
+    if (configFile) {
+      const read = ts.readConfigFile(configFile, ts.sys.readFile);
+      if (read.error) throw new Error(ts.flattenDiagnosticMessageText(read.error.messageText, '\n'));
+      config = read.config;
+    }
+    const parsed = ts.parseJsonConfigFileContent(config, ts.sys, configFile ? path.dirname(configFile) : projectRoot);
+    // Nullability must survive even in a project that has disabled strict mode.
+    // Check the server response graph, plus the project's ambient declarations.
+    // A generated web client or an unrelated test is not a server entrypoint.
+    // Imports from a controller still pull in (and check) every service it uses.
+    const roots = parsed.fileNames.filter(name => /\.d\.[cm]?ts$|\.controller\.[cm]?tsx?$/i.test(name));
+    program = ts.createProgram([...new Set([...roots, file])], {
+      ...parsed.options, strictNullChecks: true, noEmit: true, skipLibCheck: true,
+    });
+    checker = program.getTypeChecker();
+  }
+
+  return function infer(file, className, methodName) {
+    file = path.resolve(file);
+    if (!program) initialize(file);
+    const sf = program.getSourceFile(file);
+    const cls = sf?.statements.find(s => ts.isClassDeclaration(s) && s.name?.text === className);
+    const method = cls?.members.find(m => ts.isMethodDeclaration(m) && m.name.getText(sf) === methodName);
+    const refuse = detail => {
+      throw new Error(`${file} — ${className}.${methodName}: cannot infer a safe response contract (${detail}). ` +
+        'Use a named Zod return schema for this response; any/unknown is never emitted as a successful contract.');
+    };
+    if (!method) return refuse('method is outside the TypeScript project');
+    // Unresolved imports or bad calls can otherwise leave a plausible but wrong
+    // result type. Check the project's source graph once, not once per route.
+    if (!infer.checked) {
+      const errors = program.getSemanticDiagnostics().filter(d => d.category === ts.DiagnosticCategory.Error);
+      if (errors.length) return refuse(ts.formatDiagnostics(errors.slice(0, 5), {
+        getCanonicalFileName: f => f, getCurrentDirectory: () => projectRoot, getNewLine: () => '\n',
+      }));
+      infer.checked = true;
+    }
+    const signature = checker.getSignatureFromDeclaration(method);
+    const result = signature && checker.getAwaitedType(checker.getReturnTypeOfSignature(signature));
+    if (!result) return refuse('unresolved return type');
+    if (result.flags & ts.TypeFlags.Void) return null;
+    const ancestors = new Set();
+    let nodes = 0;
+    function schema(type, location) {
+      if (++nodes > 2000 || ancestors.size > 24) return refuse(`${location}: contract is too large; name its schema`);
+      const f = type.flags, F = ts.TypeFlags;
+      if (f & (F.Any | F.Unknown | F.Never | F.TypeParameter)) return refuse(`${location}: ${checker.typeToString(type)}`);
+      // Generated palbase-env.d.ts preserves PostgreSQL families using
+      // T & { readonly __pg?: "uuid" }. This optional phantom is not JSON.
+      const pgBrand = part => {
+        const props = checker.getPropertiesOfType(part);
+        if (!(part.flags & F.Object) || props.length !== 1 || props[0].name !== '__pg' ||
+            !(props[0].flags & ts.SymbolFlags.Optional) || checker.getIndexInfosOfType(part).length) return false;
+        const tag = checker.getTypeOfSymbolAtLocation(props[0], method);
+        return (tag.isUnion() ? tag.types : [tag]).every(t => t.flags & (F.StringLiteral | F.Undefined));
+      };
+      if (type.isIntersection()) {
+        const data = type.types.filter(t => !pgBrand(t));
+        if (data.length === 1 && data.length < type.types.length) return schema(data[0], location);
+      }
+      // Pg<unknown, "jsonb"> simplifies to the phantom alone. Never mistake
+      // that erased payload for an object containing an optional __pg field.
+      if (pgBrand(type)) return refuse(`${location}: unknown PostgreSQL payload; name its response schema`);
+      if (f & F.StringLiteral) return `z.literal(${JSON.stringify(type.value)})`;
+      if (f & F.NumberLiteral) return `z.literal(${JSON.stringify(type.value)})`;
+      if (f & F.BooleanLiteral) return `z.literal(${type.intrinsicName === 'true'})`;
+      if (f & F.String) return 'z.string()';
+      if (f & F.TemplateLiteral) {
+        if (type.types.length > 8 || !type.types.every(t => t.flags & F.String)) return refuse(`${location}: template literal requires an explicit schema`);
+        const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // Each intermediate delimiter takes its first occurrence; an arbitrary
+        // string interpolation can absorb later occurrences. This avoids a
+        // chain of overlapping .* groups with explosive rejection cost.
+        let pattern = '^' + escape(type.texts[0]);
+        for (const text of type.texts.slice(1, -1)) if (text) {
+          const delimiter = escape(text);
+          pattern += `(?:(?!${delimiter})[\\s\\S])*${delimiter}`;
+        }
+        pattern += '[\\s\\S]*' + escape(type.texts.at(-1)) + '$(?![\\s\\S])';
+        if (pattern.length > 4096) return refuse(`${location}: template pattern is too large`);
+        return `z.string().regex(new RegExp(${JSON.stringify(pattern)}))`;
+      }
+      if (f & F.Number) return 'z.number().finite()';
+      if (f & F.Boolean) return 'z.boolean()';
+      if (f & F.Null) return 'z.null()';
+      if (f & F.Undefined) return 'z.undefined()';
+      if (ancestors.has(type)) return refuse(`${location}: recursive response`);
+      ancestors.add(type);
+      try {
+        if (type.isUnion()) {
+          if (type.types.length > 32) return refuse(`${location}: union has more than 32 alternatives`);
+          const nullable = type.types.some(t => t.flags & F.Null);
+          const optional = type.types.some(t => t.flags & F.Undefined);
+          const members = type.types.filter(t => !(t.flags & (F.Null | F.Undefined)));
+          const base = members.length === 0 ? nullable ? 'z.null()' : 'z.undefined()'
+            : members.length === 1 ? schema(members[0], location)
+            : `z.union([${members.map(t => schema(t, location)).join(',')}])`;
+          // OpenAPI represents nullability on the value schema. A standalone
+          // null union arm becomes {} in older client generators.
+          return base + (nullable && members.length ? '.nullable()' : '') + (optional ? '.optional()' : '');
+        }
+        if (checker.isTupleType(type)) return refuse(`${location}: tuple requires an explicit schema`);
+        if (checker.isArrayType(type)) {
+          const item = checker.getTypeArguments(type)[0];
+          // never[] has one possible JSON value: []. Preserve that constraint
+          // without emitting an any/unknown item contract to client generators.
+          if (item.flags & F.Never) return 'z.array(z.string()).length(0)';
+          return `z.array(${schema(item, `${location}[]`)})`;
+        }
+        const objectIntersection = type.isIntersection() && type.types.every(t => t.flags & F.Object);
+        if (!(f & F.Object) && !objectIntersection || type.getCallSignatures().length || type.getConstructSignatures().length) {
+          return refuse(`${location}: non-JSON type ${checker.typeToString(type)}`);
+        }
+        const declaration = type.symbol?.declarations?.[0];
+        if (declaration && (ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration))) {
+          return refuse(`${location}: class instance ${checker.typeToString(type)}`);
+        }
+        const properties = checker.getPropertiesOfType(type);
+        const indexes = checker.getIndexInfosOfType(type);
+        if (indexes.length) {
+          if (indexes.length !== 1 || !(indexes[0].keyType.flags & F.String) || properties.length) {
+            return refuse(`${location}: mixed or non-string index signature`);
+          }
+          return `z.record(${schema(indexes[0].type, `${location}.*`)})`;
+        }
+        if (!properties.length) return refuse(`${location}: empty structural type`);
+        const fields = properties.map(property => {
+          if (property.escapedName.toString().startsWith('__@')) return refuse(`${location}: symbol property`);
+          const name = property.getName();
+          const value = schema(checker.getTypeOfSymbolAtLocation(property, method), `${location}.${name}`);
+          return `${JSON.stringify(name)}:${value}${property.flags & ts.SymbolFlags.Optional ? '.optional()' : ''}`;
+        });
+        return `z.object({${fields.join(',')}}).strict()`;
+      } finally { ancestors.delete(type); }
+    }
+    return schema(result, 'return');
+  };
+}
+
+module.exports = { createReturnInference };