@palbase/backend 35.0.1 → 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` 35.
+> and will not compile against `@palbase/backend` 36.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/database.md

@@ -871,62 +871,6 @@ 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
-`Promise<z.infer<typeof ListTodos>>`, and the existing build binder uses that
-same value for response validation, OpenAPI and generated clients.
-
-```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:
-
-```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.
-
-`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).
-
 ## Nested relations and unique lookups
 
 `with` accepts three relation edges, with independent selection, filtering,
@@ -1031,10 +975,8 @@ 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.
+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.
 

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` 35.
+> and will not compile against `@palbase/backend` 36.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -1975,62 +1975,6 @@ 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
-`Promise<z.infer<typeof ListTodos>>`, and the existing build binder uses that
-same value for response validation, OpenAPI and generated clients.
-
-```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:
-
-```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.
-
-`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).
-
 ## Nested relations and unique lookups
 
 `with` accepts three relation edges, with independent selection, filtering,
@@ -2135,10 +2079,8 @@ 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.
+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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "35.0.1",
+  "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 };

package/stager/return_types.js

@@ -80,7 +80,7 @@ const RETURN_BUFFER_SYMBOL_KEY = 'palbase.backend.returnBuffer';
  *   - imports: local-binding-name → module-specifier (for the injector's import)
  *   Throws ReturnTypeError on an un-resolvable/disallowed return type.
  */
-function readReturnTypes(sourceText, fileLabel) {
+function readReturnTypes(sourceText, fileLabel, inferReturn) {
   const tsapi = loadTS();
   const sf = tsapi.createSourceFile(
     fileLabel || 'controller.ts',
@@ -249,6 +249,11 @@ function readReturnTypes(sourceText, fileLabel) {
       // 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) {
+        if (inferReturn) {
+          const expression = inferReturn(fileLabel, className, fnName);
+          if (expression !== null) methods.push({ fnName, expression });
+          continue;
+        }
         throw err(
           fnName,
           'route method has no return type — annotate it (e.g. `: Promise<TodoSchema>`, ' +
@@ -326,7 +331,7 @@ function buildInjection(parsed) {
   lines.push('    __ctor[__RBUF][fn] = schema;');
   lines.push('  };');
   for (const m of parsed.methods) {
-    const expr = m.isArray ? `z.array(${m.typeName})` : m.typeName;
+    const expr = m.expression ?? (m.isArray ? `z.array(${m.typeName})` : m.typeName);
     lines.push(`  __bind(${JSON.stringify(m.fnName)}, ${expr});`);
   }
   lines.push('})();');
@@ -340,8 +345,8 @@ function buildInjection(parsed) {
  * 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);
+function injectReturnBindings(sourceText, fileLabel, inferReturn) {
+  const parsed = readReturnTypes(sourceText, fileLabel, inferReturn);
   const snippet = buildInjection(parsed);
   if (!snippet) return sourceText;
   let out = sourceText;

package/stager/stage.js

@@ -21,6 +21,7 @@ const path = require("node:path");
 
 const generics = require("./generics.js");
 const returnTypes = require("./return_types.js");
+const { createReturnInference } = require("./inferred_returns.js");
 const throwAnalysis = require("./throw_analysis.js");
 
 /**
@@ -103,6 +104,7 @@ function stageControllers(srcDir, stageDir, projectRoot) {
   // normally lives. `projectRoot` is the third argument precisely so a check
   // can be wider than the staging copy.
   const examined = generics.assertNoGenericDepsInTree(projectRoot);
+  const inferReturn = createReturnInference(projectRoot);
 
   let injected = 0;
   for (const file of walk(srcDir)) {
@@ -110,7 +112,7 @@ function stageControllers(srcDir, stageDir, projectRoot) {
     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);
+      let out = returnTypes.injectReturnBindings(fs.readFileSync(file, "utf8"), file, inferReturn);
       out = throwAnalysis.injectThrowBindings(out, file, {
         readFile: (p) => {
           try {

package/template/AGENTS.md

@@ -6,7 +6,6 @@ router to register with — a `@Module` says what exists, who owns it and what i
 may reach, and a class no module lists does not exist.
 
 Everything comes from one package:
-
 ```ts
 import { Controller, Get, Post, Body, Param, User, z, Database, NotFound } from "@palbase/backend";
 ```
@@ -24,7 +23,7 @@ agents). This file does not repeat it; it says what the code should LOOK like.
 
 | Layer | DOES | NEVER |
 |---|---|---|
-| `modules/<domain>/<name>.controller.ts` | HTTP only: validate the body through a named schema, name the 200 shape as the return type, turn a missing row into a status | imports `Database` / `Storage` / `Cache` · holds business rules · stores per-request state on the instance |
+| `modules/<domain>/<name>.controller.ts` | HTTP only: validate input, return the typed service result, turn a missing row into a status | imports `Database` / `Storage` / `Cache` · holds business rules · stores per-request state on the instance |
 | `modules/<domain>/<name>.service.ts` | the decisions: which rows, whose, in what order; throws the error classes | knows about HTTP (no `req`, no `res`) · reaches for a singleton itself — it takes its dependency through the constructor |
 | `modules/<domain>/dto/<endpoint>.ts` | zod schemas, exported twice under one name: a VALUE and a same-named `z.infer` TYPE | holds logic |
 | `db/public.ts` | IS the database: tables, columns, RLS policies | produces migration files — there are none |
@@ -84,7 +83,9 @@ wrong in this runtime:
 - **Hand-built responses** — no `JSON.stringify`, no `new Response(...)`; the 200
   body IS the schema your return type names.
 - **An inline return type** — `Promise<{ ok: boolean }>`, a union, or a bare
-  `interface`. The deploy REFUSES it; name a zod schema.
+  `interface`. Omit it for typed CRUD: the build infers the validator and client contract.
+  For unknown JSON, recursive values or classes, name a Zod schema; never use `any`.
+  Use ordinary CRUD; core owns pool/queue settings.
 
 **A controller is exported by NAME, and no file is default-exported.** Its module imports
 it (`import { NotesController } from "./notes.controller"`) to list it in `controllers`;
@@ -186,8 +187,7 @@ process-wide state. For a stand-in covering the whole database rather than one
 table, use `fakeDatabase()` from `@palbase/backend/test`; it answers from memory
 and enforces no RLS, constraints or unique violations.
 
-Relative imports inside a test need the extension (`./note.service.ts`); this
-scaffold's `tsconfig.json` allows it.
+Relative test imports need the extension (`./note.service.ts`); the scaffold allows it.
 
 `npm test` answers "is the logic right". It is not the deploy's own validation —
 decorators, return types, SDK major — which answers "would this ship".

package/template/package.json

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