fix(audit-v3): platform-wide deferred-list cleanup (rounds 1-4)

Working through the audit-v2 deferred backlog. Each round was tested
(typecheck + 1168/1168 vitest) before moving on.

Round 1 — DB performance + AI cost visibility:
- Add missing FK indexes Postgres doesn't auto-create on
  berth_reservations.{interest_id, contract_file_id},
  documents.{file_id, signed_file_id}, document_events.signer_id,
  document_templates.source_file_id, form_submissions.{form_template_id,
  client_id}, document_sends.{brochure_id, brochure_version_id,
  sent_by_user_id}. Without these, RESTRICT-checks on parent delete +
  reverse-lookups walk the child tables fully. Migration 0037.
- AI worker now writes one ai_usage_ledger row per OpenAI call so admins
  can audit spend per port/user/feature and future per-port budgets have
  history to read from. Failure to write is logged-not-thrown so the
  user-facing email draft is unaffected.

Round 2 — Boot-time + transport hardening:
- S3 backend verifies the bucket exists at startup (or auto-creates
  when MINIO_AUTO_CREATE_BUCKET=true). A typo'd bucket name now
  surfaces with a clear boot error instead of a vague Minio error
  inside the first user-facing request.
- Documenso v1 placeFields: 3-attempt exponential-backoff retry on 5xx
  + network errors, fail-fast on 4xx. Stops one transient flake from
  leaving a document with a partial field set.
- FilesystemBackend logs a structured warn-once at boot when the dev
  HMAC fallback is in effect, so two processes started with different
  BETTER_AUTH_SECRET values are observable (random 401s on file
  downloads otherwise).
- Logger redact paths extended to cover *.headers.{authorization,
  cookie}, *.config.headers.authorization, encrypted-credential blobs
  (secretKeyEncrypted, smtpPassEncrypted, etc.), the Documenso
  X-Documenso-Secret header, and 2-level nested forms.

Round 3 — UI feedback + permission gates:
- Storage admin migrate dialog: success toast with row count + error
  toast on both dryRun and migrate mutations.
- Invoice detail Send + Record-payment buttons wrapped in
  PermissionGate (invoices.send / invoices.record_payment); both
  mutations now toast on success/error.
- Admin user list Edit button wrapped in PermissionGate(admin.manage_users).
- Scan-receipt page surfaces an amber warning when OCR fails so reps
  know they can fill the form manually instead of staring at a stalled
  spinner; the editable form now also opens on scanMutation.isError
  / uploadedFile, not only on success.
- Email threads list now renders skeleton rows during load + shared
  EmptyState for the empty case (was a single "Loading…" line).

Round 4 — Service / route correctness:
- documentSends.sent_by_user_id was a free-text NOT NULL column with no
  FK. Now nullable + FK to user(id) ON DELETE SET NULL so the audit row
  survives a user being hard-deleted. Migration 0038 with a defensive
  null-out for any orphan ids before attaching the constraint.
- Saved-views route: documented why withAuth alone is correct (the
  service strictly filters by (portId, userId) — owner-only by design).
- Public-interests audit log: replaced "userId: null as unknown as
  string" cast with userId: null; AuditLogParams already accepts null
  for system-generated events.
- EOI in-app PDF fill: extracted setBerthRange() that, when the
  AcroForm field is missing AND the context has a non-empty range
  string, logs a structured warn so the deployment gap (live Documenso
  template needs the field) is observable instead of silently dropping
  the multi-berth range.

Test status: 1168/1168 vitest. tsc clean. Two new migrations
(0037/0038) need pnpm db:push (or migration apply) on the dev DB.
Deferred-doc updated with the remaining open items (bigger refactors).

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

src/lib/db/migrations/0037_missing_fk_indexes.sql

@@ -0,0 +1,38 @@
+-- Audit-final v2 follow-up: cover the FK columns Postgres doesn't auto-index.
+-- Without these, deleting a parent row (or RESTRICT-checking on update) walks
+-- the child table fully. CREATE INDEX IF NOT EXISTS keeps the migration safe
+-- to re-run.
+
+-- berth_reservations
+CREATE INDEX IF NOT EXISTS idx_br_interest
+  ON berth_reservations(interest_id);
+CREATE INDEX IF NOT EXISTS idx_br_contract_file
+  ON berth_reservations(contract_file_id);
+
+-- documents (file FKs)
+CREATE INDEX IF NOT EXISTS idx_docs_file_id
+  ON documents(file_id);
+CREATE INDEX IF NOT EXISTS idx_docs_signed_file_id
+  ON documents(signed_file_id);
+
+-- document_events
+CREATE INDEX IF NOT EXISTS idx_de_signer
+  ON document_events(signer_id);
+
+-- document_templates
+CREATE INDEX IF NOT EXISTS idx_dt_source_file
+  ON document_templates(source_file_id);
+
+-- form_submissions
+CREATE INDEX IF NOT EXISTS idx_fs_template
+  ON form_submissions(form_template_id);
+CREATE INDEX IF NOT EXISTS idx_fs_client
+  ON form_submissions(client_id);
+
+-- document_sends
+CREATE INDEX IF NOT EXISTS idx_ds_brochure
+  ON document_sends(brochure_id);
+CREATE INDEX IF NOT EXISTS idx_ds_brochure_version
+  ON document_sends(brochure_version_id);
+CREATE INDEX IF NOT EXISTS idx_ds_sent_by
+  ON document_sends(sent_by_user_id);

src/lib/db/migrations/0038_document_sends_sent_by_user_fk.sql

