feat: automated pool archival and cleanup with data preservation

[olathedev]

Description

Implements automated pool archival and cleanup: completed, emergency-withdrawn, and genuinely dead pools are moved out of Explore and My Groups into a read-only Archived view, on a daily schedule, with manual admin control in both directions and a full audit trail.

Archival never deletes anything. An archived pool keeps every row it owned — metadata, members, activity, daily metrics, messages, disputes. Its detail page still renders, its activity feed is still readable, and CSV/PDF export still works. The on-chain contract is immutable and completely unaffected; this is a Supabase-side visibility flag and nothing more. Every archival is reversible by the pool admin in one click.

Closes #212

---

What's included

Database — supabase/migrations/20260828000000_pool_archival.sql

pools gains archived_at and archive_reason, plus completed_at and emergency_withdrawn_at. A CHECK keeps archived_at and archive_reason in lockstep, so no row can claim to be archived without saying why. pools.status now also admits emergency_withdrawn.

New archive_log table records one row per archive and per unarchive — pool, action, reason, triggered_by (cron or a wallet), automated, and a note. Public SELECT, service-role writes only, matching pool_activity and disputes.

Explore and My Groups both filter on archived_at IS NULL, so the default queries are backed by partial indexes covering only the active set. Because those indexes never hold archived rows, the default views get faster as pools are archived rather than slower — which is the performance acceptance criterion.

Archival rules — frontend/lib/archival.ts

Pure and framework-free, so they run under the node test runner without a database.

Reason	Condition
completed	status = 'completed', completed_at older than 7 days
emergency_withdrawn	status = 'emergency_withdrawn', emergency_withdrawn_at older than 30 days
inactive_90d	status = 'active', no pool_activity for 90 days, and the pool holds no funds
admin_archived	Never automated — only ever set by the manual endpoint

Daily sweep — POST/GET /api/cron/archive-pools

Scheduled in vercel.json at 02:00 UTC. Vercel Cron issues a GET, so GET is the real handler and POST delegates to it for manual runs and for the endpoint shape the issue specifies.

• Two queries for the whole run (pools + their activity), not one query per pool.
• The update re-asserts archived_at IS NULL in its WHERE, so a manual archive landing between the scan and the write is not overwritten.
• Idempotent — archived pools are excluded from the query and re-checked by evaluateArchival, so a double run is a no-op.
• Safety valve: a run wanting to archive more than 200 pools stops and reports instead. At that volume a bad backfill or clock skew is likelier than a real cliff of dead pools, and the failure mode would be an emptied Explore page.
• archive_log and notification failures are collected and returned, not thrown — neither should roll back an archival that already succeeded.
• Heartbeats into cron_job_logs, so it shows up in /api/cron/health like the existing jobs. Same Bearer ${CRON_SECRET} auth as the other crons.

API

Endpoint	Notes
GET /api/pools?archived=	omitted → active only (default) · true → both · only → archived only
PUT /api/pools/[id]/archive	{ admin_address, reason?, note? } — pool creator only
PUT /api/pools/[id]/unarchive	{ admin_address, note? } — pool creator only

The archived param applies to all four list branches (explore, creator, member, fallback). The creator and explore branches filter in the query so the partial indexes are used; the member branch filters after the join, because pools there is an embedded relation PostgREST cannot filter without dropping the membership rows being paginated.

Both mutation endpoints write an archive_log row and mirror into pool_activity, so members see why a pool went quiet rather than finding it silently missing from their list. Unarchive carries the previous reason onto its log row so a reversal records what it undid.

UI

• Explore — "Show archived" switch, off by default. Archived pools render as grayed-out compact cards with an "Archived" badge.
• My Groups — "Active" / "Archived" tabs. The archived tab fetches lazily, only once opened, and pages independently of the active tab.
• components/shared/archived-pool-card.tsx — compact row with name, type, badge, reason, completion date, member count, final TVL, and "View History".
• Pool detail page — archived pools lead with a banner stating that the pool is archived, why, and that nothing was lost. Admins get "Restore pool" there, and a confirmed "Archive pool" control on active pools.

Tab and toggle state live in the URL, so an archived view survives a refresh and a back navigation from a pool's history page. All strings translated in messages/en.json and messages/es.json.

---

Design decisions worth reviewing

1. The issue assumed three columns that didn't exist. pools had no completed_at or emergency_withdrawn_at, and status only allowed active | completed | paused — but the criteria are written against all three. Without those anchors the grace periods are unimplementable: a pool would archive the instant its status flipped, and the 7-day review window in the issue would never exist. I added all three, and backfilled existing completed pools from updated_at so the first sweep gives them a grace period instead of archiving them all at once.

2. inactive_90d requires an empty balance, not just silence. This is the decision I'd most like a second opinion on. "No activity for 90 days" alone would archive a pool sitting quietly on real member deposits — and hiding a pool from the people whose money is in it is a trust problem, not a cleanup. So the rule additionally requires the pool to hold nothing: never funded, or fully withdrawn. The balance is derived from the activity feed (deposits minus withdrawals and payouts), reusing the same aggregation as /api/analytics and the metrics cron, so all three agree on what "empty" means.

