@purposeinplay/payload-version-retention 0.1.1

package/dist/lib/sweep.js

@@ -0,0 +1,799 @@
+import { DELETE_CHUNK_SIZE, FULL_BODY_PAGE_SIZE, LOG_PREFIX, MAX_VERSIONS_PER_DOCUMENT, PARENT_PAGE_SIZE } from '../defaults.js';
+import { chunkIds, collectProtectedIds, planVersionDeletions, retentionCutoff, sameStatus, toCandidate } from './retention-plan.js';
+import { versionBodiesMatch } from './snapshot-compare.js';
+import { toParentIds, toVersionRows } from './version-row.js';
+/** `greater_than` semantics for a parent id, which may be numeric or a uuid. */ function isAfter(candidate, cursor) {
+    if (typeof candidate === 'number' && typeof cursor === 'number') {
+        return candidate > cursor;
+    }
+    return String(candidate) > String(cursor);
+}
+/**
+ * Columns the retention decision reads. Anything else on a version row is a
+ * full document body — the reason these tables are 54% of the database — and
+ * pulling it into the janitor would defeat the point.
+ *
+ * A drafts-less entity has no `_status`, so `version` is left out entirely
+ * rather than asking the adapter for a field that does not exist.
+ */ export function narrowVersionSelect(hasDrafts) {
+    const base = {
+        id: true,
+        latest: true,
+        updatedAt: true
+    };
+    // `snapshot` only exists on drafts-enabled entities of a localized config;
+    // Payload's select traversal drives from the field list, so asking for it
+    // elsewhere is ignored rather than an error.
+    return hasDrafts ? {
+        ...base,
+        snapshot: true,
+        version: {
+            _status: true
+        }
+    } : base;
+}
+function staleWhere(cutoff, cursor) {
+    const stale = {
+        updatedAt: {
+            less_than: cutoff.toISOString()
+        }
+    };
+    if (cursor === undefined) {
+        return stale;
+    }
+    return {
+        and: [
+            stale,
+            {
+                parent: {
+                    greater_than: cursor
+                }
+            }
+        ]
+    };
+}
+/**
+ * True when the adapter actually honoured the nested `version._status` select.
+ * Every adapter shipped with Payload does; a third-party one that quietly
+ * drops nested selects would otherwise make every row look status-less and
+ * strip the last-publish protection, so the caller re-reads without `select`.
+ */ function nestedSelectHonoured(rows) {
+    return rows.length === 0 || rows.some((row)=>row.version !== undefined);
+}
+/** Drops everything but `_status` from a row's body. */ function withoutBody(row) {
+    const status = row.version?._status;
+    return {
+        ...row,
+        version: status === undefined ? {} : {
+            _status: status
+        }
+    };
+}
+/**
+ * Newest first, **with `id` as the tiebreak**.
+ *
+ * `updatedAt` alone is not a total order: a burst of saves inside the same
+ * millisecond, or a backfill, gives rows identical timestamps. Postgres is
+ * then free to return them in any order per page, and an OFFSET page can hand
+ * back a row the previous page already returned — which, in the dedup walk,
+ * meant comparing a row against itself, matching trivially, and deleting a
+ * unique version. The tiebreak makes every page deterministic and disjoint.
+ */ const NEWEST_FIRST = [
+    '-updatedAt',
+    '-id'
+];
+async function findVersionPage({ entity, isGlobal, parentId, payload }, args) {
+    const shared = {
+        limit: args.limit,
+        // Skips the COUNT(*) that would otherwise run alongside every page.
+        pagination: false,
+        sort: [
+            ...NEWEST_FIRST
+        ],
+        ...args.page ? {
+            page: args.page
+        } : {},
+        ...args.select ? {
+            select: args.select
+        } : {}
+    };
+    const { docs } = isGlobal ? await payload.db.findGlobalVersions({
+        ...shared,
+        global: entity.slug
+    }) : await payload.db.findVersions({
+        ...shared,
+        collection: entity.slug,
+        where: {
+            parent: {
+                equals: parentId
+            }
+        }
+    });
+    return toVersionRows(docs);
+}
+/**
+ * Fallback for an adapter that drops the nested `version._status` select:
+ * read full rows, but a page at a time, reducing each page to the retention
+ * columns before fetching the next. Peak memory is `FULL_BODY_PAGE_SIZE`
+ * bodies rather than `MAX_VERSIONS_PER_DOCUMENT` of them.
+ */ async function readNarrowedViaFullBodies(args) {
+    const rows = [];
+    for(let page = 1; rows.length < MAX_VERSIONS_PER_DOCUMENT; page++){
+        const chunk = await findVersionPage(args, {
+            limit: FULL_BODY_PAGE_SIZE,
+            page
+        });
+        for (const row of chunk){
+            rows.push(withoutBody(row));
+        }
+        if (chunk.length < FULL_BODY_PAGE_SIZE) {
+            break;
+        }
+    }
+    return rows;
+}
+/**
+ * The newest `MAX_VERSIONS_PER_DOCUMENT` rows for one document (or one
+ * global), narrowed to the retention columns.
+ */ async function readDocumentVersions(args, useNarrowSelect) {
+    if (!useNarrowSelect) {
+        return {
+            rows: await readNarrowedViaFullBodies(args),
+            useNarrowSelect: false
+        };
+    }
+    const rows = await findVersionPage(args, {
+        limit: MAX_VERSIONS_PER_DOCUMENT,
+        select: narrowVersionSelect(args.entity.hasDrafts)
+    });
+    if (args.entity.hasDrafts && !nestedSelectHonoured(rows)) {
+        args.payload.logger.warn(`${LOG_PREFIX} ${args.entity.slug}: the adapter dropped the nested \`version._status\` ` + 'select. Falling back to paged full-body reads for the rest of this run.');
+        return {
+            rows: await readNarrowedViaFullBodies(args),
+            useNarrowSelect: false
+        };
+    }
+    return {
+        rows,
+        useNarrowSelect: true
+    };
+}
+/**
+ * Deletes the planned rows in `IN (...)`-sized chunks.
+ *
+ * Chunks are small on purpose: drizzle's `deleteVersions` runs a `findMany`
+ * with no select over the chunk before deleting it, materialising every body
+ * in the chunk.
+ *
+ * Deliberately no `req`: today the job req arrives without a transaction, so
+ * each chunk commits on its own. Passing it would enroll a whole backlog pass
+ * in one transaction the moment a caller does hand us a transactional req —
+ * hours of open transaction and an unbounded rollback segment on the first run.
+ */ async function deleteVersionRows({ guardLatest, ids, isGlobal, payload, slug }) {
+    for (const chunk of chunkIds(ids, DELETE_CHUNK_SIZE)){
+        const where = guardLatest ? {
+            and: [
+                {
+                    id: {
+                        in: chunk
+                    }
+                },
+                {
+                    latest: {
+                        not_equals: true
+                    }
+                }
+            ]
+        } : {
+            id: {
+                in: chunk
+            }
+        };
+        if (isGlobal) {
+            await payload.db.deleteVersions({
+                globalSlug: slug,
+                where
+            });
+        } else {
+            await payload.db.deleteVersions({
+                collection: slug,
+                where
+            });
+        }
+    }
+}
+/**
+ * Moves the `latest` flag onto a surviving row.
+ *
+ * `versionData` carries **only** `latest`. That matters: drizzle's
+ * `shouldUseOptimizedUpsertRow` takes the plain `UPDATE ... SET latest` path
+ * when nothing in the payload is localized, a block or an array — adding
+ * `version`, `parent` or `createdAt` would instead rewrite the whole row,
+ * deleting and reinserting its `_locales`, block and relationship rows.
+ */ async function reflagLatest(payload, entity, isGlobal, id) {
+    // Payload types `versionData.version` as required even though the whole
+    // point of the optimized path is a partial payload. Asserting here is the
+    // narrow price of NOT sending `version` — sending it is the destructive
+    // branch this function exists to avoid.
+    const latestOnly = {
+        latest: true
+    };
+    if (isGlobal) {
+        await payload.db.updateGlobalVersion({
+            global: entity.slug,
+            id,
+            // Nothing needs the row back, and reading it would pull the full body
+            // through the very path this function exists to avoid.
+            returning: false,
+            versionData: latestOnly
+        });
+        return;
+    }
+    await payload.db.updateVersion({
+        collection: entity.slug,
+        id,
+        returning: false,
+        versionData: latestOnly
+    });
+}
+/**
+ * A protected-row fingerprint, used to detect a concurrent write between the
+ * read that produced a plan and the deletes that act on it.
+ */ function protectionFingerprint(rows) {
+    const candidates = rows.map(toCandidate);
+    const latest = candidates.find((candidate)=>candidate.latest);
+    const ids = [
+        ...collectProtectedIds(candidates)
+    ].map(String).sort();
+    return `${String(latest?.id ?? 'none')}|${ids.join(',')}`;
+}
+/**
+ * Collapses consecutive byte-identical rows for one document, oldest survivor
+ * wins.
+ *
+ * Rows are compared in `updatedAt` order. A pair collapses only when both
+ * carry the same `_status` (a publish that follows an identical draft is two
+ * real states, not a duplicate) and their bodies match once `createdAt`, `id`
+ * and `updatedAt` are stripped **from the top level only** — nested ids inside
+ * blocks and array rows are content, so reordering two blocks is a real change.
+ *
+ * When the newer row of a collapsing pair is `latest`, the flag moves to the
+ * survivor **before** the delete, so no window exists with zero `latest` rows.
+ */ async function dedupDocument(payload, entity, isGlobal, parentId, budget, /** Row count from the narrow read, so "did we see them all" is exact. */ totalRows) {
+    const readArgs = {
+        entity,
+        isGlobal,
+        parentId,
+        payload
+    };
+    const doomed = [];
+    // The row the `latest` flag currently sits on. It moves to the survivor
+    // every time the row carrying it is collapsed away, so a run of identical
+    // rows costs exactly one `updateVersion` at the end.
+    let latestId;
+    let originalLatestId;
+    // Read in pages, holding only the current page plus the previous row, so
+    // peak memory is FULL_BODY_PAGE_SIZE bodies whatever the history depth.
+    // Nothing is deleted during the walk — offset paging would drift under it.
+    let carry;
+    let reachedEnd = false;
+    let bodiesRead = 0;
+    let budgetLeft = Math.min(MAX_VERSIONS_PER_DOCUMENT, budget.dedupBodiesRemaining);
+    for(let page = 1; budgetLeft >= 1; page++){
+        const limit = Math.min(FULL_BODY_PAGE_SIZE, budgetLeft);
+        const chunk = await findVersionPage(readArgs, {
+            limit,
+            page
+        });
+        if (chunk.length === 0) {
+            reachedEnd = true;
+            break;
+        }
+        budget.dedupBodiesRemaining -= chunk.length;
+        budgetLeft -= chunk.length;
+        bodiesRead += chunk.length;
+        // The narrow read already counted the rows, so a budget that ran out on
+        // the document's last row finished the job and is not unfinished work.
+        if (bodiesRead >= totalRows) {
+            reachedEnd = true;
+        }
+        const sequence = carry ? [
+            carry,
+            ...chunk
+        ] : chunk;
+        for (const row of sequence){
+            if (row.latest === true && originalLatestId === undefined) {
+                originalLatestId = row.id;
+                latestId = row.id;
+            }
+        }
+        // `sequence` is newest-first. Comparing i against i+1 and dropping i
+        // collapses a run of identical rows down to its oldest member.
+        for(let index = 0; index < sequence.length - 1; index++){
+            const newer = sequence[index];
+            const older = sequence[index + 1];
+            // A row is never its own duplicate. The sort tiebreak should make this
+            // unreachable; it stays as the last line of defence, because what it
+            // prevents is deleting a unique version.
+            if (newer && older && newer.id === older.id) {
+                continue;
+            }
+            if (!(newer && older) || newer.autosave === true || older.autosave === true) {
+                continue;
+            }
+            if (!sameStatus(newer.version, older.version)) {
+                continue;
+            }
+            if (!versionBodiesMatch(newer.version, older.version)) {
+                continue;
+            }
+            doomed.push(newer.id);
+            if (latestId === newer.id) {
+                latestId = older.id;
+            }
+        }
+        carry = sequence.at(-1);
+        if (chunk.length < limit) {
+            // A short page is the end of the document, whatever the budget says.
+            reachedEnd = true;
+            break;
+        }
+    }
+    if (doomed.length === 0) {
+        return {
+            deferred: false,
+            deletedIds: [],
+            stoppedEarly: !reachedEnd
+        };
+    }
+    // Dedup deletes rows like any other pass, so they draw on the same cap.
+    const affordable = doomed.slice(0, Math.max(0, budget.deletionsRemaining));
+    if (affordable.length < doomed.length && latestId !== originalLatestId) {
+        // The re-flag target may be one of the rows we can no longer afford to
+        // delete, so the collapse has to be all or nothing. `deferred` tells the
+        // caller to step past this document instead of resuming inside it: with
+        // `maxDedupBodiesPerRun` set above `maxDeletionsPerRun`, dedup can keep
+        // reaching documents it has no deletion budget left for, and resuming on
+        // one of those every run is a livelock that never deletes a row.
+        return {
+            deferred: true,
+            deletedIds: [],
+            stoppedEarly: false
+        };
+    }
+    const reflagged = latestId !== undefined && latestId !== originalLatestId ? latestId : undefined;
+    // Flag the survivor BEFORE deleting, so no window exists in which the
+    // document has zero rows carrying `latest`.
+    if (reflagged !== undefined) {
+        await reflagLatest(payload, entity, isGlobal, reflagged);
+    }
+    await deleteVersionRows({
+        ids: affordable,
+        isGlobal,
+        payload,
+        slug: entity.slug
+    });
+    budget.deletionsRemaining -= affordable.length;
+    return {
+        deferred: false,
+        deletedIds: affordable,
+        reflaggedId: reflagged,
+        stoppedEarly: !reachedEnd || affordable.length < doomed.length
+    };
+}
+const NOTHING = {
+    dedupDeferred: false,
+    dedupRan: false,
+    dedupStoppedEarly: false,
+    dedupedCount: 0,
+    deletedCount: 0,
+    raced: false,
+    truncatedByBudget: false,
+    truncatedByWindow: false
+};
+async function sweepDocument({ budget, cutoff, entity, isGlobal, parentId, payload, useNarrowSelect }) {
+    const readArgs = {
+        entity,
+        isGlobal,
+        parentId,
+        payload
+    };
+    const first = await readDocumentVersions(readArgs, useNarrowSelect);
+    const truncatedByWindow = first.rows.length >= MAX_VERSIONS_PER_DOCUMENT;
+    const wantsDedup = entity.dedup && first.rows.length >= 2 && budget.dedupBodiesRemaining >= 2;
+    const wantsAgeSweep = planVersionDeletions(first.rows.map(toCandidate), cutoff, entity.minVersionsPerDocument).length > 0;
+    if (!(wantsDedup || wantsAgeSweep)) {
+        return {
+            ...NOTHING,
+            truncatedByWindow,
+            useNarrowSelect: first.useNarrowSelect
+        };
+    }
+    // `updateLatestVersion` rewrites the latest row in place on unpublish and on
+    // autosave, so a plan built from a stale read can delete the runner-up
+    // published row and leave the document with none. Re-read and compare the
+    // protected set; anything different and this document waits for the next run.
+    const verify = await readDocumentVersions(readArgs, first.useNarrowSelect);
+    if (protectionFingerprint(first.rows) !== protectionFingerprint(verify.rows)) {
+        payload.logger.warn(`${LOG_PREFIX} ${entity.slug}${parentId === undefined ? '' : ` document ${String(parentId)}`}: ` + 'version rows changed mid-pass (a concurrent publish or unpublish). Skipped this run.');
+        return {
+            ...NOTHING,
+            raced: true,
+            truncatedByWindow,
+            useNarrowSelect: verify.useNarrowSelect
+        };
+    }
+    let dedupedCount = 0;
+    let dedupDeferred = false;
+    let dedupStoppedEarly = false;
+    let rows = verify.rows;
+    if (wantsDedup) {
+        const deduped = await dedupDocument(payload, entity, isGlobal, parentId, budget, first.rows.length);
+        dedupedCount = deduped.deletedIds.length;
+        dedupStoppedEarly = deduped.stoppedEarly;
+        dedupDeferred = deduped.deferred;
+        if (dedupedCount > 0) {
+            const gone = new Set(deduped.deletedIds);
+            rows = rows.filter((row)=>!gone.has(row.id)).map((row)=>deduped.reflaggedId === undefined ? row : {
+                    ...row,
+                    latest: row.id === deduped.reflaggedId
+                });
+        }
+    }
+    // Recomputed after dedup: collapsing duplicates changes which rows the floor
+    // has to hold back.
+    const planned = planVersionDeletions(rows.map(toCandidate), cutoff, entity.minVersionsPerDocument);
+    // `planned` is oldest-first, so a budget-truncated plan still deletes the
+    // oldest rows rather than eating into recent history.
+    const ids = planned.slice(0, Math.max(0, budget.deletionsRemaining));
+    const truncatedByBudget = ids.length < planned.length;
+    if (ids.length > 0) {
+        await deleteVersionRows({
+            guardLatest: true,
+            ids,
+            isGlobal,
+            payload,
+            slug: entity.slug
+        });
+        budget.deletionsRemaining -= ids.length;
+    }
+    return {
+        dedupDeferred,
+        dedupRan: wantsDedup,
+        dedupStoppedEarly,
+        dedupedCount,
+        deletedCount: ids.length + dedupedCount,
+        raced: false,
+        truncatedByBudget,
+        truncatedByWindow,
+        useNarrowSelect: verify.useNarrowSelect
+    };
+}
+function budgetSpent(budget) {
+    return budget.deletionsRemaining <= 0 || budget.documentsRemaining <= 0;
+}
+/**
+ * `hasMore` means **deletable work is known to remain** — nothing weaker.
+ *
+ * A stale version row is not work: on a settled corpus most of them are the
+ * protected rows or held back by the floor, and every run would meet them
+ * again. Reporting that as "more to do" made the signal permanently true at
+ * steady state (2,115 documents scanned, 0 deleted, `hasMore: true`, ten runs
+ * running), which is the same as no signal at all.
+ *
+ * So it is true only when a budget actually cut something short:
+ *
+ * - a deletion or document budget ran out **in a run that deleted rows** —
+ *   the cap, not the corpus, ended the pass;
+ * - the dedup body budget ran out **with documents still unread**;
+ * - a document was skipped as raced or failed, which is deferred work by
+ *   definition and cannot recur every night on a settled corpus.
+ */ function computeHasMore(args) {
+    const cappedWhileWorking = args.deletedCount > 0 && budgetSpent(args.budget);
+    return cappedWhileWorking || args.dedupStarved || args.skippedRaced > 0 || args.failedDocuments > 0;
+}
+/**
+ * Sweeps one versioned collection.
+ *
+ * Rather than walking every document, the pass walks the stale-version rows
+ * themselves and visits only the parents that still hold deletable history.
+ * Paging is by an ascending `parent` cursor, not an offset, so deleting rows
+ * mid-pass cannot make it skip a document.
+ */ export async function sweepCollection(payload, entity, budget, now = new Date(), /** Resume dedup after this parent id; see `EntitySweepResult.dedupCursor`. */ dedupCursorAfter) {
+    const cutoff = retentionCutoff(entity.days, now);
+    let dedupedCount = 0;
+    let deletedCount = 0;
+    let failedDocuments = 0;
+    let scannedDocuments = 0;
+    let skippedRaced = 0;
+    let windowTruncatedWithWork = false;
+    let useNarrowSelect = true;
+    let cursor;
+    let lastDedupedParent;
+    let dedupStarved = false;
+    if (budgetSpent(budget)) {
+        // Another entity used the run's budget. Whether that leaves work here is
+        // that entity's story to tell — probing for a stale row would only report
+        // rows this pass would refuse to delete anyway.
+        return {
+            dedupResumeAfter: dedupCursorAfter,
+            dedupStarved: entity.dedup,
+            dedupedCount: 0,
+            deletedCount: 0,
+            failedDocuments: 0,
+            hasMore: false,
+            scannedDocuments: 0,
+            skippedRaced: 0
+        };
+    }
+    walk: while(!budgetSpent(budget)){
+        const { docs } = await payload.db.findVersions({
+            collection: entity.slug,
+            limit: PARENT_PAGE_SIZE,
+            pagination: false,
+            select: {
+                parent: true
+            },
+            sort: [
+                'parent',
+                'id'
+            ],
+            where: staleWhere(cutoff, cursor)
+        });
+        const parents = toParentIds(docs);
+        if (parents.length === 0) {
+            break;
+        }
+        for (const parentId of parents){
+            if (budgetSpent(budget)) {
+                break walk;
+            }
+            scannedDocuments++;
+            // Documents already deduped by the previous run are skipped for dedup
+            // (they are still age-swept), so the body budget moves down the list
+            // instead of being spent on the same first documents every night.
+            const dedupThisDocument = entity.dedup && (dedupCursorAfter === undefined || isAfter(parentId, dedupCursorAfter));
+            // A document we would have deduped but cannot afford to read is the one
+            // honest form of "dedup has unfinished business".
+            if (dedupThisDocument && budget.dedupBodiesRemaining < 2) {
+                dedupStarved = true;
+            }
+            let result;
+            try {
+                result = await sweepDocument({
+                    budget,
+                    cutoff,
+                    entity: dedupThisDocument ? entity : {
+                        ...entity,
+                        dedup: false
+                    },
+                    isGlobal: false,
+                    parentId,
+                    payload,
+                    useNarrowSelect
+                });
+            } catch (error) {
+                // One bad document must not cost the rest of the entity, or the
+                // entities queued behind it.
+                failedDocuments++;
+                payload.logger.error({
+                    err: error
+                }, `${LOG_PREFIX} ${entity.slug} document ${String(parentId)}: sweep failed; skipped. ` + 'The next scheduled run retries it.');
+                continue;
+            }
+            useNarrowSelect = result.useNarrowSelect;
+            dedupedCount += result.dedupedCount;
+            deletedCount += result.deletedCount;
+            // Only advance past a document dedup actually finished. A document cut
+            // short must be resumed *inside*, so the cursor stays on its predecessor
+            // — unless the collapse was merely unaffordable, in which case resuming
+            // on it forever is the livelock and stepping past it is the fix.
+            if (result.dedupRan && (!result.dedupStoppedEarly || result.dedupDeferred)) {
+                lastDedupedParent = parentId;
+            }
+            if (result.dedupStoppedEarly || result.dedupDeferred) {
+                dedupStarved = true;
+            }
+            if (result.dedupDeferred) {
+                payload.logger.warn(`${LOG_PREFIX} ${entity.slug} document ${String(parentId)}: found duplicate versions ` + 'but the run is out of deletion budget; stepping past it. Raise ' + '`maxDeletionsPerRun`, or lower `maxDedupBodiesPerRun` to match it, if this recurs.');
+            }
+            if (result.raced) {
+                skippedRaced++;
+            }
+            // Only a document that actually gave up rows draws on the document
+            // budget. Documents whose stale rows are all protected or floor-kept
+            // reappear on every run and must not consume it.
+            if (result.deletedCount > 0) {
+                budget.documentsRemaining--;
+            }
+            if (result.truncatedByWindow && result.deletedCount > 0) {
+                // Only unfinished if the window actually yielded rows: a window that
+                // gave up nothing will give up nothing next time either.
+                windowTruncatedWithWork = true;
+            }
+            if (result.truncatedByWindow) {
+                payload.logger.warn(`${LOG_PREFIX} ${entity.slug} document ${String(parentId)} holds at least ` + `${MAX_VERSIONS_PER_DOCUMENT} versions — only the newest were inspected this pass. ` + 'The next scheduled run continues.');
+            }
+        }
+        const lastParent = parents.at(-1);
+        if (lastParent === undefined) {
+            break;
+        }
+        cursor = lastParent;
+        if (docs.length < PARENT_PAGE_SIZE) {
+            break;
+        }
+    }
+    const hasMore = windowTruncatedWithWork || computeHasMore({
+        budget,
+        dedupStarved,
+        deletedCount,
+        failedDocuments,
+        skippedRaced
+    });
+    if (scannedDocuments > 0) {
+        payload.logger.info(`${LOG_PREFIX} ${entity.slug}: ` + (deletedCount === 0 && !hasMore ? `nothing to do — ${scannedDocuments} document(s) scanned, every stale row is ` + `protected or held by the floor (window ${entity.days} day(s))` : `deleted ${deletedCount} version row(s) (${dedupedCount} identical) across ` + `${scannedDocuments} document(s), window ${entity.days} day(s)` + (skippedRaced > 0 ? `, ${skippedRaced} skipped as raced` : '') + (failedDocuments > 0 ? `, ${failedDocuments} failed` : '') + (hasMore ? ' — work remains, the next scheduled run continues' : '')));
+    }
+    return {
+        // Only carry a resume point when dedup genuinely stopped short. A
+        // completed walk reports none, and the run then moves on to the next
+        // entity — that is what makes the rotation a cycle, not a dead end.
+        dedupResumeAfter: dedupStarved ? lastDedupedParent : undefined,
+        dedupStarved,
+        dedupedCount,
+        deletedCount,
+        failedDocuments,
+        hasMore,
+        scannedDocuments,
+        skippedRaced
+    };
+}
+/** Sweeps one versioned global. A global is a single "document". */ export async function sweepGlobal(payload, entity, budget, now = new Date()) {
+    const empty = {
+        dedupStarved: false,
+        dedupedCount: 0,
+        deletedCount: 0,
+        failedDocuments: 0,
+        hasMore: false,
+        scannedDocuments: 0,
+        skippedRaced: 0
+    };
+    const cutoff = retentionCutoff(entity.days, now);
+    if (budgetSpent(budget)) {
+        // Another entity spent the budget. That entity reports whether work
+        // remains; a stale row here proves nothing on its own.
+        return {
+            ...empty,
+            dedupStarved: entity.dedup
+        };
+    }
+    let result;
+    try {
+        result = await sweepDocument({
+            budget,
+            cutoff,
+            entity,
+            isGlobal: true,
+            payload,
+            useNarrowSelect: true
+        });
+    } catch (error) {
+        payload.logger.error({
+            err: error
+        }, `${LOG_PREFIX} ${entity.slug} (global): sweep failed; skipped. ` + 'The next scheduled run retries it.');
+        return {
+            ...empty,
+            failedDocuments: 1,
+            hasMore: true
+        };
+    }
+    if (result.deletedCount > 0) {
+        budget.documentsRemaining--;
+    }
+    const skippedRaced = result.raced ? 1 : 0;
+    const hasMore = result.truncatedByWindow && result.deletedCount > 0 || computeHasMore({
+        budget,
+        dedupStarved: result.dedupStoppedEarly,
+        deletedCount: result.deletedCount,
+        failedDocuments: 0,
+        skippedRaced
+    });
+    payload.logger.info(`${LOG_PREFIX} ${entity.slug} (global): ` + (result.deletedCount === 0 && !hasMore ? `nothing to do (window ${entity.days} day(s))` : `deleted ${result.deletedCount} version row(s) (${result.dedupedCount} identical), ` + `window ${entity.days} day(s)`));
+    return {
+        dedupStarved: result.dedupStoppedEarly,
+        dedupedCount: result.dedupedCount,
+        deletedCount: result.deletedCount,
+        failedDocuments: 0,
+        hasMore,
+        scannedDocuments: 1,
+        skippedRaced
+    };
+}
+/**
+ * One full janitor pass. Globals go first: there are a handful of them and
+ * they are cheap, and letting a large collection's backlog eat the budget
+ * would otherwise starve them run after run.
+ *
+ * Dedup rides a single cursor over this whole order rather than one per
+ * entity. That is what guarantees progress: a run resumes at the entity the
+ * last one stopped in, skips everything already covered in this cycle, and
+ * carries on into the entities behind it. With a per-entity cursor the
+ * entities *before* the stalled one were re-read from scratch every night and
+ * consumed the entire body budget, so the pass never advanced — measured on
+ * the production copy, where dedup collapsed pairs only in the four
+ * collections ahead of `categories` and never reached `pages` or `games`.
+ */ export async function runRetentionSweep({ collections, dedupCursor, globals, maxDedupBodiesPerRun, maxDeletionsPerRun, maxDocumentsPerRun, now = new Date(), payload }) {
+    const budget = {
+        dedupBodiesRemaining: maxDedupBodiesPerRun,
+        deletionsRemaining: maxDeletionsPerRun,
+        documentsRemaining: maxDocumentsPerRun
+    };
+    const order = [
+        ...globals.map((entity)=>({
+                entity,
+                isGlobal: true
+            })),
+        ...collections.map((entity)=>({
+                entity,
+                isGlobal: false
+            }))
+    ];
+    // A cursor naming a slug that is no longer configured restarts the cycle
+    // rather than skipping everything.
+    const found = dedupCursor ? order.findIndex((item)=>item.entity.slug === dedupCursor.slug) : -1;
+    const resumeIndex = found === -1 ? 0 : found;
+    const output = {
+        dedupCursor: null,
+        dedupedCount: 0,
+        deletedCount: 0,
+        failedDocuments: 0,
+        hasMore: false,
+        scannedDocuments: 0,
+        skippedRaced: 0
+    };
+    let stopped;
+    for (const [index, { entity, isGlobal }] of order.entries()){
+        // Everything before the resume point was deduped earlier in this cycle.
+        // It is still age-swept; only the body reads are skipped.
+        const dedupHere = index >= resumeIndex;
+        const effective = dedupHere ? entity : {
+            ...entity,
+            dedup: false
+        };
+        // A cursor whose slug is gone restarts the cycle, so its parent id must
+        // not leak into the first entity and silently skip its early documents.
+        const resumeAfter = index === resumeIndex && found !== -1 ? dedupCursor?.parentId : undefined;
+        let result;
+        try {
+            result = isGlobal ? await sweepGlobal(payload, effective, budget, now) : await sweepCollection(payload, effective, budget, now, resumeAfter);
+        } catch (error) {
+            // An entity that blows up entirely (a dropped table, a permission
+            // change) must not take the rest of the run down with it.
+            output.failedDocuments++;
+            output.hasMore = true;
+            payload.logger.error({
+                err: error
+            }, `${LOG_PREFIX} ${entity.slug}: sweep aborted; the remaining entities still ran.`);
+            continue;
+        }
+        output.dedupedCount += result.dedupedCount;
+        output.deletedCount += result.deletedCount;
+        output.failedDocuments += result.failedDocuments;
+        output.scannedDocuments += result.scannedDocuments;
+        output.skippedRaced += result.skippedRaced;
+        output.hasMore = output.hasMore || result.hasMore;
+        // The FIRST entity that ran short is where the next run picks up.
+        if (stopped === undefined && dedupHere && result.dedupStarved) {
+            stopped = {
+                slug: entity.slug,
+                ...result.dedupResumeAfter === undefined ? {} : {
+                    parentId: result.dedupResumeAfter
+                }
+            };
+        }
+    }
+    output.dedupCursor = stopped ?? null;
+    // A live cursor IS unfinished work, whatever else the run concluded.
+    output.hasMore = output.hasMore || output.dedupCursor !== null;
+    return output;
+}