Skip to content

Commit 34708ff

Browse files
Retention: extend instead of keeping forever; grace after release; clock skew; shared budget
Review fixes for the retention mechanics (data deletion; every change keeps data longer, never shorter): - A stored retain_until earlier than the date required today (the period derived under the current configuration, never less than three years after creation) is extended to that date under the queue lock (compare-and-set) instead of making the job undeletable forever; the job is deleted when the later date arrives. Raising evidence/legacy retention after closure is honoured; lowering it never shortens a stored date. - A legacy acceptance dated more than a day before its record was created gets three full years from creation: later than the promise, and finite. - Releasing a hold ends it now (purpose kept, releaser recorded) so the documented three-day grace applies; releasing an expired hold never lengthens it. - Deletions stop while the PHP and database clocks disagree by more than five minutes; the clock problem is logged once per occurrence, not every run. - One budget of 50 deletion attempts per run, shared by the evidence step and both tombstone loops; a refused restored-post deletion is counted and skipped. - A restored job row's post is deleted only if it carries the tombstone's identity (recycled post ids); a due job whose post carries another identity is kept whole. - Retention on the admin path catches exceptions like the claim path; on the claim path it runs only on polls that hand out no job. - Tests: config raised after closure (extended, then deleted at the new date, not shortened when lowered), legacy accepted-before-created deadline, release grace, clock skew (both directions) and log-once, shared budget, recycled post ids, foreign identity, leap-day bases, claim latency. Docs updated. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 36aba06 commit 34708ff

5 files changed

Lines changed: 413 additions & 80 deletions

File tree

‎docs/WORDPRESS.md‎

Lines changed: 45 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -477,7 +477,8 @@ evidence must remain available. A started job with a missing receipt needs
477477
operator investigation, not a blind retry.
478478

479479
Retention follows the owner's decisions of 2026-10-22, implemented in
480-
maintenance (which runs on every worker claim and on the admin queue page):
480+
maintenance (which runs on worker polls that hand out no job and on the admin
481+
queue page):
481482

