@stjoseph/prumo 0.0.1

package/.prumo-templates/api/auth.md

@@ -0,0 +1,130 @@
+# Authentication
+
+## Rule
+
+Mount Better Auth on a Nest controller: a catch-all route `@All('*path')` under `auth`, declared
+`version: VERSION_NEUTRAL`, passing the request and response to `toNodeHandler(auth)`. With the global `api`
+prefix this resolves to `/api/auth/*`. Mark that controller `@Public()`. It is the one controller that takes
+`@Req()` and `@Res()`.
+
+Register the authentication guard globally. Every route is protected.
+
+Declare a route that does not require a session with `@Public()`. There is no third state: the guard
+always attempts to resolve the session, and `@Public()` means only *do not return 401*.
+
+Read the session with a `@CurrentUser()` parameter decorator. Pass it to the service as an ordinary
+argument. Do not inject a request-scoped session provider, do not take `@Req()`, and do not read the
+session from ambient context inside a service.
+
+Keep Better Auth's tables in their own Postgres schema, on their own connection, migrated by its own
+CLI. Point that CLI at the **compiled** configuration, and run its migrations **before** ours.
+
+Set `advanced.database.generateId` to `'uuid'`.
+
+Better Auth's tables follow Better Auth's conventions, not `database/entities.md`. Reference `auth.user(id)`
+from an application table with a real foreign key and `ON DELETE RESTRICT`.
+
+Create what the application keeps about a user in `databaseHooks.user.create.after`. Pass that hook into the
+factory that builds Better Auth, so the factory does not depend on Nest.
+
+## Rationale
+
+`VERSION_NEUTRAL` keeps the auth routes out of the version segment, because you version what you own
+and the shape of these endpoints is Better Auth's contract, not this project's. Mounting inside Nest
+rather than as middleware ahead of the router means the logging and the request id apply to the
+authentication flow, the path where investigating matters most. **The exception filter does not:**
+`toNodeHandler` writes Better Auth's own responses, so an authentication error arrives as
+`{ message, code }`, not as problem+json. The client converts it; the server does not rewrite another
+library's responses.
+
+`toNodeHandler` rather than `auth.handler(req)`, because `handler` expects a Fetch API `Request` and Nest
+hands the controller an Express one; `toNodeHandler` is Better Auth's own adapter between the two. Running it
+after Nest's body parser was expected to break sign-up and does not: verified with a real sign-up through the
+controller.
+
+The CLI reads the compiled file because it loads TypeScript through its own transpiler, which cannot handle
+the legacy property decorators the validated environment class uses. Migrations before ours, because an
+application table references Better Auth's.
+
+**Its ids are `text` by default**, which no application column typed `uuid` can reference. `generateId:
+'uuid'` makes them `uuid` columns. What remains different is deliberate and not ours to fix: camelCase column
+names, and `gen_random_uuid()` (version 4) rather than `uuidv7()`. Rewriting another library's schema is
+a migration fighting its CLI on every upgrade.
+
+The foreign key into `auth.user` exists because between the database guaranteeing and the application
+remembering, this project chooses the database. **What it costs:** deleting a user fails while rows reference
+it, so the application removes them first, deliberately.
+
+The hook is Better Auth's extension point for work that must follow sign-up, and it is the only place where a
+client never learns that identity and profile are two tables. **It is not atomic:** the user and the
+application's row are written over two connections, so a failure between them leaves a user with no row. The
+result is a visible 404, not corrupted data.
+
+The guard is global because of the asymmetry between the two possible mistakes. A forgotten guard
+leaves an endpoint open: nothing errors, nothing breaks, and the route test still passes, because
+route tests rarely assert refusal. A forgotten `@Public()` returns 401 on the first call and is fixed
+in seconds.
+
+The session resolves even on public routes so that "works signed out, shows more signed in" needs no
+third decorator. With no cookie there is no lookup, so an anonymous request to a public endpoint pays
+nothing.
+
+The session arrives as an argument so that a service's signature says what it needs. Ambient context
+would hide the dependency and force every test to construct a context before it can run.
+
+## Applies to
+
+Every controller and every service. The guard, the Better Auth controller and its connection are
+registered once at bootstrap.
+
+## Examples
+
+Declaring access:
+
+```
+✅  @Public() @Get('health') health() {}
+❌  @Get('health') health() {}          // 401, because protected is the default
+```
+
+Mounting the handler:
+
+```
+✅  @Public() @All('*path') handle(@Req() req: Request, @Res() res: Response) {
+      return toNodeHandler(this.auth)(req, res)
+    }
+❌  @All('*') handle(@Req() req: Request) { return this.auth.handler(req) }
+```
+
+Referencing a user from an application table:
+
+```
+✅  foreign key ("user_id") references "auth"."user" ("id") on delete restrict
+❌  "user_id" uuid not null           // nothing stops an orphan
+```
+
+Receiving the session:
+
+```
+✅  findMine(@CurrentUser() user: SessionUser) { return this.orders.forUser(user.id) }
+❌  findMine(@Req() req: Request)          { return this.orders.forUser(req.session.user.id) }
+```
+
+Inside a service:
+
+```
+✅  forUser(userId: string) {}
+❌  forUser() { const userId = context.get('userId') }
+```
+
+## Enforcement
+
+**Boot.** The guard is global, so a route cannot be unprotected by omission, only by an explicit
+`@Public()`.
+
+**The database.** A row referencing a user that does not exist is refused.
+
+**The migration script.** One command runs Better Auth's migrations and then ours, so the order cannot be
+forgotten.
+
+**Review only.** That each `@Public()` is deliberate. It is the one decorator in the system whose
+mistaken use is invisible at runtime: the route works, and it works for everyone.

