@stjoseph/prumo 0.0.6 → 0.1.0

package/.prumo-templates/core/testing.md

@@ -2,13 +2,16 @@
 
 ## Rule
 
-Run tests with Vitest, **except in `mobile`, which runs Jest with the `jest-expo` preset.** Put a test beside the
-file it tests, named `*.spec.ts`.
+Run tests with Vitest, **except in `mobile`, which runs Jest with the `jest-expo` preset.** Put every test under
+`test/`, at the path of the file it tests with `src/` replaced by `test/`, named `*.spec.ts`. Put what tests share
+(setup, factories, fakes, a fake transport) under `test/support/`. Import code with `@/` and support with `@test/`,
+never with a relative path.
 
-**Do not mock the database.** Test code that touches it against the real one. Write a test without a
-database only for code without a database.
+**Do not mock the database.** In `api`, test a use case against an in-memory fake of its port, a class of
+ours in `test/support/fakes/` that implements the port's interface. Test a repository adapter against the real
+Postgres, and a route through `buildApp()` and `inject()`, also against the real Postgres.
 
-Do not mock `EntityManager`, a repository, or any concrete class from a library.
+Do not mock `EntityManager` or any concrete class from a library.
 
 **In a client, replace the network through the injected transport**: pass a fake `fetch` to `createClient`.
 Do not add a request-mocking library. Test a component that shows an error by rendering it and asserting
@@ -20,19 +23,24 @@ Assert behaviour, not execution. A test that calls a function without asserting
 
 ## Rationale
 
-A mirrored test tree has to be moved when the code moves, and nobody moves it, so the old path survives
-as an orphan that still passes. Co-located, a test travels with its file without anyone thinking about it.
-`.spec.ts` follows the generator, so no rename step is needed after generating a module.
-
-**There are no interfaces to mock.** The architecture has no ports, so a service talks to MikroORM's
-concrete `EntityManager`. Mocking it means imitating identity map, unit of work and flush: the hardest
-thing in a suite to write and the least trustworthy. Each time the imitation is wrong, the test passes and
+`src/` holds only what ships, so a folder of product code reads as the product, and everything that exists only
+to test it lives in one tree with its setup and fakes beside it. Mirroring `src/` keeps finding a test mechanical:
+the path is the file's own. The aliases keep an import independent of how deep a test sits, so moving a test never
+breaks one.
+
+**What it costs:** a mirrored tree has to move when the code moves. A test left behind still passes, as an orphan
+whose path no longer matches any file, and nothing reports it. Moving a file means moving its test in the same
+change.
+**A fake of our port is not a mock of the database.** The port is an interface we wrote, the fake
+implements it, and the compiler keeps the two in step; the use case under test has no idea a database
+exists. Mocking `EntityManager` would mean imitating identity map, unit of work and flush: the hardest thing
+in a suite to write and the least trustworthy. Each time that imitation is wrong, the test passes and
 production does not, and **a test that passes for the wrong reason is worse than no test, because it grants
-permission not to look.**
+permission not to look.** So the SQL is proved where it lives, in the adapter, against the real database.
 
 A real Postgres is already provided, one per worker, with its schema built from the migrations. That also
-dissolves the *unit or integration* argument every project has and nobody wins: the answer is mechanical;
-the code touches the database or it does not.
+dissolves the *unit or integration* argument every project has and nobody wins: the answer is mechanical. A
+use case gets a fake, an adapter gets the database, a route gets both through the real application.
 
 A client has no database, and a `web` generated `alone` has no API beside it to test against. The transport is
 already a parameter (the integration layer takes it from the app) so a fake `fetch` needs no library and
@@ -68,32 +76,41 @@ factories) belongs to the database area, not here.
 Placement:
 
 ```
-✅  features/orders/order-list.tsx
-    features/orders/order-list.spec.tsx
-❌  tests/features/orders/order-list.test.tsx
+✅  src/features/orders/order-list.tsx
+    test/features/orders/order-list.spec.tsx
+❌  src/features/orders/order-list.spec.tsx       beside the file
+❌  test/order-list.spec.tsx                      not at the file's path
+
+✅  import { renderApp } from '@test/support/render-app'
+❌  import { renderApp } from '../../support/render-app'
 ```
 
