#3537 Docs: garbageCollection retention — per-kind keys, automatic passes, and what is never removed

Summary

swamp-club#3473 (swamp PR #3157) shipped a new retention segment of .swamp.yaml garbageCollection: one timeframe covering every kind of history, enforced automatically by swamp serve and the CLI. The manual has no page for it yet — only the bundled skill's troubleshooting reference and the in-repo design docs mention it. Users need a reference page and a how-to.

What the docs need to cover

Configuration reference (.swamp.yaml)

garbageCollection:
  retention: 30d          # default for workflowRuns, evaluatedSnapshots, outputs, audit
  automatic: true         # off unless set
  workflowRuns: 14d
  evaluatedSnapshots: 3d  # unset: follows the run retention
  outputs: 7d
  data: 30d               # opt-in only: deletes every version past the cutoff, the latest included
  audit: 90d
  bookkeeping: 24h        # opt-in only: serve worker GC grace

• Each key, its default, and which kinds fall back to retention (data and bookkeeping never do — they are opt-in only).
• data retention is a repository-wide maximum age on top of each spec's own policy: it ignores lifetime: infinite and count caps and deletes a name's latest version once it is older than the cutoff. Call this out prominently.
• Duration limits: values are held at 1000y; an unrepresentable cutoff means "no retention" (previously workflowRuns: 300000y made swamp run gc delete every finished run).
• .swamp.yaml is never rewritten: a bad value in a newly recognised key is warned about and ignored; only workflowRuns/outputs keep their existing refusals.

How automatic retention runs

• swamp serve: first pass 5 minutes after start, then hourly; batched, takes the sync gate per batch, shares a mutex with run.gc/data.gc, writes one retention.pass audit event per pass.
• CLI: a writing command runs a pass in teardown at most once an hour (waits at most 2s for the lock, stops after 10s of batches). Serve and CLI claim each hour separately.
• Audit store targets without their own retention.days take audit (else retention), rounded up to whole days; read at serve start, so changes need a restart.
• bookkeeping sets the serve worker GC grace period (workers, tokens, leases/dispatches) when automatic is on.

What is never removed

• Running and suspended runs and their snapshots.
• Control-plane data: grants and groups (both spellings), tokens, workers.
• Data names with an unpromoted write.

Behaviour users will notice

• Version numbers never go back: retention records a per-name version floor before emptying a name (on v3, it keeps each name's latest version instead).
• Lookups of missing runs, outputs and data say retention reaped them; searches mark the cutoff.
• v3 reclaim timing: removed content leaves commits.db ~7 days after removal (outbox window), chunks ~24h later.

Checking it works

• swamp doctor datastores --retention — scans storage for overdue items.
• Serve health shows each kind's last pass.
• Relationship to the manual commands swamp run gc and swamp data gc (which now apply garbageCollection.data first).

Operational guidance

• Enabling automatic: true on a busy serve: link to #3535 / #3518 (contention under load) until those are resolved.

Sources

• PR #3157 description
• design/surfaces/repo.md#retention, design/primitives/data.md, design/enablers/serve-audit.md, design/enablers/remote-execution.md
• .claude/skills/swamp/references/behavior/references/troubleshooting.md