@stjoseph/prumo 0.0.6 → 0.1.0

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

@@ -2,129 +2,85 @@
 
 ## 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()`.
+Mount Better Auth at `/api/auth/*` with the catch-all route in `src/infra/http/controllers/auth.controller.ts`,
+which rebuilds the request for `auth.handler`, as Better Auth's Fastify guide does. Mark it
+`config: { public: true }`.
 
-Register the authentication guard globally. Every route is protected.
+Every route is protected by the global `preHandler` hook in `src/infra/http/hooks/auth.hook.ts`. Mark a route
+that needs no session with `config: { public: true }`; that means only *do not answer 401*, and the session is
+still read.
 
-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 user in the handler with `currentUser(request)` and pass its id to the use case as an argument. A use
+case never reads the request or any ambient session.
 
-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, `auth`, on their own connection, migrated by its own
+CLI from the compiled `dist/infra/auth/auth.cli.js`, before our migrations. `pnpm db:migrate` does both, in
+that order.
 
-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'`. Reference `auth.user(id)` from an application table with a
+real foreign key and `ON DELETE RESTRICT`, declared in its schema as a to-one relation to `AuthUser` with
+`mapToPk: true`, so the domain still holds a plain `userId`. `AuthUser`, in `auth-user.schema.ts`, maps only
+the id and is the one Better Auth table the ORM knows. Keep `schemaGenerator.ignoreSchema: ['auth']` and
+`skipTables: ['auth.user']` in `mikro-orm.factory.ts`. Better Auth's tables follow Better Auth's conventions,
+not `database/entities.md`.
 
-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.
+Create what the application keeps about a user in `databaseHooks.user.create.after`, through a use case:
+`src/infra/di/index.ts` passes the hook into `createAuth`.
 
 ## 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
+The route sits inside Fastify, so the request id and the logs cover the authentication flow. **The error
+handler does not:** Better Auth writes its 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.
+Protected is the default because of the asymmetry between the two mistakes. A route someone forgot to
+protect is open, and nothing breaks. A route someone forgot to mark public answers 401 on the first call and
+is fixed in seconds.
 
-**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 user arrives as an argument so a use case's signature says what it needs, and its test passes an id
+instead of building a request.
 
-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.
+Better Auth's ids are `text` by default, which no `uuid` column can reference; `generateId: 'uuid'` fixes
+that. What stays different is not ours to fix: camelCase columns and `gen_random_uuid()`. Rewriting another
+library's schema fights its CLI on every upgrade. Better Auth's migrations run first because an application
+table references its tables.
 
-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 ORM compares its entities with everything in the database, so without `ignoreSchema` it reads Better
+Auth's tables as leftovers and every generated migration drops them, with every login in them. The foreign
+key is declared rather than written by hand in a migration because the ORM would otherwise drop that too,
+every time. `AuthUser` exists only as that anchor.
 
-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.
+**The sign-up hook is not atomic:** the user and the application's row are written over two connections, so
+a failure between them leaves a user without a profile. The result is a visible 404, not corrupted data. And
+the foreign key means deleting a user fails while rows reference it, so the application removes them first.
 
 ## Applies to
 
-Every controller and every service. The guard, the Better Auth controller and its connection are
-registered once at bootstrap.
+Every route, every use case that acts for a user, and `src/infra/auth/`, where Better Auth is built.
 
 ## 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
 ```
+✅  app.get('/health', { config: { public: true } }, …)
+❌  app.get('/health', …)                         401: protected is the default
 
-Receiving the session:
+✅  execute(currentUser(request).id)
+❌  execute(request)
 
-```
-✅  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') }
+✅  userId: { kind: 'm:1', entity: () => 'AuthUser' as never, mapToPk: true, deleteRule: 'restrict' }
+❌  userId: { type: 'uuid' }                         nothing stops an orphan
 ```
 
 ## Enforcement
 
-**Boot.** The guard is global, so a route cannot be unprotected by omission, only by an explicit
-`@Public()`.
+**Boot.** The hook is global, so a route is unprotected only by an explicit `public: true`.
 
-**The database.** A row referencing a user that does not exist is refused.
+**Tests.** `users.controller.spec.ts` signs up through the real route and proves 401 without a session.
+`mikro-orm.factory.spec.ts` asserts that a migrated database leaves the schema generator nothing to change,
+so a configuration that would drop Better Auth's schema, or the foreign key, fails the suite.
 
-**The migration script.** One command runs Better Auth's migrations and then ours, so the order cannot be
-forgotten.
+**The database.** A row referencing a user that does not exist is refused.
 
-**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.
+**Review only.** That each `public: true` is deliberate: the one mistake that is invisible at runtime, because
+the route works, for everyone.

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

@@ -2,84 +2,58 @@
 
 ## Rule
 
-Validate the environment with `@nestjs/config`'s `validate` function, using class-validator. Do not
-add Joi.
+Validate the environment with the Zod schema in `src/infra/config/env.ts`. Convert a value that is not a
+string with `z.coerce`. Do not add another configuration library.
 
-Register the validated class as a provider and inject it with its type. Do not call
-`ConfigService.get()` with a string key.
+Register the parsed value in the container under `ENV` and inject it with the `Env` type. Nothing reads a
+setting by 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.
+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.
+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`.
+Load `.env` outside production with Node's `process.loadEnvFile`, inside `loadEnv()`, before validating.
 
