Skip to content

Expose retention purge batch size as admin-configurable #74

Open

Description

@prometheusgr

Context

docs/CONFIG_AUDIT_2026-09-04.md found that backend/app/services/retention_service.py:48 hardcodes DEFAULT_BATCH_SIZE = 500 — the number of rows deleted per round-trip during retention purges (conversations, knowledge base, API keys). This is distinct from the retention windows themselves (conversation_retention_hours etc.), which are already fully SystemSettings-backed since Phase 4b; the batch size is a resource-tuning knob that was left out of that config surface.

Why this matters

An operator with a very large backlog (e.g. after enabling retention for the first time on a long-lived deployment) or tighter lock-duration/replication-lag requirements might want a smaller or larger batch size than 500. This is resolved fresh on every scheduled CronJob run (app.cli.retention_sweep), so a DB override takes effect on the very next run with no restart implication — same category as the retention windows it sits beside.

Scope

  1. Add nullable SystemSettings column retention_purge_batch_size (int, sensible bounds e.g. ge=1), following the exact pattern of the existing retention fields in retention_service.py.
  2. Wire into the purge logic, replacing DEFAULT_BATCH_SIZE.
  3. Add to the existing Settings UI retention section with a tooltip.
  4. Audit-log on change, folded into the existing "retention.update" event.

Definition of Done

  • retention_purge_batch_size nullable column + Alembic migration.
  • resolve_retention_config extended, unit-tested.
  • Wired into the purge logic used by app.cli.retention_sweep.
  • Settings UI field + tooltip added to the existing Retention section.
  • Audit logging on change (existing retention.update event).
  • RBAC call-out per AGENTS.md TDD Discipline step 0: admin feature.
  • Standard merge gate from AGENTS.md's Definition of Done applies in full.

Activity

  1. added
    polishAdmin/UI surfacing or refinement of existing capability, not new functionality
    type:improvementMakes an existing capability better/safer/more complete
    priority:P3Deferred/speculative — explicitly not scheduled yet
    effort:SSmall: single file/component, hours not days
    area:retentionData retention windows and purge behavior
    on Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:retentionData retention windows and purge behavioreffort:SSmall: single file/component, hours not dayspolishAdmin/UI surfacing or refinement of existing capability, not new functionalitypriority:P3Deferred/speculative — explicitly not scheduled yettype:improvementMakes an existing capability better/safer/more complete

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions