@dunx/create-app 2.4.0 → 3.0.0

package/dist/{chunk-mpa5nv1v.js → chunk-nn9ekg83.js}

@@ -360,10 +360,10 @@ var manifest = (features) => {
     dependencies,
     devDependencies: {
       "@dunx/testing": "__DUNX_VERSION__",
-      "@types/bun": ">=1.3.0",
+      "@types/bun": ">=1.4.0",
       typescript: "^5.7.0"
     },
-    engines: { bun: ">=1.3.0" }
+    engines: { bun: ">=1.4.0" }
   }, null, 2)}
 `;
 };
@@ -791,6 +791,3 @@ var scaffold = async (options) => {
 };
 
 export { FEATURES, featureNames, impliedBy, TEMPLATES, VERSION_PLACEHOLDER, ScaffoldError, scaffold };
-
-//# debugId=8590CB93017DD8C964756E2164756E21
-//# sourceMappingURL=chunk-mpa5nv1v.js.map

package/dist/cli.js

@@ -7,7 +7,7 @@ import {
   featureNames,
   impliedBy,
   scaffold
-} from "./chunk-mpa5nv1v.js";
+} from "./chunk-nn9ekg83.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -129,6 +129,3 @@ try {
     fail(error.message);
   throw error;
 }
-
-//# debugId=01853E264154F96764756E2164756E21
-//# sourceMappingURL=cli.js.map

package/dist/features.d.ts

@@ -1,16 +1,11 @@
 /**
- * The features a generated app can be composed from, each one a directory of
- * `examples/full` - the example CI boots and tours on every push.
+ * The features a generated app can be composed from, each a directory of
+ * `examples/full`, which CI boots and tours on every push - a template nobody runs
+ * rots. `bun run sync:templates` copies them in and `features.test.ts` fails on
+ * drift.
  *
- * That is the whole point of sourcing them there rather than writing starter code
- * here: a template nobody runs rots, and this repo already runs `examples/full`
- * end to end. `bun run sync:templates` copies the directories in and
- * `features.test.ts` fails if a copy drifts, so what gets scaffolded is what CI
- * proved works.
- *
- * What is **not** copied is the wiring: `app.module.ts`, `config.ts`,
- * `bootstrap.ts` and `main.ts` in the full example name every feature at once, so
- * they are generated from the selection instead. See `generate.ts`.
+ * The wiring is not copied: `app.module.ts`, `config.ts`, `bootstrap.ts` and
+ * `main.ts` name every feature at once, so they are generated from the selection.
  */
 export interface Feature {
     /** Flag name, and the directory under `templates/features/`. */

package/dist/index.js

@@ -4,13 +4,10 @@ import {
   TEMPLATES,
   VERSION_PLACEHOLDER,
   scaffold
-} from "./chunk-mpa5nv1v.js";
+} from "./chunk-nn9ekg83.js";
 export {
   ScaffoldError,
   TEMPLATES,
   VERSION_PLACEHOLDER,
   scaffold
 };
-
-//# debugId=2DFAD801C180F0A064756E2164756E21
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dunx/create-app",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Scaffold a new dunx application - bunx @dunx/create-app my-api",
   "keywords": [
     "bun",
@@ -58,6 +58,6 @@
     }
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   }
 }

package/templates/features/assets/assets.module.ts

@@ -6,28 +6,19 @@ import { AssetsDemo } from './assets.demo.js';
 const HASHED = /\.[0-9a-f]{8}\.(js|css)$/;
 
 /**
- * The `public/` directory next to this file, served at `/assets`.
- *
- * `StaticModule` binds `StaticFiles`; the **app** registers it, in `bootstrap.ts`.
- * Position in the chain is the app's decision and no default can make it: assets
- * usually want to be outside an auth guard and inside request logging.
- *
- * The mount is outside `setGlobalPrefix('api')`, because middleware is not a
- * discovered route and never gets the prefix.
+ * `public/` served at `/assets`. `StaticModule` binds `StaticFiles`; the app
+ * registers it in `bootstrap.ts`, because position in the chain is the app's
+ * call. The mount skips the global prefix: middleware is not a discovered route.
  */
 @Module({
   imports: [
     StaticModule.forRoot({
-      // Inside the feature folder rather than at the app root, so the folder is
-      // self-contained: `@dunx/create-app` vendors this directory wholesale, and
-      // an asset kept outside it would need machinery to travel with it.
+      // Inside the feature folder, which `@dunx/create-app` vendors wholesale.
       root: new URL('./public', import.meta.url).pathname,
       path: '/assets',
-      // Short, because a long max-age on a name that can change is a promise the
-      // server cannot keep.
       maxAge: 60,
-      // Only honest for a content-addressed name. Guessing wrong here is a stale
-      // asset nobody can flush, which is why the default claims nothing.
+      // Only honest for a content-addressed name: guessing wrong leaves a stale
+      // asset nobody can flush.
       immutable: (pathname) => HASHED.test(pathname),
     }),
   ],

package/templates/features/auth/auth.demo.ts

@@ -11,11 +11,8 @@ const CREDENTIALS = {
   name: 'Ada',
 };
 
-/**
- * The whole loop over HTTP: better-auth's own mounted endpoints sign a user up and
- * in, then dunx's `SessionGuard` decides who reaches `/api/profile`. Nothing here
- * reimplements an auth flow - every `/api/auth/*` call lands in better-auth.
- */
+/** The whole loop over HTTP: better-auth's mounted endpoints sign a user up and
+ * in, then `SessionGuard` decides who reaches `/api/profile`. */
 export class AuthDemo {
   constructor(
     private readonly logger: Logger,
@@ -28,8 +25,6 @@ export class AuthDemo {
 
   async demonstrate(url: string): Promise<void> {
     const base = new URL(url).origin;
-    // `$context` is where the resolved configuration lands; `options.baseURL` is
-    // whatever was passed in, which better-auth also allows to be a function.
     this.#origin = (await this.auth.$context).baseURL;
     this.logger.info(
       `better-auth ${this.auth.options.basePath} mounted, hashing with Bun.password bcrypt`,
@@ -46,8 +41,7 @@ export class AuthDemo {
     });
     await this.report('POST /api/auth/sign-in/email', signIn);
 
-    // The `bearer` plugin returns the session token in a header, so a server-side
-    // client authenticates without a cookie jar.
+    // The `bearer` plugin returns the token in a header, so no cookie jar.
     const token = signIn.headers.get('set-auth-token') ?? '';
     const cookie = signIn.headers
       .getSetCookie()
@@ -81,8 +75,7 @@ export class AuthDemo {
       },
     );
 
-    // What an admin console would do. The `admin` plugin's own `setRole` endpoint
-    // needs an existing admin to call it, and there is none yet.
+    // The `admin` plugin's `setRole` needs an existing admin, and there is none.
     this.db
       .update(user)
       .set({ role: 'admin' })
@@ -122,8 +115,7 @@ export class AuthDemo {
       },
     );
 
-    // The instance is injectable, so a service can ask better-auth directly rather
-    // than going over HTTP.
+    // Injectable, so a service can ask better-auth without going over HTTP.
     const session = await this.auth.api.getSession({
       headers: new Headers({ cookie }),
     });
@@ -132,12 +124,8 @@ export class AuthDemo {
     );
   }
 
-  /**
-   * `Origin` is set because better-auth rejects a cookie-bearing state change without
-   * one - `MISSING_OR_NULL_ORIGIN`, its CSRF check. A browser sends it for free; a
-   * server-side client has to, and the value that has to match is `trustedOrigins`,
-   * which defaults to the configured `baseURL`.
-   */
+  /** better-auth rejects a cookie-bearing state change with no `Origin`
+   * (`MISSING_OR_NULL_ORIGIN`); it has to match `trustedOrigins`. */
   private post(
     base: string,
     endpoint: string,

package/templates/features/auth/auth.module.ts

@@ -10,46 +10,36 @@ import { AuthTables } from './auth.tables.js';
 import { Audit } from './audit.service.js';
 import { ProfileController } from './profile.controller.js';
 
-/** Named for the feature rather than the package, so `AuthModule` still means `@dunx/auth`'s. */
+/** Named for the feature, so `AuthModule` still means `@dunx/auth`'s. */
 @Module({
   imports: [
-    // The drizzle handle, for `AuthTables` and `Audit`.
     DatabaseModule,
-    // `forRootAsync` because the secret and the base URL come from the validated
-    // config, and the database from the connection `DatabaseModule` already opened -
-    // none of which a zero-argument factory could reach.
+    // `forRootAsync`: the secret, base URL and connection all come from the
+    // container, which a zero-argument factory cannot reach.
     AuthModule.forRootAsync(
       {
-        // `DbConnection` comes from DatabaseModule, and the provider this factory
-        // configures lives in AuthModule's scope - so the module it comes from has to
-        // be named. `AppConfigService` needs no naming: ConfigModule is global.
+        // `DbConnection` is in DatabaseModule's scope, so it has to be named.
+        // `AppConfigService` does not: ConfigModule is global.
         imports: [DatabaseModule],
         useFactory: (config: AppConfigService, connection: DbConnection) => ({
           secret: config.get('auth').secret,
           baseURL: `http://localhost:${config.get('port')}`,
-          // What better-auth matches an incoming pathname against. `app.setGlobalPrefix('api')`
-          // is what makes the mounted `/auth` route answer here.
+          // What better-auth matches a pathname against; the global prefix is
+          // what makes the mounted `/auth` route answer here.
           basePath: '/api/auth',
-          // The app's one drizzle handle. No second pool, no second SQLite file, and
-          // the connection still closes exactly once, last.
           database: drizzleDatabase(connection),
-          // `password: bunPassword` is what `AuthModule` would apply anyway when
-          // `emailAndPassword` is on and no hasher is given - named here so it is
-          // visible. better-auth's own default is a pure-JavaScript scrypt;
-          // `bunPassword` is `Bun.password`'s native bcrypt, which is Rule 1's
-          // first half. Bun pre-hashes, so bcrypt's 72-byte cap is a non-issue.
+          // The default `AuthModule` would apply anyway, named here to be
+          // visible. better-auth's own default is JavaScript scrypt; this is
+          // `Bun.password`'s native bcrypt.
           emailAndPassword: {
             enabled: true,
             minPasswordLength: 8,
             password: bunPassword,
           },
-          // `admin` puts `role` on the user, which `@Roles()` then reads. `bearer`
-          // lets a non-browser client send `Authorization: Bearer <token>` instead of
-          // a cookie - which is what the tour does.
-          // `openAPI()` is what makes `generateOpenAPISchema` exist, and
-          // `betterAuthDocument` in bootstrap.ts is what puts its paths in the app's
-          // document. `disableDefaultReference` because dunx already serves an
-          // explorer at /api/docs and two reference pages is one too many.
+          // `admin` puts `role` on the user for `@Roles()`; `bearer` lets the
+          // tour send a token instead of a cookie. `openAPI()` is what makes
+          // `generateOpenAPISchema` exist for `betterAuthDocument` to merge, and
+          // `disableDefaultReference` keeps it to one explorer.
           plugins: [
             admin(),
             bearer(),
@@ -58,18 +48,13 @@ import { ProfileController } from './profile.controller.js';
         }),
         inject: [AppConfigService, DbConnection] as const,
       },
-      // The route path. The global prefix turns it into `/api/auth`, the `basePath`
-      // above - see AuthOptions.mountAt.
       '/auth',
     ),
   ],
   controllers: [ProfileController],
   providers: [AuthTables, Audit, AuthDemo],
-  // `AuthTables` creates them on the app's own handle, so this module needs the
-  // drizzle handle as well as the connection the factory above used.
-  //
-  // `Auth` comes back out because `OpenApiModule` wraps the root and can only
-  // inject what the root exports - see bootstrap.ts.
+  // `Auth` is exported because `OpenApiModule` wraps the root and can only
+  // inject what the root exports. See bootstrap.ts.
   exports: [Audit, AuthDemo, Auth],
 })
 export class AccountsModule {}

package/templates/features/auth/auth.tables.ts

@@ -4,17 +4,12 @@ import { sql } from 'drizzle-orm';
 import * as schema from '../database/schema.js';
 
 /**
- * better-auth's tables, created at `onInit` for the same reason `Ledger` creates its
- * own: a `:memory:` database has nowhere to keep a migration journal. A real app runs
- * `bunx @better-auth/cli generate` and then `drizzle-kit`, which own the SQL.
+ * better-auth's tables, created at `onInit` because a `:memory:` database has
+ * nowhere to keep a migration journal. A real app runs
+ * `bunx @better-auth/cli generate` and then `drizzle-kit`.
  *
- * The column names are drizzle's defaults for the schema in `database/auth.schema.ts`
- * - camelCase, because that file passes no explicit names.
- */
-/**
- * One statement per entry, not one template with four. `db.run` goes through
- * `bun:sqlite`'s `prepare`, which compiles a single statement and silently drops
- * whatever follows the first semicolon - the table after it simply never exists.
+ * One statement per entry: `db.run` goes through `bun:sqlite`'s `prepare`, which
+ * compiles one statement and silently drops whatever follows the first semicolon.
  */
 const TABLES = [
   sql`CREATE TABLE IF NOT EXISTS user (
@@ -72,11 +67,8 @@ export class AuthTables implements OnInit {
     private readonly logger: Logger,
   ) {}
 
-  /**
-   * `onInit`, not the module factory: `betterAuth()` opens no connection and issues
-   * no query when it is built, so the tables only have to exist before the first
-   * request - and this runs before `listen()` binds.
-   */
+  /** `onInit` rather than the module factory: `betterAuth()` queries nothing when
+   * built, and this still runs before `listen()` binds. */
   onInit(): void {
     for (const table of TABLES) this.db.run(table);
     this.logger.info(`better-auth tables created (${TABLES.length})`);

package/templates/features/cache/cache.module.ts

@@ -6,20 +6,15 @@ import { Sessions } from './sessions.service.js';
 
 @Module({
   imports: [
-    // Without a url Bun's own chain decides it - $VALKEY_URL, then $REDIS_URL,
-    // then valkey://localhost:6379. Connections are lazy, so nothing is dialled
-    // here and an unavailable cache cannot stop the process from booting.
-    // `eager: true` would opt into finding out at startup, which is the opposite
-    // of the point: the cache routes report themselves degraded instead.
+    // No url, so Bun resolves $VALKEY_URL, $REDIS_URL, then localhost.
+    // Connections are lazy, so an unavailable cache cannot stop boot.
     //
-    // `maxRetries: 0` is not just impatience: measured on Bun 1.3.14, a client
-    // that failed to connect with `maxRetries > 0` keeps a retry timer alive even
-    // after `close()`, and the process never exits. With 0 it exits cleanly.
+    // `maxRetries: 0` because on Bun 1.3.14 a client that failed to connect with
+    // `maxRetries > 0` keeps a retry timer alive after `close()` and never exits.
     RedisModule.forRootAsync({
       useFactory: (config: AppConfigService) => {
-        // Destructured first: `exactOptionalPropertyTypes` will not let a
-        // `string | undefined` reach a `url?: string`, even inside the branch
-        // that has already ruled `undefined` out.
+        // `exactOptionalPropertyTypes` will not let `string | undefined` reach
+        // a `url?: string`, even where `undefined` is ruled out.
         const { url } = config.get('redis');
         return {
           ...(url === undefined ? {} : { url }),
@@ -32,8 +27,7 @@ import { Sessions } from './sessions.service.js';
   ],
   controllers: [CacheController],
   providers: [Sessions],
-  // Re-exported: the chat gateway fans out across processes through the same
-  // connection, so it imports this module rather than opening a second client.
+  // Re-exported so the chat gateway fans out through the same connection.
   exports: [RedisConnection, Sessions],
 })
 export class CacheModule {}

package/templates/features/chat/chat.demo.ts

@@ -58,12 +58,9 @@ const connect = async (base: string): Promise<Client> => {
 };
 
 /**
- * A second node, in-process. Two `Bun.serve` instances, two containers, two
- * `PubSub`s with two different origin ids - everything a second deployment has
- * except a second pid, which the relay logic cannot tell apart anyway.
- *
- * It reuses the very same `ChatGateway`, and takes only what that gateway needs:
- * `ChatDemo` itself is not in here, so this module cannot recurse.
+ * A second node in-process: two `Bun.serve` instances, two containers, two
+ * `PubSub` origin ids. It reuses the same `ChatGateway` and excludes `ChatDemo`,
+ * so it cannot recurse.
  */
 @Module({ providers: [ChatGateway, Lobby] })
 class PeerNode {}
@@ -107,20 +104,13 @@ export class ChatDemo {
 
     ada.close();
     grace.close();
-    // Long enough for @OnClose to run before the tour moves on.
     await Bun.sleep(20);
   }
 
   /**
-   * The relay: a publish on this node reaching a client connected to a *different*
-   * node, exactly once. Both nodes run in this process - two `Bun.serve`
-   * instances, two containers - which is every part of a two-machine deployment
-   * that the fan-out logic can distinguish.
-   *
-   * Node A relays through `RedisRelay`, which `createApp` handed to
-   * `HttpFactory`. Node B relays through the application's **own**
-   * `RedisConnection`, which satisfies `PubSubRelay` structurally - two methods,
-   * no adapter, and `@dunx/http` depending on `@dunx/infra` not at all.
+   * A publish on one node reaching a client connected to the other, exactly once.
+   * Node A relays through `RedisRelay`; node B through its own `RedisConnection`,
+   * which satisfies `PubSubRelay` structurally with no adapter.
    */
   async relayed(url: string): Promise<void> {
     const { logger } = this;
@@ -139,8 +129,8 @@ export class ChatDemo {
 
     try {
       logger.info(`node A on ${url}, node B on ${peerUrl}`);
-      // The last chars, not the first: a v7 uuid starts with a timestamp, so two
-      // ids minted in the same second share their leading digits.
+      // The last chars: a v7 uuid leads with a timestamp, so two minted in the
+      // same second share their leading digits.
       logger.info(
         `origins: A …${this.pubsub.origin.slice(-6)} / B …${peerPubsub.origin.slice(-6)} ` +
           '- what tells a node its own echoed frame',
@@ -152,9 +142,8 @@ export class ChatDemo {
       const said = 'across nodes';
       this.pubsub.publishEvent(Lobby.TOPIC, 'said', said);
       logger.info(`node B's client <- ${await onB.next()} (relayed via Redis)`);
-      // Redis echoes a publish back to its publisher. Fanning that out again would
-      // deliver twice on node A, so the origin check drops it - and these counts
-      // are what would show it if it did not.
+      // Redis echoes a publish back to its publisher; the origin check drops it
+      // so node A does not deliver twice.
       await Bun.sleep(200);
       const delivered = (client: Client): number =>
         client.received.filter((frame) => frame.includes(said)).length;

package/templates/features/chat/chat.gateway.ts

@@ -14,10 +14,8 @@ import {
 import type { BunRequest } from 'bun';
 import { Lobby } from './lobby.service.js';
 
-/**
- * Served by the same `Bun.serve` call as the HTTP routes: `HttpFactory` discovers
- * it from `providers`, and `listen()` mounts the upgrade as a native route.
- */
+/** Served by the same `Bun.serve` call as the HTTP routes: `listen()` mounts the
+ * upgrade as a native route. */
 @Gateway('/chat')
 export class ChatGateway {
   constructor(
@@ -26,13 +24,9 @@ export class ChatGateway {
   ) {}
 
   /**
-   * Runs before the socket exists, and is the only place a connection can be
-   * refused: return a `Response` and there is no upgrade. Anything else returned
-   * becomes `socket.data.context`, which is how a room name or an authenticated
-   * user gets carried onto the connection.
-   *
-   * It is handed the `BunRequest` because the upgrade really is a route - Bun
-   * matched it - so headers, query and path params are all readable here.
+   * The only place a connection can be refused: return a `Response` and there is
+   * no upgrade. Anything else becomes `socket.data.context`. Handed the
+   * `BunRequest`, since Bun matched the upgrade as a route.
    */
   @OnUpgrade()
   upgrade(req: BunRequest): Response | { nickname: string } {
@@ -45,23 +39,18 @@ export class ChatGateway {
 
   @OnOpen()
   opened(socket: Socket): void {
-    // Bun's own pub/sub - topics live in the runtime, not in a JavaScript map.
+    // Bun's own pub/sub: topics live in the runtime.
     socket.subscribe(Lobby.TOPIC);
     socket.send('welcome');
   }
 
   @OnMessage('say')
   say(text: string): { delivered: number } {
-    // The broadcast reaches everyone subscribed; the return value is replied to
-    // the sender under the same event name.
+    // Broadcast reaches every subscriber; the return value replies to the sender.
     return { delivered: this.lobby.broadcast(text) };
   }
 
-  /**
-   * Backpressure relieved: Bun buffered because the client was not reading fast
-   * enough and has now flushed. This is where a server streaming to a slow
-   * consumer resumes.
-   */
+  /** Backpressure relieved: where a server streaming to a slow consumer resumes. */
   @OnDrain()
   drained(socket: Socket): void {
     this.logger.info(`${socket.data.path} drained, safe to resume sending`);

package/templates/features/database/database.module.ts

@@ -12,27 +12,18 @@ import * as schema from './schema.js';
 
 @Module({
   imports: [
-    // `forRootAsync` is not a second mechanism: dunx settles every async factory
-    // before the first constructor runs, so the connection is open and its pragmas
-    // applied by the time a repository is built.
+    // The token comes first, unlike `forRoot`: which class a repository injects
+    // is only known once the factory has produced the options.
     //
-    // The first argument is the token, unlike `forRoot`. The database class is
-    // what a repository injects, and which class that is only becomes known once
-    // the factory has produced the options - too late to register a provider
-    // under it.
-    //
-    // `SyncSqliteOptions` rather than `SqliteOptions`, so this app runs SQLite in
-    // **synchronous mode**: the token becomes `SyncDatabase`, and `transactionSync`
-    // becomes reachable. `SqliteOptions` is the default and still what an app
-    // wants if it might move to Postgres later - sync mode is SQLite for good.
+    // `SyncSqliteOptions` runs SQLite in synchronous mode, so the token is
+    // `SyncDatabase` and `transactionSync` is reachable. `SqliteOptions` is the
+    // default and what an app wants if it might move to Postgres.
     DbModule.forRootAsync(SyncDatabase, {
       useFactory: (config: AppConfigService) =>
         new SyncSqliteOptions({
-          // Required, and the reason it is: this is the type argument that reaches
-          // `SyncDatabase<typeof schema>` in every constructor below.
+          // Required: the type argument every constructor below sees.
           schema,
           filename: config.get('database').file,
-          // The only place a pragma can run before the first query.
           pragmas: ['foreign_keys = ON'],
         }),
       inject: [AppConfigService],
@@ -41,10 +32,8 @@ import * as schema from './schema.js';
   controllers: [LedgerController],
   providers: [Ledger],
   /**
-   * The drizzle handle, re-exported so every feature module that imports this one can
-   * inject it. `DbModule` exports it to *this* module; naming it again is what passes
-   * it on, and it is why a repository declares `imports: [DatabaseModule]` rather than
-   * reaching into `@dunx/infra/db` itself.
+   * Re-exported so importers can inject it. `DbModule` exports to this module
+   * only; naming it again passes it on.
    */
   exports: [SyncDatabase, DbConnection, Ledger],
 })

package/templates/features/database/ledger.controller.ts

@@ -23,17 +23,13 @@ const CreateEntry = z
   })
   .meta({ id: 'CreateEntry', description: 'A single ledger movement' });
 
-/** Both legs succeed or neither does - the rollback is the point of the route. */
 const Transfer = z
   .object({
     from: z.string().min(1).max(80),
     to: z.string().min(1).max(80),
     amount: z.number().int().positive(),
-    /**
-     * Throw between the two legs on purpose. The response is a 409 and the row
-     * count is unchanged - which is the only way to see from outside that the
-     * first insert was rolled back rather than committed.
-     */
+    /** Throws between the two legs: a 409 with an unchanged row count is how
+     * the rollback is visible from outside. */
     fail: z.boolean().default(false),
   })
   .meta({ id: 'Transfer', description: 'Move an amount between two memos' });
@@ -44,11 +40,10 @@ const listEntries = {
   }),
 } as const;
 /**
- * The page query, written as zod here rather than shipped by `@dunx/infra/pagination`.
- * That package deliberately ships no schema - route validation targets Standard
- * Schema, so the app picks the library - and stating it here is what puts the
- * parameters in the OpenAPI document. `PAGINATION` supplies the bounds so they
- * cannot drift from what `parsePageOptions` would enforce.
+ * The page query as zod. `@dunx/infra/pagination` ships no schema - validation
+ * targets Standard Schema, so the app picks the library - and stating it here is
+ * what puts the parameters in the OpenAPI document. `PAGINATION` supplies the
+ * bounds so they cannot drift from `parsePageOptions`.
  */
 const pageQuery = z
   .object({
@@ -93,11 +88,8 @@ export class LedgerController {
     };
   }
 
-  /**
-   * The same rows as `GET /ledger`, walked by cursor. Declared **before** `/:id` for
-   * readability only - `Bun.serve` matches a static segment ahead of a parameter, so
-   * `/ledger/page` cannot be swallowed by `/ledger/:id`.
-   */
+  /** Walked by cursor. Declared before `/:id` for readability only: `Bun.serve`
+   * matches a static segment ahead of a parameter. */
   @Get('/page', pagedEntries)
   page(input: Input<typeof pagedEntries>): Page<Entry> {
     return this.ledger.page(input.query);
@@ -120,11 +112,8 @@ export class LedgerController {
     return this.ledger.add(input.body.memo, input.body.amount);
   }
 
-  /**
-   * The failure path is the interesting one: `"fail": true` throws between the
-   * two inserts, and the 409's `rows` is unchanged - proof the first leg was
-   * rolled back rather than committed.
-   */
+  /** `"fail": true` throws between the two inserts; the 409's unchanged `rows`
+   * is proof the first leg rolled back. */
   @Post('/transfer', transfer)
   async transfer(
     input: Input<typeof transfer>,
@@ -142,11 +131,9 @@ export class LedgerController {
   }
 
   /**
-   * The same transfer with no `async` and no `await` on the path at all - the
-   * handler returns a value, `@dunx/http` turns it into a `Response` without
-   * allocating a promise, and SQLite answered on the same tick. What makes it
-   * possible is `SyncSqliteOptions` in `DatabaseModule`; `transactionSync` will not
-   * compile against the async mode's handle.
+   * The same transfer with no `async` anywhere: the handler returns a value and
+   * SQLite answers on the same tick. `SyncSqliteOptions` in `DatabaseModule` is
+   * what allows it - `transactionSync` will not compile against the async handle.
    */
   @Post('/transfer-sync', transfer)
   transferSync(input: Input<typeof transfer>): {