-What a service test uses:
+What a test of the API uses:
 
 ```
-✅  const em = await testEntityManager()      // real Postgres
+✅  new UpdateProfileUseCase(new InMemoryProfileRepository())      a use case: our fake
+✅  new MikroOrmProfileRepository(testOrm().em.fork())             an adapter: real Postgres
+❌  new UpdateProfileUseCase({ findByUserId: vi.fn(), save: vi.fn() })
 ❌  const em = { findOne: vi.fn(), flush: vi.fn() }
 ```
 
 Asserting:
 
 ```
-✅  expect(await service.activate(id)).toMatchObject({ status: 'active' })
-❌  await service.activate(id)                 // covers the line, checks nothing
+✅  expect(await activate.execute(id)).toMatchObject({ status: 'active' })
+❌  await activate.execute(id)                 // covers the line, checks nothing
 ```
 
 ## Enforcement
 
-**Structural.** With no mock of the database available as a convention, a service test has to use the real
-one.
+**Compiler.** A fake implements the port's interface, so a port that changes breaks every fake that no
+longer matches.
+
+**Configuration.** Each runner collects only `test/**`. That also means a spec written beside its file under
+`src/` is never run, and nothing says so.
 
-**Review only.** That a test asserts something, that a new module arrived with tests at all, and that
-nobody introduced a mock of a library class.
+**Review only.** That a test asserts something, that a new module arrived with tests at all, that nobody
+introduced a mock of a library class, that no spec sits under `src/`, and that a moved file took its test along.
 
 **The known gap:** with no threshold, coverage can fall and CI stays green. Review is the only defence, and
 review tires. If a floor is ever added, the honest form is on the diff (new code arrives tested) rather

package/.prumo-templates/core/tooling.md

@@ -2,8 +2,8 @@
 
 ## Rule
 
-Base the TypeScript configuration on `nestjs/typescript-starter`: `module` and `moduleResolution` both
-`nodenext`, `target` `ES2023`, `strict` on, `strictPropertyInitialization` off.
+Configure TypeScript with `module` and `moduleResolution` both `nodenext`, `target` `ES2023`, `strict` on,
+`strictPropertyInitialization` off.
 
 Add `noUncheckedIndexedAccess`. Do not add `exactOptionalPropertyTypes`.
 
@@ -13,13 +13,16 @@ modules.
 Run Biome's recommended preset, configured in `biome.jsonc`. Write a one-line reason in the configuration
 for any rule added or disabled.
 
-In `api`, enable `javascript.parser.unsafeParameterDecoratorsEnabled` and turn `style.useImportType` off.
+In `api`, enable `experimentalDecorators` and `emitDecoratorMetadata`, enable Biome's
+`javascript.parser.unsafeParameterDecoratorsEnabled`, turn `style.useImportType` off, and turn
+`performance.noBarrelFile` on. Run TypeScript through SWC: `@swc-node/register` in development,
+`unplugin-swc` in tests, `@swc/cli` for the build. Never `tsx`.
 
 In a client using shadcn, turn `a11y.noLabelWithoutControl` and `a11y.useSemanticElements` off for
 `components/ui/` only, through an override. Keep both on everywhere else.
 
-**Never import a class with `import type` where Nest reads its type at runtime**: a constructor
-dependency, or a DTO received through a decorated handler parameter.
+**Never import a class with `import type` where tsyringe reads its type at runtime**: a constructor
+dependency injected without `@inject`.
 
 Run `biome check --staged --write` in `.githooks/pre-commit`. Run `tsc --noEmit` in `.githooks/pre-push`.
 Wire both with `"prepare": "node .githooks/install.mjs"`, which sets `core.hooksPath` inside a Git repository,
