#104: one schema engine (upstream alpha.9, zod everywhere)

[tnramalho]

Implements RFC #104: one schema engine for the whole stack.

What changes, in plain terms

• Every request and response in Rockets is now described by one zod schema — one schema contract, not one execution path. The same schema validates the request, shapes the response and generates the API docs. Three executors read it, each where it fits: Nest's per-route Standard Schema pipe for every request body/query/param; upstream's CRUD serializer for generated responses; and operationResource keeps its own inline output validation on purpose (Nest's serializer lets null/undefined through and maps arrays per item, which contradicts the pinned 500-on-mismatch policy). There are no more DTO classes, no class-validator, no class-transformer, no nestjs-zod.
• Upstream @concepta/nestjs-* moves to 8.0.0-alpha.10 and Nest to stable 12.0.1 (the upstream CRUD engine already works this way; this PR adopts it).
• @nestjs/config is no longer needed by Rockets.
• Generated CRUD, operationResource, /me, the built-in auth routes and all three examples run on the same engine.

What you get

• Responses can no longer leak columns a schema does not declare.
• Every validation error carries structured details (which field, which message).
• The OpenAPI document references named components (TagResponseDto, TagResponseDtoPaginatedDto, …) instead of inlining shapes.
• Real defects found on the way are fixed with tests: hook errors (409/403/400) were being served as 500, generated operation routes were not documenting their parameters, and defineSubResource({ scope: false }) skipped the ancestor-chain check (see the alpha.10 pass below).

How to read it

One commit per stage (1–4, then 5+6 together); the root CHANGELOG.md has the migration notes per stage. The public API report (api/public-api-reports.json) lists every removed and added symbol.

Review pass (commit 4419137)

An adversarial review of the branch plus the first run of the only external consumer (realtystack) surfaced these; each one landed with a test that failed first:

• A create whose body is legitimately empty (everything stamped by hooks — path parent, owner, ids) is a 201 now, not an unexplained 400. Generated resources run on RocketsCrudAdapter.
• The "no open objects in a response" check reaches every wrapper (intersections, tuples, records, .readonly(), .catch(), …) and the paginated envelope; hidden columns stay hidden at every depth of a computed field.
• One OpenAPI component describes one side: a schema reused as both request and response is a document-build error, instead of silently documenting one side with the other's shape.
• f.date() rejects null and booleans (they used to become 1970).
• Invitation acceptance validates userMetadata with the same default as signup and admin when the app configures none.
• A route that declares a schema on a body/query/param but has no validation pipe fails the boot (requireSchemaPipe). The route audit is always on; the route policy stays opt-in.
• The built-in auth request bodies keep their component names (LocalLoginDto, RefreshDto, Recovery*Dto).
• Docs and agent instructions that still described the class-DTO era are rewritten.

Checked against realtystack (re-run on this branch's head): typecheck clean, 264/264, plus a real boot via tsx with a single @nestjs/core@12.0.1 resolved, auth answering 401 and /api/docs-json serving 44 paths. Its only change beyond version pins was routing document generation through SwaggerUiService.createDocument — hand-rolling it had silently dropped the schema converter. None of this branch's public API breaks touch anything it uses. Earlier run notes: typecheck clean, 249/249 tests green. Two real gaps came back from that run (the empty create body, and three hand-written routes that documented a schema but validated by hand — the new boot check caught them).

Second review pass (commit eca78ea)

A second adversarial review after the first fixes, plus the realtystack rerun:

• Generated CRUD request bodies are named components again (PetCreateDto, TagUpdateDto, …) — upstream stamps them inline (nestjs-modules#467); Rockets drops that stamp where the route's own schema is named, so bodies and responses go through the same path. Both example contracts regenerated; nothing else in them moved.
• The "one component, one side" rule also covers named schemas nested inside a request and a response.
• A hand-written route's @SerializeOptions({ schema }) gets the same "no open objects" check at boot as generated resources; the schema-pipe check has its own exemption list instead of riding on allow.
• rockets-auth: the admin PATCH /admin/users/:id and /admin/roles/:id bodies were documented but not validated (schema declared at controller level; upstream only wires the pipe from the operation) — fixed, and the user update no longer answers 500 (it ran a query on the finished transaction upstream leaves behind, nestjs-modules#468). The metadata repository pins userId from the caller on updates.
• Migration note for the renamed/removed OpenAPI components (AuthenticationResponse, RocketsAuthUserDto, RocketsAuthRoleDto, per-resource PaginatedDto, CrudInvalidResponseDto gone).

realtystack on this commit: typecheck clean, 264/264.

Third review pass (commits bad0dfb, f3098e5)

• The /me metadata handlers now forward the request context to every repository call (hooks run, the write joins the request transaction) and pin userId from the caller on updates — the same fix rockets-auth got, applied where it was still missing. UpsertUserMetadataCommand(ctx, userId, data) / GetUserMetadataQuery(ctx, userId) take the context first: breaking for apps that override or dispatch them directly (migration note in the changelogs).
• The defect class behind the admin update bodies now has a structural guard: a generated CRUD body with no schema fails the boot. Two e2e fixtures that relied on unvalidated bodies now declare theirs.
• The schema-pipe exemption list gets the same "more than one match" guard as allow; the audit report lists responses documented with standardSchema but not serialized (reported, not enforced).
• Migration notes: an explicit @ApiBody beside a named @Body({ schema }) is dropped in favour of the schema; allow / allowControllers no longer exempt the schema-pipe check.

realtystack on bad0dfb: typecheck clean, 264/264.

Review fixes (commits 8716489 → 72a921e) — from the change request, plus an adversarial pass on the first fix:

• A hidden column (dto: { response: false }) stays hidden on every PROJECTED response path — computed fields, JSON columns, exposed relations and operationResource outputs — through union, intersection, pipe (a top-level z.preprocess included), prefault, readonly, nonoptional and lazy (rebuilt; a recursive lazy no longer overflows the stack, including one whose cycle crosses a z.preprocess). .default() / .catch() hand their payload over without running the inner schema, so a hidden column below them (top-level or nested) is rejected at definition time, like discriminated union, tuple, record, map and set. A HAND-WRITTEN response schema (dto.response, operations.*.output, dto.paginated, userMetadata.responseSchema) is not projected and keeps its author-chosen component id, so a hidden field inside it is rejected at definition time with a pointer at .omit(); rockets-auth runs the same check on a consumer-supplied userCrud.model / roleCrud.model (signup, admin users, admin roles), which reach upstream CRUD directly. An op.sse() operation declares no output at all, so nothing is serialized — or stripped — there by design. A hand-written route's @SerializeOptions({ schema }) with a hidden field fails the boot through the route audit. Runtime regressions for the reported f.compute(z.union([nested, fallback])) case and each of the others; all fail against the previous code.
• The "no open objects in a response" check walks the IN side of a pipe whenever its OUT passes values through (transform, any, unknown, custom — also behind wrappers, unions, arrays, object properties, record values, intersections and nested pipes); its memo caches only true, so the verdict never depends on visit order, so .passthrough().transform(v => v) is rejected; z.pipe(open, closed) strips on the way out and is accepted.
• Node floor is 20.19.0 in every published engines, the docs and the CI matrix (20.19.0 + 22.x); both legs run the unit and package e2e suites, and release-readiness runs the example apps and the packed-consumer contract on exactly 20.19.0. The Vitest runner preloads @nestjs/core in a setup file: @nestjs/cqrs (CommonJS) requiring the ESM @nestjs/core while the runner's async import of it is still evaluating throws ERR_REQUIRE_CYCLE_MODULE on 20.19 (plain-Node orderings are fine; noted in the README for consumers whose own runner externalises ESM; filed upstream as @nestjs/cqrs (CommonJS) requiring the ESM @nestjs/core throws ERR_REQUIRE_CYCLE_MODULE on Node 20.19 under ESM-externalising test runners nestjs/nest#17583). fail-fast: false; module cache keyed by Node version.

alpha.10 pass (commits d26731d → d72ccc9) — the three issues filed from this PR are fixed upstream, so the Rockets-side workarounds are deleted rather than kept. One commit per theme.

• Bump to 8.0.0-alpha.10 (nestjs-modules#466 / #467 / #468).

• Retired: RocketsCrudAdapter, restoreNamedRequestBodies, liftInlineRequestBodyDefinitions, crud-compat.ts, ConceptaRepositoryCompatModule, resolveConceptadevAppContext (→ upstream AppContextHost.from(), which throws where the local helper silently discarded a live transaction context), defineHook's HttpException pre-wrap, and the two mirrored metadata keys (→ upstream isAuthPublic() / isTransactional()). ROCKETS_DISABLE_GUARDS_TOKEN and RocketsCrudAdapter leave the public API; AuthServerGuard no longer injects Reflector. The served OpenAPI document is byte-identical — both example contracts unchanged.

• Forced by the bump: TransactionManager.get() is gone (the Firestore dirty flag went with it — upstream removed the same pair from TypeOrmTransaction, and nothing read it), and propagation / TransactionRequiredException are gone, so there is no fail-closed transaction mode any more. A nested readOnly contradicting the scope it joins now throws instead of being ignored.

• Security fix, found while auditing the adapter deletion: defineSubResource({ scope: false }) — and owner: false — dropped PathScopeGuard outright, and with it the ancestor-chain check. Ancestor route params are disabled: true and never reach buildWhere, so at three levels or more /parents/A/children/CHILD_OF_B/notes served CHILD_OF_B's rows where the scoped route answers 404. The guard now takes an optional ownerColumn and is attached to every sub-resource: the flags drop ownership only. Breaking for apps on either flag — a missing or hook-hidden parent is a 404, and a mismatched ancestor is refused. Four e2e tests including a depth-3 probe; each fails against the previous code.

• Also closed: requestOverride.body / bodyBatch and resource-level request.body / bodyBatch now clear the same named-component bar as operations.X.input; a hand-written class @EntityHook has e2e coverage for 409/403/passthrough (the contract the removed pre-wrap used to work around); CONFIGURATION.md, AGENTS.md rule 16 and the changelogs no longer describe propagation, RocketsCrudAdapter or scope: false as "unscoped".

• Nest leaves the 12 alpha line for stable 12.0.1 (commit 31e98eb). Not cosmetic: alpha.10 requires @nestjs/common / core ^12.0.1 and @nestjs/cqrs ^12.0.0, and a prerelease does not satisfy a stable caret range. A clean npm install of the published tarballs therefore nested a second copy under every upstream package — 13 copies of @nestjs/core, 16 of @nestjs/common, 2 of @nestjs/cqrs — and two copies means two class identities: RESULT_TYPE_SYMBOL is a unique symbol (TS2420 on the user-port queries) and ModuleRef stopped resolving (Nest can't resolve dependencies of the HookResolverService). Every @nestjs/* pin moves to the stable line across the packages, the examples, the root resolutions and the packed-consumer script. @nestjs/typeorm@12 is ESM, so one spec swaps vi.spyOn on a module namespace for vi.mock.

  This was caught by CI, not locally: the root resolutions block flattens the workspace tree, so every local suite ran against a shape the published consumer never sees. release:packages is the gate that models a real consumer, and it is now part of the local pre-push routine.

• @nestjs/throttler is replaced by core's rate-limit port (commit 4c2f3f6). Its latest release (6.5.0, unchanged even on master) caps peers at Nest 11, so npm install @concepta/rockets-auth answered ERESOLVE on default npm — pre-existing on main, hidden by the consumer gate's --legacy-peer-deps. Core's @RateLimit / RateLimitGuard grew named dimensions enforced together (per-field merge by name, so a route tightening limit keeps the dimension's composite key); auth keeps its exact policy — per-IP ceiling no route overrides + per-(ip, account) fine limits, counters per route. The four pre-existing throttling e2e blocks pass unchanged against the new engine, and they caught two bugs in the swap itself (whole-dimension merge sharing the fine counter across accounts; cross-route counters draining the OTP allowance). Breaking: extras.throttling is now false | { ip?, default?, store? } with windowMs. The consumer gate installs with strict npm — no flags — as the enforced contract.

• Generated recursive-definition names left the author namespace (commit b0d053d, from external review). The qualifier named a lifted z.lazy() inner object with a counter (TreeDtoRef0); an author schema carrying that exact id made the outcome depend on route scan order (author-first: silent rename; generated-first: document build aborted blaming a request/response split that does not exist). Names are now <ownerId>Ref_<8 hex of the definition's own JSON> — out of the author space by construction, stable while the shape is — and the residual deliberate collision throws a precise error naming the generating component, in either order. Both cross-conversion cases fail against the previous code.

• The in-memory rate-limit store is bounded (commit d72ccc9, from adversarial review of the swap above). It never freed an entry, and its counter key carries an attacker-supplied account field — guards run BEFORE pipes, so that value is unvalidated and bounded only by the body parser. Every request on a public login / signup / recovery / OTP route inserted a permanent map entry, and the per-IP ceiling could not stop it: each admitted request carries a NEW account value, so the growth happened inside the policy. Not a regression (@nestjs/throttler's own map never evicted either — checked against the packed tarball) but ownership moved: it is Rockets' default store now. The store sweeps expired windows on write and enforces a hard key cap, dropping soonest-expiring entries first and warning when a live window has to go; the auth key function hashes any account value over 128 chars. Same commit: Retry-After now reports the latest reset among rejected dimensions (a client blocked for an hour by the ip ceiling was told to retry in 60s), the generated-name digest hashes canonical JSON (key order can't rename components), and the duplicate-copy tolerance is keyed by path rather than version.

Gates, the full CI set from a clean build: build, api:report:check-built, lint:all, typecheck:spec, test:config-native, test:ci (1126), test:e2e:cov (463), release:packages, samples:build, samples:test:e2e (191 / 49 / 8), both contract:check, and — on CI, which has the JDK 21 the emulator needs — the Firestore emulator suite.

Open follow-ups (not in this PR)

• Upstream, fixed in 8.0.0-alpha.10: empty create body rejected with a bare 400 (nestjs-crud / nestjs-repository: a create body that validates to {} is rejected with a bare 400 nestjs-modules#466), CRUD request bodies inlined in the OpenAPI document (nestjs-crud: generated CRUD request bodies are inlined in the OpenAPI document instead of $ref'ing the named schema nestjs-modules#467), second TransactionScope.run on one context reusing the committed transaction (nestjs-repository: a second TransactionScope.run on the same context reuses the committed transaction ("No active transaction") nestjs-modules#468).
• No fail-closed transaction mode exists after alpha.10 removed propagation. A boot assertion that each registered store has a transaction factory would replace it; that is a new guarantee, not a cleanup, so it is deliberately not in this PR.
• The realtystack consumer run has not been repeated on alpha.10. Three public symbols and one constructor signature changed; a grep found no usage, but a grep is not a boot.
• Component ids of nested relation projections are checked at document time only, not at plan time.
• Rebuilding a schema to strip a hidden column drops what it cannot carry over: object-level .refine() checks, and the withOpenApi id of a nested named schema (it documents inline after the rebuild). Only schemas that actually contain a hidden column are affected.
• Hand-written @ApiResponse({ standardSchema }) WITHOUT a serializer is documentation only; the audit report lists those routes (unserializedResponseSchemas), the boot check covers @SerializeOptions({ schema }).
• /me claims the generic UserResponseDto / UserUpdateDto ids with no override.
• An e2e flake with ROTATING victims at NORMAL duration (~20s) — one occurrence included Parse Error: Expected HTTP/, a protocol-level symptom. It does NOT match the documented memory-pressure signature (30s timeouts at ~20x duration), and every victim is green in isolation and on re-run. Bisected against the rate-limit guard's new setHeader path and exonerated: the earliest occurrence predates that code by 1h45, the failing spec (rockets-multi-auth-provider) uses no RateLimitGuard, and pool: 'forks' isolates each spec file in its own process. Prime remaining suspect is supertest ephemeral-port reuse across workers. Unresolved; worth a dedicated pass on an idle machine.
• Examples were only booted against SQLite; a Postgres/MySQL boot is still due.

Not merged without review — leave it as a draft until you have gone through it.

🤖 Generated with Claude Code

[leoafarias]

The schema-unification direction is strong, and the route-scoped Standard Schema pipe is the right correction to the RFC's original global-pipe sketch. I am requesting changes because two response-safety guarantees and the published runtime compatibility contract fail with reproducible inputs.

I verified the branch with build, typecheck, API reports, lint, 1,074 unit tests, 440 package E2E tests, and the sample suites. Those gates pass, but they do not cover the wrapper shapes in the first two comments.

Please also update Issue #104 / the PR framing from one native execution path to one schema contract. operationResource deliberately retains inline output validation because Nest's serializer has different null/array semantics; that is sensible, but it means the stronger one-executor claim is not accurate.

[tnramalho]

Request validation: where it landed

Rockets validates through Nest 12's native path — @Body({ schema }) on the parameter, StandardSchemaValidationPipe reading metadata.schema. Generated routes carry the same { schema } in route metadata. One form everywhere.

What was there before. A DTO carrier: a class holding the schema, discovered by a pipe subclass through the parameter's type. It was the right call when it was written — Nest did not accept a schema on the parameter yet. Its foundation survived and is what every route runs on today: sitting on Nest's native pipe instead of writing our own validation, and the exceptionFactory that attaches details[] to every 400.

What changed. Nest 12 accepts the schema directly, so the intermediate class had nothing left to carry. Both forms were compared in packages/rockets-core/src/__e2e__/schema-approaches.e2e-spec.ts, 11 cases with assertions: at runtime they are identical. Each has one silent hole — a mismatched type annotation on the native form, a missing emitDecoratorMetadata on the carrier — and both are closable. What decides is cost: native needs a lint rule, the carrier needs a pipe subclass, a factory, and an audit that understands two declaration forms. Native is also what Nest documents.

Fixes in this branch

• A second recursive schema no longer aborts document generation. z.toJSONSchema names extracted definitions positionally (__schema0), restarting per conversion, so two unrelated recursive schemas both claimed that name.
• A discriminated union is documented as one, with an explicit discriminator.mapping — the implicit form matches the tag against the component name, and 'circle' is not 'CircleDto'.
• A qualified definition name never lands on one an author already owns. Reported by @leoafarias: TreeDtoRef0 invented next to an authored TreeDtoRef0 overwrote it inside the same batch, and the recursive property was documented with the wrong shape, silently. The qualifier now walks to a free name. Regression test fails against the previous code.

Follow-ups

1. Boot check for a body/query/param that resolves no schema at all — hits both forms, not caught by the current requireSchemaPipe audit on hand-written routes.
2. Lint rule for decorator schema vs type annotation mismatch.

[MrMaz]

@concepta/nestjs-crud, @concepta/nestjs-repository, and @concepta/nestjs-core 8.0.0-alpha.10 are published, with fixes for the three issues filed from this PR: #466, #467, #468. Went through the branch at ac719397 looking for what's retirable — sharing in case it saves a pass.

Retirable once you bump to alpha.10:

• rockets-core/src/infrastructure/crud/rockets-crud.adapter.ts (RocketsCrudAdapter) — RepositoryAdapter.prepare() no longer rejects a create body that validates to {} (#466). Check before deleting: your override's params merge is selective (if (field in merged) — a route param only overrides a key already present in the body), while upstream's CrudAdapter.prepareEntityBeforeSave merges unconditionally ({ ...dto, ...context.params }). Dropping the shim will start writing param values onto columns that previously stayed untouched for any route whose param names aren't already body keys — fine for a nested FK, a silent data change otherwise. Worth a diff of route params against entity columns first.
• rockets-core/src/common/swagger-ui/restore-named-request-bodies.ts and most of lift-inline-definitions.ts — CRUD request bodies now $ref a named component the same way responses do (#467); CrudInitApiBody no longer stamps raw inline JSON Schema, so isInlineBodyParameter won't match anything to strip. Your swagger e2e assertions that pin the old inline-body behavior (rockets-core-zod-operation-io.e2e-spec.ts:16-19, the inverse case in rockets-core-schema-engine.e2e-spec.ts:409-416) will need updating in the same commit.
• TransactionScope — no code workaround on your side for #468, so this one's a pure correctness win on upgrade, nothing to delete.

Retirable independent of the version bump:

• rockets-core/src/infrastructure/crud-compat.ts — the three re-exported types (CrudParamOptionInterface, CrudRequestConfig, CrudResponseConfig) are already in 8.0.0-alpha.10's dist/index.d.ts.
• rockets-server-auth/.../concepta-repository-compat.module.ts — already a self-declared no-op; still imported and registered in rockets-auth.module-definition.ts:118,411 though, so it's dead but wired.
• rockets-core/.../resolve-conceptadev-app-context.ts — AppContextHost.from() already ships in alpha.10 with equivalent instanceof-or-mint semantics, and it's actually stricter than your version: it throws on a non-empty non-host value, where yours silently mints a fresh host and discards whatever the caller passed. A few of your callers invoke this inside password/OTP/user handlers where that could quietly drop live transaction context. Worth switching to .from().
• rockets-core/.../define-hook.ts:166-183 (and the matching bit in exceptions.filter.ts) — the originalError-loss bug this pre-wrap works around doesn't reproduce against the actual alpha.10 tarball; I tested it (RuntimeException sets context.originalError, RepositoryQueryException spreads this.context not super.context). Might be worth re-verifying on your end before trusting my read, but if it holds, the pre-wrap (and the "throw RepositoryQueryException directly" contract it imposes on hook authors) isn't needed.

Also in alpha.10: isTransactional(...targets) / getTransactionalOptions(...targets) from @concepta/nestjs-repository, and isAuthPublic(...targets) from @concepta/nestjs-authentication — pass a handler/class the same way you'd pass them to Nest's own Reflector.getAllAndOverride. These replace mirroring the metadata key strings (TRANSACTIONAL_KEY, AUTHENTICATION_MODULE_DISABLE_GUARDS_TOKEN stay unexported on purpose — the point is to stop coupling to how we store the metadata, not just hand you the string).

Also, re: #74 vs #104 — we independently landed on the same call you did (@Body({ schema }) + native StandardSchemaValidationPipe, no carrier class) before seeing this PR. crud-init-validation.decorator.ts resolves the schema through a parameter → operation → controller hierarchy on top of that, but it's the same native-form direction either way.

[kauandotnet]

Blocking: document generation aborts for a recursive or z.json() named schema referenced from two routes.

taken includes every name already emitted, so on the second conversion of the same instance the generated definition is renamed to <id>Ref_<hex>_2, the owner's $ref moves with it, and the shape comparison below (:367-379) throws "emitted with two different shapes". Reproduced on this head:

const convert = createRocketsStandardSchemaConverter();
const J = withOpenApi(z.object({ id: z.string(), data: z.json() }), 'JsonDto');
convert(J, { schemaType: 'output' });                              // read route
convert(buildPaginatedSchema(J, 'ctx'), { schemaType: 'output' }); // list route: throws

z.json() is a z.lazy in zod 4.4.3, so any resource with a JSON column or a recursive field in its response cannot serve /api/docs-json. The converter spec only covers the non-recursive double conversion.

My take: when taken.has(base) because the already-emitted definition under that name has identical content, reuse the name instead of suffixing. A regression that converts a z.json() response for read and then for the paginated envelope would pin it.

[tnramalho]

Reproduced, fixed — but the mechanism is not the one described, and the suggested fix would not have fired.

taken never collides here. The generated name was prefixed with the OWNER's id, so the same lifted definition got a different name per conversion:

owner JsonDto           -> JsonDtoRef_b3e672be
owner JsonDtoPaginated  -> JsonDtoPaginatedDtoRef_b3e672be   (same digest, other prefix)

JsonDto's own $ref moved with it, and that is what tripped the two-shapes check — so taken.has(base) is false and reusing on identical content never runs.

First fix dropped the owner prefix entirely (RocketsRef_<hash>, content only). That was wrong in a second way, found by an adversarial pass over the fix: a lifted definition is not self-contained. One can reference another, and the __schemaN it does that through is positional:

"__schema0": { "leaf": { "$ref": "#/definitions/__schema1" }, ... }

so two definitions with the same outer shape and different children shared a digest, and the document aborted — the same failure, newly reachable because the prefix had been hiding it. The digest is now transitive: each reference is substituted with the digest of what it points at, a back-edge with its distance up the stack. Equal digests mean equal meaning.

Both regressions are pinned in rockets-standard-schema.converter.spec.ts: two same-shaped parents with different leaves get four distinct components, and one shared leaf under two different parents becomes one shared component.

[kauandotnet]

Blocking: responseOverride skips all three response checks.

output and paginated go through assertNamedSchema / assertFailClosedResponse / assertNoHiddenFields; this branch assigns the escape hatch as is, and buildOperationDecorators stamps it as the serializer. Reproduced: read: { responseOverride: { resource: withOpenApi(z.looseObject({ id: z.string() }), 'Leak') } } is accepted at definition time (an unnamed one too) where the same schema via output throws. This PR gave requestOverride.body the named-component bar; the response side did not get the same treatment.

Suggested change

	if (cfg.responseOverride !== undefined)
	next.response = cfg.responseOverride;
	if (cfg.responseOverride !== undefined) {
	// Same bar as `output` / `paginated`: the escape hatch is stamped as
	// the serializer directly, so it must be a named, fail-closed
	// component with no hidden column.
	for (const slot of ['resource', 'paginated'] as const) {
	const schema = cfg.responseOverride[slot];
	if (schema === undefined) continue;
	const context = `defineResource(${resourceKey}): operations.${label}.responseOverride.${slot}`;
	assertNamedSchema(schema, context);
	assertFailClosedResponse(schema, context);
	assertNoHiddenFields(schema, context);
	}
	next.response = cfg.responseOverride;
	}

collection probably wants the same bar; I left it out because I have not traced how upstream reads it.

[tnramalho]

Applied as suggested — assertNamedSchema + assertFailClosedResponse + assertNoHiddenFields on both resource and paginated.

On collection: traced it rather than guessing. It is declared on upstream's CrudResponseConfig but read nowhere in @concepta/nestjs-crud's dist — the only hit is the .d.ts field declaration, no runtime read. So it reaches no response and is not checked; there is a comment at the call site saying to add it the moment upstream consumes it.

Pinned by three cases in define-resource.spec.ts: unnamed, open, and hidden-column overrides all throw with the operations.*.responseOverride.* context.

[kauandotnet]

Blocking: this eviction is both the CPU hot spot and the ceiling reset under the flood it exists for.

Two things, one rewrite:

1. Once size > maxKeys, every consume runs the O(n) sweep above and, whenever nothing has expired, this O(n log n) copy-and-sort of 100k entries on the request path. Under a unique-account flood the map hovers at the cap, so each request pays the full scan. Rejected requests still mint keys (the guard consumes every dimension, rate-limit.guard.ts:126-159), so the 429s do not stop it. A windowMs of one hour reaches the cap at under 30 rps.
2. expiresAt is anchored at a key's first request, so within one policy the soonest-expiring live window is the oldest-created one. For an attacker that is their ip: ceiling key, created on request one and only updated since. The account-rotation traffic the ceiling exists to stop is what evicts the ceiling, and admitted volume then scales with attack rate.

My take: evict by insertion order in an amortised batch (the Map already iterates oldest-first, so no copy and no sort), or refuse new keys at the cap instead of dropping live ones. Either way a regression that fills the store past maxKeys and asserts the ip: window survives would catch this. The warn below also fires once per request in steady state.

[tnramalho]

Both points confirmed, and measured: 1.8 ms per consume at 20k keys with nothing expired, and the warn fired once per request in steady state.

One correction, on the proposed fix: evicting by insertion order makes point 2 worse. The ceiling key is created on request one of the flood, so it is also the oldest inserted — insertion order puts it at the head of the queue instead of the tail.

It is now LRU by last touch: consume deletes and re-inserts its key, so Map iteration order is recency order and eviction drops from the front, bounded by the overflow (one entry per request at the cap — no scan, no sort). A hot key is touched every request, so the ceiling survives by construction. Pinned: after a 200-key flood at maxKeys: 10, the ip: window still reports 1000 - 202. The live-drop warning is coalesced to one a minute, carrying the count.

The same pass found two more ways the store could be switched off, both introduced by fixes on this PR: a key function returning [] contributed no counter at all (the guard then answered true for every request — now falls back to the route's default key), and maxKeys at 0/NaN/Infinity made eviction drop the entry consume had just inserted (now refused at construction, integer >= 1).

[kauandotnet]

Worth considering: the marker is only read on direct object properties after unwrapField's peels (optional, nullable, default, non-transform pipe). Anything else wrapping the leaf hides it, and the recursive fallback below cannot recover it because a bare string has no children. On this head, with secret = f.string({ dto: { response: false } }) inside a hand-written or f.compute object:

wrapper	assertNoHiddenFields	withHiddenFieldsRemoved
secret().readonly()	accepted	keeps pw
secret().nonoptional()	accepted	keeps pw
secret().prefault('x')	accepted	keeps pw
secret().catch('x')	accepted	keeps pw
z.array(secret())	accepted	keeps pw
secret().transform(v => v)	accepted	keeps pw

.readonly() and .transform() are ordinary things to write on a response field. Checking the marker on every node the shared walker visits, rather than on direct properties only, would close all six at once.

[tnramalho]

All six reproduced exactly as tabulated, and the diagnosis is right: the marker sits one level down where the recursive walk cannot recover it, because the marked node is a bare leaf with no children.

The marker is now read on every node the walker visits, and stripHiddenObject peels the wrapper chain (single-child wrappers via the shared innerType slot, plus arrays — a list of a hidden value is hidden) so the property is dropped rather than kept.

Two of the six do not drop, they now throw at definition time, which is the answer this file already gives for .default() / .catch(): .transform(), because its output cannot be rebuilt without the hidden input, and z.lazy(), which a later pass caught — the rebuilt getter used to run first at serialization, so that error arrived as a 500 on the first response the route served.

Table is pinned as a describe.each in zod-projections.spec.ts, both directions (assert rejects, projection drops).

[kauandotnet]

Worth considering: the only rejection is catchall on a ZodObject; pass-through leaves are accepted everywhere except under a pipe. passesThrough below knows any / unknown / custom / transform are leaky, but it is consulted only from the ZodPipe branch. On this head all of these pass assertFailClosedResponse:

• z.record(z.string(), z.unknown()) as the whole response (ships every row column, hidden ones included)
• z.object({ blob: z.any() }), z.object({ blob: z.unknown() })
• z.custom(() => true), z.json(), z.function({ output: z.looseObject(...) })

The /me response has one: claims: z.record(z.string(), z.unknown()) in me.schemas.ts:35-38, so whatever the adapter puts there reaches the client. Either extend the check to pass-through values in output position, or narrow the "no open objects" wording in the changelog so it does not read as covering these.

[tnramalho]

Took the first option — extended the check — but scoped narrower than the comment implies, and the /me half went the other way. Both deliberate:

Root is now a POSITION, not a node. z.unknown() / z.any() / z.custom() and a record/map of one are refused at a response root, and so is anything that wraps them without naming a key: optional, nullable, readonly, catch, lazy, an array's or set's element, a union branch, either side of an intersection, a pipe's out side. z.array(z.unknown()) ships each row verbatim exactly like the bare version, so it goes the same way.

It stops at an object or a tuple, and that is the part that is not in the comment: a nested z.record(z.string(), z.unknown()) is the shape of a JSON column (rockets-core-json-column.e2e-spec.ts has three), and rejecting it would make JSON columns unserializable. Inside a declared property the author named the key and chose the value type.

/me's claims stays z.unknown() — the second option offered. It is a declared property, so the new rule does not touch it; and narrowing it to z.json() was tried and reverted, because it adds a recursive component to every generated client without constraining anything the adapter puts there. Its description now says the values are the provider's and are not validated.

[kauandotnet]

Minor: this header and Retry-After can disagree. Retry-After correctly uses the latest reset among rejected dimensions; X-RateLimit-Reset comes from verdict, and when two dimensions reject both report remaining: 0, so the tie-break picks whichever came first. A client blocked for an hour by ip and a minute by default sees Retry-After: 3600 next to a reset one minute out. Using latestRejectedResetAt here on the rejected path would align them.

[tnramalho]

Fixed. Both headers now state the same instant on a rejection: X-RateLimit-Reset uses latestRejectedResetAt when the verdict is a rejection, and the reported dimension's own resetAt when it is not.

Pinned in rate-limit.guard.spec.ts with two dimensions rejecting at now + 3.6M and now + 60s — the assertion picks the hour, not the minute, so a revert flips it.

[kauandotnet]

Minor: key carries the raw account value and the client IP. During a store outage this logs every login / recovery / OTP attempt's account identifier at error level, into whatever aggregator the app ships to. Logging the dimension name plus a hash of the key would keep the diagnostic without the PII.

[tnramalho]

Fixed. The message is now Rate limit store failed for key <dimension>:<8 hex> — the dimension name (which names no one) plus a SHA-256 prefix of the whole key, so two failures for the same counter still correlate without writing an address or an IP to the aggregator.

Pinned: the test drives a key containing 1.2.3.4 and victim@example.com and asserts neither string appears in the logged message.

[kauandotnet]

Worth considering: the chain guarantee depends on the middle level's PathScopeHook, so scope: false on a middle resource silently weakens every leaf under it. The guard verifies the immediate parent and replays its hooks; with no hook there is nothing tying the middle row to :parentId, and rockets-core-sub-resource.e2e-spec.ts pins the wrong-ancestor leaf request as 200 "as observed". For an access-control check I lean toward not pinning the hole: each link is a known (param, FK column) pair at materialisation time, so the guard could add Where.eq(middleFk, params[grandparentParam]) to the parent lookup structurally, without hook replay. Failing that, refusing (or at least warning) when a scope: false resource declares subResources would make the trade explicit.

[tnramalho]

Agreed on the principle — a hole should not be pinned as observed behaviour — and the e2e now pins the 404 with the middle level scoped.

Went the cheaper way for the fix itself: defineResource refuses a scope: false sub-resource that declares subResources, naming the segment and the two ways out (scope that level, or move its children up). That closes the class at definition time rather than leaving the trade to be made by accident.

The structural fix suggested — the guard adding Where.eq(middleFk, params[grandparentParam]) from the materialisation-time (param, FK) pair, without hook replay — is not done and is the better long-term shape. It is named as such in the commit and the changelog rather than left implied, so it does not get lost.

[kauandotnet]

Behaviour change worth a changelog line: with ownerColumn unset the guard now runs for unauthenticated callers too, and answers 404 for a missing parent versus a normal response for an existing one. Before this PR no guard was attached on owner: false / scope: false, so an owner-less nested route was not a parent-existence oracle unless the app gates it with its own auth guard. Fine if intended, but it is new surface.

[tnramalho]

Right, and it is new surface introduced by this PR rather than pre-existing. Recorded in both places a consumer would look:

• CHANGELOG, on the scope: false / owner: false entry: with no ownerColumn the guard runs for unauthenticated callers too, so a public nested route answers 404 for a missing parent where before no guard was attached at all.
• CONFIGURATION.md, on the owner: false bullet, with what to do about it — gate the route with your own auth guard if the distinction is sensitive.

[kauandotnet]

Worth considering: userId is pinned, id and the audit columns are not. defineZodUserMetadata omits UPDATE_MANAGED_FIELDS from the update schema, but a hand-written updateSchema is the documented pattern and validateRocketsUserMetadataConfig never checks it. A schema declaring id: z.string().optional() lets PATCH /me hand a foreign primary key to repo.update(existing, ...). SignupUserHandler already strips identity fields for this reason; the same strip here (and in rockets-auth's user-metadata.repository.ts:45-52), or a boot-time rejection of an update schema that declares any managed field, would close it.

[tnramalho]

Confirmed and closed at both ends.

validateRocketsUserMetadataConfig now rejects at boot an updateSchema declaring any of USER_METADATA_MANAGED_FIELDS (id, userId, dateCreated, dateUpdated, dateDeleted, version — exported from core so the list has one home), naming the fields and the .omit({ … }) to add.

Both write paths strip them regardless, for the reason the comment implies but the check cannot cover: the boot check can only read a plain object shape, so a union, an intersection or a pipe passes it. That is upsert-user-metadata.handler.ts and rockets-auth's user-metadata.repository.ts.

Worth reporting: the repo's own aggregate-resources.spec.ts fixture declared id in its update schema, and the new boot check caught it on the first run.

[tnramalho]

@kauandotnet — all twelve reproduced, all twelve addressed. Replies are on the threads; this is the map and the three places the fix differs from the comment.

Commits (d72ccc9..4e77170)

6af8bc5	rate limit: LRU store, per-field keys, header agreement, key not logged, store/maxKeys wiring
bcfaae1	response safety: responseOverride checks, hidden marker through wrappers, pass-through root, /me managed fields
196b240	converter naming, scope: false + subResources refusal, the guard's new surface
b24a139	docs + API report
4374419	second pass over those fixes (see below)
4e77170	rate-limit override typed as an intent union instead of Partial<>

Where the fix differs from the comment

1. Converter — the mechanism described (taken → _2 suffix) does not fire; the collision was the owner prefix giving one definition two names across conversions, so "reuse the name when the content is identical" would not have run. Fixed by naming from transitive content. A second pass then caught that my first fix had introduced a real digest collision — a lifted definition is not self-contained, one can reference another.
2. Store eviction — the suggested insertion-order eviction makes point 2 of the same comment worse: the ceiling key is the oldest inserted, so it would be dropped first. LRU by last touch instead.
3. Fail-closed responses — extended the check, but the new rule stops at an object or a tuple: a nested z.record(z.string(), z.unknown()) is a JSON column and stays legal. /me's claims therefore stays z.unknown() (the other option offered), with a description that says it is not validated.

One thing not done, named rather than implied: the structural ancestor-chain check for sub-resources (Where.eq(middleFk, params[grandparentParam]) without hook replay). defineResource refuses scope: false with subResources instead, which closes the class; the structural version is the better long-term shape and is called out in the commit and the changelog.

Three breaking changes now labelled in the CHANGELOG, all boot-time: an updateSchema declaring a server-managed column, a scope: false level with sub-resources, and a hand-written response schema whose root is a pass-through or that hides a column behind a wrapper.

Adversarial passes over the fixes produced their own findings — two ways the limiter could be switched off by ordinary-looking config (key: () => [], maxKeys: 0), the account-less half of the decoy class, and the digest collision above. Those are in 4374419 and 4e77170.

Gates on 4e77170: build, api:report:check-built, typecheck:spec, 1185 unit, 468 package e2e, lint:all, the three sample suites, and release:packages.

[kauandotnet]

LGTM!