persistence · git:20261031.8ab7ca4 · 2026-10-31 · sha256 9344336e1c4f99cf

persistence git:20261031.8ab7ca4A

Immutable. This exact content never changes and is served at /api/v1/blob/9344336e1c4f99cf.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_hebmjzacvm5tkd5o/9344336e1c4f99cf979763da7274bc7e075cbe34ef25dbf3a42aa0023fdc3f85.json

Then /plugin install persistence@markdownregistry-hebmjzacvm5tkd5o in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: persistence
description: >-
  Use when adding a table, a repository, a lookup, a read model or a migration, replacing
  the in-memory adapter by a real one, choosing an ORM, or when persistence types leak out
  of infrastructure. Mapper, unit of work, optimistic concurrency, Drizzle, Knex, Prisma,
  TypeORM.
argument-hint: "<context> <Aggregate>"
allowed-tools:
  - Read
  - Edit
  - Bash(npx ddd-ts-kit generate *)
  - Bash(npx ddd-ts-kit check *)
  - Bash(npx ddd-ts-kit list *)
  - Bash(npm test *)
---

# Persistence

Subject: `$ARGUMENTS`

```bash
npx ddd-ts-kit generate repository <ctx> <Aggregate> [--tenant-scoped] [--personal <column>,... [--subject <column>] [--erasure pseudonymise|row]] --json
```

writes the port (an abstract class extending the kernel `Repository<Aggregate>` in
`domain/repositories/`), the adapter of the project's ORM with its mapper and table in
`infrastructure/persistence/`, the fake, and one `repositoryContract` spec that both must
pass. `generate command --aggregate` creates it when missing. Fill the `todos` places: the
lookups of the port, the columns, the mapper.

## Rules, whatever the technology

- **One repository per aggregate root**, whole-aggregate load and save. Add only the lookups
  a use case needs, named in the ubiquitous language; a screen reads through a read port.
- **Rows stay inside.** The mapper translates row to aggregate (`rehydrate`) and back; it is
  the one place where a type assertion is acceptable. No ORM type crosses the port.
- **Each context owns its tables**, in its own database schema and in a file of its own: the
  tables file of `infrastructure/persistence/` (Drizzle, Knex, TypeORM) or, on Prisma,
  `prisma/schema/<context>.prisma` beside the main `prisma/schema/schema.prisma` (a project still
  on the one `prisma/schema.prisma` of versions before 0.95 moves it first: `generate repository`
  refuses with the steps). A stored field changes its column and the mapper in one commit. No foreign key, join or
  query across contexts: reference by identifier, read through a published contract or a
  local projection fed by integration events (`context/extractable`).
- **Transactions belong to the application.** The unit of work is a middleware of the command
  bus; a repository picks up the ambient transaction, never receives one, never commits.
  Domain events are dispatched at its end, before the commit. A unit of work of your own
  builds `run` on `withinUnitOfWork` of the kernel and passes `unitOfWorkContract`.
- **Optimistic concurrency** on the aggregate's `version`: a conflicting save raises
  `ConcurrencyError`. A deadlock or a serialization failure anywhere in the transaction
  rejects the unit of work with `TransactionConflictError`, a `ConcurrencyError`: retry the
  command, never map the driver error by hand. A taken unique value (an email) raises
  `UniqueViolationError` (`CONFLICT`), never retried; the handler turns it into its own refusal.
- **Audit and tenant columns are standard**: `created_at`, `created_by`, `updated_at`,
  `updated_by`, and `tenant_id` with `--tenant-scoped`, stamped by the adapter from the
  `ExecutionScope` and the `Clock` through the kernel helpers. The domain does not know them.
- **Files never in a table.** No binary or base64 column (`persistence/no-file-content`): the
  content lives in the `FileStorage` port (`stack.storage`), a row keeps the key, size, media
  type and checksum of its `StoredFile`, and `FileStaging` orders the write (staged before the
  transaction, recorded, moved to its key with the commit, an orphan in `staging/` purged a day
  later). `docs/concepts/file-storage.md`.
- **Multi-tenant**: every statement on tenant data is confined to the tenant of the work
  (`tenancy/scoped-statement`). Under `stack.tenancy: shared-table` (or another strategy, or to
  become multi-tenant), read [tenancy.md](tenancy.md) first.