@@ -0,0 +1,23 @@
+-- Audit-final v2 follow-up: document_sends.sent_by_user_id was a free-text
+-- column with no FK. If a user is hard-deleted (rare; we soft-delete), an
+-- orphan id remained without any ON DELETE handling. Add the FK with
+-- SET NULL semantics so the audit row keeps recipient + timestamp + body
+-- even when the originating user is removed.
+
+-- Drop the NOT NULL so SET NULL is legal.
+ALTER TABLE document_sends
+  ALTER COLUMN sent_by_user_id DROP NOT NULL;
+
+-- Defensive: if any historical rows have sent_by_user_id values that don't
+-- match an existing user (dev-only), null them out so the FK can attach.
+UPDATE document_sends
+SET sent_by_user_id = NULL
+WHERE sent_by_user_id IS NOT NULL
+  AND sent_by_user_id NOT IN (SELECT id FROM "user");
+
+ALTER TABLE document_sends
+  ADD CONSTRAINT document_sends_sent_by_user_id_user_id_fk
+    FOREIGN KEY (sent_by_user_id) REFERENCES "user"(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_ds_sent_by
+  ON document_sends(sent_by_user_id);

src/lib/db/migrations/meta/_journal.json

@@ -260,6 +260,20 @@
       "when": 1778100000000,
       "tag": "0036_polymorphic_check_constraints",
       "breakpoints": true
+    },
+    {
+      "idx": 37,
+      "version": "7",
+      "when": 1778150000000,
+      "tag": "0037_missing_fk_indexes",
+      "breakpoints": true
+    },
+    {
+      "idx": 38,
+      "version": "7",
+      "when": 1778200000000,
+      "tag": "0038_document_sends_sent_by_user_fk",
+      "breakpoints": true
     }
   ]
 }

src/lib/db/schema/brochures.ts

@@ -13,6 +13,7 @@ import { ports } from './ports';
 import { clients } from './clients';
 import { interests } from './interests';
 import { berths } from './berths';
+import { user } from './users';
 
 /**
  * Port-wide brochures (Phase 7 — see plan §3.3 / §4.8).
@@ -123,7 +124,12 @@ export const documentSends = pgTable(
     }),
     /** Exact body used (after merge-field expansion + sanitization). */
     bodyMarkdown: text('body_markdown'),
-    sentByUserId: text('sent_by_user_id').notNull(),
+    /**
+     * better-auth user id of the sender. SET NULL on user delete so the
+     * audit row keeps `recipientEmail` + timestamp + body for compliance
+     * even when the originating user is removed from the system.
+     */
+    sentByUserId: text('sent_by_user_id').references(() => user.id, { onDelete: 'set null' }),
     fromAddress: text('from_address').notNull(),
     sentAt: timestamp('sent_at', { withTimezone: true }).notNull().defaultNow(),
     /** SMTP provider message-id for deliverability tracking. */
@@ -143,6 +149,11 @@ export const documentSends = pgTable(
     index('idx_ds_interest').on(t.interestId, t.sentAt),
     index('idx_ds_berth').on(t.berthId, t.sentAt),
     index('idx_ds_port').on(t.portId, t.sentAt),
+    // Reverse-lookups: "what sends used this brochure / version" and
+    // FK-RESTRICT scans on brochure delete.
+    index('idx_ds_brochure').on(t.brochureId),
+    index('idx_ds_brochure_version').on(t.brochureVersionId),
+    index('idx_ds_sent_by').on(t.sentByUserId),
   ],
 );
 

src/lib/db/schema/documents.ts

@@ -80,6 +80,11 @@ export const documents = pgTable(
     index('idx_docs_reservation').on(table.reservationId),
     index('idx_docs_type').on(table.portId, table.documentType),
     index('idx_docs_status_port').on(table.portId, table.status),
+    // Cover the file FKs Postgres doesn't auto-index. Without these,
+    // deleting (or RESTRICT-checking) a referenced files row scans
+    // the documents table fully.
+    index('idx_docs_file_id').on(table.fileId),
+    index('idx_docs_signed_file_id').on(table.signedFileId),
   ],
 );
 
@@ -122,6 +127,8 @@ export const documentEvents = pgTable(
   },
   (table) => [
     index('idx_de_doc').on(table.documentId),
+    // Reverse-lookup signer→events without scanning the events table.
+    index('idx_de_signer').on(table.signerId),
     uniqueIndex('idx_de_dedup')
       .on(table.documentId, table.signatureHash)
       .where(sql`${table.signatureHash} IS NOT NULL`),
@@ -161,6 +168,7 @@ export const documentTemplates = pgTable(
   (table) => [
     index('idx_dt_port').on(table.portId),
     index('idx_dt_type').on(table.portId, table.templateType),
+    index('idx_dt_source_file').on(table.sourceFileId),
   ],
 );
 
@@ -221,7 +229,11 @@ export const formSubmissions = pgTable(
     submittedAt: timestamp('submitted_at', { withTimezone: true }),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   },
-  (table) => [uniqueIndex('idx_fs_token').on(table.token)],
+  (table) => [
+    uniqueIndex('idx_fs_token').on(table.token),
+    index('idx_fs_template').on(table.formTemplateId),
+    index('idx_fs_client').on(table.clientId),
+  ],
 );
 
 export type File = typeof files.$inferSelect;

src/lib/db/schema/reservations.ts

@@ -41,6 +41,11 @@ export const berthReservations = pgTable(
     index('idx_br_client').on(table.clientId),
     index('idx_br_yacht').on(table.yachtId),
     index('idx_br_port').on(table.portId),
+    // Cover the FKs Postgres doesn't auto-index. Without these, deleting
+    // (or restrict-checking) the parent interest / contract file row
+    // requires a full scan of berth_reservations.
+    index('idx_br_interest').on(table.interestId),
+    index('idx_br_contract_file').on(table.contractFileId),
     uniqueIndex('idx_br_active')
       .on(table.berthId)
       .where(sql`${table.status} = 'active'`),