@purposeinplay/payload-version-retention 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Purpose In Play
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,553 @@
+# @purposeinplay/payload-version-retention
+
+[![npm version](https://img.shields.io/npm/v/%40purposeinplay%2Fpayload-version-retention)](https://www.npmjs.com/package/@purposeinplay/payload-version-retention)
+[![license: MIT](https://img.shields.io/npm/l/%40purposeinplay%2Fpayload-version-retention)](https://github.com/purposeinplay/payload-plugins/blob/main/packages/payload-version-retention/LICENSE)
+
+Version retention plugin for Payload CMS 3 — an age-and-status janitor plus identical-snapshot dedup, so version history stops growing without a count cap evicting the last good publish.
+
+## Table of contents
+
+- [Why this exists](#why-this-exists)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Scheduling requires a consumer migration](#scheduling-requires-a-consumer-migration)
+- [Postgres consumers need a task-slug enum migration](#postgres-consumers-need-a-task-slug-enum-migration)
+- [The full migration set](#the-full-migration-set)
+- [What it keeps and what it deletes](#what-it-keeps-and-what-it-deletes)
+  - [Under `drafts.localizeStatus`, protection is per document](#under-draftslocalizestatus-protection-is-per-document)
+- [Worked example](#worked-example)
+- [Identical-snapshot dedup](#identical-snapshot-dedup)
+- [Attribution: who a surviving version belongs to](#attribution-who-a-surviving-version-belongs-to)
+- [Memory and chunk sizes](#memory-and-chunk-sizes)
+- [Relationship to `maxPerDoc`](#relationship-to-maxperdoc)
+- [Options](#options)
+- [The janitor task](#the-janitor-task)
+- [Postgres does not shrink on delete](#postgres-does-not-shrink-on-delete)
+- [Exports](#exports)
+- [License](#license)
+
+## Why this exists
+
+Payload prunes versions by **count and date only**. `enforceMaxVersions` keeps the newest `maxPerDoc` rows for a document and deletes everything older, with no idea which of them is the last good publish. A burst of saves inside one afternoon can therefore evict the only `published` row a document has — which is why lowering `maxPerDoc` was rejected in review as a way to shrink the tables.
+
+Measured on the wild production copy (2026-09-02):
+
+- version tables are **54% of a 1.9 GB database**;
+- **37%** of `_games_v` rows (6,297 of 16,917) are byte-identical to the live body;
+- **48%** are drafts;
+- **75 of 96** `pages` documents have their *entire* version history older than 30 days, and 51 sit at the 25-version cap.
+
+This plugin bounds history by **age, status and a per-document floor** instead of by count, and collapses no-op saves at write time.
+
+## Features
+
+- **Age + status janitor** as a scheduled Payload job task — daily at 03:00 on the `default` queue
+- **Protected rows** — the `latest` row, the newest `published` row and the newest `draft` row are never deleted, whatever their age
+- **Per-document floor** — a document never drops below `minVersionsPerDocument` rows (default 5)
+- **Identical-snapshot dedup** — byte-identical consecutive versions collapse, off the write path
+- **Bounded runs** — per-run deletion and document caps, with `hasMore` so the next run continues
+- **Concurrent-write guard** — a document whose protected rows move mid-pass is skipped, not guessed at
+- **Failure isolation** — a document (or an entity) whose sweep throws is logged and skipped; the rest of the run continues
+- **Startup checks** — the scheduling migration, the Postgres task-slug enums, the drained queue and an empty schedule are all reported at boot
+- **Per-collection and per-global overrides** for the window, the floor and dedup
+- Zero environment variables — configured entirely through plugin options
+
+## Requirements
+
+- **Payload** `^3.0.0` (peer dependency)
+- **Node.js** `>= 20`
+- **ESM only** — the package ships `"type": "module"`; no CommonJS build
+
+This plugin is server-side only: it adds no admin UI components, so there is no `payload generate:importmap` step and no `next`/`react` peer dependency.
+
+## Installation
+
+```sh
+pnpm add @purposeinplay/payload-version-retention
+# or
+npm install @purposeinplay/payload-version-retention
+# or
+yarn add @purposeinplay/payload-version-retention
+```
+
+## Quick start
+
+```ts
+import { buildConfig } from 'payload'
+import { versionRetentionPlugin } from '@purposeinplay/payload-version-retention'
+
+export default buildConfig({
+  // ...
+  plugins: [
+    versionRetentionPlugin({
+      days: 30,
+      minVersionsPerDocument: 5,
+    }),
+  ],
+})
+```
+
+With no options at all it sweeps **every** collection and global that has `versions` enabled, on a 30-day window with a floor of 5, and attaches the dedup hook to every versioned collection that has drafts.
+
+Register it **last** in the `plugins` array if other plugins inject versioned collections — the janitor resolves its entities from the running config at run time, but the dedup hook can only be attached to collections that already exist when this plugin runs.
+
+## Scheduling requires a consumer migration
+
+**This plugin schedules its janitor task, and that turns on Payload's job scheduling for your whole config. Adopting it without the matching database migration stalls every job on the `default` queue.**
+
+Payload flips `jobs.scheduling = true` during config sanitization as soon as any task declares a `schedule`, and injects the `payload-jobs-stats` global. From then on `handleSchedules` reads that global **on every autoRun tick, before `jobs.run`**. If the `payload_jobs_stats` table does not exist, that read throws, `jobs.run` is never reached, and the consumer's entire default queue stops draining — every minute, with nothing else in the config having changed.
+
+What you must do:
+
+1. **Ship the plugin adoption and the migration in the same release.** After installing, run `npx payload migrate:create` and `npx payload migrate`. The migration must create `payload_jobs_stats` (wild consumers additionally need the `payload_jobs.meta` column).
+2. **Keep the schedule on a queue you actually drain.** `handleSchedules` skips every queue the running autoRun config does not drain unless it is invoked with `allQueues`, so the default schedule targets `default`. If you point `janitor.schedule` at a dedicated queue, make sure something drains that queue.
+3. **A dedicated worker must pass `--handle-schedules`.** Payload's bin only calls `handleSchedules` when the flag is present:
+
+   ```sh
+   payload jobs:run --handle-schedules
+   # or, to only queue scheduled jobs:
+   payload jobs:handle-schedules
+   ```
+
+The plugin probes all of it at boot: an **error** when the `payload-jobs-stats` global cannot be read, an **error** when the task slug is missing from the Postgres jobs enums (see the next section), a **warning** when nothing in `jobs.autoRun` drains the scheduled queue, and a **warning** when `janitor.schedule` is `[]`. Pass `janitor: false` to register neither the task nor the schedule.
+
+## Postgres consumers need a task-slug enum migration
+
+**On Postgres, registering a new task is a schema change. Without the matching migration the janitor cannot be queued at all — it fails with `invalid input value for enum enum_payload_jobs_task_slug: "version-retention-janitor"`.**
+
+Payload generates `payload_jobs.task_slug` and `payload_jobs_log.task_slug` as **enum** columns whose members are the registered task slugs. Adding this plugin adds a slug, so both enum types have to learn it before anything can queue a job with it. This was hit on the wild production copy.
+
+`npx payload migrate:create` generates the statements for you; they look like this:
+
+```sql
+ALTER TYPE "enum_payload_jobs_task_slug" ADD VALUE 'version-retention-janitor';
+ALTER TYPE "enum_payload_jobs_log_task_slug" ADD VALUE 'version-retention-janitor';
+```
+
+Both are required — the first lets the job row be written, the second lets its log entry be written. Ship them in the same release as the plugin adoption, alongside the `payload_jobs_stats` migration above.
+
+> `ALTER TYPE ... ADD VALUE` cannot run inside a transaction block on PostgreSQL below 12. On 12+ it can, which is what Payload's generated migration relies on.
+
+**MongoDB and SQLite are unaffected** — both store the task slug as plain text.
+
+The plugin checks this at boot on Postgres and logs an error naming the exact `ALTER TYPE` statements when a slug is missing. It reads `pg_enum` through the adapter's own pool and never throws; an adapter it cannot inspect is left alone.
+
+## The full migration set
+
+Adopting this plugin adds **four** things a consumer's database must have. Generate them all with one `npx payload migrate:create` after installing, and ship that migration in the same release as the plugin.
+
+| What | Why | Applies to |
+|---|---|---|
+| `payload_jobs_stats` table | scheduling a task turns on `jobs.scheduling` config-wide; `handleSchedules` reads this global on every autoRun tick | all adapters |
+| `payload_jobs.meta` column | the same sanitize branch sets `jobs.stats`, and scheduled jobs are queued with `meta.scheduled = true` | all adapters |
+| `enum_payload_jobs_task_slug` + `enum_payload_jobs_log_task_slug` values | the task slug is an enum member on Postgres; without it the job cannot be queued at all | **Postgres only** |
+| `version_retention_state` table | the plugin's own global, holding the dedup cursor across runs | all adapters |
+
+That last one deserves a word. Payload's `deleteJobOnComplete` defaults to `true` and hard-deletes the job row the moment it finishes, so a cursor written into a job's output is unreadable by the time the next run starts. The plugin therefore keeps it in a global of its own: slug `version-retention-state`, one hidden JSON field, access denied to everyone, read and written with `overrideAccess`. Without its table the age sweep is unaffected, but dedup restarts its cycle at the first entity on every run and never reaches the rest of the corpus.
+
+Each of the four is probed at boot and reported by name. The state global is
+checked whenever the janitor is enabled — including with `janitor.schedule: []`,
+since a manually queued run writes the cursor too — while the other three are
+checked once a schedule exists.
+
+The state global is registered **unconditionally**, even with `enabled: false`
+or `janitor: false`. Schema must not depend on a runtime flag: gating it would
+make `migrate:create` emit a `DROP` in an environment where the plugin happens
+to be off, and `push: true` in development drop the table outright.
+
+## What it keeps and what it deletes
+
+For every document of every selected collection (and for every selected global), the janitor deletes version rows whose **`updatedAt` is older than `days`** — with four exceptions that are always kept:
+
+| Always kept | Why |
+|---|---|
+| the row flagged `latest: true` | `getLatestCollectionVersion` resolves the admin document from exactly this flag |
+| the newest row with `version._status === 'published'` | **the last good publish** — the row a count cap evicts and this plugin does not |
+| the newest row with `version._status === 'draft'` | the work in progress |
+| **the newest N rows, where N = `minVersionsPerDocument`** | the floor, default **5** — the protected rows above count toward it |
+
+Plus one hard invariant: **a document is never left with zero versions.** On an entity with versions but no drafts (no `_status` at all) and no `latest` flag, the newest row stands in as the protected one.
+
+**Snapshot rows** (`snapshot = true`, Payload's pre-publish copies —
+`_promotions_v2_v` is full of them) are never chosen as the protected publish
+or draft, and never count toward the floor: the admin hides them, so they are
+not history anyone can read. They remain deletable by age like any other row.
+
+### Dedup only visits documents the age sweep already reached
+
+The dedup pass piggybacks on the sweep's walk of the **stale-version index**,
+so it only ever looks at documents that own at least one version older than the
+retention window. A document whose entire history is inside the window — one
+created and edited this week — is not deduped until part of it ages out.
+
+This is deliberate: the alternative is a second walk over every document in
+every versioned collection on every run, to find duplicates in content nobody
+is close to pruning. The duplicates do not go anywhere, and the first run after
+they age past `days` collapses them.
+
+### Under `drafts.localizeStatus`, protection is per document
+
+When `_status` is localized, Payload stores a per-locale object
+(`{ en: 'published', de: 'draft' }`) instead of a string. A row counts as
+published when **any** locale in it is published, and as a draft when any locale
+is a draft — so the protected rows are still *one* newest published row and
+*one* newest draft row **for the whole document**, not one per locale.
+
+The consequence to be aware of: if `en` was last published five months ago and
+`de` has been published weekly since, the newest any-locale published row is a
+`de` one. The older row carrying `en`'s last publish is not separately
+protected, and the floor may not reach far enough back to keep it. If you need
+per-locale publish history preserved indefinitely, raise
+`minVersionsPerDocument` for that collection or exclude it.
+
+Status *equality* is stricter than protection: dedup only collapses two rows
+whose per-locale objects match in **every** locale, so publishing one locale
+never looks like a no-op against a draft of another.
+
+The floor is what makes the age rule safe on real data. Age alone would leave most `pages` documents with a single version after the first night, because their whole history predates the window. The floor keeps a usable tail of recent history for every document regardless of how old it is; set `minVersionsPerDocument: 0` for pure age-and-status behaviour.
+
+Rows kept to satisfy the floor are the **newest** of the deletable ones.
+
+## Worked example
+
+`pages/62` on the production copy: **25 versions, all `published`, newest 2026-06-16** — the whole history is older than a 30-day window run on 2026-09-02.
+
+| Rule | Rows kept |
+|---|---|
+| newest row is `latest` | 1 |
+| newest `published` | same row |
+| no `draft` row exists | 0 |
+| floor of 5 tops it up with the next-newest | 4 |
+| **total kept** | **5** |
+| **deleted** | **20** |
+
+Run with `minVersionsPerDocument: 0` the same document would keep 1 row and delete 24 — which is why the floor is on by default.
+
+This is the case the integration test pins down against real Postgres: 25
+versions of a localized, blocks-bearing page, one of them a genuine no-op save,
+swept down to exactly 5 — with every surviving body byte-identical to what it
+was before, and the live document row untouched.
+
+At the collection level, `_games_v` (16,924 rows) would lose **6,738 rows** on a
+30-day window with the protected rows alone. The floor holds some of those back
+and dedup removes some more; the net depends on the per-document distribution,
+so read it off a first run's `deletedCount` rather than assuming a number.
+
+## Identical-snapshot dedup
+
+Two consecutive version rows can hold byte-identical content — a save that
+changed nothing, a re-publish, an editor pressing save twice. On the production
+copy there are **51 such consecutive pairs across 33 games**, and 37% of
+`_games_v` rows are byte-identical to the live body.
+
+By default dedup runs **inside the janitor**, off the write path
+(`dedup: { mode: 'sweep' }`).
+
+For each document the sweep already visits, it reads that document's version
+bodies — in pages of 50, bounded across the whole run by
+`maxDedupBodiesPerRun` (default 2,000) — and walks them in `updatedAt` order.
+A consecutive pair collapses only when **all** of these hold:
+
+- neither row is an `autosave` row;
+- both rows carry the **same** `_status`. A publish that follows a
+  byte-identical draft keeps both rows, always — they are the same content in
+  two different states. Under `drafts.localizeStatus` the per-locale status
+  objects must match in every locale, so publishing one locale never looks like
+  a no-op against a draft of another;
+- the bodies match once the noise keys are stripped.
+
+**Noise keys**, stripped from the *top level* of the version body before
+comparing: `createdAt`, `updatedAt` (Payload backfills both from the version
+row, and the document's `updatedAt` moves on every save) and `id` (the parent
+document id, identical for both rows by construction). Nothing else.
+
+In particular, **nested ids are content**. The `id` on a block row or an array
+row identifies that row; reordering two blocks, or replacing one, changes those
+ids and is a real change. Only a save that posts the same row ids back — which
+is exactly what the admin does when an editor saves without editing — produces
+an identical pair.
+
+When a pair collapses, the **newer** row is deleted and the older one survives,
+keeping its original `createdAt` (the moment the content actually first
+appeared) and `updatedAt` (so a no-op save cannot silently reset the retention
+window). A run of three identical rows collapses to its oldest member.
+
+If the collapsed row carried `latest`, the flag is moved to the survivor
+**first** and the delete follows, so no window exists in which the document has
+no `latest` row. The move sends `versionData: { latest: true }` and nothing
+else — that is what keeps drizzle on its plain `UPDATE ... SET latest` path
+instead of the full-row rewrite, which would delete and reinsert the survivor's
+`_locales`, block and relationship rows.
+
+Turn it off with `dedup: false`, or per entity with
+`overrides: { games: { dedup: false } }`.
+
+### On-save mode is experimental and off
+
+`dedup: { mode: 'onSave' }` attaches an `afterChange` hook that does the same
+collapse at write time. **It is not the default and is not recommended.**
+
+- It runs **inside the editor's save transaction**. Catching its errors does
+  not make it non-fatal: in Postgres a failed statement aborts the surrounding
+  transaction (`25P02`), so every later statement in the save fails and the
+  editor sees a cryptic error from somewhere unrelated.
+- It reads two full version bodies on **every** save of every tracked document,
+  on the write path.
+- Any mistake in the re-flag payload rewrites the survivor row through the full
+  `upsertRow` path — delete and reinsert of its `_locales`, block and
+  relationship rows — inside that same transaction, where
+  `onConflictDoUpdate` can resurrect a row another transaction deleted.
+
+The sweep does the same work where a failure costs a log line instead of an
+editor's save.
+
+## Attribution: who a surviving version belongs to
+
+Worth knowing before you turn dedup on: **the older row is the one that
+survives**, so a version's author field points at whoever created the *first*
+occurrence of that content.
+
+The case that surprises people: the ai-translate plugin finishes a run and
+writes its version row. An editor then opens the document and saves without
+changing anything, producing a byte-identical row of their own. Sweep dedup
+deletes the editor's newer row and leaves the run's row as `latest` — so
+`version_created_by` on the surviving row reads as the translation run, not the
+editor. Nothing was lost (the bodies were identical), but the attribution is
+the run's.
+
+If per-save attribution matters more than the row count for a collection, opt
+it out with `overrides: { <slug>: { dedup: false } }`.
+
+## Memory and chunk sizes
+
+Version bodies are the whole problem with these tables, so every read is
+bounded:
+
+| Path | Bound | Why |
+|---|---|---|
+| retention decision | **0 bodies** | reads are narrowed with `select` to `id`, `latest`, `snapshot`, `updatedAt` and `version._status` |
+| dedup comparison | **50 bodies** at a time | paged, with only the previous row carried across a page boundary; capped run-wide by `maxDedupBodiesPerRun` |
+| nested-select fallback | **50 bodies** at a time | each page is reduced to the retention columns before the next is fetched |
+| deletion | **25 bodies** per call | `DELETE_CHUNK_SIZE` |
+
+Every version read is sorted `['-updatedAt', '-id']`, and the parent index walk
+`['parent', 'id']`. `updatedAt` alone is not a total order — a burst of saves
+inside one millisecond gives rows identical timestamps — and under an unstable
+sort a paged read can return the same row twice, which in the dedup walk would
+compare a row against itself and delete a unique version.
+
+That last one is the non-obvious one. Drizzle's `deleteVersions` runs a
+`findMany` with **no select** over the `IN (...)` list before deleting it, so
+every row in a chunk is materialised as a full version body first. A chunk of
+200 would peak at 200 bodies; 25 keeps the peak at 25. On the wild copy the
+largest `_games_v` body is a few hundred KB, so the bound is on the order of a
+few MB per delete call rather than tens.
+
+## Relationship to `maxPerDoc`
+
+**Leave `maxPerDoc` where it is (25 on wild).** This plugin is what bounds history; `maxPerDoc` is now a backstop, not the retention policy.
+
+`enforceMaxVersions` prunes by count and date only and has no notion of a protected row, so a burst of saves inside the window can delete the last publish — that is exactly why lowering the cap was rejected. Raising or lowering it changes only how much history exists *before* the janitor's next pass. What matters is that `maxPerDoc` stays **above** `minVersionsPerDocument`, or the count cap will trim below the floor the janitor is trying to hold.
+
+One operational note: the janitor inspects at most the newest **1,000** version rows per document in a single pass. That is far above any sane `maxPerDoc`; if a document ever exceeds it the pass logs a warning and reports `hasMore` so the next run continues.
+
+## Options
+
+All options are optional (`VersionRetentionPluginOptions`):
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `true` | Enable/disable the plugin entirely. When `false`, the plugin makes no changes other than recording its options under `config.custom.versionRetention` |
+| `days` | `number` | `30` | Retention window. Version rows whose `updatedAt` is older than this are deletable, subject to the protected rows and the floor |
+| `minVersionsPerDocument` | `number` | `5` | Floor on rows left per document (per global), whatever their age. Protected rows count toward it; rows kept to reach it are the newest deletable ones. `0` = pure age-and-status |
+| `collections` | `string[]` | all versioned collections | Collection slugs to sweep and dedup |
+| `excludeCollections` | `string[]` | `[]` | Collection slugs to skip, applied after `collections` |
+| `globals` | `string[]` | all versioned globals | Global slugs to sweep |
+| `excludeGlobals` | `string[]` | `[]` | Global slugs to skip, applied after `globals` |
+| `dedup` | `boolean \| { mode?: 'off' \| 'onSave' \| 'sweep'; maxDedupBodiesPerRun?: number }` | `{ mode: 'sweep', maxDedupBodiesPerRun: 2000 }` | Identical-snapshot dedup. `true` = `{ mode: 'sweep' }`, `false` = `{ mode: 'off' }`. **`'onSave'` is experimental** — see [Identical-snapshot dedup](#identical-snapshot-dedup) |
+| `overrides` | `Record<string, { days?: number; minVersionsPerDocument?: number; dedup?: boolean }>` | `{}` | Per-slug overrides, keyed by collection **or** global slug. Unknown slugs are ignored; `dedup` is meaningless for globals |
+| `janitor` | `VersionRetentionJanitorOptions \| false` | `{}` | Janitor configuration, or `false` to register neither the task nor the schedule (leaving only the dedup hook) |
+| `janitor.schedule` | `{ cron: string; queue: string }[]` | `[{ cron: '0 3 * * *', queue: 'default' }]` | Cron entries. `[]` registers the task without scheduling it — see [Scheduling requires a consumer migration](#scheduling-requires-a-consumer-migration) |
+| `janitor.maxDeletionsPerRun` | `number` | `5000` | Ceiling on version rows deleted per invocation, across every collection and global. Dedup deletions count against it too |
+| `janitor.runLockTtl` | `number` | `21600000` (6 h) | How old a `processing` janitor job may be before its lock is ignored as debris from a crashed run. Payload never clears the flag itself |
+| `janitor.maxDocumentsPerRun` | `number` | `20000` | Ceiling on documents that **give up rows** per invocation. A document whose stale rows are all protected or floor-kept does not draw on it, so it cannot burn the budget every night |
+
+Example:
+
+```ts
+versionRetentionPlugin({
+  days: 30,
+  minVersionsPerDocument: 5,
+  excludeCollections: ['audit-logs'],
+  overrides: {
+    games: { days: 14 },
+    'site-nav': { days: 365, minVersionsPerDocument: 10 },
+    pages: { dedup: false },
+  },
+  dedup: { maxDedupBodiesPerRun: 5_000 },
+  janitor: { maxDeletionsPerRun: 20_000 },
+})
+```
+
+### `maxDedupBodiesPerRun` and `maxDeletionsPerRun` are related
+
+A collapse is atomic: every duplicate in a run goes, or none of it does, because
+the `latest` flag has to land on a row that survives. So dedup can read a
+document, find duplicates, and be unable to pay for them out of the deletion
+budget.
+
+When that happens the pass **steps past** the document with a warning rather
+than resuming on it — resuming would be a livelock that reads the same bodies
+every run and never deletes a row. The document gets another chance on the next
+cycle. If you see that warning regularly, either raise `maxDeletionsPerRun` or
+bring `maxDedupBodiesPerRun` down toward it; the defaults (2,000 bodies against
+5,000 deletions) leave plenty of headroom.
+
+## The janitor task
+
+Registered in `jobs.tasks` as **`version-retention-janitor`**, `retries: 3`, scheduled daily at 03:00 on the `default` queue.
+
+**Globals are swept first.** There are a handful of them and they are cheap;
+letting a large collection's backlog eat the run budget would otherwise starve
+them night after night.
+
+It resolves its collections and globals from the **running** config, so a
+versioned collection injected by a plugin registered after this one is still
+swept.
+
+Rather than walking every document, each collection's pass walks the
+stale-version index and visits only the parents that still hold deletable
+history, paging by an ascending `parent` cursor — not an offset, so deleting
+rows mid-pass cannot make it skip a document.
+
+**Concurrent-write guard.** Payload's `updateLatestVersion` rewrites the latest
+row in place on unpublish and on autosave, so a plan built from a stale read
+could delete the runner-up published row and leave the document with none.
+Before deleting anything for a document, the pass re-reads it and compares the
+protected ids and the `latest` id against what it planned from. If anything
+moved, the document is skipped for this run and counted in `skippedRaced`.
+
+Deletion order is **oldest first**, so a plan cut short by the deletion budget
+still removes the oldest rows rather than eating into recent history. The
+age-sweep delete also carries `latest: { not_equals: true }` — belt and braces
+for the window between the verification read and the delete: whatever else goes
+wrong, the row the admin resolves the document from stays. Deletes are issued
+as `deleteVersions({ where: { id: { in: [...] } } })` in chunks of 25
+(see [Memory and chunk sizes](#memory-and-chunk-sizes)), deliberately
+**without** a `req`, so a first-run backlog does not sit inside one hours-long
+transaction.
+
+Output:
+
+```ts
+{
+  dedupCursor: Record<string, number | string>  // per-slug dedup resume point
+  dedupedCount: number
+  deletedCount: number       // dedup included
+  failedDocuments: number
+  hasMore: boolean
+  scannedDocuments: number
+  skippedRaced: number
+}
+```
+
+`hasMore: true` means **deletable work is known to remain**, and nothing
+weaker. It is true only when:
+
+- a deletion or document budget ran out **in a run that deleted rows** — the
+  cap ended the pass, not the corpus;
+- the dedup body budget ran out **with documents still unread**;
+- a document was skipped as raced, or its sweep failed.
+
+A stale version row on its own is not work: on a settled corpus most stale rows
+are the protected ones or held by the floor, and every run meets them again. An
+earlier version treated "a stale row exists" as evidence, which made the signal
+permanently true at steady state — 2,115 documents scanned, nothing deleted,
+`hasMore: true`, run after run. A run that finds nothing deletable now says so:
+`hasMore: false`, and the log line reads *nothing to do*.
+
+The **age sweep** keeps no cursor: each run starts from the beginning of the
+stale index, which is correct because the rows it deleted last time are gone.
+
+**Dedup does**, because a document it has already cleaned still costs a body
+read to prove it is clean. The cursor is **one position over the whole run
+order** — `{ slug, parentId }` — not one per entity:
+
+```ts
+{ dedupCursor: { parentId: 21, slug: 'categories' } }
+```
+
+A run resumes at that entity, after that document, and carries on into every
+entity behind it; entities *ahead* of it were covered earlier in the cycle and
+are skipped for dedup (they are still age-swept). When a run reaches the end
+without running short, the cursor clears and the next run starts the cycle
+again. Every entity is therefore deduped within
+`ceil(total bodies / maxDedupBodiesPerRun)` runs.
+
+A per-entity cursor is what does **not** work, and this was measured: with one
+cursor per slug, the entities ahead of the stalled one carried none, so every
+run re-read them from scratch and spent the entire body budget before reaching
+the stall. On the production copy dedup collapsed pairs only in the four
+collections ahead of `categories` and never once reached `pages` or `games`,
+run after run, with `dedupCursor` frozen at `{ categories: 21 }`.
+
+The cursor is stored in the plugin's own `version-retention-state` global, and
+that is not incidental: Payload's `deleteJobOnComplete` defaults to `true`, so a
+cursor kept in a job's output is deleted with the job before the next run can
+read it — which made an earlier version of this rotation inert under the default
+configuration, however carefully the cursor was computed.
+
+Resolution order at the start of every run: an explicit `input.dedupCursor`,
+then the state global, then (legacy, for consumers who turned job deletion off)
+the last completed janitor job's output. Scheduled and manual runs behave
+identically. If none is available the run starts the cycle from the beginning
+and says so in a warning; a cursor naming a slug that is no longer configured
+also restarts it.
+
+**Failure isolation.** A document whose sweep throws is logged with its id,
+counted in `failedDocuments` and skipped; the rest of the entity, and the
+entities queued behind it, still run. An entity that fails outright is logged
+and skipped the same way. Both set `hasMore`.
+
+**One at a time.** A run that finds another janitor job already `processing`
+logs a line and declines to start, rather than splitting the run budget with it
+and racing it for the cursor — which is easy to reach by queueing one by hand
+while the schedule fires.
+
+The lock is time-bounded, and that matters: Payload sets `processing` when a
+job starts and never clears it if the process dies, so an unbounded lock would
+turn one OOM into a janitor that never runs again. A `processing` row older
+than `janitor.runLockTtl` (default 6 hours) is ignored as crash debris, with a
+warning naming how many were skipped.
+
+One `info` line is logged per entity that had anything to scan, plus one
+closing summary.
+
+## Postgres does not shrink on delete
+
+Deleting rows marks them dead; it does not return space to the operating system. After the first large pass the tables will still be the same size on disk, with the freed space reusable by future inserts.
+
+To actually reclaim it you need `VACUUM FULL` (which takes an `ACCESS EXCLUSIVE` lock and rewrites the table) or `pg_repack` (which does not). Autovacuum will keep the bloat from growing but will not give the space back. Plan that as a separate, scheduled maintenance step after the backlog has drained — not as part of adopting this plugin.
+
+## Exports
+
+The package ships a single entry point:
+
+```ts
+import { versionRetentionPlugin } from '@purposeinplay/payload-version-retention'
+import type {
+  VersionRetentionJanitorOptions,
+  VersionRetentionJanitorOutput,
+  VersionRetentionPluginOptions,
+} from '@purposeinplay/payload-version-retention'
+```
+
+There is no `./client` or other subpath — the plugin has no admin UI components and no client/server split. No environment variables are read.
+
+## License
+
+[MIT](./LICENSE)
+
+Part of the [purposeinplay/payload-plugins](https://github.com/purposeinplay/payload-plugins) monorepo. Issues and contributions: [GitHub issues](https://github.com/purposeinplay/payload-plugins/issues).

package/dist/defaults.d.ts

@@ -0,0 +1,93 @@
+/** Default retention window in days for version rows. */
+export declare const DEFAULT_RETENTION_DAYS = 30;
+/**
+ * Floor on version rows left behind per document, whatever their age.
+ *
+ * Measured on the wild copy: 75 of 96 `pages` documents have their entire
+ * version history older than 30 days and 51 sit at the 25-version cap. Age
+ * plus the protected rows alone would leave most of them with a single
+ * version after one night, so a floor keeps a usable tail of recent history.
+ */
+export declare const DEFAULT_MIN_VERSIONS_PER_DOCUMENT = 5;
+/** Default cron schedule for the janitor task: daily at 03:00. */
+export declare const DEFAULT_JANITOR_CRON = "0 3 * * *";
+/**
+ * Queue the janitor is scheduled onto. `handleSchedules` skips queues the
+ * running autoRun config does not drain, so this must be a queue the consumer
+ * actually drains — `default` is the one every consumer has.
+ */
+export declare const DEFAULT_JANITOR_QUEUE = "default";
+/**
+ * How long a `processing` janitor job is believed before the lock it holds is
+ * treated as debris.
+ *
+ * Payload never resets `processing` after a crash — nothing in its queue code
+ * sweeps abandoned jobs — so an OOM mid-run would otherwise wedge every future
+ * run behind one warning, for good.
+ */
+export declare const DEFAULT_RUN_LOCK_TTL_MS: number;
+/** Retries so one transient error does not skip the day's retention pass. */
+export declare const DEFAULT_JANITOR_RETRIES = 3;
+/** Slug of the janitor task, as registered in `jobs.tasks`. */
+export declare const JANITOR_TASK_SLUG = "version-retention-janitor";
+/**
+ * Slug of the tiny global this plugin owns to persist its dedup cursor across
+ * runs. Its table is `version_retention_state`.
+ *
+ * A store of our own is not a nicety: Payload's `deleteJobOnComplete` defaults
+ * to `true` and hard-deletes the job row the moment it finishes, so a cursor
+ * kept only in a job's output is gone before the next run can read it.
+ */
+export declare const STATE_GLOBAL_SLUG = "version-retention-state";
+/**
+ * Slug of Payload's jobs collection. The same sanitize branch that injects the
+ * jobs-stats global adds a `meta` JSON field to this collection (`jobs.stats`),
+ * so its column is part of the very same migration.
+ */
+export declare const JOBS_COLLECTION_SLUG = "payload-jobs";
+/** Ceiling on version rows deleted per invocation, across every entity. */
+export declare const DEFAULT_MAX_DELETIONS_PER_RUN = 5000;
+/** Ceiling on documents examined per invocation, across every entity. */
+export declare const DEFAULT_MAX_DOCUMENTS_PER_RUN = 20000;
+/**
+ * Rows per page when walking the stale-version index to discover which parent
+ * documents still hold deletable history.
+ */
+export declare const PARENT_PAGE_SIZE = 500;
+/**
+ * Newest-first window of version rows inspected per document. Must exceed the
+ * collection's `maxPerDoc` (25 in the wild consumer, 100 by Payload default)
+ * or the oldest rows fall outside the window and are never reached.
+ */
+export declare const MAX_VERSIONS_PER_DOCUMENT = 1000;
+/**
+ * Ids per `deleteVersions` call.
+ *
+ * Deliberately small: drizzle's `deleteVersions` runs a `findMany` with **no
+ * select** over the chunk before deleting, so every row in the chunk is
+ * materialised as a full version body first. 25 bounds that peak at 25 bodies
+ * — see the README's "Memory" note.
+ */
+export declare const DELETE_CHUNK_SIZE = 25;
+/**
+ * Rows per page when the nested-select fallback has to read full bodies. Keeps
+ * the peak at 50 bodies instead of `MAX_VERSIONS_PER_DOCUMENT` of them; each
+ * page is reduced to the retention columns before the next is fetched.
+ */
+export declare const FULL_BODY_PAGE_SIZE = 50;
+/** Dedup runs inside the janitor sweep by default. */
+export declare const DEFAULT_DEDUP_MODE: "sweep";
+/**
+ * Ceiling on version bodies the sweep reads for dedup in one invocation.
+ * Bodies are the expensive thing in these tables, so this is a separate
+ * budget from the deletion cap.
+ */
+export declare const DEFAULT_MAX_DEDUP_BODIES_PER_RUN = 2000;
+/**
+ * Request-context key the ai-translate plugin sets while a translation run is
+ * in flight. That plugin collapses a whole run into a single version row of
+ * its own, so the dedup hook must keep its hands off those writes.
+ */
+export declare const AI_TRANSLATE_RUN_CONTEXT_KEY = "aiTranslateRunId";
+/** Log prefix shared by every message this plugin emits. */
+export declare const LOG_PREFIX = "[version-retention]";