package/.prumo-templates/api/config.md

@@ -0,0 +1,85 @@
+# Configuration
+
+## Rule
+
+Validate the environment with `@nestjs/config`'s `validate` function, using class-validator. Do not
+add Joi.
+
+Register the validated class as a provider and inject it with its type. Do not call
+`ConfigService.get()` with a string key.
+
+Fail the boot when validation fails. Report every invalid variable at once, ignore unknown ones, and
+name the variable without printing its value.
+
+Keep `.env` in `.gitignore`. Commit `.env.example` with every variable and a safe sample value. Do not
+read an env file in production.
+
+Load `.env` outside production with Node's `process.loadEnvFile`, in the environment module, before
+validating. Give `ConfigModule` `ignoreEnvFile: true` and that loading function as its `validate`.
+
+Read `process.env` in exactly one place: the environment module. Nowhere else.
+
+## Rationale
+
+class-validator is already installed for DTOs, so using it here means one validation vocabulary
+instead of two doing the same kind of work. Joi is genuinely better at configuration schemas
+(coercion and defaults read more naturally there) but not enough to justify a second grammar in the
+same project.
+
+Injecting the validated class rather than calling `ConfigService.get()` keeps the type honest. `get()`
+returns `string | undefined`, so every call site needs a `!` or a guard for a value that was already
+proven present at boot, and the key is a string nothing checks: rename the variable, miss one call,
+and it compiles and breaks in production. A class property breaks the build instead.
+
+Reporting every failure at once turns eight missing variables into one cycle rather than eight. The
+value is never printed because most of these are secrets and a boot error goes to the orchestrator's
+log, which usually has more readers than the database.
+
+**Unknown variables are ignored here, and that is deliberate.** Rejecting the unknown is the rule for
+request bodies and query parameters; a process environment legitimately carries `PATH`, `HOME` and
+whatever the CI runner sets, so the same rule would make the application impossible to start. This
+exception is written down so nobody harmonises it later.
+
+**The file is loaded by the environment module rather than by `ConfigModule`** because the application is not
+the only entry point. The ORM's CLI and Better Auth's CLI both import the configuration long before any Nest
+module exists, so `ConfigModule`'s own loading reaches the application and neither CLI. Node's `--env-file`
+would do it without code, but it has to be typed on every command, and Node refuses it inside
+`NODE_OPTIONS`. One function every entry point calls keeps one policy, including *never in production*.
+
+## Applies to
+
+The configuration module and every consumer of a setting.
+
+## Examples
+
+Reading a setting:
+
+```
+✅  constructor(private readonly config: AppConfig) {}
+    this.config.databaseUrl
+
+❌  this.configService.get<string>('DATABASE_URL')!
+```
+
+Reporting a bad value:
+
+```
+✅  DATABASE_URL is not a valid URL
+❌  DATABASE_URL is not a valid URL: postgres://admin:hunter2@prod-db/app
+```
+
+Reaching the environment:
+
+```
+✅  // only inside the environment module
+❌  const url = process.env.DATABASE_URL
+```
+
+## Enforcement
+
+**Boot.** The application does not start with an invalid environment, so a missing variable cannot
+reach a request.
+
+**Review only.** That `.env.example` gained the variable someone added to the config class, and that
+no error message quotes a value. A drifted example is caught the next time somebody clones, because
+boot lists everything missing.

