From bd432fc6c718dfd591897ca7c368e05c0eadbbe2 Mon Sep 17 00:00:00 2001 From: Matt Date: Wed, 13 May 2026 14:18:58 +0200 Subject: [PATCH] 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) --- docs/BACKLOG.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index a5ea1ced..ce3eb125 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -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 ` 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.