@@ -27,13 +30,12 @@ does nothing outside one, and fails when Git is present and the setting cannot b
 
 ## Rationale
 
-Following Nest's starter is not deference: it is what keeps the generator and the convention in agreement,
-so a freshly generated project needs no correction afterwards. `nodenext` also happens to be one of the
-three values MikroORM v7 accepts, so the ORM and the framework ask for the same thing.
+`nodenext` is one of the three values MikroORM v7 accepts, and it is what Node itself resolves.
 
-`strictPropertyInitialization` is off because a DTO's properties are filled by validation rather than by a
-constructor, so the flag reports an error about something correct. The cost is real and wider than DTOs:
-with it off, **any** class may declare a property that is never assigned and the compiler stays quiet.
+`strictPropertyInitialization` is off because an entity's columns are filled by hydration or by the
+database, not by its constructor, so the flag reports an error about something correct. The cost is real
+and wider than entities: with it off, **any** class may declare a property that is never assigned and the
+compiler stays quiet.
 
 `noUncheckedIndexedAccess` is added because `rows[0]` treated as present is the most common source of a
 runtime `undefined`. `exactOptionalPropertyTypes` is left out because it is the one strictness flag whose
@@ -48,17 +50,21 @@ the machine, which is what pre-push is.
 `biome.jsonc` rather than `biome.json`, because the reason has to live beside the rule and JSON cannot hold
 a comment.
 
-**Biome cannot parse Nest without the parser option.** Decorators on constructor and handler parameters
-(`@Inject()`, `@Body()`, `@CurrentUser()`) belong to the legacy proposal, and Biome reports every one as a
-syntax error, not a lint warning, until the option is on.
+**Biome cannot parse the API without the parser option.** `@inject(TOKEN)` on a constructor parameter
+belongs to the legacy decorator proposal, and Biome reports every one as a syntax error, not a lint warning,
+until the option is on.
 
-**`useImportType` breaks injection, and nothing reports it.** Nest resolves a dependency from the type the
-compiler emits into the constructor's metadata. `import type` is erased from the output, so the emitted type
-becomes `Function` and the application refuses to boot. The rule's autofix makes that rewrite across the
-codebase in one pass; in this template it did, and lint, typecheck, build and every service test still
-passed. **On a DTO it is worse:** `ValidationPipe` receives `Object`, validates nothing, and raises nothing,
-so `whitelist` and `forbidNonWhitelisted` silently stop existing. Written by hand, the same `import type`
-does the same damage, which is why the rule forbids the import and not only the lint rule.
+**`useImportType` breaks injection, and nothing reports it.** tsyringe resolves a dependency injected by
+class from the type the compiler emits into the constructor's metadata. `import type` is erased from the
+output, so the emitted type becomes `Object`, and resolving the class fails with *TypeInfo not known for
+"Object"*. It type-checks, and because a use case is resolved per request, it fails on the first request to
+that route rather than at boot. The rule's autofix would make that rewrite across the codebase in one pass,
+and written by hand the same `import type` does the same damage, which is why the rule forbids the import and
+not only the lint rule.
+
+**SWC and never `tsx`** because tsyringe needs the decorator metadata, and esbuild, which `tsx` runs on, does
+not emit it: a class injected by type fails in development only, while build and tests pass. SWC is the one
+transformer that emits it in all three places, and `tsc` only checks types.
 
 **The shadcn override is scoped because both rules are right in application code.** A generated `Label`
 receives `htmlFor` through props the rule cannot see, and shadcn's `Field` uses `role="group"` deliberately.
@@ -87,13 +93,11 @@ Configuration changes:
 ❌  "noUnusedVariables": "off"
 ```
 
-Importing what Nest reads at runtime:
+Importing what tsyringe reads at runtime:
 
 ```