package/.prumo-templates/api/errors.md

@@ -0,0 +1,82 @@
+# Errors
+
+## Rule
+
+Throw Nest's built-in exceptions: `NotFoundException`, `ForbiddenException`, `BadRequestException`
+and the rest. Do not define an exception hierarchy of your own, and do not construct a problem
+document anywhere but in the filter.
+
+Register one global exception filter, declared with a bare `@Catch()` so it receives everything.
+
+Respond with `application/problem+json` per RFC 9457: `type`, `title`, `status`, `detail`, `instance`.
+
+Carry validation failures in an `errors` extension member, keyed by field name. Use a dotted key for a
+nested field. Produce it from the `ValidationPipe`'s `exceptionFactory`.
+
+Give an unhandled exception a generic 500 problem document carrying nothing from the exception, in
+every environment. Send the exception itself to the log and to Sentry.
+
+Generate a request id at the start of every request, propagate it with `AsyncLocalStorage`, return it
+in an `X-Request-Id` header on every response, and include it in every problem document. Reuse an
+inbound `X-Request-Id` rather than replacing it.
+
+## Rationale
+
+Nest's own error bodies are not consistent: an `HttpException` produces `{ statusCode, message }` with
+`message` a string, while the `ValidationPipe` produces `{ statusCode, error, message }` with `message`
+an array. The field set and the type of a field both change, and every client that displays an error
+pays for it. Fixing that already requires a filter, and once a filter is being written a documented
+standard costs exactly what a bespoke shape costs, with the difference that clients, libraries and
+assistants already know the standard.
+
+The filter catches everything because otherwise the least predictable failures get the least
+predictable shape. A 500 says nothing because an unhandled exception's message carries whatever was
+nearby: a file path, a fragment of SQL, sometimes a connection string. It says the same thing in every
+environment because the error path is the least tested code in the system and does not need two
+versions of itself.
+
+That silence is only supportable because the request id makes it findable. The id covers the whole
+request rather than the moment of failure, since most investigations begin with what the request did
+before it threw.
+
+## Applies to
+
+Every route. The filter, the `exceptionFactory` and the request-id middleware are registered once at
+bootstrap.
+
+## Examples
+
+A validation failure:
+
+```
+✅  { "type": "about:blank", "title": "Bad Request", "status": 400,
+      "errors": { "email": ["must be an email"] },
+      "requestId": "01J..." }
+
+❌  { "statusCode": 400, "error": "Bad Request",
+      "message": ["email must be an email"] }
+```
+
+Raising an error:
+
+```
+✅  throw new NotFoundException()
+❌  throw new ProblemDetails({ status: 404, title: 'Not Found' })
+```
+
+An unhandled exception:
+
+```
+✅  { "type": "about:blank", "title": "Internal Server Error", "status": 500,
+      "requestId": "01J..." }
+
+❌  { "status": 500, "detail": "null value in column \"tenant_id\" of relation \"orders\"" }
+```
+
+## Enforcement
+
+**Boot.** The filter, the `exceptionFactory` and the request-id middleware are registered once, so no
+route can produce a different shape by accident.
+
+**Review only.** That handlers throw Nest's exceptions rather than building responses by hand, and
+that no `detail` written by hand quotes something internal. Nothing checks either.

package/.prumo-templates/api/logging.md