- **Outbox in the same transaction** as the business write (`events/outbox-required`).
- **An event-sourced aggregate** (chosen per aggregate, `generate aggregate ... --event-sourced`)
  keeps the same port: under `stack.eventSourcing: on`, read [event-sourcing.md](event-sourcing.md)
  first.
- **What a table keeps of a person is declared** (`--personal`), with its erasure, export and
  retention: under `stack.privacy: on` (the default with an ORM), read
  [personal-data.md](personal-data.md) first when a table keeps something of a person.
  `privacy/declared-field` (a warning) reports a personal column no declaration names.
- **Searches** use the kernel `Page` and `PageRequest`; a cursor ends on a unique tie-breaker.
- **Queries may skip aggregates**: `generate query` writes a read port and an in-memory
  reader; replace the reader by an adapter that queries the tables and returns the shape of
  the port.
- **Migrations** are generated from the schema, named by what they do
  (`npm run db:generate add-invoices`, which writes `<timestamp>_add-invoices`; it refuses
  to run without the name; under drizzle-kit a rename is never left for it to guess, since
  without a terminal it fails: add then drop in a later migration, or `-- <name> --custom`;
  never under `script` or another pseudo-terminal, where it waits), applied with
  `npm run db:migrate`, committed, forward-only, and compatible with the version still running.
  A table of `generate repository` reaches no database until then, on the four ORM: the specs
  pass before it, on the in-process database. `db:migrate` reads `DATABASE_URL` from the shell,
  else from `.env`. Under TypeORM it builds first, `db:generate` does not:
  `npm run build && npm run db:generate migrations/add-invoices`. Under Knex the steps are the
  same, and a migration holds its SQL and never calls `createTables`; what `db:generate` does not
  write there is in [migrations.md](migrations.md).
  Under drizzle-kit, `drizzle-generate` (what `db:generate` runs) formats the snapshot and journal it wrote with the project's formatter, and
  warns when the SQL changes a primary key in an order that fails, which
  `persistence/primary-key-order` reports until fixed: reorder it (old key dropped first) or
  write it with `--custom`. One `db:generate` writes every schema change made since the last one
  as one migration: to keep two apart (a table, then a constraint once it is filled), change the
  schema in two steps, with a `db:generate` after each. Under `agents.profile: regulated` (or any
  sandbox where a command cannot reach the database), when a merge brings a migration from the
  main branch before yours is merged, or as a worker of a parallel build, read
  [migrations.md](migrations.md) first; `persistence/migration-history` reports a forked or
  unordered history.

## By ORM

`stack.orm` decides what is generated. Each package provides the unit of work with an
ambient transaction, the outbox store and the processed-event store, and documents its
dialects: `@ddd-ts-kit/drizzle` (the default, PostgreSQL, one schema per context),
`@ddd-ts-kit/knex`, `@ddd-ts-kit/prisma`, `@ddd-ts-kit/typeorm`. With `none` or `custom` the
generated adapter is in-memory, held to the same contract suite, behind a `TODO(platform)`.

An outside system is not storage: a provider an environment runs without (a sandbox, a demo,
an environment for examiners, a provider not ready yet) is simulated by an adapter of
production code, `npx ddd-ts-kit generate adapter <ctx> <Port> --kind simulated`, never by a
repository nor by the fake of `test/fakes/`, which production code never imports. Its records
keep the shape the system sends and go through the translator of `infrastructure/anti-corruption/`.

Anything else (another query builder, a document store) is `stack.orm: custom`: provide in
`src/platform/database/` a `UnitOfWork`, an `OutboxStore` and a `ProcessedEventStore`, each
passing its contract suite of `@ddd-ts-kit/testing/contracts`, then the repository adapters.
Nothing in `domain/` or `application/` changes: that is the test of the boundary. A niche
store needs a decision record.

## Tests

The contract spec in `test/integration/` runs the fake and the adapter through the same
suite; adapter specs run on an in-process PostgreSQL unless a database URL is given. Add
what is specific to the adapter: every column mapped, the tenant filter, a rollback.

Finish with
`npx ddd-ts-kit check --rule layer/domain-purity --rule context/extractable --rule ports/implements-never-extends`
and the integration specs of the context.