feat(audit-cleanup): finish all 15 outstanding items from verified backlog

Audit cleanup completion plan, all tiers shipped:

Tier 1 (security + data integrity)
- A.7 RTBF true wipe: redact email_messages body/subject/addresses for
  threads owned by deleted client; redact document_sends.recipient_email;
  collect file storage keys + delete blobs post-commit.
- A.8 user_permission_overrides FK: documented inline why cascade is
  correct (not set-null as audit suggested) — overrides have no value
  without their user.
- W2.14 PII redaction: camelCase normalization in audit.ts +
  error-events.service.ts isSensitiveKey; added city/postal/country/
  birth fragments. firstName/lastName/dateOfBirth/postalCode etc. now
  caught in BOTH masker paths. 12 new test cases lock the coverage.

Tier 2 (Documenso completion + refactor)
- C.2: documentEvents.recipient_email column + partial unique index for
  per-recipient webhook dedup (migration 0075). handleDocumentSigned
  now sets recipient_email on insert.
- Phase 2: completion_cc_emails distribution. handleDocumentCompleted
  reads documents.completionCcEmails, filters out signer-duplicates
  case-insensitively, fans signed PDF out to non-signer recipients.
- C.4: extracted createPublicInterest() service from the 346-line
  api/public/interests route. Route becomes a thin shell (rate-limit,
  port resolution, audit log, email fan-out). The trio creation logic
  is now unit-testable without an HTTP fixture.
- Phase 4: POST /api/v1/document-templates/[id]/detect-fields wired
  to document-field-detector.detectFields(). Sparkles "Auto-detect"
  button added to template-editor.tsx — maps DetectedField → marker
  with best-guess merge token (DATE / NAME / EMAIL); user retags.

Tier 3 (reporting + recommender snapshot lockfiles)
- W7.reports: extracted rollupStageRevenue / rollupStageCounts /
  computeTotalForecast / computeOccupancyRate / rollupBerthStatusCounts
  into src/lib/services/report-math.ts (pure functions). 16 new tests
  including an inline-snapshot lockfile on a representative 7-stage
  forecast. report-generators.ts now delegates.
- W7.recommender: 18 new toMatchSnapshot tripwires on classifyTier
  boundaries + computeHeat at canonical input points.

Tier 4 (rolling)
- W6.attach: fixed outdated CLAUDE.md claim — threshold banner is
  informational and never depended on IMAP; bounce monitoring (the
  IMAP poller) is separate.
- D.1 + D.2: documented deferral inline with full why-not-build-it
  reasoning so a future engineer sees the rationale.
- G.1: representative formatDate sweep (audit-log-list, user-list,
  document-templates merge tokens, document-signing email). Rest of
  the ~100 sites stay rolling.

Quality gates: 1420/1420 vitest (46 new tests above baseline of 1374),
tsc clean, 0 lint errors.

Plan: docs/superpowers/plans/2026-05-18-audit-cleanup-completion.md
Migration: 0075_c2_document_events_recipient_email.sql (applied to dev DB).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/services/report-generators.ts

@@ -6,6 +6,13 @@ import { berths } from '@/lib/db/schema/berths';
 import { auditLogs, systemSettings } from '@/lib/db/schema/system';
 import { STAGE_WEIGHTS, canonicalizeStage } from '@/lib/constants';
 import { activeInterestsWhere } from '@/lib/services/active-interest';