@@ -0,0 +1,79 @@
+# Logging
+
+## Rule
+
+Log through `nestjs-pino`. Do not use Nest's default logger directly and do not add a second logging
+library.
+
+Write JSON to stdout. Render it with `pino-pretty` in development only, as a dev dependency. Never
+write a log file.
+
+Keep automatic request logging on. Put the request id on every line, taken from `nestjs-pino`'s
+per-request context, the same id returned in `X-Request-Id`. Exclude the health route by name, and
+the documentation route outside production.
+
+Never log a request or response body. Configure pino's `redact` for `authorization`, `cookie`,
+`set-cookie`, `password`, `token` and `secret`.
+
+Set the level from `LOG_LEVEL`, defaulting to `info`:
+
+- `error`: it broke and somebody has to look
+- `warn`: it degraded and continued: a retry, a fallback, a limit reached
+- `info`: an event that matters to the business
+- `debug`: off in production
+
+A handled 4xx is not an error. Log it at `info`.
+
+## Rationale
+
+pino emits structured JSON natively, which is what an aggregator expects, and Nest's default logger
+prints prose for a human terminal. It also carries per-request context, so the request id needs no
+second storage mechanism alongside it.
+
+Pretty-printing in development changes only how bytes are rendered for a person: the fields, values
+and structure are identical, and nothing in the system depends on the output format. That is why this
+environment difference is allowed where the error-response one is not; there, the content sent to a
+client changed.
+
+Automatic logging exists because *did this request even arrive* is the first question in half of all
+investigations, and without it a successful request leaves no trace. Health checks are excluded
+because a probe every five seconds is seventeen thousand lines a day saying nothing is wrong, and that
+drowns search results and costs money at ingestion.
+
+The two secrecy rules cover different holes: bodies are the largest surface, and the automatic request
+log touches headers, where the session cookie lives.
+
+Levels carry a written rule because the names look self-explanatory and are not. When a 400 from a
+careless client is logged as `error`, the service's error rate stops measuring health, the alert fires
+constantly, and someone silences the alert that mattered.
+
+## Applies to
+
+Every module. The logger, redaction and route exclusions are configured once at bootstrap.
+
+## Examples
+
+Choosing a level:
+
+```
+✅  warn   payment retried after gateway timeout
+❌  error  validation failed: email must be an email
+```
+
+Logging an object:
+
+```
+✅  logger.info({ userId: user.id }, 'subscription activated')
+❌  logger.info({ user }, 'subscription activated')   // whatever user carries goes too
+```
+
+## Enforcement
+
+**Configuration.** Redaction and the route exclusions are set once and cannot be bypassed per call
+site.
+
+**Review only.** That no one logs a whole object whose contents are unknown; `redact` covers named
+paths, so `{ user }` with a token inside defeats it entirely. And that a 4xx is not raised to `error`.
+
+Access to the logs is a security boundary: an unhandled exception is sent there in full, so stack
+traces, SQL fragments and parameter values are legitimately present.

package/.prumo-templates/api/modules.md

@@ -0,0 +1,117 @@
+# Modules
+
+## Rule
+
+Create one module per resource: `users`, `orders`, `invoices`.
+
+A module contains exactly what `nest g resource` produces: `*.module.ts`, `*.controller.ts`,
+`*.service.ts`, `dto/`, `entities/` and the co-located spec files. Add nothing to that set, **except further
+services**.
+
+Add a service to a module when a group of its methods has a name of its own that the resource's name does
+not cover: `order-refunds`, `order-shipping`. Generate it with `nest g service <name> <module> --flat`, beside
+the resource's service. Do not split by line count, and do not create a `services/` directory or one service
+per action.
+
+Two services in one module never inject each other in both directions.
+
+Export the service. Mark every method that serves only its own module `private`.
+
+Reach another module through `imports: [OtherModule]` and inject what it exports. Reference another
+module's entity when a relation requires it.
+
+Two modules never depend on each other. When they appear to, move the common part into a third
+module. Do not use `forwardRef`.
+
+Do not use barrel files inside a module.
+
+Anything serving more than one module becomes its own module, named for what it does:
+`notifications`, `pdf`, `storage`. There is no `SharedModule`.
+
+A pure function is a function in a file, imported directly. It gets no module.
+
+## Rationale
+
+Nest supplies the mechanism and decides none of this, so every rule above exists to remove a choice
+that would otherwise be made differently in each module and by each assistant.
+
+One module per resource is the shape `nest g resource` generates and the shape every Nest example
+already has, so the generator and the convention never disagree and a generated module needs no
+correction afterwards. Designing an anatomy instead is what previously cost thirteen files per
+feature, five of which carried no guarantee.
+
+`private` makes the compiler enforce the module's surface, at no cost. A cycle is refused because
+Nest's own guidance is to avoid one: `forwardRef` is its escape hatch, and its documented caveats
+include an indeterminate order of instantiation, the class of failure that appears once in
+production and does not reproduce. Barrel files are refused because Nest names them as a way to
+create a cycle nobody can see.
+
+**The extra service exists for the module that is large and still one thing.** Splitting into another
+module is right when a second responsibility has crept in, and wrong when it has not: two modules sharing the
+same entities and invariants end up wanting to call each other, which is the cycle refused above. Nest's own
+answer is several providers in one module, and `nest g service <name> <module>` both creates the file and
+registers it, so the generator and the convention still agree.
+
+The criterion is a name rather than a size because a line limit ages and invites gaming: somebody moves
+arbitrary methods out to pass the number, and the result is worse than the long file. `--flat` keeps the
+anatomy one level deep. One service per action is refused on evidence: it is what produced thirteen files
+per feature.
+
+**What this costs:** the split is a judgement, held by review. And a module with several services can form a
+cycle inside itself, which is why the cycle rule now reaches between services as well as between modules.
+
+A `SharedModule` has no admission criterion, so it only grows. Requiring a name forces the question
+*what is this*, and a module nobody can name should not exist.
+
+## Applies to
+
+Every module under `src/`. The rules about reaching across modules apply wherever one module's code
+refers to another's.
+
+## Examples
+
+Exporting the service, with internals closed:
+
+```
+✅  export class UsersService {
+      findById(id: string) {}
+      private normaliseEmail(v: string) {}
+    }
+
+❌  export class UsersService {
+      findById(id: string) {}
+      normaliseEmail(v: string) {}   // reachable from any module that injects this
+    }
+```
+
+Growing a module that is still one thing:
+
+```
+✅  orders/orders.service.ts
+    orders/order-refunds.service.ts     // nest g service order-refunds orders --flat
+❌  orders/services/cancel-order.service.ts
+❌  refunds/refunds.module.ts           // needs orders' entities, and orders needs it back
+```
+
+Reaching another module:
+
+```
+✅  @Module({ imports: [UsersModule] })
+❌  @Module({ imports: [forwardRef(() => UsersModule)] })
+```
+
+Importing inside a module:
+
+```
+✅  import { UsersService } from './users.service'
+❌  import { UsersService } from './index'
+```
+
+## Enforcement
+
+**Lint.** Barrel-file imports inside a module are verifiable and are caught by a lint rule.
+
+**Review only.** Everything else. Nothing checks that a module maps to a resource, that an extra service
+has a name of its own rather than an arbitrary slice, that a method that
+should be `private` is, or that a `SharedModule` has not been created; a reviewer does. `private`
+prevents accidental injection; it does not prevent someone widening the method next week to reach it.