Two more guards in the same spirit: paused pools are exempt (pausing is a deliberate admin decision the sweep must not quietly undo), and unparseable or future timestamps fail closed — a bad date keeps a pool visible rather than hiding it.

3. Read-only is enforced server-side, not just in the UI. Hiding the deposit button is presentation. lib/server/archival-guard.ts blocks writes aimed at an archived pool at the API boundary, returning 409 with the archival reason, on PATCH /api/pools, POST /api/pools/deposit, and POST /api/pools/messages. A stale tab, a bookmarked request, or a direct curl therefore cannot mutate an archived pool. GET paths are deliberately untouched so archived pools stay fully readable and exportable.

On the page itself, read-only is done by not mounting the actions column, lending tab, and yield dashboard, rather than disabling each control individually — there is no disabled button to re-enable in devtools. Details, members, activity, audit logs, and export are unchanged, with the activity feed labelled historical.

4. The archived card deliberately does less than PoolCard. No on-chain read, no health badge, no sparkline. An archived pool's numbers are final, so per-card RPC calls would buy nothing, and the archived list is exactly where a page of them would be pure waste. It also keeps that list cheap however long it grows.

---

Type of Change

• feat: new feature
• fix: bug fix
• chore: maintenance, tooling, dependencies
• docs: documentation only
• refactor: code restructuring (no functional changes)
• test: adding or updating tests

---

How Has This Been Tested?

• cargo test — not run: no smart-contract changes in this PR. Archival is entirely off-chain.
• pnpm build succeeds — compiles clean, and all three new routes register (/api/cron/archive-pools, /api/pools/[id]/archive, /api/pools/[id]/unarchive)
• pnpm lint passes with 0 errors
• pnpm test:unit — 273 passing, including 30 new tests for the archival rules
• pnpm test:components — 128 passing (up from 121; 7 new), 20 files
• prettier --check clean on every file this PR touches
• Manual testing — not performed. I don't have a Supabase instance with the migration applied, so the cron sweep and the archive/unarchive endpoints have not been exercised against a live database. Everything below the API boundary is covered by tests; a maintainer running this against staging before merge would be worthwhile, particularly the first cron run against real data.

New unit tests — lib/archival.test.ts (30)

Each criterion and both sides of every grace boundary (day 6 vs 7, day 29 vs 31, day 89 vs 90); the balance guard, including the case that matters most — a pool silent for 290 days but still holding funds is asserted not archived; paused pools exempt; idempotency across daily runs; NaN, unparseable, and future timestamps failing closed; and the balance/latest-activity derivation helpers.

New component tests — __tests__/archived-pool.test.tsx (7)

The archived banner and its reason text; the absence of every mutating control on an archived pool; the historical activity label; and the archived card's fields and View History link.

The not-archived case asserts Quick Actions is present — so the hidden-controls test is proving the archival gate rather than a mock that never mounted them in the first place.

Note on the existing typecheck baseline

tsc --noEmit reports 73 errors on this branch — and 73 on main, unchanged. This PR introduces none, and none are in files it touches. They live in GroupClient.tsx, app/[locale]/join/[contractId]/page.tsx, and app/api/admin/pools/route.ts; next.config.mjs sets ignoreBuildErrors: true, so they don't block the build. Worth a separate issue, but out of scope here.

---

Checklist

• My code follows the coding conventions of this project
• I have added/updated tests if needed
• I have updated documentation if needed — docs/pool-archival.md, plus CHANGELOG.md and a pointer from supabase/README.md (the archival job is a Vercel Cron route rather than an Edge Function, so it would otherwise not appear alongside the other scheduled jobs)
• My changes generate no new warnings or errors

---

Deployment notes

1. Apply supabase/migrations/20260828000000_pool_archival.sql. It is additive and nullable throughout; the only destructive step is dropping and rebuilding the pools.status CHECK constraint to admit emergency_withdrawn.
2. vercel.json gains the 02:00 UTC cron entry. It needs the existing CRON_SECRET — no new environment variables.
3. Consider running the sweep manually once against staging first and inspecting the response before letting the schedule fire:

   curl -X POST https://<host>/api/cron/archive-pools -H "Authorization: Bearer $CRON_SECRET"
   # → { "scanned": 412, "archived": 7, "byReason": { "completed": 5, "inactive_90d": 2 }, "errors": [] }

Rollback

Low-risk, because the feature is a visibility layer:

1. Remove the /api/cron/archive-pools entry from vercel.json to stop new archivals.
2. UPDATE public.pools SET archived_at = NULL, archive_reason = NULL; restores every pool to discovery. archive_log retains the full history of what had been archived and why.

The columns and table can be left in place — they are additive and nullable. Full detail in docs/pool-archival.md.

[Sendi0011]

Lfg!