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

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

package/docs/paltimate/2026-09-06-fake-offset-claim/research.md

@@ -0,0 +1,75 @@
+# Fake pagination and claim: verification sources
+
+Verified 2026-09-06. Scope: repair the two existing in-memory fake contracts,
+using the repository's existing runtime and test runner. No new dependency or
+public API is introduced.
+
+| ID | Existing tool | Stakes | Tier | Status | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| UD-001 | Bun 1.3.9 for independent consumer probes | 1 | quick | verified | `bun --version`; published-package and built-package probe executions |
+| UD-002 | Vitest 3.2.4 for SDK regressions | 1 | quick | verified | `backend/package.json`, runtime version output, Context7 CLI documentation |
+
+CLAIM: Bun supports direct TypeScript execution and reports test/runtime failures
+with a nonzero exit status. SOURCE:
+https://github.com/oven-sh/bun/blob/main/docs/test/runtime-behavior.mdx
+VERIFIED: 2026-09-06 via Context7 and actual Bun 1.3.9 probe exits 1/0.
+TIER: quick. Current docs are not an assertion that their latest Bun version is
+the installed version; the installed runtime was measured separately.
+
+CLAIM: Vitest's file arguments select test paths; `run` performs a single run.
+SOURCE: https://github.com/vitest-dev/vitest/blob/v3.2.4/docs/guide/cli.md
+VERIFIED: 2026-09-06 via Context7 and focused red/green executions.
+TIER: quick.
+
+CLAIM: `--no-file-parallelism` runs test files without file concurrency.
+SOURCE: https://github.com/vitest-dev/vitest/blob/v3.2.4/docs/guide/debugging.md
+VERIFIED: 2026-09-06 via Context7 and installed
+`pnpm --filter @palbase/backend exec vitest --help --fileParallelism`.
+TIER: quick. This flag changes scheduling, preserving test assertions, selected
+files, type checking, and timeouts.
+
+The SDK contracts were checked against local primary sources:
+
+- `docs/database.md:179`: `now()` works in `claim` and other insert operations.
+- `docs/database.md:355`: offset requires limit.
+- `src/engine/db.ts:1403`: nonnegative integer limit validation.
+- `src/engine/db.ts:1417`: nonnegative integer offset validation and limit requirement.
+- `src/engine/db.ts:2362`: claim merges unique/extra and compiles insert expressions.
+- `src/__tests__/helpers/mock-db.ts:277`: existing insert-expression resolver.
+
+Runtime evidence separating the hypotheses is in `verification.md`.
+
+## Publication follow-up
+
+The user requested publication after the source fix was verified. Publication
+uses the repository's existing Changesets workflow; stakes 3, standard tier.
+Context7 was attempted twice but its transport was unavailable, so the official
+Changesets CLI documentation was read directly and checked against the local
+workflow and a successful live run.
+
+| ID | Existing approach | Stakes | Tier | Status | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| UD-003 | Changesets version commit followed by the main release workflow | 3 | standard | verified | `.github/workflows/release.yml`, `package.json`, official CLI docs and run 34035374818 |
+
+CLAIM: `changeset version` updates package versions/changelogs, and `publish`
+publishes package versions absent from npm. SOURCE:
+https://github.com/changesets/changesets/blob/main/docs/command-line-options.md
+VERIFIED: 2026-09-06 via official documentation, installed CLI 2.30.0, and the
+repository's `ci:version`/`ci:publish` scripts. TIER: standard.
+
+CLAIM: This repository versions locally, pushes to main, verifies matching core
+images first, then publishes npm and advances latest/next. SOURCE:
+https://github.com/palgroup/palbase-ts/blob/e9765e8460bbe9c4a20641f805a5e682f0097174/.github/workflows/release.yml
+and https://github.com/palgroup/palbase-ts/actions/runs/34035374818
+VERIFIED: 2026-09-06 via the workflow source and GitHub run state. TIER: standard.
+
+Registry evidence: `latest` and `next` both resolve to 36.0.1; querying 36.0.2
+returned E404 before versioning. Only the backend package is selected for a
+patch release, with the existing image-before-npm order preserved.
+
+Publication preflight observation: `ci:version` initially failed in the GitHub
+changelog adapter because the local fix commit was not yet on GitHub. The commit
+API returned HTTP 422 for `bfd6060` and resolved the existing base commit, ruling
+out an authentication failure. Publishing the fix commit to a temporary branch
+made the same `ci:version` command succeed without changing tooling or workflow.
+Only backend package version/changelog and the consumed changeset changed.