+import {
+  rollupStageRevenue,
+  rollupStageCounts,
+  rollupBerthStatusCounts,
+  computeOccupancyRate,
+  computeTotalForecast,
+} from '@/lib/services/report-math';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -76,14 +83,9 @@ export async function fetchPipelineData(
     .groupBy(interests.pipelineStage);
 
   // M-L02: legacy 9-stage values (deposit_10pct, contract_sent…) may
-  // still be present on historical rows. canonicalizeStage maps them
-  // back to the modern 7-stage keys so the rollup doesn't carry phantom
-  // buckets through to the PDF.
-  const stageCountMap: Record<string, number> = {};
-  for (const row of stageCounts) {
-    const key = canonicalizeStage(row.stage);
-    stageCountMap[key] = (stageCountMap[key] ?? 0) + row.count;
-  }
+  // still be present on historical rows. rollupStageCounts canonicalizes
+  // via canonicalizeStage so historical rows fold into the modern bucket.
+  const stageCountMap = rollupStageCounts(stageCounts);
 
   // Top 10 interests by berth price (via primary-berth junction join, plan §3.4).
   const topInterestsRows = await db
@@ -141,13 +143,7 @@ export async function fetchRevenueData(
     .groupBy(interests.pipelineStage);
 
   // M-L02: canonicalize so legacy 9-stage rows fold into the modern bucket.
-  const stageRevenueMap: Record<string, string> = {};
-  for (const row of stageRevenue) {
-    const key = canonicalizeStage(row.stage);
-    const prior = parseFloat(stageRevenueMap[key] ?? '0');
-    const next = row.revenue ? parseFloat(String(row.revenue)) : 0;
-    stageRevenueMap[key] = String(prior + next);
-  }
+  const stageRevenueMap = rollupStageRevenue(stageRevenue);
 
   // Total revenue from WON interests only. Reporting audit caught the
   // `outcome='won'` is the canonical money-changed-hands signal — won
@@ -196,20 +192,14 @@ export async function fetchRevenueData(
     .where(activeInterestsWhere(portId))
     .groupBy(interests.pipelineStage);
 
-  let totalForecast = 0;
-  for (const row of forecastRows) {
-    if (!row.revenue) continue;
-    // M-L02: canonicalize so legacy keys hit pipelineWeights via their
-    // modern equivalent (otherwise the lookup falls through to 0 and the
-    // forecast silently undershoots).
-    const weight = pipelineWeights[canonicalizeStage(row.stage)] ?? 0;
-    totalForecast += parseFloat(String(row.revenue)) * weight;
-  }
+  // M-L02 covered inside computeTotalForecast via canonicalizeStage —
+  // legacy stage keys hit the weight map under their modern equivalent.
+  const totalForecast = computeTotalForecast(forecastRows, pipelineWeights);
 
   return {
     stageRevenue: stageRevenueMap,
     totalCompleted: completedRevenue[0]?.total ? String(completedRevenue[0].total) : '0',
-    totalForecast: totalForecast.toFixed(2),
+    totalForecast,
     pipelineWeights,
     generatedAt: new Date().toISOString(),
   };
@@ -278,23 +268,16 @@ export async function fetchOccupancyData(
     .where(eq(berths.portId, portId))
     .groupBy(berths.status);
 
-  const statusCountMap: Record<string, number> = {};
-  let totalBerths = 0;
-  for (const row of statusCounts) {
-    statusCountMap[row.status] = row.count;
-    totalBerths += row.count;
-  }
-
+  const { statusCounts: statusCountMap, totalBerths } = rollupBerthStatusCounts(statusCounts);
   // Occupied = sold only. Per 2026-05-14 decision, `under_offer` is a
   // hold (blocks the berth from sale to other clients) but the berth is
-  // still technically available until the deal closes. Aligned with the
-  // KPI tile + analytics timeline so the same dashboard shows one number.
-  const occupiedCount = statusCountMap['sold'] ?? 0;
-  const occupancyRate = totalBerths > 0 ? (occupiedCount / totalBerths) * 100 : 0;
+  // still technically available until the deal closes. computeOccupancyRate
+  // implements that rule + rounds to 1 decimal.
+  const { occupancyRate } = computeOccupancyRate(statusCountMap);
 
   return {
     statusCounts: statusCountMap,
-    occupancyRate: Math.round(occupancyRate * 10) / 10,
+    occupancyRate,
     totalBerths,
     generatedAt: new Date().toISOString(),
   };