482483
- **Closure is explicit.** The first time a job is seen in a terminal state
483484
(`completed`, `failed`, `failed_unknown`, `cancelled`, `expired`, `blocked`)
@@ -489,35 +490,58 @@ maintenance (which runs on every worker claim and on the admin queue page):
489490
(366 days, so a leap day cannot make it early) after closure. The signed
490491
evidence stays.
491492
- **Signed authorization evidence** (the job row and its linked private request,
492-
in whatever post status it is in): deleted at `retain_until`, fixed once at
493-
closure: **six years after closure**, except that r2 and earlier acceptances
493+
in whatever post status it is in): deleted at `retain_until`, set at closure
494+
and afterwards only ever extended, never shortened: **six years after
495+
closure**, except that r2 and earlier acceptances
494496
(versions `YYYY-MM-DD-rN` up to `2026-10-21-r2`) keep their promised **three
495497
years from acceptance**. Never less than three years, whatever the
496498
configuration; a version that cannot be parsed gets the longer period. The
497499
configured `evidence_retention_years` is floored at **six** for non-legacy
498500
versions: a word, null, a boolean, 0 or a value below six means six, never
499501
less.
502+
- **`retain_until` can be extended, never shortened.** When a job's stored date
503+
comes due, it is compared with the date required today: the period derived
504+
from the row under the current configuration, and never less than three years
505+
after the job's creation. If the stored date is earlier (for example,
506+
`evidence_retention_years` or `legacy_retention_years` was raised after
507+
closure), it is extended to the required date (compare-and-set, under the
508+
queue lock) and the job is deleted only when that later date arrives. Lowering
509+
the configuration never moves a stored date earlier. A displayed date can
510+
therefore grow when it comes due after a configuration change.
511+
- **Legacy acceptance dated before its record.** A record is created within
512+
moments of the acceptance it records. If an r2-or-earlier acceptance is dated
513+
more than a day before the job's creation, the stated acceptance date and the
514+
plugin's own creation stamp disagree. The job then gets three full years from
515+
creation. That is later than the promised three years from acceptance, and it
516+
is a definite date rather than "never".
500517
- **Doubtful data is kept.** Deletion requires every date involved to be a real
501518
`Y-m-d H:i:s` date no earlier than 2020 (zero dates and other restore debris
502-
are refused), the stored deletion date to be no earlier than the one derived
503-
from the row today and no earlier than three years after the job's creation,
504-
(less a day) and the job to be in a terminal state. A job whose base date cannot be trusted
505-
keeps `retain_until` empty and is shown as "unknown (kept)" in the admin queue.
506-
A record that appears to have closed before it was created is kept. Nothing is
507-
deleted while the server clock is earlier than a stored job timestamp (a clock
508-
jumped backwards, a bad restore): the run logs once and only the
509-
non-destructive steps proceed. Each run examines at most 50 due jobs, and a job judged doubtful is looked at
510-
again at most daily (`retention_checked_at`), so doubtful rows cannot hide due
511-
ones and the queue lock is held briefly.
519+
are refused), the stored deletion date to have arrived and to be no earlier
520+
than the date required today (see above), and the job to be in a terminal
521+
state. A job whose base date cannot be trusted keeps `retain_until` empty and
522+
is shown as "unknown (kept)" in the admin queue. A record that appears to
523+
have closed before it was created is kept. Nothing is deleted while the PHP
524+
clock and the database clock (`UTC_TIMESTAMP()`) disagree by more than five
525+
minutes, or while the server clock is earlier than a stored job timestamp (a
526+
clock jumped backwards, a bad restore). The problem is logged once (not on
527+
every run) until the clocks agree again, and only the non-destructive steps
528+
proceed. A forward jump of both clocks together cannot be detected. Each run
529+
makes at most 50 deletion attempts in total, shared by the evidence step and
530+
the tombstone clean-up. A job judged doubtful is looked at again at most daily
531+
(`retention_checked_at`), so doubtful rows cannot hide due ones, and the queue
532+
lock is held briefly.
512533
- **Narrow preservation hold** (admin queue): one job, a stated purpose of 20 to
513534
190 characters, a mandatory expiry of at most 730 days, recorded with who set
514535
it and when (and who released it). While it stands nothing about that job is
515536
cleared or deleted, including by a tombstone; after it expires or is released,
516-
the job stays preserved for a further three days. A damaged hold (purpose
537+
the job stays preserved for a further three days. Releasing ends the hold at
538+
that moment (an already expired hold keeps its own end). The stated purpose is
539+
kept, and who released it and when are recorded. A damaged hold (purpose
517540
without an expiry) preserves rather than deletes.
518541
- **Retention runs outside the queue lock.** Only one retention run at a time
519-
(its own advisory lock, throttled to about once a minute on the worker's poll
520-
and run again on the admin queue page). The non-destructive steps are single
542+
(its own advisory lock, throttled to about once a minute on worker polls that
543+
hand out no job, so a lease is never delayed by it, and run again on the admin
544+
queue page; a failure is logged and never breaks the poll or the page). The non-destructive steps are single
521545
statements; every deletion takes the queue lock for that one job only, without
522546
waiting (a busy queue means "next run"), re-reads the row under it and
523547
re-checks every condition, so Stop (which waits up to three seconds for that
@@ -526,15 +550,18 @@ maintenance (which runs on every worker claim and on the admin queue page):
526550
request id, a keyed MAC of the scope, creation time, an opaque random identity, time and
527551
reason; no personal or customer data) before the deletion. If a restored backup
528552
brings the rows back, the next maintenance run deletes them again: a job row
529-
matches on its ids, scope and creation time; a restored request post matches
553+
matches on its ids, scope and creation time, and its request post is deleted
554+
with it only if the post carries the tombstone's opaque identity (otherwise
555+
the post id was recycled and belongs to another record); a restored request post matches
530556
only on its opaque identity and only when no job row currently uses that request
531557
or job id (auto-increment ids can be recycled after a restore and must never
532558
reach a live record). Jobs created before the identity existed are given one
533559
(adopting what their request already carries) by the next maintenance run. Tombstones are kept 120 days, longer than the 90-day backup
534560
rotation, then purged.
535561
- Deletion scrubs the contact fields first, then deletes the private request and
536562
the job row; if any step fails the record stays (and is retried) rather than
537-
being half-deleted.
563+
being half-deleted. A due job whose linked request carries another record's
564+
identity is not touched at all.
538565

539566
Not covered here: backup rotation itself, the contract archive's historical Git
540567
objects and clones (issue 11), unsigned caller leads (there is no lead record in

0 commit comments

Comments
 (0)