-✅  import { UsersService } from './users.service'
-    import { UpdateProfileDto } from './dto/update-profile.dto'
-❌  import type { UsersService } from './users.service'        // boot fails: Function
-❌  import type { UpdateProfileDto } from './dto/update-profile.dto' // nothing is validated
+✅  import { EntityManager } from '@mikro-orm/postgresql'
+❌  import type { EntityManager } from '@mikro-orm/postgresql'   // TypeInfo not known for "Object"
 ```
 
 Reading an array:
@@ -110,9 +114,8 @@ Reading an array:
 **The hooks.** Formatting cannot reach a commit unformatted, and a type error cannot reach the remote,
 unless somebody uses `--no-verify`, or never ran an install and so never got `core.hooksPath` configured.
 
-**Boot, partially.** A constructor dependency imported as a type fails at boot. **A DTO imported as a type
-does not fail anywhere**, not at boot and not in a service test, so it is caught only by a request test
-that sends an invalid body, or by review.
+**Route tests.** A constructor dependency imported as a type fails the first request that resolves it, so a
+route test covering that use case catches it. A use case tested only through its fake does not.
 
 **Review only.** That a disabled rule carries its reason, and that `strictPropertyInitialization` being
-off did not leave an uninitialised property somewhere outside a DTO.
+off did not leave an uninitialised property somewhere outside an entity.

package/.prumo-templates/database/entities.md

@@ -2,96 +2,88 @@
 
 ## Rule
 
-Declare an entity with `defineEntity` **and a class**. Put the schema in the `defineEntity` call and
-no MikroORM decorators on the class. The class carries `@Exclude` and `@ApiProperty` only: the
-serialization and documentation decorators.
+Write an entity as a plain class in `src/domain/<module>/entities/<name>.entity.ts`, with its data and its
+behaviour. Map it in `src/infra/database/mikroorm/entities/<name>.schema.ts` with
+`new EntitySchema({ class })`, and list the schema in `mikro-orm.factory.ts`.
 
-Keep the default `UnderscoreNamingStrategy`. Table names are singular and match the class name;
-columns are snake_case. Do not configure a naming strategy and do not set `tableName`.
+Import nothing from the ORM in an entity, except `Ref`, `ref` and `Collection` from `@mikro-orm/core` for a
+relation. Declare a to-one relation as `Ref<T>` and a to-many one as `Collection<T>`.
 
-Give every table `id`, `created_at` and `updated_at`. Let `id` be `uuid` with `DEFAULT uuidv7()`. Let
-both timestamps be `timestamptz`, maintained by MikroORM's `onCreate` and `onUpdate`.
+Keep the default `UnderscoreNamingStrategy`. Table names are singular and match the class name; columns are
+snake_case. Do not configure a naming strategy and do not set `tableName`.
+
+Give every table `id`, `created_at` and `updated_at`. Let `id` be `uuid` with `defaultRaw: 'uuidv7()'`. Let
+both timestamps be `datetime`, which is `timestamptz`, maintained by `onCreate` and `onUpdate`.
 
 Add `tenant_id` to every tenant-scoped table. Add `deleted_at` only with a stated reason.
 
-Map types as follows: money is `numeric`, text is `text`, JSON is `jsonb`, time is `timestamptz`, and
-an enum is `text` with a CHECK constraint. Never `float` for money, never `varchar(n)`, never `json`,
-never a native Postgres enum.
+Map types as follows: money is `numeric`, text is `text`, JSON is `jsonb`, time is `datetime`, and an enum
+is `text` with a CHECK constraint. Never `float` for money, never `string`, which is `varchar(255)`, never
+`json`, never a native Postgres enum.
 
-Index `tenant_id`, every foreign key column, and every column used to fetch a single row. Add any
-other index on measurement, not on suspicion.
+Index `tenant_id`, every foreign key column, and every column used to fetch a single row. Add any other
+index on measurement, not on suspicion.
 
-Declare `ON DELETE RESTRICT` on every foreign key. Use `CASCADE` only where the child cannot exist
-without its parent, and say so where you use it.
+Declare `ON DELETE RESTRICT` on every foreign key. Use `CASCADE` only where the child cannot exist without
+its parent, and say so where you use it.
 
 ## Rationale
 
-The class exists because responses are serialized from the entity, which needs `@Exclude` to mark what
-must not leave. `defineEntity` exists because v7 made it the primary path and it keeps the ORM's own
-metadata off the class. The two are separate on purpose.
+The class is the domain's, so a use case and its test work with it without a database. The schema is the
+infrastructure's, so the ORM's metadata never reaches the domain. Hydration does not call the constructor,
+so a class can require its essential fields in the constructor and still be loaded from a row.
+
+`Ref` and `Collection` are the exception because they carry the one compile-time guarantee in the area: an
+unpopulated relation has no `$` on its type, so an N+1 does not compile. They also let an aggregate, an order
+and its items, be written by one flush. Nothing else from the ORM is worth that exception.
 
-snake_case is not a style choice: Postgres folds an unquoted identifier to lower case, so a camelCase
-column must be quoted in every hand-written query, psql session and dashboard, forever. Singular is the
-strategy's default, so it costs nothing and makes the table name match the class name.
+snake_case is not a style choice: Postgres folds an unquoted identifier to lower case, so a camelCase column
+must be quoted in every hand-written query, forever. Singular is the strategy's default.
 
-`numeric` because floating point does not represent 0.10 exactly and the error accumulates across a
-sum. `text` because it performs identically to `varchar(n)` in Postgres while adding no limit that
-hurts to change. `jsonb` because `json` stores raw text and cannot be indexed. A CHECK rather than a
-native enum because adding a value to a native enum is painless but removing or reordering one
-requires recreating the type and rewriting every dependent column.
+`numeric` because floating point does not represent 0.10 exactly and the error accumulates across a sum.
+`text` because it performs identically to `varchar(n)` in Postgres while adding no limit that hurts to
+change. `jsonb` because `json` cannot be indexed. A CHECK rather than a native enum because removing or
+reordering a native enum value requires recreating the type.
 
-The three mandatory indexes need no measurement, because they are consequences of the design.
-**Postgres does not index the referencing side of a foreign key** (only the referenced side, by virtue
-of being a primary key), so `order.customer_id` has no index unless someone declares it, and that is
-the most commonly forgotten index there is.
+**Postgres does not index the referencing side of a foreign key**, so `order.customer_id` has no index
+unless someone declares it: the most commonly forgotten index there is.
 
-`RESTRICT` matters because deletes are real here. `CASCADE` by default would remove a customer's
-orders, invoices and payments in one transaction and return success, with no error and no warning.
-`RESTRICT` makes that command fail and forces the decision into explicit code.
+`RESTRICT` matters because deletes are real here. `CASCADE` by default would remove a customer's orders,
+invoices and payments in one transaction and return success. `RESTRICT` makes that fail and forces the
+decision into code.
 
 ## Applies to
 
-Every entity file, which lives inside its module's `entities/` directory.
+Every file under `domain/<module>/entities/` and `infra/database/mikroorm/entities/`.
 
 ## Examples
 
-Naming:
-
-```
-✅  class User {}      → table user, column created_at
-❌  class User {}      → table users, column createdAt
-```
-
-Money and enums:
-
-```
-✅  amount: numeric          status: text + CHECK (status IN (...))
-❌  amount: double precision status: CREATE TYPE ... AS ENUM
 ```
+✅  class Profile { … }                        no ORM import
+❌  class Profile extends ProfileSchema.class   the schema leaks into the domain
 
-Declaring text:
+✅  customer: Ref<Customer>      items = new Collection<OrderItem>(this)
+❌  customer: Customer           an unpopulated relation looks loaded
 
-```
-✅  displayName: p.text()     → text
-❌  displayName: p.string()   → varchar(255)
-```
+✅  displayName: { type: 'text' }
+❌  displayName: { type: 'string' }            varchar(255)
 
-Deletes:
+✅  class User {}      → table user, column created_at
+❌  class User {}      → table users, column createdAt
 
-```
 ✅  ON DELETE RESTRICT