-Read `process.env` in exactly one place: the environment module. Nowhere else.
+Read `process.env` in exactly one place: `env.ts`.
 
 ## 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.
+Zod already validates every request, so the environment uses the same vocabulary. `Env` is inferred from the
+schema, so a renamed variable breaks the build at every consumer instead of reading `undefined` in
+production.
 
-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.
 
-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
+**Unknown variables are ignored here, and that is deliberate.** Rejecting the unknown is the rule for request
+bodies; a process environment legitimately carries `PATH`, `HOME` and whatever the CI runner sets. 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*.
+**The file is loaded by `loadEnv()` rather than by the server** because the server is not the only entry
+point: the ORM's CLI and Better Auth's CLI both read the configuration without starting it. Node's
+`--env-file` would work without code, but it has to be typed on every command. One function every entry
+point calls keeps one policy, including *never in production*.
 
 ## Applies to
 
-The configuration module and every consumer of a setting.
+`src/infra/config/env.ts` 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
+✅  constructor(@inject(ENV) private readonly env: Env) {}
 ❌  const url = process.env.DATABASE_URL
+
+✅  Invalid environment: DATABASE_URL, BETTER_AUTH_SECRET
+❌  DATABASE_URL is invalid: postgres://admin:hunter2@prod-db/app
 ```
 
 ## Enforcement
 
-**Boot.** The application does not start with an invalid environment, so a missing variable cannot
-reach a request.
+**Boot.** The application does not start with an invalid environment.
 
-**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.
+**Review only.** That `.env.example` gained the variable someone added to the schema. A drifted example is
+caught the next time somebody clones, because boot names everything missing.

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

@@ -2,81 +2,101 @@
 
 ## 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.
+Throw from the domain a class extending `DomainError`, one per failure, in `domain/<module>/errors/`. Give
+it a `kind` from the closed set and a `message` written for the client, because it becomes the `detail`
+the client reads.
 
-Register one global exception filter, declared with a bare `@Catch()` so it receives everything.
+| `kind` | Status |
+|---|---|
+| `not_found` | 404 |
+| `conflict` | 409 |
+| `invalid` | 422 |
+| `forbidden` | 403 |
+| `unauthorized` | 401 |
 
-Respond with `application/problem+json` per RFC 9457: `type`, `title`, `status`, `detail`, `instance`.
+Map `kind` to a status in one place only: `src/infra/http/errors/error-handler.ts`. Throw `HttpError` only
+from `src/infra/http`, for a condition that exists only in HTTP, such as a missing session. Do not return
+an error response from a handler, and do not build a problem document anywhere but in the error handler.
 
-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`.
+Respond with `application/problem+json` per RFC 9457: `type`, `title`, `status`, `detail`, `instance`,
+plus `requestId`.
 
-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.
+Answer a request the schema refuses with 400, and carry the fields in an `errors` extension member keyed by
+field name, with a dotted key for a nested field. A field the schema does not know is named with the
+message `Unrecognized key`.
 
-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.
+Give anything else a generic 500 problem document carrying nothing from the error, in every environment.
+Send the error itself to the log, and to error reporting once it is installed.
+
+Take the request id from an inbound `X-Request-Id`, or generate one, through Fastify's `requestIdHeader`
+and `genReqId`. Return it in `X-Request-Id` on every response and include it in every problem document.
 
 ## 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 domain says what went wrong and never how HTTP says it. A `kind` is a fact about the failure, *there is