package/docs/paltimate/2026-09-06-fake-offset-claim/verification.md

@@ -0,0 +1,145 @@
+# Backend fake defects: proof, fix, proof
+
+Date: 2026-09-06. Runtime: Bun 1.3.9, macOS arm64.
+Published baseline: `@palbase/backend@36.0.0` from npm, unchanged.
+Source baseline: nested `palbase-ts` repository, commit `295958d`, package 36.0.1.
+The source checkout still contained both reported defects.
+
+## Reproduction
+
+The supplied `scripts/reproduce-sdk-bugs.ts` was absent from this workspace.
+`backend/scripts/reproduce-sdk-bugs.ts` reconstructs the two supplied independent
+contracts with public package imports and no application fixtures or credentials.
+An identical copy was run in a scratch consumer of the published npm tarball.
+
+Published baseline commands:
+
+```sh
+npm pack @palbase/backend@36.0.0 --ignore-scripts --pack-destination /tmp/palbase-sdk-fake-proof.CaHHuo --json
+# Scratch package depends on that unchanged tarball.
+bun install --ignore-scripts
+bun reproduce-sdk-bugs.ts
+```
+
+Observed before any source fix:
+
+```text
+FAIL findMany honors offset before limit
+  actual: [{ id: 'a' }], expected: [{ id: 'b' }]
+FAIL claim evaluates now() in returned and stored rows
+  actual typeof created_at: 'object', expected: 'string'
+0 passed, 2 failed
+exit 1
+```
+
+The raw claim's returned AND stored rows carried `Symbol(palbase.tx.expr)`.
+Tarball SHA-1 from npm pack: `0c665f63e2a9b98f5f736df050d17038305a5399`.
+
+## Hypotheses and runtime discrimination
+
+Pagination hypotheses: ignored offset, lost typed forwarding, wrong ordering.
+With deliberately unsorted `c,a,b` seeds, raw calls at offsets 0, 1, 2 and 3
+all returned `a`. Sorting therefore ran, and bypassing the typed wrapper still
+failed. The source pagination step used `slice(0, limit)` and its local option
+type omitted offset.
+
+Claim hypotheses: skipped insert-expression evaluation, incompatible expression
+marker, accidental materialization during reading. Passing the SAME `now()`
+object to insert and claim returned a timestamp from insert, while claim stored
+that original expression object by identity. A later read also returned the
+expression, excluding a return-only formatting error.
+
+Observed paths, cross-checked against the source:
+
+- Public `/test` export → `src/test/fake-db.ts:65` → shared
+  `src/__tests__/helpers/mock-db.ts` operation implementation.
+- Typed `fake.db.public.<table>.findMany` → `src/runtime.ts:498` → the same
+  raw operation, with offset forwarded.
+- Typed claim → `src/runtime.ts:531` → raw claim.
+- The helper is bundled into the shipped `/test` entry by `tsup.config.ts`;
+  its `__tests__` directory name does not make it an unused test-only copy.
+
+## Source regression proof and changes
+
+Command before and after the implementation change, from `backend`:
+
+```sh
+pnpm test src/test/fake-db.test.ts src/test/fake-db-parity.test.ts
+```
+
+| Tree | Result | Exit |
+| --- | --- | --- |
+| Original existing focused suite | 37 passed | 0 |
+| New regressions, original implementation | 12 failed, 38 passed | 1 |
+| Same tests, fixed implementation | 50 passed, no type errors | 0 |
+
+The repair applies offset after filtering/ordering and before projection, and
+uses the engine's existing limit/offset validation contract. Claim reuses the
+insert-expression resolver and write-value guards before storing a new row.
+Existing-row claims still return the original row without recording a new write.
+
+Coverage includes raw and typed calls, filter/sort/projection ordering, distinct
+pages, omitted/zero offset, an empty tail, zero limit, invalid pagination,
+timestamp validity in returned/stored/tracked rows, repeated claims, and refusal
+of invalid insert values without side effects. Explicit `id` lookup/deletion
+semantics are unaffected.
+
+## Built package and review
+
+Fresh build: `pnpm -w turbo run build --filter=@palbase/backend` → exit 0,
+backend cache miss, ESM/CJS/declarations generated.
+
+From `backend`, against the built public package entry points:
+
+```text
+$ bun scripts/reproduce-sdk-bugs.ts
+PASS findMany honors offset before limit
+PASS claim evaluates now() in returned and stored rows
+2 passed, 0 failed
+exit 0
+```
+
+`pnpm typecheck` → exit 0.
+`pnpm check:api` → exit 0; 424 exports and 421 signatures unchanged.
+Independent reviewer: no actionable findings; separate source probe and
+42-test fake suite both passed.
+
+## Full-suite environment findings
+
+The first shared-workspace `pnpm test` exited 1: 6 failed / 1900 passed tests,
+3 collection failures and 3 worker RPC errors. It included ignored generated
+Bun consumer tests under `bench/database-dx/generated/...`, which Vitest cannot
+load (`bun:test`), plus five timeouts under concurrent load.
+
+The sixth failure was an existing probabilistic cursor-test assertion:
+`src/engine/cursor.test.ts:15` replaces character 10 with `x`, even when it
+already is `x`. An independent loop observed this at attempt 82: the
+"changed" token equalled the original, and decoding correctly accepted it.
+Neither this test nor cursor implementation is changed by this fix.
+
+Final suite verification uses a detached temporary checkout at the same commit,
+with identical fix/test/probe files and the existing installed dependencies.
+File scheduling is serial; no assertions, timeouts or test selections are changed.
+The copied implementation, regression tests, and independent probe were checked
+byte-for-byte against the working files with `cmp` (all exit 0).
+
+Final command, from the isolated checkout's `backend` directory:
+
+```text
+$ pnpm test --no-file-parallelism
+Test Files  128 passed (128)
+     Tests  1906 passed (1906)
+Type Errors  no errors
+Duration  38.41s
+exit 0
+```
+
+The isolated checkout was also freshly built (backend cache miss, exit 0), and
+`bun scripts/reproduce-sdk-bugs.ts` there returned 2 passed / 0 failed, exit 0.
+The shared workspace's generated Bun tests are not tracked SDK test files; their
+absence in this checkout accounts for the three fewer collected files.
+
+Full raw command logs are retained in `/tmp/palbase-sdk-fake-proof.CaHHuo`.
+This initial verification covered source and local build artifacts, with no live
+PostgreSQL run. The user subsequently requested publication as backend 36.0.2;
+its registry installation is checked with the same independent contract probes.