package/.prumo-templates/api/observability.md

@@ -0,0 +1,91 @@
+# Observability
+
+## Rule
+
+Expose two health routes with `@nestjs/terminus`. Liveness reports that the process is up and checks
+no dependency. Readiness checks that dependencies answer, the database included. Mark both `@Public()`
+and exclude them from request logging.
+
+Connect the ORM explicitly at bootstrap, before the application listens.
+
+Do not install an error-reporting or tracing service by default. A project has structured logs and
+these two routes, and nothing else, until its owner chooses otherwise.
+
+When Sentry is chosen, wire it exactly as follows and not otherwise.
+
+Import `instrument.ts` as the first line of the bootstrap, before `NestFactory` and before every other
+import. Register `SentryModule` in the root module. Add `@SentryExceptionCaptured()` to the existing
+global exception filter's `catch()` method. Do not register `SentryGlobalFilter`.
+
+Send an event for any 5xx response: an unhandled exception and a deliberately thrown 5xx alike. Never
+send one for a 4xx, and never make a `logger.error` call create one by itself.
+
+Attach the request id as a **tag**, and the user's identifier when a session exists. Leave PII sending
+off. Never attach a request body.
+
+## Rationale
+
+Liveness and readiness answer opposite questions (*should I restart this process* and *should I send
+it traffic*) and a single endpoint forces one answer to both. The failure that causes is routine: the
+endpoint checks the database, the database wobbles, and the orchestrator restarts a healthy process.
+Restarting does not fix a database, and the wobble becomes an outage.
+
+**MikroORM 7's `init` no longer connects**, and the readiness check asks whether a connection exists. Without
+the explicit connect, readiness reports the database down until a first query, and an orchestrator sends no
+query to an instance that is not ready. The instance never becomes ready. Connecting at bootstrap also means
+an unreachable database fails the boot instead of a request.
+
+Error reporting is not installed because it requires a commercial account. Installing a service that
+needs an account, a DSN and eventually a bill decides something commercial on the owner's behalf,
+inside a project that is theirs. Free tooling can simply be deleted; a SaaS dependency is different in
+kind. So the wiring is written down and ready, and absent until wanted.
+
+`Sentry.init` must run before other modules load, because the instrumentation patches them as they are
+imported. Nothing enforces that ordering, which makes it the most fragile line in the project.
+
+The 5xx boundary is the status, not the exception type: a deliberately thrown `ServiceUnavailableException`
+is a real failure somebody must see, and treating it as routine because it was explicit would hide the
+case that matters most. Sending everything instead turns the issue list into a stream of invalid client
+input until somebody mutes the project.
+
+**What reaches Sentry leaves your perimeter.** A log stays in infrastructure you control; a third-party
+service does not, and is readable by anyone with access to that project. That is why the bar here is
+higher than for logs, and why the body never goes: on an authentication route it is the password, on a
+payment route it is the card. Reproduction is a convenience; a leak into someone else's system is an
+incident.
+
+## Applies to
+
+The bootstrap, the health module, and the global exception filter.
+
+## Examples
+
+Health routes:
+
+```
+✅  GET /api/health/live    → process is up, checks nothing
+    GET /api/health/ready   → database answers
+❌  GET /api/health         → used for both
+```
+
+Wiring Sentry into the existing filter:
+
+```
+✅  @Catch()
+    export class ProblemFilter implements ExceptionFilter {
+      @SentryExceptionCaptured()
+      catch(exception: unknown, host: ArgumentsHost) {}
+    }
+
+❌  app.useGlobalFilters(new SentryGlobalFilter(), new ProblemFilter())
+```
+
+## Enforcement
+
+**Boot.** The health routes and the filter are registered once.
+
+**Review only, and this is the weakest line in the project:** that `instrument.ts` stays the first
+import. Reordering imports for tidiness, or a formatter doing it unasked, silently stops the
+instrumentation, and nothing fails.
+
+Also review: that no event carries a body, and that a 4xx never becomes one.