+no such profile*, which holds for an MCP tool as much as for a route; the status is HTTP's translation of
+it, and lives with HTTP. A closed set keeps the translation total: the table is a
+`Record<DomainErrorKind, number>`, so adding a `kind` without a status does not compile.
+
+`invalid` is 422 rather than 400 so that a client can tell the two refusals apart without reading text:
+400 means the request had the wrong shape and says which fields, 422 means the shape was right and a rule
+of the product refused it.
 
-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.
+One handler builds every error body because otherwise the least predictable failures get the least
+predictable shape. Fastify's own errors, the validator's and the domain's all pass through it, so a client
+parses one format. Once a single shape is being written, a documented standard costs exactly what a bespoke
+one costs, and clients, libraries and assistants already know it.
 
-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.
+A 500 says nothing because an unhandled error'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. Fastify writes the id into
+every log line of the request, not only the one at 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.
+Every error class under `src/domain/`, every route, and `src/infra/http/errors/`, where the handler and the
+not-found handler are registered once when the application is built.
 
 ## Examples
 
-A validation failure:
+A domain error:
 
 ```
-✅  { "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"] }
+✅  class ProfileNotFoundError extends DomainError { readonly kind = 'not_found' }
+❌  class ProfileNotFoundError extends DomainError { readonly status = 404 }
+❌  throw new HttpError(404, 'Profile not found')          from a use case
 ```
 
-Raising an error:
+A validation failure:
 
 ```
-✅  throw new NotFoundException()
-❌  throw new ProblemDetails({ status: 404, title: 'Not Found' })
+✅  { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Validation failed",
+      "errors": { "displayName": ["Too small: expected string to have >=1 characters"],
+                  "role": ["Unrecognized key"] },
+      "requestId": "0199…" }
+
+❌  { "statusCode": 400, "code": "FST_ERR_VALIDATION", "message": "body/displayName Too small…" }
 ```
 
-An unhandled exception:
+An unhandled error:
 
 ```
 ✅  { "type": "about:blank", "title": "Internal Server Error", "status": 500,
-      "requestId": "01J..." }
+      "detail": "An unexpected error occurred.", "requestId": "0199…" }
 
 ❌  { "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.
+**Typecheck.** The status table is a `Record<DomainErrorKind, number>`: a `kind` without a status does not
+compile.
+
+**Boot.** The error handler and the not-found handler are registered once when the application is built,
+so no route produces 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.
+**Review only.** That the domain throws `DomainError` and never `HttpError`, that a handler throws rather
+than answering an error itself, and that no `message` quotes something internal. Nothing checks these.

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

@@ -2,78 +2,61 @@
 
 ## Rule
 
-Log through `nestjs-pino`. Do not use Nest's default logger directly and do not add a second logging
-library.
+Log through Fastify's built-in Pino: `request.log` inside a request, `app.log` outside one. 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.
+Write JSON to stdout. Render it with `pino-pretty` in development only, as a dev dependency. Never write a log
+file. Tests run without a logger.
 
-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.
+Keep Fastify's request logging on. Every line of a request carries its id, the same one returned in
+`X-Request-Id`. Silence the health routes with `logLevel: 'silent'`.
 
-Never log a request or response body. Configure pino's `redact` for `authorization`, `cookie`,
-`set-cookie`, `password`, `token` and `secret`.
+Never log a request or response body. Keep the `redact` paths in `src/infra/http/app.ts` for the
+`authorization`, `cookie` and `set-cookie` headers.
 
-Set the level from `LOG_LEVEL`, defaulting to `info`:
+Set the level from `LOG_LEVEL`:
 
 - `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`.
+A handled 4xx is not an error. The error handler logs only a 500.
 
 ## 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.
+Pino emits structured JSON, which is what an aggregator expects, and Fastify gives each request a child
+logger carrying its id, so the id needs no second storage mechanism.
 
-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.
+Pretty-printing in development changes only how bytes are rendered for a person; nothing depends on the output
+format. That is why this environment difference is allowed where the error-response one is not.
 
-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.
+Request logging exists because *did this request even arrive* is the first question in half of all
+investigations. Health checks are silenced because a probe every five seconds is seventeen thousand lines a
+day saying nothing is wrong.
 
-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.
+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 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.
+Every file that logs. The logger, redaction and silenced routes are configured when the application is built.
 
 ## 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
+✅  request.log.info({ userId: user.id }, 'subscription activated')
+❌  request.log.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`.
+**Configuration.** Redaction and the silenced routes are set once.
 
-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.
+**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. Access to the logs is a security boundary: an unhandled error is
+sent there in full.