package/package.json

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

package/stager/return_types.js

@@ -18,7 +18,7 @@
  *       foo(): Promise<TodoSchema>           → schema = TodoSchema
  *       foo(): Promise<TodoSchema[]>         → schema = z.array(TodoSchema)
  *       foo(): TodoSchema / TodoSchema[]     → (Promise optional)
- *   - `void` / `Promise<void>` / no annotation → no 200 body (allowed)
+ *   - `void` / `Promise<void>` → explicit z.void() binding, bodyless 204
  *   - anything else (inline object, union, intersection, a type with no
  *     same-named exported zod) → HARD error naming <Controller>.<method>.
  *
@@ -76,7 +76,7 @@ const RETURN_BUFFER_SYMBOL_KEY = 'palbase.backend.returnBuffer';
  * @param {string} sourceText  the controller's .ts source
  * @param {string} fileLabel   path/name for error messages
  * @returns {{ className: string, methods: Array<{ fnName, typeName, isArray }>, imports: Record<string,string> }}
- *   - methods: only routes that HAVE a resolvable named return type (void/none omitted)
+ *   - methods: named schemas or expressions, including explicit no-body schemas
  *   - imports: local-binding-name → module-specifier (for the injector's import)
  *   Throws ReturnTypeError on an un-resolvable/disallowed return type.
  */
@@ -251,7 +251,7 @@ function readReturnTypes(sourceText, fileLabel, inferReturn) {
       if (!m.type) {
         if (inferReturn) {
           const expression = inferReturn(fileLabel, className, fnName);
-          if (expression !== null) methods.push({ fnName, expression });
+          methods.push({ fnName, expression: expression ?? 'z.void()' });
           continue;
         }
         throw err(
@@ -261,7 +261,12 @@ function readReturnTypes(sourceText, fileLabel, inferReturn) {
         );
       }
       const resolved = resolveType(m.type, fnName);
-      if (!resolved) continue; // explicit void/Promise<void> — no 200 body, allowed
+      if (!resolved) {
+        // Absence of a binding means unknown, not no content. Keep the written
+        // contract so OpenAPI can emit 204 and the runtime can reject a body.
+        methods.push({ fnName, expression: 'z.void()' });
+        continue;
+      }
 
       const { typeName, isArray } = resolved;
       // The schema name must be an imported (or locally-defined) value. If it's

package/template/package.json

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