nestjs-ddd-cli 3.2.1 → 3.3.0

package/dist/templates/controller/controller.hbs

@@ -1,7 +1,9 @@
 import {
   Body,
   Controller,
+{{#if deleteEnabled}}
   Delete,
+{{/if}}
   Get,
   HttpCode,
   HttpStatus,
@@ -15,7 +17,9 @@ import { CommandBus, QueryBus } from "@nestjs/cqrs";
 import { ApiOperation, ApiParam, ApiQuery, ApiResponse, ApiTags } from "@nestjs/swagger";
 import { Create{{entityNamePascal}}Command } from "@modules/{{moduleNameKebab}}/application/commands/create-{{entityNameKebab}}.command";
 import { Update{{entityNamePascal}}Command } from "@modules/{{moduleNameKebab}}/application/commands/update-{{entityNameKebab}}.command";
+{{#if deleteEnabled}}
 import { Delete{{entityNamePascal}}Command } from "@modules/{{moduleNameKebab}}/application/commands/delete-{{entityNameKebab}}.command";
+{{/if}}
 import { Get{{entityNamePascal}}ByIdQuery } from "@modules/{{moduleNameKebab}}/application/queries/get-{{entityNameKebab}}-by-id.query";
 import { GetAll{{entityNamePluralPascal}}Query } from "@modules/{{moduleNameKebab}}/application/queries/get-all-{{entityNamePluralKebab}}.query";
 import { Create{{entityNamePascal}}Dto } from "@modules/{{moduleNameKebab}}/application/dto/requests/create-{{entityNameKebab}}.dto";
@@ -77,6 +81,7 @@ export class {{entityNamePascal}}Controller {
     return this.commandBus.execute(command);
   }
 
+{{#if deleteEnabled}}
   @Delete(":id")
   @HttpCode(HttpStatus.NO_CONTENT)
   @ApiOperation({ summary: "Delete {{entityNameCamel}}" })
@@ -87,4 +92,5 @@ export class {{entityNamePascal}}Controller {
     const command = new Delete{{entityNamePascal}}Command(id);
     return this.commandBus.execute(command);
   }
+{{/if}}
 }

package/dist/templates/dto/create-dto.hbs

@@ -3,33 +3,44 @@ import {
   IsArray,
   IsBoolean,
   IsDate,
+  IsDecimal,
   IsDefined,
   IsEmail,
   IsIn,
   IsInt,
   IsNotEmpty,
   IsNumber,
+  IsObject,
   IsOptional,
   IsString,
   IsUUID,
   IsUrl,
+  ArrayMaxSize,
+  Matches,
+  Max,
+  MaxLength,
+  Min,
+  MinLength,
 } from "class-validator";
 import { Type } from "class-transformer";
 
 export class Create{{entityNamePascal}}Dto {
-{{#if hasFields}}
-{{#each fields}}
+{{#if hasRequestFields}}
+{{#each requestFields}}
 {{#if this.isOptional}}
-  @ApiPropertyOptional({ description: "{{this.description}}"{{#if this.example}}, example: "{{this.example}}"{{/if}} })
+  @ApiPropertyOptional({ description: "{{this.description}}"{{#if this.isMoney}}, type: String, format: "decimal"{{/if}}{{#if this.example}}, example: "{{this.example}}"{{/if}} })
 {{else}}
-  @ApiProperty({ description: "{{this.description}}"{{#if this.example}}, example: "{{this.example}}"{{/if}} })
+  @ApiProperty({ description: "{{this.description}}"{{#if this.isMoney}}, type: String, format: "decimal"{{/if}}{{#if this.example}}, example: "{{this.example}}"{{/if}} })
 {{/if}}
 {{#each this.validators}}
   {{this}}
 {{/each}}
-  {{this.snakeCase}}{{#if this.isOptional}}?{{/if}}: {{this.tsType}};
+  {{this.camelCase}}{{#if this.isOptional}}?{{/if}}: {{this.tsType}};
 
 {{/each}}
+{{else}}
+{{#if hasFields}}
+  // This aggregate has no client-writable scaffold fields.
 {{else}}
   // Add your DTO properties here in snake_case
   // Example:
@@ -39,4 +50,5 @@ export class Create{{entityNamePascal}}Dto {
   // @IsDefined()
   // name: string;
 {{/if}}
+{{/if}}
 }

package/dist/templates/dto/filter-dto.hbs

@@ -1,7 +1,7 @@
 import { ApiPropertyOptional } from "@nestjs/swagger";
 import { IsOptional, IsString, IsBoolean, IsDate, IsUUID } from "class-validator";
 import { Type } from "class-transformer";
-import { PaginationQueryDto } from "./pagination.query.dto";
+import { PaginationQueryDto } from "./pagination-query.dto";
 
 export class {{entityNamePascal}}FilterDto extends PaginationQueryDto {
   @ApiPropertyOptional({ description: "Search by ID" })

package/dist/templates/dto/response-dto.hbs

@@ -8,7 +8,7 @@ export class {{entityNamePascal}}ResponseDto {
 
 {{#if hasFields}}
 {{#each fields}}
-  @ApiProperty({ description: "{{this.description}}"{{#if this.example}}, example: "{{this.example}}"{{/if}} })
+  @ApiProperty({ description: "{{this.description}}"{{#if this.isMoney}}, type: String, format: "decimal"{{/if}}{{#if this.example}}, example: "{{this.example}}"{{/if}} })
   @Expose()
   {{this.camelCase}}: {{this.tsType}};
 

package/dist/templates/entity/entity.hbs

@@ -3,7 +3,9 @@ export interface {{entityNamePascal}}EntityProps {
   isActive?: boolean;
   createdAt?: Date;
   updatedAt?: Date;
+{{#if softDelete}}
   deletedAt?: Date;
+{{/if}}
 {{#if hasFields}}
 {{#each fields}}
   {{this.camelCase}}{{#if this.isOptional}}?{{/if}}: {{this.tsType}};
@@ -19,7 +21,9 @@ export class {{entityNamePascal}}Entity {
   public readonly isActive?: boolean;
   public readonly createdAt?: Date;
   public readonly updatedAt?: Date;
+{{#if softDelete}}
   public readonly deletedAt?: Date;
+{{/if}}
 {{#if hasFields}}
 {{#each fields}}
   public readonly {{this.camelCase}}{{#if this.isOptional}}?{{/if}}: {{this.tsType}};

package/dist/templates/mapper/mapper.hbs

@@ -1,5 +1,5 @@
 import { Injectable } from "@nestjs/common";
-import { {{entityNamePascal}}Entity } from "@modules/{{moduleNameKebab}}/domain/entities/{{entityNameKebab}}.entity";
+import { {{entityNamePascal}}Entity } from "@modules/{{moduleNameKebab}}/application/domain/entities/{{entityNameKebab}}.entity";
 import { {{entityNamePascal}}OrmEntity } from "@modules/{{moduleNameKebab}}/infrastructure/orm-entities/{{entityNameKebab}}.orm-entity";
 import { {{entityNamePascal}}ResponseDto } from "@modules/{{moduleNameKebab}}/application/dto/responses/{{entityNameKebab}}.response.dto";
 
@@ -15,7 +15,9 @@ export class {{entityNamePascal}}Mapper {
       isActive: ormEntity.isActive,
       createdAt: ormEntity.createdAt,
       updatedAt: ormEntity.updatedAt,
-      deletedAt: ormEntity.deletedAt,
+{{#if softDelete}}
+      deletedAt: ormEntity.deletedAt ?? undefined,
+{{/if}}
       // Map additional fields from ORM entity (snake_case) to domain entity (camelCase)
       {{#each fields}}
       {{this.camelCase}}: ormEntity.{{this.snakeCase}},
@@ -33,7 +35,9 @@ export class {{entityNamePascal}}Mapper {
       isActive: domainEntity.isActive,
       createdAt: domainEntity.createdAt,
       updatedAt: domainEntity.updatedAt,
+{{#if softDelete}}
       deletedAt: domainEntity.deletedAt,
+{{/if}}
       // Map additional fields from domain entity (camelCase) to ORM entity (snake_case)
       {{#each fields}}
       {{this.snakeCase}}: domainEntity.{{this.camelCase}},

package/dist/templates/orm-entity/orm-entity.hbs

@@ -1,7 +1,9 @@
 import {
   Column,
   CreateDateColumn,
+{{#if softDelete}}
   DeleteDateColumn,
+{{/if}}
   Entity,
   PrimaryGeneratedColumn,
   UpdateDateColumn,
@@ -49,8 +51,12 @@ export class {{entityNamePascal}}OrmEntity {
   {{this.camelCase}}: {{this.relationTarget}}OrmEntity[];
 
 {{/if}}
+{{else}}
+{{#if this.isMoney}}
+  @Column({ type: "decimal"{{#if this.isUnique}}, unique: true{{/if}}{{#if this.isOptional}}, nullable: true{{/if}} })
 {{else}}
   @Column({{#if this.isUnique}}{ unique: true{{#if this.isOptional}}, nullable: true{{/if}} }{{else}}{{#if this.isOptional}}{ nullable: true }{{/if}}{{/if}})
+{{/if}}
   {{this.snakeCase}}{{#if this.isOptional}}?{{/if}}: {{this.tsType}};
 
 {{/if}}
@@ -70,6 +76,8 @@ export class {{entityNamePascal}}OrmEntity {
   @UpdateDateColumn({ name: "updated_at" })
   updatedAt: Date;
 
+{{#if softDelete}}
   @DeleteDateColumn({ name: "deleted_at" })
-  deletedAt?: Date;
+  deletedAt?: Date | null;
+{{/if}}
 }

package/dist/templates/prisma/prisma-mapper.hbs

@@ -11,10 +11,16 @@ export class {{entityNamePascal}}Mapper {
       isActive: prismaEntity.is_active,
       createdAt: prismaEntity.created_at,
       updatedAt: prismaEntity.updated_at,
+{{#if softDelete}}
       deletedAt: prismaEntity.deleted_at ?? undefined,
+{{/if}}
 {{#if hasFields}}
 {{#each fields}}
+{{#if this.isMoney}}
+      {{this.camelCase}}: prismaEntity.{{this.snakeCase}}{{#if this.isOptional}}?{{/if}}.toString(),
+{{else}}
       {{this.camelCase}}: prismaEntity.{{this.snakeCase}},
+{{/if}}
 {{/each}}
 {{else}}
       // Map your Prisma fields to domain entity

package/dist/templates/prisma/prisma-repository.hbs

@@ -4,11 +4,23 @@ import { {{entityNamePascal}}Entity } from "@modules/{{moduleNameKebab}}/applica
 import { {{entityNamePascal}}Mapper } from "@modules/{{moduleNameKebab}}/infrastructure/mappers/{{entityNameKebab}}.mapper";
 import { Prisma } from "@prisma/client";
 
-export interface PaginationOptions {
+const {{entityNameCamel}}OrderFields = [
+  "id",
+{{#each fields}}
+  "{{this.snakeCase}}",
+{{/each}}
+  "is_active",
+  "created_at",
+  "updated_at",
+] as const satisfies readonly (keyof Prisma.{{entityNamePascal}}OrderByWithRelationInput)[];
+
+export type {{entityNamePascal}}OrderField = (typeof {{entityNameCamel}}OrderFields)[number];
+
+export interface {{entityNamePascal}}PaginationOptions {
   skip: number;
   take: number;
-  orderBy: string;
-  orderDirection: "asc" | "desc";
+  orderBy: {{entityNamePascal}}OrderField;
+  orderDirection: "ASC" | "DESC";
 }
 
 @Injectable()
@@ -18,6 +30,10 @@ export class {{entityNamePascal}}Repository {
     private readonly mapper: {{entityNamePascal}}Mapper,
   ) {}
 
+  static isOrderByField(value: string): value is {{entityNamePascal}}OrderField {
+    return {{entityNameCamel}}OrderFields.some((field) => field === value);
+  }
+
   async create(entity: {{entityNamePascal}}Entity): Promise<{{entityNamePascal}}Entity> {
     const data = this.mapper.toPrismaCreate(entity);
     const created = await this.prisma.{{entityNameCamel}}.create({ data });
@@ -26,7 +42,11 @@ export class {{entityNamePascal}}Repository {
 
   async findById(id: string): Promise<{{entityNamePascal}}Entity | null> {
     const record = await this.prisma.{{entityNameCamel}}.findFirst({
+{{#if softDelete}}
       where: { id, deleted_at: null },
+{{else}}
+      where: { id },
+{{/if}}
     });
 
     if (!record) {
@@ -37,28 +57,41 @@ export class {{entityNamePascal}}Repository {
   }
 
   async findAll(): Promise<{{entityNamePascal}}Entity[]> {
+{{#if softDelete}}
     const records = await this.prisma.{{entityNameCamel}}.findMany({
       where: { deleted_at: null },
     });
+{{else}}
+    const records = await this.prisma.{{entityNameCamel}}.findMany();
+{{/if}}
 
     return records.map((record) => this.mapper.toDomainEntity(record));
   }
 
   async findAllPaginated(
-    options: PaginationOptions,
+    options: {{entityNamePascal}}PaginationOptions,
   ): Promise<[{{entityNamePascal}}Entity[], number]> {
     const { skip, take, orderBy, orderDirection } = options;
+    const order: Prisma.{{entityNamePascal}}OrderByWithRelationInput = {
+      [orderBy]: orderDirection.toLowerCase() as Prisma.SortOrder,
+    };
 
     const [records, total] = await Promise.all([
       this.prisma.{{entityNameCamel}}.findMany({
+{{#if softDelete}}
         where: { deleted_at: null },
+{{/if}}
         skip,
         take,
-        orderBy: { [orderBy]: orderDirection },
+        orderBy: order,
       }),
+{{#if softDelete}}
       this.prisma.{{entityNameCamel}}.count({
         where: { deleted_at: null },
       }),
+{{else}}
+      this.prisma.{{entityNameCamel}}.count(),
+{{/if}}
     ]);
 
     const entities = records.map((record) => this.mapper.toDomainEntity(record));
@@ -74,7 +107,9 @@ export class {{entityNamePascal}}Repository {
     return this.mapper.toDomainEntity(updated);
   }
 
+{{#if deleteEnabled}}
   async delete(id: string): Promise<void> {
+{{#if softDelete}}
     await this.prisma.{{entityNameCamel}}.update({
       where: { id },
       data: {
@@ -82,17 +117,30 @@ export class {{entityNamePascal}}Repository {
         is_active: false,
       },
     });
+{{else}}
+    await this.prisma.{{entityNameCamel}}.delete({
+      where: { id },
+    });
+{{/if}}
   }
 
+{{#if hardDelete}}
   async hardDelete(id: string): Promise<void> {
     await this.prisma.{{entityNameCamel}}.delete({
       where: { id },
     });
   }
 
+{{/if}}
+
+{{/if}}
   async exists(id: string): Promise<boolean> {
     const count = await this.prisma.{{entityNameCamel}}.count({
+{{#if softDelete}}
       where: { id, deleted_at: null },
+{{else}}
+      where: { id },
+{{/if}}
     });
     return count > 0;
   }
@@ -102,7 +150,11 @@ export class {{entityNamePascal}}Repository {
     value: Prisma.{{entityNamePascal}}WhereInput[K],
   ): Promise<{{entityNamePascal}}Entity | null> {
     const record = await this.prisma.{{entityNameCamel}}.findFirst({
+{{#if softDelete}}
       where: { [field]: value, deleted_at: null },
+{{else}}
+      where: { [field]: value },
+{{/if}}
     });
 
     if (!record) {

package/dist/templates/prisma/prisma-schema.hbs

@@ -14,7 +14,9 @@ model {{entityNamePascal}} {
   is_active  Boolean  @default(true)
   created_at DateTime @default(now())
   updated_at DateTime @updatedAt
+{{#if softDelete}}
   deleted_at DateTime?
+{{/if}}
 
   @@map("{{tableName}}")
 }

package/dist/templates/query/get-all.query.hbs

@@ -22,14 +22,22 @@ export class GetAll{{entityNamePluralPascal}}Handler
     query: GetAll{{entityNamePluralPascal}}Query,
   ): Promise<PaginatedResponseDto<{{entityNamePascal}}ResponseDto>> {
     const { pagination } = query;
-    const { page = 1, limit = 10, sortBy = "createdAt", sortOrder = "DESC" } = pagination;
+    const {
+      page = 1,
+      limit = 10,
+      sortBy = {{#if isPrisma}}"created_at"{{else}}"createdAt"{{/if}},
+      sortOrder = "DESC",
+    } = pagination;
 
     const skip = (page - 1) * limit;
+    const orderBy = {{entityNamePascal}}Repository.isOrderByField(sortBy)
+      ? sortBy
+      : {{#if isPrisma}}"created_at"{{else}}"createdAt"{{/if}};
 
     const [entities, total] = await this.repository.findAllPaginated({
       skip,
       take: limit,
-      orderBy: sortBy,
+      orderBy,
       orderDirection: sortOrder,
     });
 

package/dist/templates/recipes/bounded-json-http/README.md.hbs

@@ -0,0 +1,36 @@
+# Bounded JSON HTTP transport
+
+```sh
+ddd recipe bounded-json-http --path <application> --dry-run
+ddd recipe bounded-json-http --path <application>
+```
+
+This emits only the reusable transport and this handoff. It requires the native
+Fetch, Headers, Web Streams and TextEncoder APIs supplied by Node 18+ or Bun. It
+does not emit a Nest module, install packages, register routes, validate a human
+identity or grant domain permissions. Import the client directly from
+`src/shared/auth/oauth2-token-introspection/bounded-json-http.client.ts`.
+
+The output path and unchanged template are shared with the OAuth recipes. A
+matching existing file is preserved; a conflicting file, symlink or unsafe
+destination rejects the complete plan before writes. Dry-run performs the same
+preflight without creating files or directories. If later filesystem operations
+fail, rollback preserves a concurrent owner's successor content and reports a
+rollback conflict.
+
+Supply a fixed, validated origin from deployment configuration. HTTPS is the
+default; `trustedInternalHttp: true` is an explicit operator-owned exception for
+a proven private HTTP service. Dynamic path segments are encoded individually.
+Do not accept origins, authorization headers or arbitrary paths from callers.
+Constructor headers are snapshotted and private. Request policies use bounded
+deadlines and byte limits, refuse redirects and do not retry or positively cache
+responses. Errors expose a safe category/status, never credentials or bodies.
+
+`get`, `postForm`, `postJson`, `putJson` and `patchJson` return immutable JSON evidence. The
+consumer must validate its exact schema and distinguish an authoritative denial
+from an unavailable or malformed provider. A successful transport response does
+not admit an account, link identities, complete a callback or authorize a write.
+Provider-specific token and membership policy belongs to the owning application.
+Use the owning application's tests to prove those decisions and verify this
+mechanism under its supported runtime. Next.js consumers should add their own
+`server-only` wrapper; the framework-neutral generated file has no Next import.

package/dist/templates/recipes/external-projection-worker/README.md.hbs

@@ -0,0 +1,157 @@
+# External projection worker
+
+Generated by `ddd recipe external-projection-worker`. This is generic
+PostgreSQL/TypeORM infrastructure for committing an external-system projection
+intent with domain state, then reconciling it outside the request transaction.
+It does not define provider calls, business roles, authorization, Kafka policy,
+or a source-of-truth aggregate.
+
+## Generate and integrate
+
+Use a reviewed, explicit migration timestamp so every checkout emits the same
+migration identity:
+
+```bash
+ddd recipe external-projection-worker \
+  --migration-timestamp 1790000000000 \
+  --dry-run
+ddd recipe external-projection-worker \
+  --migration-timestamp 1790000000000 \
+  --install-deps
+```
+
+The recipe supports only `.dddrc.json` configurations with `orm: "typeorm"`
+and `database: "postgres"`. It honors `paths.shared` and `paths.migrations`,
+preflights every output before writing, refuses symlink traversal, and will not
+create a second migration under a different timestamp. An identical rerun is a
+no-op; an adapted target is left untouched and reported as a conflict. Recipe
+generation is locked per project, and dependency installation begins only after
+the timestamp, schema, symlink, migration, and target conflict checks pass.
+
+1. Review and register the generated migration in the service's existing
+   migration runner before enabling the worker.
+2. Generate the application adapter with `ddd generate service`. Implement
+   `ExternalProjectionHandler`, export it from its owning module, and import that
+   module through `ExternalProjectionWorkerModule.register(...)`. Do not
+   redeclare the handler in the worker module. The imported composition must
+   also expose TypeORM's default `DataSource` provider to the worker module.
+3. Enable Nest shutdown hooks. Supply bounded settings from validated service
+   configuration. Keep `enabled: false` until the migration is applied.
+4. Export `ExternalProjectionWorkerModule` only from the composition root that
+   owns this worker. Run one logical projection name per handler contract.
+
+```ts
+ExternalProjectionWorkerModule.register(
+  {
+    projectionName: 'directory-v1',
+    enabled: true,
+    pollIntervalMs: 1_000,
+    batchSize: 25,
+    leaseSeconds: 30,
+    maxAttempts: 8,
+    retryBaseMs: 1_000,
+    retryMaxMs: 300_000,
+  },
+  DirectoryProjectionHandler,
+  [DirectoryProjectionHandlerModule],
+);
+```
+
+## Atomic enqueue is mandatory
+
+`enqueue` intentionally accepts an `EntityManager`, not a `DataSource`, and
+rejects a manager without an active transaction-bound `QueryRunner`. Call it
+inside the same transaction that commits the owning domain change:
+
+```ts
+await dataSource.transaction(async (manager) => {
+  await writeOwnedDomainState(manager, command);
+  await projectionEnqueuer.enqueue(manager, {
+    projectionName: 'directory-v1',
+    targetKey: command.subjectId,
+    operationKind: 'upsert',
+    idempotencyKey: command.commandId,
+    payload: command.publicProjection,
+  });
+});
+```
+
+The payload accepts only bounded plain JSON. Keys are sorted recursively before
+hashing. Repeating a projection/idempotency key with the same projection name,
+target, operation and payload returns the stored operation; reusing it for
+different content fails closed. Never place credentials, tokens, clinical
+documents, or other secrets in projection payloads or error codes.
+
+Enqueue takes an exact `(projection_name, target_key)` row lock through the
+durable target-head table before allocating `enqueue_sequence`. This prevents a
+later transaction from committing a visible same-target operation while an
+earlier enqueue is still uncommitted. If one owning transaction enqueues several
+targets, call `enqueue` in stable projection-name/target-key order so independent
+transactions cannot create a lock-order cycle. Direct inserts bypass this
+contract and are unsupported.
+
+Canonical application JSON remains limited to 256 KiB and 10,000 nodes. The
+database allows up to 4 MiB for `jsonb::text` because PostgreSQL expands valid
+JavaScript exponent notation (for example `1e+308`) when rendering `jsonb`.
+The larger database envelope is representation headroom, not a larger public
+payload limit.
+
+## Lifecycle and external effects
+
+- `pending`: committed intent awaiting a worker.
+- `processing`: one live lease owns the attempt. Claims use `FOR UPDATE SKIP
+LOCKED`; renewal and completion require the current owner, token and an
+  unexpired lease.
+- `retry_wait`: a known retryable failure, with a bounded next-attempt time.
+- `uncertain`: the external result is unknown. On the next attempt, the handler
+  must read back using stable provider identifiers before repeating a write.
+- `blocked`: terminal operator action is required.
+- `applied`: reconciliation completed and may retain a non-secret provider
+  reference.
+
+Each worker is bound to exactly one configured `projectionName`; it cannot
+claim another handler's rows. Transactional target-head locking serializes
+sequence allocation, then claims enforce `(projection_name, target_key)`
+`enqueue_sequence` order: a later operation cannot overtake any earlier
+operation that has not reached `applied`. A `blocked` operation deliberately
+remains an ordering barrier until an owning operator resolves it.
+Attempts exhausted by repeated lease expiry are changed to `blocked` before
+another handler call.
+
+The handler has separate entry points. `execute` receives only fresh or known
+retryable work. `reconcile` receives `uncertain_recovery` and
+`expired_lease_recovery` claims, including their prior status and prior error
+when one exists. Reconciliation must read the external system with stable
+identifiers before deciding whether any write is still required. The worker
+never routes recovery claims through `execute`; a retryable reconciliation
+failure remains `uncertain` so the following attempt also enters `reconcile`.
+An unclassified handler exception is also `uncertain`, because it may have been
+raised after the external system accepted a write. The same rule applies when
+the handler returns but the final lease-renewal call throws: the operation must
+be read back through `reconcile` and must never be dispatched to `execute`
+again.
+
+This is at-least-once orchestration, not exactly-once external delivery. The
+handler must pass the durable operation id or another stable idempotency key to
+the external provider when supported. A lost lease fences database completion;
+it cannot undo an external side effect. Do not convert an unknown timeout into
+success, and do not blindly repeat non-idempotent writes.
+
+The worker runs one batch at a time per process, renews leases during handler
+execution, stops scheduling before shutdown, and waits for the active batch.
+Multiple replicas may run because claims use row locks and `SKIP LOCKED`.
+An optional result reference is trimmed and must be a non-empty, control-free
+string of at most 500 characters.
+
+## Acceptance before enablement
+
+Prove against disposable PostgreSQL: migration up/down, same-key replay,
+changed-payload conflict, an uncommitted-earlier/concurrent-later same-target
+enqueue schedule, expanded exponent-number payloads, concurrent distinct claims,
+expired-lease reclaim, same-target ordering, cross-projection routing, handler
+and final-renewal uncertainty recovery, stale-owner completion rejection,
+renewal, every disposition, crash-driven max-attempt blocking, and graceful
+shutdown. Also prove the concrete provider adapter's
+create/update/delete/readback behavior and its own target-ordering requirements.
+Alert on old `pending`, `retry_wait`, `uncertain`, `blocked`, expired
+`processing`, attempt count, and worker poll failures.