Process instance retention: scheduled cleanup of terminal instances (#3604793)

Frank Mablyrequested to merge
issue/orchestra-3604793:feature/instance-retention into 1.x

Implements Phase 1 of #3604793: an opt-in, scheduled retention policy that deletes finished process instances (and, through the delete cascade, their tokens, variables, incidents and tasks) once they are older than a configured age. The audit log keeps the durable history, so only operational runtime data is pruned.

What changed

  • RetentionManager: purges terminal instances past their per-status retention age (completed / cancelled / failed), measured from when they became terminal, in bounded chunks. It never touches a running instance, one with an open incident, or a subprocess child whose parent is still running. A --dry-run mode counts without deleting.
  • InstanceRetentionSweep: a hook_cron handler that purges a bounded batch each run when retention is enabled (so a large backlog clears over several runs).
  • orchestra.settings gains retention_completed / retention_cancelled / retention_failed (a number of seconds or an ISO-8601 duration; empty keeps that status forever), exposed as a Retention section on the Orchestra settings form.
  • drush orchestra:purge-instances [--dry-run] [--limit=N].

Design

It is a garbage collector on top of the existing delete cascade (the *Cleanup hooks already remove an instance's tokens, variables, incidents, work items and subprocess children), not new cleanup logic. Default is keep-forever, so enabling it is a deliberate, safe-by-construction choice.

Tests

Kernel tests cover the age/status rules, the open-incident and running-parent exclusions, the cascade, and dry run; the full core kernel suite passes (95).

Docs and i18n

docs/retention.md (+ nav); French translations for the new settings strings.

Migration

No schema change: retention is config, and age is measured from the instance's existing changed field. Existing sites only need a cache rebuild (done on the maintainer's live site).

Follow-ups (per the issue)

Per-workflow / per-tenant overrides and a legal-hold flag (Phase 2); the workflow-version-snapshot GC noted in #3604588 fits here, on the same liveness principle and chunked-delete plumbing.

Merge request reports