package/.prumo-templates/api/pagination.md

@@ -0,0 +1,71 @@
+# Pagination
+
+## Rule
+
+Paginate every list endpoint by cursor. The UUID v7 primary key is the cursor.
+
+Order by id descending. `after` means *older than this*. Do not accept a sort parameter.
+
+Accept two query parameters, declared on a query DTO: `limit`, defaulting to 20 and carrying
+`@Max(100)`, and `after`.
+
+Return `{ "data": [...], "nextCursor": "01J..." | null }`. Add nothing else: no `hasMore`, no
+`total`, no nested `meta`.
+
+Set `nextCursor` to the id of the last item on the page, or `null` when the page is the last one.
+
+## Rationale
+
+Offset pagination fails silently. Under concurrent inserts, page 2 repeats an item from page 1 or
+skips one (no error, just a wrong list) and it degrades at depth, because the database counts and
+discards every skipped row. A cursor is stable at any depth, and UUID v7 being time-ordered means the
+id already is one: no extra sort column, no extra index.
+
+That choice fixes the order. `WHERE id < :cursor ORDER BY id DESC` only works over one ordering, so a
+sort parameter would break the cursor without erroring. Descending, because that is what a list screen
+shows.
+
+`hasMore` is omitted because a null `nextCursor` already says it, and a field derived from another
+field can disagree with it. `total` is omitted because it costs a `COUNT` on every request: the most
+expensive part of an otherwise cheap endpoint, paid whether or not anyone reads it. Adding it to one
+route later breaks no client.
+
+The parameters are an ordinary query DTO, so validation already covers them and the maximum is a
+decorator rather than clamping logic. Clamping would return 100 rows to a client that asked for 500
+without saying so, and the client would advance as though it had consumed 500.
+
+## Applies to
+
+Every endpoint returning a collection. Filtering is not covered here: a filter is a query DTO field
+like any other, and it composes with the cursor without special handling.
+
+## Examples
+
+The response:
+
+```
+✅  { "data": [ ... ], "nextCursor": "01JQ8Z..." }
+❌  { "data": [ ... ], "meta": { "page": 2, "total": 3204, "hasMore": true } }
+```
+
+The query DTO:
+
+```
+✅  @Max(100) limit: number = 20
+❌  limit: number = 20        // no maximum; ?limit=1000000 is a denial of service
+```
+
+Ordering:
+
+```
+✅  GET /api/v1/orders?limit=20&after=01JQ8Z...
+❌  GET /api/v1/orders?sort=total&page=3
+```
+
+## Enforcement
+
+**Validation.** `limit`'s bounds are enforced by the pipe, and an unknown parameter (`page`, `sort`,
+`offset`) is already rejected because unknown properties are forbidden.
+
+**Review only.** That `nextCursor` is the last item's id and is null on the final page, and that a new
+list endpoint paginates at all rather than returning an unbounded array.