[Danny5487401]

Fixes #6942
Related: #6959

Problem and behavior

Self-hosted PostgreSQL installations can exhaust storage on workflow execution results/TOAST and execution logs. This adds an opt-in maintenance CLI that defaults to a consistent, read-only preview and requires explicit tenant scope and --apply before deleting history. No retention task is automatically scheduled.

python -m keep.cli.workflow_retention \
  --tenant-id TENANT_ID \
  --success-retention-days 14 \
  --failure-retention-days 30 \
  --success-log-retention-days 7
# Inspect the complete preview, then rerun with --apply if appropriate.

The implementation follows the maintenance-script approach discussed in #6959, with these safeguards:

• Validate retention periods, batch sizes, and runtime limits before loading the application database engine; use synchronous connection/transaction lifecycles.
• Protect the latest non-test successes and scheduler-relevant last completed record per tenant/workflow; leave checkpoint payloads and Keep's existing history lookup window unchanged. Skip active, unknown, and ambiguous timeout records.
• Select execution IDs without loading result JSON. Bound log and association deletes separately from parent batches, pause between committed batches, and recheck that children are gone before final parent deletion. Preserve alerts, incidents, workflow definitions, and versions.
• Count the full eligible scope in dry-run, with explicit incomplete reports on time/query limits. Apply reports contain only committed progress; interrupted cleanup can resume.
• Refuse missing/invalid/partial execution-ID lookup indexes and unadapted inbound dependencies, including cascading references to child history tables.
• Add a concurrent PostgreSQL log execution-ID index migration that accepts a valid prebuilt equivalent and refuses to silently replace an invalid named index. Other database dialects retain normal index migration behavior; the cleanup CLI itself is PostgreSQL-only.

Validation

• 44 focused tests passed, using an isolated local PostgreSQL 16.2 server for constraints, previews, bounded cleanup, tenant/checkpoint protection, timeout, rollback/retry, and concurrent index migration behavior; SQLite migration compatibility is also exercised.
• Ruff, Black, and isort checks passed for the changed Python files.
• Documentation navigation, JSON, and the focused Actions workflow YAML were checked.
• Added a dedicated GitHub Actions job for PostgreSQL 16.14, Python 3.11 / 3.13, with narrowly scoped dependencies and isolated test schemas. Those remote jobs have not yet been reported as passed.
• The full application test suite and a large-history performance benchmark were not run locally. No existing deployment's data, indexes, or retention schedule were changed.

Rollout notes

Existing large installations should inspect free space and prebuild the documented index before upgrading, so API startup does not wait for a long index build. Cleanup performs no DDL or VACUUM. The documentation covers backups/restoration, bounded catch-up, single-process scheduling, ordinary VACUUM/autovacuum, and why deleted storage does not necessarily immediately reduce filesystem usage.

Reducing newly persisted intermediate step outputs remains a separate follow-up; this PR does not truncate or rewrite successful checkpoints.

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit be26a57.

Approve preview