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-math.ts

@@ -0,0 +1,117 @@
+/**
+ * Pure-math helpers extracted from report-generators.ts so the
+ * revenue/forecast/occupancy/funnel computations can be unit-tested
+ * deterministically without spinning up a Postgres fixture.
+ *
+ * The corresponding DB-bound `fetch*Data` functions in report-generators
+ * call into these helpers after gathering rows. Tests for the SQL itself
+ * remain integration-tier; this module covers the arithmetic so a future
+ * weight-tuning change can't silently shift the forecast number.
+ */
+import { STAGE_WEIGHTS, canonicalizeStage } from '@/lib/constants';
+
+export interface StageRevenueRow {
+  stage: string;
+  revenue: string | number | null;
+}
+
+export interface StageCountRow {
+  stage: string;
+  count: number;
+}
+
+export interface BerthStatusRow {
+  status: string;
+  count: number;
+}
+
+/**
+ * Collapse a per-pipeline-stage revenue list into a canonicalized
+ * Record<canonicalStage, totalRevenueString>. Handles the legacy 9-stage
+ * keys via canonicalizeStage so historical rows fold into the modern
+ * 7-stage bucket they belong to.
+ */
+export function rollupStageRevenue(rows: StageRevenueRow[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const row of rows) {
+    const key = canonicalizeStage(row.stage);
+    const prior = parseFloat(out[key] ?? '0');
+    const next = row.revenue ? parseFloat(String(row.revenue)) : 0;
+    out[key] = String(prior + next);
+  }
+  return out;
+}
+
+/**
+ * Same as rollupStageRevenue but for counts (funnel breakdown).
+ */
+export function rollupStageCounts(rows: StageCountRow[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const row of rows) {
+    const key = canonicalizeStage(row.stage);
+    out[key] = (out[key] ?? 0) + row.count;
+  }
+  return out;
+}
+
+/**
+ * Pipeline-weighted forecast: sum(berth_price × stage_weight) for every
+ * active interest. The weight per stage resolves from per-port admin
+ * overrides (`system_settings.pipeline_weights`) and falls back to the
+ * STAGE_WEIGHTS defaults. Legacy stage keys canonicalize before lookup
+ * so the forecast doesn't silently undershoot due to a key miss.
+ *
+ * Returns the forecast as a 2-decimal-fixed string for stable
+ * comparison + downstream PDF rendering.
+ */
+export function computeTotalForecast(
+  rows: StageRevenueRow[],
+  weights: Record<string, number> = STAGE_WEIGHTS,
+): string {
+  let total = 0;
+  for (const row of rows) {
+    if (!row.revenue) continue;
+    const weight = weights[canonicalizeStage(row.stage)] ?? 0;
+    total += parseFloat(String(row.revenue)) * weight;
+  }
+  return total.toFixed(2);
+}
+
+/**
+ * Occupancy rate as a percentage. "Occupied" = sold only — per the
+ * 2026-05-14 product decision, under_offer is a hold (blocks sale to
+ * other clients) but doesn't count as the berth being occupied yet.
+ * Returns the rate to 1 decimal place; returns 0 when totalBerths=0
+ * to avoid NaN propagation through the PDF.
+ */
+export function computeOccupancyRate(statusCounts: Record<string, number>): {
+  occupancyRate: number;
+  totalBerths: number;
+} {
+  let totalBerths = 0;
+  for (const k of Object.keys(statusCounts)) {
+    totalBerths += statusCounts[k] ?? 0;
+  }
+  const occupiedCount = statusCounts['sold'] ?? 0;
+  const occupancyRate =
+    totalBerths > 0 ? Math.round((occupiedCount / totalBerths) * 100 * 10) / 10 : 0;
+  return { occupancyRate, totalBerths };
+}
+
+/**
+ * Build the per-status count map from a status-grouped query result.
+ * Returns the map AND the total count so callers don't have to sum
+ * again themselves.
+ */
+export function rollupBerthStatusCounts(rows: BerthStatusRow[]): {
+  statusCounts: Record<string, number>;
+  totalBerths: number;
+} {
+  const statusCounts: Record<string, number> = {};
+  let totalBerths = 0;
+  for (const row of rows) {
+    statusCounts[row.status] = row.count;
+    totalBerths += row.count;
+  }
+  return { statusCounts, totalBerths };
+}