docs(backlog): document the deferred-refactor list with rationale

Five engineering refactors and six mechanical service splits the
AUDIT-2026-05-12 dossiers flagged. Assessed against today's reality
(no active webhook subscribers, small DB, low-frequency storage
paths) and explicitly deferred. Listed here so future-me doesn't
re-research them when triaging the audit.

Each entry carries its cost estimate and the trigger condition that
should bring it back onto the roadmap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-13 14:18:58 +02:00
parent adebd5f91d
commit bd432fc6c7

View File

@@ -279,6 +279,29 @@ Migrate as a focused day's work (~40 × 10-15 min), then promote `react-hooks/se
- **Search** (search-auditor): dead `void wantEmail; void wantPhone;` + unused `looksLikeEmail` helper removed (H3).
- **Maintainability** (maintainability-auditor M2): swept seven `void <symbol>` abandoned-scaffolding markers and their dead imports across `clients/bulk`, `interests/bulk`, `admin/email-templates`, `admin/website-submissions`, `alert-rules`, and `notes.service`.
### Wave 11 — explicitly deferred items (revisited 2026-05-13, deferred again)
Each was flagged by the audit but assessed as not-yet-needed for production correctness. Listed here so future-you doesn't re-research them.
**Engineering refactors deferred:**
- **Orphan-blob reaper** (storage-pathing C2, ~4-6h) — `handleDocumentCompleted` already has compensating delete for the only frequent orphan path. Other paths (gdpr-export, backup, etc.) are low-frequency. Revisit when storage costs grow.
- **Webhook deliveries reaper** (outbound-webhook C2, ~2-3h) — `webhook_deliveries` table grows unbounded on high-volume events. Zero active webhook subscribers today; revisit when customers actually subscribe.
- **DNS-rebind TOCTOU** (outbound-webhook H1, ~2h) — Requires admin AND DNS control on the target host. Defense-in-depth on already-low-risk vector. Revisit before exposing webhooks to external integrators.
- **Streaming pass on backup/migrator/email-compose** (storage-pathing H3+H4, ~4-6h) — pg_dump OOM at multi-GB. DB is ~10s of MB today. Revisit when DB grows 100x.
- **Webhook circuit-breaker** (outbound-webhook H3, ~3-4h) — Auto-disable webhooks after N consecutive dead-letters. Saturating worker slots requires active webhook subscribers; none today.
**Mechanical service splits deferred:**
- `documents.service.ts` split (1982 lines → 4 files, ~3-4h)
- `search.service.ts` split (2163 lines → per-bucket files, ~4-6h)
- `notes.service.ts` dedup → dispatch table (1121 → ~500 lines, ~3-4h)
- `interest-tabs.tsx` split (959 lines → 3 files, ~2-3h)
- `expense-pdf.service.ts` split (987 → 3 files, ~2h)
- `command-search.tsx` split (1177 → 5 files, ~3-4h)
Pure code-hygiene work. The files are large but functional. Splitting touches hundreds of imports, risks regression, delivers zero user value. Revisit if/when navigation friction becomes a real bottleneck.
### How to use this section
- Pick a wave; pick an item; read the linked audit section for full context.