@palbase/backend 35.0.0 → 36.0.0

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

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^34.0.0",
+    "@palbase/backend": "^36.0.0",
     "reflect-metadata": "^0.2.2"
   },
   "engines": {