Process instance retention: scheduled cleanup of terminal instances and their runtime data

Orchestra never automatically removes finished process instances. Instances (and their tokens, variables, incidents, work items and attachments) accumulate for the life of the site unless an operator deletes them by hand from the instance list. This proposes an opt-in, scheduled retention policy that prunes terminal instances and their runtime data, leaning on the audit trail as the durable history so nothing of record is lost.

The runtime-vs-history split (why this is safe)

Orchestra already separates two kinds of data:

• Runtime data (instances, tokens, variables, incidents, work items, attachments): operational, grows unbounded.
• The audit trail (orchestra_audit_trail): the durable, tamper-evident record, designed to survive instance deletion, with permanent and transient (GDPR-purgeable) buckets.

Because the audit trail retains the "what happened" record, runtime data can be pruned without losing history. Retention should rely on that split.

What exists vs what is missing

• Already present: the cascade. Deleting an instance cleans up its tokens, variables and subprocess children (InstanceCleanup), its incidents, its work items (InstanceWorkItemCleanup) and its attachments (AttachmentCleanup); the UI offers manual bulk delete.
• Missing: anything automatic. There is no scheduled retention, so instances live forever unless deleted by hand.

So this is a retention garbage-collector on top of the existing cascade, not new cleanup logic.

Proposed design

1. Opt-in retention config (default keeps everything, so it never surprises anyone): per terminal status max age (completed, cancelled, failed) as seconds or an ISO-8601 duration, with failed typically kept longer for diagnosis. Optional per-workflow and per-tenant overrides, and a legal-hold flag that exempts a workflow or tenant.
2. Eligibility, safety first: only terminal instances (completed, cancelled, failed), never running, and never an instance with an open incident. Measured from when the instance became terminal (its changed timestamp, or a dedicated finished field if needed).
3. A cron garbage-collector (or queue worker): find eligible instances past their threshold and delete them through the existing cascade, chunked and bounded per run (or enqueued), since a bulk delete hydrates every token. Log how many were pruned (no silent caps).
4. Subprocess children: prune a child only once it is terminal and its parent is gone or terminal, so data a running parent still needs is never deleted (deleting a parent already cascades to its children).
5. A dry-run / preview and a Drush command alongside cron, so an operator can see how many instances a policy would prune before enabling it.

Relationship to version cleanup (#3604588)

Instance retention is what makes workflow version snapshots prunable: a snapshot becomes orphaned once its last referencing instance is gone. The version garbage-collector in #3604588 and this instance garbage-collector run on the same liveness principle and should share the chunked-delete plumbing.

GDPR

This complements the audit trail's transient-bucket purge: runtime PII is removed when the instance is pruned on schedule, while the durable audit keeps non-PII permanently and purges its transient (actor) fields separately. Together that is a coherent data-lifecycle story.

Phases

1. Retention config (per-status max age) + a cron GC over terminal instances via the existing cascade, chunked, logged, opt-in. The 80% of the value.
2. Per-workflow and per-tenant overrides + legal hold.
3. Dry-run/preview UI + Drush command, and optional pre-delete archival (or simply rely on the audit trail as the archive).

Open questions

• Whether a finished timestamp is needed on the instance, or the changed timestamp is sufficient as the "became terminal" marker.
• Whether to delete inline in cron (chunked) or enqueue per-instance deletes for very large backlogs.
• Default retention values, if any, versus keep-forever as the only safe default.