-❌  ON DELETE CASCADE        // on customer → order
+❌  ON DELETE CASCADE        on customer → order
 ```
 
 ## Enforcement
 
-**Migration review.** Every rule here shows up as SQL in a migration, which is the one place a human
-reads the schema as text. That makes migration review the real check, and the reason migrations are
-generated as readable SQL rather than applied invisibly.
+**Compiler.** Reading `$` on an unpopulated relation does not typecheck.
+
+**Migration review.** Every other rule here shows up as SQL in a migration, the one place a human reads the
+schema as text.
 
-**Review only.** That a new table carries the structural columns, that a foreign key got its index, and
-that each `CASCADE` was deliberate.
+**Review only.** That an entity imports nothing else from the ORM, that a new table carries the structural
+columns, that a foreign key got its index, and that each `CASCADE` was deliberate.
 
-**A caveat worth knowing:** `user` is a reserved word in Postgres. `SELECT * FROM user` in psql returns
-the session user, not the table, and does not error. Quote it: `FROM "user"`. The ORM always quotes
-identifiers, so this only bites hand-written queries.
+`user` is a reserved word in Postgres: `SELECT * FROM user` returns the session user and does not error.
+Quote it in hand-written SQL.

package/.prumo-templates/database/queries.md

@@ -2,78 +2,65 @@
 
 ## Rule
 
-Inject the `EntityManager`. Read with `em.find` and `em.findOne`, write with `em.persist` and
-`em.flush`. **Do not use `@InjectRepository`.**
+Query only inside a repository adapter in `src/infra/database/mikroorm/repositories/`. It injects the
+`EntityManager`; read with `em.find` and `em.findOne`, write with `em.persist` and `em.flush`. Do not use
+MikroORM's `EntityRepository`: the port is ours.
 
-Declare every relation as `Ref<T>` or `Collection`. Access it only through `$`. State `populate` on
-every read that needs the relation.
+Give a port one method per question the domain asks, named for it: `findByUserId`, not a generic `find`
+taking a filter.
+
+State `populate` on every read that needs a relation, and access a relation only through `$`.
 
 Reach for the QueryBuilder only where the operation does not exist in `em.find`: aggregation, window
-functions, CTEs, upserts. Reach for raw SQL only where the QueryBuilder cannot express it either.
-Write one comment line saying why, at each step down.
+functions, CTEs, upserts. Reach for raw SQL only where the QueryBuilder cannot express it either. Write one
+comment line saying why, at each step down.
 
 Apply the tenant rules to raw SQL exactly as to everything else.
 
-Return the managed entity from a service. **Only the services of the module that owns an entity mutate
-it.** A controller, an interceptor and a serializer read it and never write to it.
+Return the managed entity from the repository. Only the use cases of the module that owns an entity change
+it.
 
 ## Rationale
 
-MikroORM's own guidance is that the `EntityManager` is the persistence API and repositories are an
-extension point; `persist`, `flush` and `remove` were removed from repositories in v6 for being
-shortcuts to it. Since nothing can be persisted without the `em`, using a repository as well would put
-**two** doors in every service with a boundary somebody decides per method. This rule fights muscle
-memory (every Nest-with-an-ORM example reaches for `@InjectRepository`), which is why it is written
-negatively.
+The adapter is the only file that knows the database, so a use case reads as the product's rule and its
+test replaces the adapter with a fake. A method per question keeps the port honest: a generic filter would
+leak the ORM's query language into the domain, and the fake would have to reimplement it.
+
+`EntityRepository` is refused because it would be a second repository beside ours, with the same name and a
+different contract.
 
-`Ref` and `$` turn N+1 from a review item into a compile error, because `Loaded<Entity, Hints>` tracks
-what was populated and accessing `$` on an unloaded relation does not typecheck. N+1 is the most silent
-database defect there is: the page works and merely gets slower as the list grows. Eager loading would
-trade it for over-fetching on every query, invisible at the call site.
+`Ref` and `$` turn N+1 from a review item into a compile error, because `Loaded<Entity, Hints>` tracks what
+was populated. N+1 is the most silent database defect there is: the page works and merely gets slower as the
+list grows.
 
-The comment on a QueryBuilder query exists because a year later nobody can tell whether it is there
-because it was needed or because the author did not know how to express it otherwise, and that
-difference decides whether anyone may simplify it.
+The comment on a lower-level query exists because a year later nobody can tell whether it is there because
+it was needed or because the author did not know how to express it otherwise.
 
-An entity from `em.find` is managed, so changing it and flushing later writes to the database with no
-`persist` call. That is the Unit of Work, accepted deliberately. The ownership rule is what keeps a
-cosmetic change in an interceptor from becoming a write when some service downstream flushes.
+An entity from `em.find` is managed, so changing it and flushing writes it with no `persist` call. That is
+the Unit of Work, accepted deliberately. The ownership rule keeps a change made for display from becoming a
+write when something downstream flushes.
 
 ## Applies to
 
-Every service. The relation rules also shape how entities are declared.
+Every repository adapter and every port. The relation rules also shape how entities are declared.
 
 ## Examples
 
-The door:
-
-```
-✅  constructor(private readonly em: EntityManager) {}
-❌  constructor(@InjectRepository(User) private readonly users: EntityRepository<User>) {}
 ```
+✅  findByUserId(userId: string): Promise<Profile | null>
+❌  find(filter: FilterQuery<Profile>)            the ORM's language in the domain
 
-Relations:
+✅  em.findOne(Order, id, { populate: ['customer'] })   then order.customer.$.name
+❌  em.findOne(Order, id)                               then order.customer.$.name: does not compile
 
-```
-✅  const u = await em.findOne(User, id, { populate: ['organization'] })
-    u.organization.$.name
-❌  const u = await em.findOne(User, id)
-    u.organization.name
-```
-
-Dropping a level:
-
-```
 ✅  // QueryBuilder: needs a window function, which em.find cannot express
