ddd-ts-kit 0.16.1 → 0.18.0

package/templates/init/CLAUDE.md.tpl

@@ -1,46 +1,3 @@
-# {{project.name}}
+@AGENTS.md
 
-A ddd-ts-kit project: one bounded context per directory of `{{config.contextsDir}}/`, each described by its `CONTEXT.md`. The plan and what is next: `docs/architecture/plan.md`, when the project follows the method.
-
-## Commands
-
-- `npm run verify`: types, lint, format, tests with the coverage thresholds of `ddd-ts-kit.config.json` (per context and layer), architecture rules, import graph, dead code, documentation drift. Once, before a commit that closes a slice. A layer under its threshold gets the missing test, never an exclusion.
-- `npx ddd-ts-kit check --changed-since <ref>`: the architecture rules on what changed; `npx ddd-ts-kit explain <rule-id>` gives the reason and an example.
-- `npx ddd-ts-kit list --json`: the map of the contexts. `npx ddd-ts-kit describe <context> --json`: one context as data (use cases, routes, events, ports, dependencies).
-- `npx ddd-ts-kit status`: the next step of the plan, the slices by status, the markers left per context. `npx ddd-ts-kit todo [<context>]`: each remaining `TODO(domain)` and `it.todo` as `file:line`.
-- `npx ddd-ts-kit docs`: regenerates the context map and the generated sections of each `CONTEXT.md`; `npm run docs:generate` the OpenAPI contract, the forms and the event catalog.
-
-## Read less
-
-1. `describe <context> --json` and the `CONTEXT.md` of the context before the tree: do not browse `{{config.sourceRoot}}/` to learn what exists.
-2. Open only what the `next` list of a generator (`file:line`) or a violation names.
-3. `check --changed-since <ref>` and the tests of the context while iterating; `npm run verify` once at the end.
-
-## Rules by layer
-
-Loaded with the files they apply to, from `.claude/rules/`: `domain.md` (`domain/`, the shared kernel), `application.md`, `published-language.md`, `infrastructure.md`, `presentation.md` (and the OpenAPI contract), `platform.md` (`{{config.platformDir}}/`, `main.ts`, `apps/`{{#if style.explicit}}, module files{{/if}}), `tests.md` (specs, fakes, builders, `test/`).
-
-## Generated files
-
-Create every file of a role with `npx ddd-ts-kit generate <kind> ... --json`, then fill the `TODO(domain)` places it lists; never write one by hand, never restructure what a generator wrote.
-{{#if assembly.barrel}}
-Never edit `<context>.declarations.ts`: `generate`, `docs` and `npm run dev` rewrite it, from the role files and from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
-{{/if}}
-{{#if assembly.discovery}}
-Never edit `<context>.dependencies.ts`: `generate`, `docs` and `npm run dev` rewrite it from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
-{{/if}}
-Never edit the contracts under `openapi/` (`openapi/openapi.yaml`, one file per document when `openapi.documents` splits it, the forms of `openapi/forms/`), `docs/integration/asyncapi.yaml`, `docs/integration/event-catalog.md`, `{{config.platformDir}}/http/openapi-documents.ts`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run docs:generate`, `npx ddd-ts-kit docs` and `npx ddd-ts-kit depcruise-config --write`. `stored-events.lock.json` is written by `npx ddd-ts-kit docs --stored-events` once the shape of a version is final (`docs --check` fails while one is unrecorded), never by hand: a stored shape changes only by a new version with its upcaster (`event-sourcing/upcaster-required`).
-{{#if sdk.on}}
-{{sdk.instruction}}
-{{/if}}
-Imports: a file of the project is imported by its alias from the project root, never by a relative path, the same directory included: `{{alias.source}}/...` for `{{config.sourceRoot}}/`, `{{alias.test}}/...` for `test/`, `{{alias.scripts}}/...` for `scripts/`, {{#if alias.extensionless}}never ending in `.js` or `.ts`, and naming a file, never a directory{{/if}}{{#unless alias.extensionless}}always ending in `.js`{{/unless}} (`imports/alias-only`, `imports/extension`; `npm run lint:fix` rewrites a relative import and a wrong ending). The alias is declared once, under `paths` in `tsconfig.json`, from `importAlias` of `ddd-ts-kit.config.json`, and the ending follows `importExtension`: never add a second entry or mapping, never change `module` or `moduleResolution` in `tsconfig.json`, and never compile without `npm run build`, which rewrites the aliases of `dist/` into relative paths ending in `.js` for Node (`imports/alias-declared`).
-Everywhere: one exported class, interface or function per file, named after it in kebab-case; at most 350 lines a file, 30 lines and 3 parameters a function; `private` members, never `#name`; a blank line before a `return` and around `if`, `for`, `try` (`npm run lint:fix`); braces around the body of every `if`, `else`, `for`, `while` and `do`, on its own lines: a branch is visible at a glance, and a statement added to it later cannot silently fall outside it. `npm run format` (Biome, line width 120) lays out every file: do not spend tokens on line breaks.
-
-## TypeScript
-
-The compiler is the native TypeScript 7, installed as `@typescript/native`; `typescript` 6 is there for the tools that need its API (ESLint, dependency-cruiser). Use `npm run typecheck` and `npm run build`, never `npx tsc`, which would run version 6.
-
-## Workflow
-
-Follow the recommended steps in order, the supported path (`README.md`, "Recommended steps"): discover the domain, bounded contexts, glossaries, context map, bootstrap, plan the slices, build slice by slice, quality gate, document. `npx ddd-ts-kit status` says where the project stands. When asked to skip a step, say which one and what it costs, and record it in `docs/architecture/plan.md`.
-With the ddd-ts-kit plugin: `/ddd-ts-kit:start` for a new project or to resume one, `/ddd-ts-kit:glossary` before a new name, `/ddd-ts-kit:use-case` for a feature, `/ddd-ts-kit:document` for the contracts, `/ddd-ts-kit:quality-gate` before a pull or merge request.
+The rules by layer of `.claude/rules/` load with the files they apply to.

package/templates/init/README.md.tpl

@@ -1,7 +1,7 @@
 # {{project.name}}
 
 Domain-Driven Design and Clean Architecture on [ddd-ts-kit](https://www.npmjs.com/package/ddd-ts-kit).
-The rules are in `CLAUDE.md` and `.claude/rules/`; `npx ddd-ts-kit explain <rule-id>` explains each one.
+The rules are in `AGENTS.md`, which every coding agent reads, and by layer in `.claude/rules/` and `.github/instructions/`; `npx ddd-ts-kit explain <rule-id>` explains each one.
 
 ## Run it
 

package/templates/init/rules/application.md.tpl

@@ -6,12 +6,12 @@ paths:
 # Application layer
 
 - Imports `domain/`, `application/`, published languages, `@ddd-ts-kit/kernel` and `@ddd-ts-kit/auth` only (`layer/application-inward`): never `infrastructure/`, `presentation/`, a framework or a driver.
-- One use case per folder, `commands/<use-case>/` or `queries/<use-case>/`: the message, its handler, a `*.result.ts` when the answer has a shape of its own. The handler has one public method, `execute` (`application/handler-shape`): it loads or builds, calls ONE intention method, `await repository.save(aggregate)`, and returns at most an identifier.
+- One use case per folder, `commands/<use-case>/` or `queries/<use-case>/`: the message, its handler, a `*.result.ts` when the answer has a shape of its own. The handler has one public method, `execute` (`application/handler-shape`): it loads or builds, calls ONE intention method, `await repository.save(aggregate)`, and returns at most an identifier. Each binding is named after the concept it holds, `const invoice = await this.invoiceRepository.findById(command.invoiceId)`, `for (const reminder of dueReminders)`, never `target`, `data` or `item` (`naming/business-name`).
 - Events leave with the save: never `pullEvents()`, never a `DomainEventDispatcher` here (`domain-events/dispatched-on-save`). A reaction is a class of `event-handlers/` or a publisher of `integration/publishers/`. It runs at the end of the unit of work, before the commit, and depends only on what the transaction covers (`domain-events/transactional-before-commit`): repositories, the integration event publisher, the command bus. An effect outside the database is a handler of the `after-commit` phase (`generate event-handler ... --phase after-commit`: at most once, never saves, sends a command) or, when it must not be lost, the handler of an integration event.
 - Nothing here reads the event store: an event-sourced aggregate is loaded and saved through its repository port like any other (`event-sourcing/store-behind-repository`). A projection writes its read model and never a stream (`event-sourcing/projection-never-appends`); one fed by the store is declared `@Projection(name, { feed: 'event-store' })`.
 {{#if style.declared}}
 - Every command and query carries `@Requires(permission)` or `@Public()` (`authz/declared`), and the actor is in the message (`authz/actor-explicit`). Permissions live in `authorization/<context>.permissions.ts`, rules that need loaded state in `authorization/*.policy.ts`.
-- The decorator is the registration (`declarations/role-declared`): `@CommandHandler(Message)`, `@QueryHandler(Message)`, `@DomainEventHandler(Event, { name })`, `@IntegrationEventHandler(definition, { consumer })`, `@Scheduled('<context>.<job>', schedule)`, `@Background(options)` (the name is the static `jobName`), `@Projection('<context>.<name>')`, `@Policy(permission, { name })`. Names are string literals.
+- The decorator is the registration (`declarations/role-declared`): `@CommandHandler(Message)`, `@QueryHandler(Message)`, `@DomainEventHandler(Event)` (the name is the static `eventName` of the event class), `@IntegrationEventHandler(definition, { consumer })`, `@Scheduled('<context>.<job>', schedule)`, `@Background(options)` (the name is the static `jobName`), `@Projection('<context>.<name>')`, `@Policy(permission, { name })`. Names are string literals.
 - The constructor is the one statement of what a class depends on (`declarations/constructor-injection`): each parameter is typed by one port class, with no `?`, default value, rest or destructuring, and no list repeats it in the decorator. To add a dependency, add the parameter: `npx ddd-ts-kit docs` reads the signature into the generated file of the context (`npm run dev` does it on every change), never edit that file.
 {{/if}}
 {{#if style.explicit}}

package/templates/init/rules/domain.md.tpl

@@ -7,7 +7,7 @@ paths:
 # Domain layer
 
 - Imports only its own `domain/`, the shared kernel and `@ddd-ts-kit/kernel` (`layer/domain-purity`): no framework, no decorator, no validation library, no `node:` module.
-- Names come from the glossary of `CONTEXT.md`, written first (`language/glossary-term`); no `Manager`, `Helper`, `Data`, `Info`, `Model` (`language/no-technical-name`).
+- Names come from the glossary of `CONTEXT.md`, written first (`language/glossary-term`); no `Manager`, `Helper`, `Data`, `Info`, `Model` (`language/no-technical-name`). A variable, a parameter or a property is named after the concept it holds, `appointment`, `calendar`, never `target`, `data`, `item` (`naming/business-name`).
 - Aggregate: private constructor, `create` for birth, `rehydrate` for loading, state changed by methods named after the business intention, no setter, no public mutable property (`domain/aggregate-encapsulation`). One aggregate per transaction; another one is referenced by its id.
 - A status that moves through a lifecycle is declared once as a state machine, `state-machines/<aggregate>.state-machine.ts` (`generate state-machine <context> <Aggregate> --value .. --transition ..`): the aggregate writes its status only from `machine.next(..)` or `machine.start(..)` (`lifecycle/status-through-machine`), and a forbidden transition is refused by a static factory of its error class (`refused`).
 - A value object is a class extending `ValueObject` of the kernel, one per `value-objects/*.vo.ts` (`npx ddd-ts-kit generate value-object <context> <Name>`): a private constructor, static factories that check its rules (`create`, or named after what they build: `of`, `between`), its operations as methods that return a new instance. It is immutable and compared with `equals` (`domain/value-object-immutability`). An email, an amount, a period are types, not strings.{{#if values.classes}} A value is never a function that builds a plain object, nor an exported object literal (`domain/value-object-class`): the class compares by value, checks its invariants once and is recognised with `instanceof` by a mapper. A function of `domain/` or of the shared kernel that answers a record of data, `({ amount, currency })`, is reported; one that answers value objects it builds (`Money.of(..)`), derives a record with a spread, or answers functions (a specification) is not, and a decision is a refusal thrown by a factory or a value object.{{/if}}

package/templates/init/scripts/events.ts.tpl

@@ -9,7 +9,7 @@ import { contractFormat, stringifyContract } from 'ddd-ts-kit/dist/contracts.js'
 // published language; with --check, fails when a committed file differs. Both files are build
 // products: never edit them by hand.
 const contextsDirectory = '{{config.contextsDir}}';
-const target = path.resolve('docs/integration');
+const catalog = path.resolve('docs/integration');
 const format = contractFormat();
 const other = format === 'yaml' ? 'asyncapi.json' : 'asyncapi.yaml';
 
@@ -34,17 +34,17 @@ const generated: Readonly<Record<string, string>> = {
 if (process.argv.includes('--check')) {
   reportStale();
 } else {
-  fs.mkdirSync(target, { recursive: true });
-  fs.rmSync(path.join(target, other), { force: true });
+  fs.mkdirSync(catalog, { recursive: true });
+  fs.rmSync(path.join(catalog, other), { force: true });
 
   for (const [file, content] of Object.entries(generated)) {
-    fs.writeFileSync(path.join(target, file), content);
+    fs.writeFileSync(path.join(catalog, file), content);
   }
 }
 
 function reportStale(): void {
   for (const [file, content] of Object.entries(generated)) {
-    const committed = fs.existsSync(path.join(target, file)) ? fs.readFileSync(path.join(target, file), 'utf8') : '';
+    const committed = fs.existsSync(path.join(catalog, file)) ? fs.readFileSync(path.join(catalog, file), 'utf8') : '';
 
     if (committed.replaceAll('\r\n', '\n') !== content) {
       console.error('docs/integration/' + file + ' is out of date: run the script `docs:generate` and commit it.');
@@ -52,7 +52,7 @@ function reportStale(): void {
     }
   }
 
-  if (fs.existsSync(path.join(target, other))) {
+  if (fs.existsSync(path.join(catalog, other))) {
     console.error('docs/integration/' + other + ' is in the other format: run the script `docs:generate`.');
     process.exitCode = 1;
   }

package/templates/init/scripts/openapi.ts.tpl

@@ -65,8 +65,8 @@ if (process.argv.includes('--check')) {
 
 function reportDrift(): void {
   for (const [file, content] of generated) {
-    const target = path.join(directory, file);
-    const committed = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+    const contract = path.join(directory, file);
+    const committed = fs.existsSync(contract) ? fs.readFileSync(contract, 'utf8') : '';
 
     if (committed.replaceAll('\r\n', '\n') !== content) {
       console.error(`openapi/${file} is out of date: run the script \`docs:generate\` and commit it.`);

package/templates/integration-event/publisher.declared.ts.tpl

@@ -3,7 +3,7 @@ import { DomainEventHandler } from '@ddd-ts-kit/kernel/declarations';
 import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event{{alias.ext}}';
 import { {{event.camel}}V{{event.version}} } from '{{alias.context}}/published-language/{{event.kebab}}.v{{event.version}}.integration-event{{alias.ext}}';
 
-@DomainEventHandler({{event.pascal}}, { name: {{event.reference}} })
+@DomainEventHandler({{event.pascal}})
 export class {{publisher.pascal}}Publisher implements DomainEventHandler<{{event.pascal}}> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/pipeline/github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,26 @@
+name: Copilot setup steps
+
+# The environment the Copilot cloud agent starts in: Node and the dependencies of the lockfile,
+# so that the checks and the generators of the kit answer at once. Copilot reads this file from
+# the default branch, and only a job of this name; the runs below check it when it changes.
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+permissions:
+  contents: read
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup

package/templates/pipeline/package-scripts.json

@@ -23,7 +23,7 @@
     "@biomejs/biome": "2.5.15",
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
-    "@ddd-ts-kit/eslint-plugin": "^0.16.1",
+    "@ddd-ts-kit/eslint-plugin": "^0.18.0",
     "@eslint/js": "^10.0.1",
     "@typescript/native": "npm:typescript@~7.0.2",
     "@vitest/coverage-v8": "5.0.3",

package/templates/policy/policy.declared.ts.tpl

@@ -2,7 +2,7 @@ import { isAuthenticated, type Actor } from '@ddd-ts-kit/kernel';
 import { Policy } from '@ddd-ts-kit/kernel/declarations';
 import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions{{alias.ext}}';
 
-// TODO(domain): give `allows` the aggregate "{{name.words}}" reads as its second parameter, add `appliesTo(subject: unknown): boolean { return subject instanceof <Aggregate>; }`, and decide from the actor, the loaded element and `now`; the handler asks it through `Access.authorize(command.actor, permission, element)`.
+// TODO(domain): give `allows` the aggregate "{{name.words}}" reads as its second parameter, add `appliesTo(subject: unknown): boolean { return subject instanceof <Aggregate>; }`, and decide from the actor, the loaded element and `now`; the handler asks it through `Access.authorize(command.actor, permission, <aggregate>)`, the loaded aggregate named after its concept (`invoice`, never `element`).
 @Policy({{context.camel}}Permissions['{{access.permission}}'], { name: '{{context.kebab}}.{{name.kebab}}' })
 export class {{name.pascal}}Policy {
   allows(actor: Actor): boolean {

package/templates/policy/policy.ts.tpl

@@ -2,7 +2,7 @@ import { definePolicy } from '@ddd-ts-kit/auth';
 import { isAuthenticated } from '@ddd-ts-kit/kernel';
 import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions{{alias.ext}}';
 
-// TODO(domain): replace `unknown` by the aggregate "{{name.words}}" reads, add `appliesTo: (subject): subject is <Aggregate> => subject instanceof <Aggregate>`, and decide from the actor, the loaded element and `now`; the handler asks it through `Access.authorize(command.actor, permission, element)`.
+// TODO(domain): replace `unknown` by the aggregate "{{name.words}}" reads, add `appliesTo: (subject): subject is <Aggregate> => subject instanceof <Aggregate>`, and decide from the actor, the loaded element and `now`; the handler asks it through `Access.authorize(command.actor, permission, <aggregate>)`, the loaded aggregate named after its concept (`invoice`, never `element`).
 export const {{name.camel}} = definePolicy<unknown>({
   name: '{{name.kebab}}',
   permission: {{context.camel}}Permissions['{{access.permission}}'],

package/templates/presets/identity/context/application/integration/publishers/account-deactivated.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { AccountDeactivated } from '{{alias.context}}/domain/events/account-deac
 import { accountDeactivatedV1 } from '{{alias.context}}/published-language/account-deactivated.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(AccountDeactivated, { name: AccountDeactivated.eventName })
+@DomainEventHandler(AccountDeactivated)
 export class AccountDeactivatedPublisher implements DomainEventHandler<AccountDeactivated> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/delegation-granted.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { DelegationGranted } from '{{alias.context}}/domain/events/delegation-gr
 import { delegationGrantedV1 } from '{{alias.context}}/published-language/delegation-granted.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(DelegationGranted, { name: DelegationGranted.eventName })
+@DomainEventHandler(DelegationGranted)
 export class DelegationGrantedPublisher implements DomainEventHandler<DelegationGranted> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/delegation-revoked.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { DelegationRevoked } from '{{alias.context}}/domain/events/delegation-re
 import { delegationRevokedV1 } from '{{alias.context}}/published-language/delegation-revoked.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(DelegationRevoked, { name: DelegationRevoked.eventName })
+@DomainEventHandler(DelegationRevoked)
 export class DelegationRevokedPublisher implements DomainEventHandler<DelegationRevoked> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/member-joined.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { MemberJoined } from '{{alias.context}}/domain/events/member-joined.even
 import { memberJoinedV1 } from '{{alias.context}}/published-language/member-joined.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(MemberJoined, { name: MemberJoined.eventName })
+@DomainEventHandler(MemberJoined)
 export class MemberJoinedPublisher implements DomainEventHandler<MemberJoined> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/member-removed.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { MemberRemoved } from '{{alias.context}}/domain/events/member-removed.ev
 import { memberRemovedV1 } from '{{alias.context}}/published-language/member-removed.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(MemberRemoved, { name: MemberRemoved.eventName })
+@DomainEventHandler(MemberRemoved)
 export class MemberRemovedPublisher implements DomainEventHandler<MemberRemoved> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/member-role-changed.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { MemberRoleChanged } from '{{alias.context}}/domain/events/member-role-c
 import { memberRoleChangedV1 } from '{{alias.context}}/published-language/member-role-changed.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(MemberRoleChanged, { name: MemberRoleChanged.eventName })
+@DomainEventHandler(MemberRoleChanged)
 export class MemberRoleChangedPublisher implements DomainEventHandler<MemberRoleChanged> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/organisation-opened.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { OrganisationOpened } from '{{alias.context}}/domain/events/organisation
 import { organisationOpenedV1 } from '{{alias.context}}/published-language/organisation-opened.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(OrganisationOpened, { name: OrganisationOpened.eventName })
+@DomainEventHandler(OrganisationOpened)
 export class OrganisationOpenedPublisher implements DomainEventHandler<OrganisationOpened> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/infrastructure/persistence/drizzle-search-members-reader.repository.drizzle.ts.tpl

@@ -22,7 +22,7 @@ export class DrizzleSearchMembersReader implements SearchMembersReader {
     const order = page.sort[0]?.direction === 'desc' ? desc : asc;
     const current = and(eq(members.organisationId, organisationId), isNull(members.removedAt));
 
-    const items = await executorOf(this.database)
+    const currentMembers = await executorOf(this.database)
       .select({
         memberId: members.id,
         accountId: members.accountId,
@@ -40,7 +40,7 @@ export class DrizzleSearchMembersReader implements SearchMembersReader {
 
     const [counted] = await executorOf(this.database).select({ total: count() }).from(members).where(current);
 
-    return pageOf(items, { total: counted?.total ?? 0 });
+    return pageOf(currentMembers, { total: counted?.total ?? 0 });
   }
 }
 

package/templates/presets/identity/context/presentation/http/organisations/search-members/search-members.controller.ts.tpl

@@ -81,6 +81,6 @@ export class SearchMembersController {
   }
 }
 
-function toLine(item: SearchMembersItem): SearchMembersLine {
-  return { ...item, joinedAt: item.joinedAt.toISOString() };
+function toLine(member: SearchMembersItem): SearchMembersLine {
+  return { ...member, joinedAt: member.joinedAt.toISOString() };
 }

package/templates/presets/identity/context/test/integration/search-members-reader.spec.ts.tpl

@@ -76,7 +76,7 @@ describe('{{#if orm.knex}}Knex{{/if}}{{#if orm.drizzle}}Drizzle{{/if}}SearchMemb
 
     const page = await reader.search('acme', offsetPage({ limit: 1, offset: 1, sort: [{ field: 'joinedAt', direction: 'desc' }] }));
 
-    expect(page.items.map((item) => item.memberId)).toEqual(['member-1']);
+    expect(page.items.map((member) => member.memberId)).toEqual(['member-1']);
     expect(page.total).toBe(2);
   });
 });

package/templates/query/handler.declared.ts.tpl

@@ -1,13 +1,32 @@
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import { QueryHandler } from '@ddd-ts-kit/kernel/declarations';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import type { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port{{alias.ext}}';
 import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query{{alias.ext}}';
 import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result{{alias.ext}}';
 
 @QueryHandler({{name.pascal}}Query)
 export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+{{#if access.policy}}
+  constructor(
+    private readonly reader: {{name.pascal}}Reader,
+    private readonly access: Access,
+  ) {}
+{{/if}}
+{{#unless access.policy}}
   constructor(private readonly reader: {{name.pascal}}Reader) {}
+{{/unless}}
 
   async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" reads once it is read, in place of `query`.
+    await this.access.authorize(query.actor, {{access.reference}}, query);
+
+{{/if}}
     // TODO(domain): narrow what is read to what the asker may see: ask `Access.scope(query.actor, permission, '<type>')` for the scope and hand it to the reader, never filter in memory after loading; a query never changes state.
     return this.reader.read(query);
   }

package/templates/query/handler.spec.buses.ts.tpl

@@ -1,6 +1,11 @@
 import { describe, expect, it } from '{{tests.module}}';
 {{#if access.protected}}
+{{#if access.policy}}
+import { AuthorizationMap, PolicyAccess, RoleBasedAuthorizer, authorizationMiddleware, requires } from '@ddd-ts-kit/auth';
+{{/if}}
+{{#unless access.policy}}
 import { AuthorizationMap, RoleBasedAuthorizer, authorizationMiddleware, requires } from '@ddd-ts-kit/auth';
+{{/unless}}
 import { anActor } from '@ddd-ts-kit/auth/testing';
 {{/if}}
 import { createTestBuses } from '@ddd-ts-kit/testing';
@@ -13,12 +18,22 @@ import type { {{name.pascal}}Result } from '{{alias.context}}/application/querie
 import { Fake{{name.pascal}}Reader } from '{{alias.context}}/test/fakes/{{name.kebab}}-reader.fake{{alias.ext}}';
 {{#if access.protected}}
 
+{{#if access.policy}}
+const authorizer = new RoleBasedAuthorizer({ roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] } });
+
+const holders = authorizationMiddleware({
+  authorizer,
+  map: AuthorizationMap.of(requires({{name.pascal}}Query, {{context.camel}}Permissions['{{access.permission}}'])),
+});
+{{/if}}
+{{#unless access.policy}}
 const holders = authorizationMiddleware({
   authorizer: new RoleBasedAuthorizer({
     roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] },
   }),
   map: AuthorizationMap.of(requires({{name.pascal}}Query, {{context.camel}}Permissions['{{access.permission}}'])),
 });
+{{/unless}}
 
 const holder = anActor().withRole('holder').build();
 {{/if}}
@@ -47,8 +62,14 @@ describe('{{name.title}}', () => {
 });
 
 function arrange(answer: {{name.pascal}}Result) {
+{{#if access.policy}}
+  const { queryBus, clock } = createTestBuses();
+  const handler = new {{name.pascal}}Handler(new Fake{{name.pascal}}Reader(answer), new PolicyAccess({ authorizer, clock }));
+{{/if}}
+{{#unless access.policy}}
   const { queryBus } = createTestBuses();
   const handler = new {{name.pascal}}Handler(new Fake{{name.pascal}}Reader(answer));
+{{/unless}}
 
   return queryBus{{spec.guard}}.register({{name.pascal}}Query, handler);
 }

package/templates/query/handler.ts.tpl

@@ -1,12 +1,31 @@
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import type { QueryHandler } from '@ddd-ts-kit/kernel';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import type { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port{{alias.ext}}';
 import type { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query{{alias.ext}}';
 import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result{{alias.ext}}';
 
 export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+{{#if access.policy}}
+  constructor(
+    private readonly reader: {{name.pascal}}Reader,
+    private readonly access: Access,
+  ) {}
+{{/if}}
+{{#unless access.policy}}
   constructor(private readonly reader: {{name.pascal}}Reader) {}
+{{/unless}}
 
   async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" reads once it is read, in place of `query`.
+    await this.access.authorize(query.actor, {{access.reference}}, query);
+
+{{/if}}
     // TODO(domain): narrow what is read to what the asker may see: ask `Access.scope(query.actor, permission, '<type>')` for the scope and hand it to the reader, never filter in memory after loading; a query never changes state.
     return this.reader.read(query);
   }

package/templates/query/search.reader.fake.ts.tpl

@@ -2,7 +2,7 @@ import type { {{name.pascal}}Item } from '{{alias.context}}/application/queries/
 import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}{{alias.ext}}';
 
 export class Fake{{name.pascal}}Reader extends InMemory{{name.pascal}}Reader {
-  constructor(protected override readonly items: readonly {{name.pascal}}Item[]) {
+  constructor(protected override readonly {{search.elements}}: readonly {{name.pascal}}Item[]) {
     super();
   }
 }

package/templates/query/search.reader.in-memory.ts.tpl

@@ -17,38 +17,40 @@ import type {
 @Repository({{name.pascal}}Reader)
 {{/if}}
 export class InMemory{{name.pascal}}Reader implements {{name.pascal}}Reader {
-  protected readonly items: readonly {{name.pascal}}Item[] = [];
+  protected readonly {{search.elements}}: readonly {{name.pascal}}Item[] = [];
 
   async search(scope: AccessScope, page: PageRequest<{{name.pascal}}Sort>): Promise<{{name.pascal}}Result> {
     // TODO(domain): replace these canned lines by a real read of the projection; a production adapter (SQL view, search index) implements the same port next to this file, turns the scope into a condition of its statement, and orders by the sort field then by `id` in the same direction, so that a cursor resumes on a total order.
-    const visible = this.items.filter((item) => isVisible(item, scope)).sort(inOrder(page));
+    const visible = this.{{search.elements}}.filter(isVisibleTo(scope)).sort(inOrder(page));
     const start = page.kind === 'offset' ? page.offset : positionAfter(visible, page.cursor);
-    const items = visible.slice(start, start + page.limit);
+    const {{search.elements}} = visible.slice(start, start + page.limit);
 
     if (page.kind === 'offset') {
-      return pageOf(items, { total: visible.length });
+      return pageOf({{search.elements}}, { total: visible.length });
     }
 
-    const last = items.at(-1);
+    const last = {{search.elements}}.at(-1);
 
     return pageOf(
-      items,
+      {{search.elements}},
       last !== undefined && start + page.limit < visible.length ? { nextCursor: encodeCursor({ id: last.id }) } : {},
     );
   }
 }
 
-function isVisible(item: {{name.pascal}}Item, scope: AccessScope): boolean {
-  switch (scope.kind) {
-    case 'all':
-      return true;
-    case 'none':
-      return false;
-    case 'ids':
-      return scope.ids.includes(item.id);
-    case 'filter':
-      return Object.entries(scope.filter).every(([field, value]) => Reflect.get(item, field) === value);
-  }
+function isVisibleTo(scope: AccessScope): ({{search.element}}: {{name.pascal}}Item) => boolean {
+  return ({{search.element}}) => {
+    switch (scope.kind) {
+      case 'all':
+        return true;
+      case 'none':
+        return false;
+      case 'ids':
+        return scope.ids.includes({{search.element}}.id);
+      case 'filter':
+        return Object.entries(scope.filter).every(([field, value]) => Reflect.get({{search.element}}, field) === value);
+    }
+  };
 }
 
 function inOrder(page: PageRequest<{{name.pascal}}Sort>): (left: {{name.pascal}}Item, right: {{name.pascal}}Item) => number {
@@ -68,5 +70,5 @@ function positionAfter(visible: readonly {{name.pascal}}Item[], cursor: string |
     throw new InvalidPageRequestError('The cursor of a page is the nextCursor of a previous page');
   }
 
-  return visible.findIndex((item) => item.id === id) + 1;
+  return visible.findIndex(({{search.element}}) => {{search.element}}.id === id) + 1;
 }

package/templates/query/wiring.manual.tpl

@@ -7,6 +7,6 @@ import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/
 @@registrations
 const {{name.camel}}Reader = platform.adapter(new InMemory{{name.pascal}}Reader(), { kind: 'repository', context: '{{context.kebab}}' });
 
-platform.queries.register({{name.pascal}}Query, new {{name.pascal}}Handler({{name.camel}}Reader), { context: '{{context.kebab}}' });
+platform.queries.register({{name.pascal}}Query, new {{name.pascal}}Handler({{name.camel}}Reader{{#if access.policy}}, platform.access{{/if}}), { context: '{{context.kebab}}' });
 @@authorization
 {{access.manualDeclaration}}

package/templates/query/wiring.tsyringe.tpl

@@ -1,4 +1,7 @@
 @@imports
+{{#if access.policy}}
+import { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 {{access.permissionsImport}}
 import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port{{alias.ext}}';
 import { {{name.pascal}}Handler } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.handler{{alias.ext}}';
@@ -6,4 +9,4 @@ import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{na
 import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}{{alias.ext}}';
 @@registrations
 builder.bind({{name.pascal}}Reader).toClass(InMemory{{name.pascal}}Reader).as('repository');
-builder.query({{name.pascal}}Query){{access.declaration}}.handledBy({{name.pascal}}Handler, [{{name.pascal}}Reader]);
+builder.query({{name.pascal}}Query){{access.declaration}}.handledBy({{name.pascal}}Handler, [{{name.pascal}}Reader{{#if access.policy}}, Access{{/if}}]);

package/templates/route/route.search.ts.tpl

@@ -84,7 +84,7 @@ export function {{name.camel}}Route(queries: QueryBus): Route {
       // TODO(domain): hand the criteria of the query over too, once the query schema declares them next to the page; map each line to its public fields.
       const page = await queries.execute(new {{route.input}}(actorOf(input.context.principal), input.query));
 
-      return { status: 200, body: pageResponse(page, (item) => ({ id: item.id })) };
+      return { status: 200, body: pageResponse(page, ({{search.element}}) => ({ id: {{search.element}}.id })) };
     },
   );
 }