-❌  // (no comment)
+❌  (no comment)
 ```
 
 ## Enforcement
 
-**Compiler.** Accessing an unpopulated relation through `$` does not typecheck. This is the only
-compile-time guarantee in the area, and it covers the most expensive common defect.
+**Compiler.** Reading `$` on an unpopulated relation does not typecheck.
 
-**Review only.** That `@InjectRepository` did not creep back in, that each step down the query ladder
-carries its reason, and that nothing outside the owning module's services mutates an entity. Nothing prevents the
-last one (a managed entity and a detached one have the same shape), and its failure is silent: a
+**Review only.** That queries stay in the adapters, that each step down the query ladder carries its reason,
+and that nothing outside the owning module's use cases changes an entity. The last one fails silently: a
 change made for display becomes a write on the next flush of that request.

package/.prumo-templates/database/transactions.md

@@ -2,67 +2,57 @@
 
 ## Rule
 
-Open a transaction only where more than one operation must succeed or fail together. A single
-`em.flush()` is already atomic.
+Open a transaction only where more than one write must succeed or fail together. A single `save()` is
+already atomic.
 
-Open it with `em.transactional(async em => …)`. Do not use the `@Transactional()` decorator, and never
-write `begin` / `commit` / `rollback` by hand.
+Open it in the use case, through the `TransactionManager` port: `await this.transactions.run(async () => …)`.
+Every repository called inside the callback joins the transaction. Never write `begin` / `commit` /
+`rollback` by hand.
 
-Keep every network call outside the transaction block: an email, a payment gateway, any HTTP request.
+Keep every network call outside the callback: an email, a payment gateway, any HTTP request.
 
-Leave the isolation level at READ COMMITTED. Where an invariant depends on reading a row and then
-deciding, lock it with `SELECT … FOR UPDATE`. Do not raise the isolation level.
+Leave the isolation level at READ COMMITTED. Where an invariant depends on reading a row and then deciding,
+lock it: give the port a method that says so, `findByIdForUpdate`, and implement it with
+`lockMode: LockMode.PESSIMISTIC_WRITE`. Do not raise the isolation level.
 
 Do not retry a failed transaction. Fix the lock ordering instead.
 
 ## Rationale
 
-`em.flush()` wraps its changes in an implicit transaction, so an explicit one is not for writing
-correctly; it is for the case where two units of work must happen together. A per-request transaction
-would last as long as the request, so a five-second timeout at an email provider becomes five seconds of
-row locks; under concurrency that becomes a queue and the queue becomes an outage. The database ends up
-paying for someone else's slowness.
+The boundary is the use case's decision, because only the use case knows which writes belong together; the
+port keeps that decision in the domain without importing the ORM. The adapter uses `em.transactional`, and
+inside it the global `EntityManager` resolves to the transaction's fork, which is why repositories need
+nothing passed to them.
 
-The callback rather than the decorator, because the decorator makes the whole method the boundary and
-cannot be narrowed. A method that writes two rows and also sends an email would sit entirely inside the
-transaction with nothing in the code showing it. The decorator composes better through `REQUIRED`
-propagation; that is given up because its failure mode is silent and only appears under load.
+A per-request transaction would last as long as the request, so a five-second timeout at an email provider
+becomes five seconds of row locks; under concurrency that becomes a queue and the queue an outage.
 
 READ COMMITTED does not prevent read-decide-write: two requests read the same balance, both find it
-sufficient, and both write. Nothing fails. `FOR UPDATE` is the local, visible fix: the second
-transaction waits instead of aborting, so it needs no retry. Raising the isolation level would make
-every transaction in the system need retry logic, including the ones that never conflicted.
+sufficient, and both write. Nothing fails. `FOR UPDATE` is the local, visible fix: the second transaction
+waits instead of aborting, so it needs no retry. The lock is a named port method so the use case shows it.
 
-A deadlock is an ordering bug, not bad luck, and retrying hides it: the system slows under load and
-nothing ever fails loudly enough to be investigated. A retry also repeats whatever side effects already
+A deadlock is an ordering bug, and retrying hides it. A retry also repeats whatever side effects already
 happened outside the database.
 
 ## Applies to
 
-Every service method that writes more than once.
+Every use case that writes more than once, and `MikroOrmTransactionManager`.
 
 ## Examples
 
-Keeping the network out:
-
-```
-✅  await em.transactional(async (em) => { … })
-    await mailer.send(…)
-❌  await em.transactional(async (em) => { … ; await mailer.send(…) })
 ```
+✅  await this.transactions.run(async () => { … })
+    await this.mailer.send(…)
+❌  await this.transactions.run(async () => { … ; await this.mailer.send(…) })
 
-Read, decide, write:
-
-```
-✅  const acc = await em.findOne(Account, id, { lockMode: LockMode.PESSIMISTIC_WRITE })
-❌  const acc = await em.findOne(Account, id)   // two requests both pass the check
+✅  const account = await this.accounts.findByIdForUpdate(id)
+❌  const account = await this.accounts.findById(id)     two requests both pass the check
 ```
 
 ## Enforcement
 
-**Review only, and one line of it matters more than anything else in this area:** that a read-decide-write
-sequence locks the row. Nothing detects a missing `FOR UPDATE`. The failure is silent and expensive
-(a negative balance, stock sold twice), and no transaction errors when it happens.
+**Tests.** The template proves that a failed write inside `run()` rolls back the one before it.
 
-Also review: that no network call sits inside a transaction block, and that nobody added a retry
-wrapper.
+**Review only, and one line of it matters more than anything else in this area:** that a read-decide-write
+sequence locks the row. Nothing detects a missing lock, and no transaction errors when a balance goes
+negative. Also review that no network call sits inside `run()` and that nobody added a retry.