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/storage/filesystem.ts

@@ -362,7 +362,21 @@ function resolveHmacSecret(encryptedSecret: string | null): string {
   // Dev fallback: derive a stable per-process secret so the filesystem
   // backend works without explicit configuration during local development.
   const seed = process.env.BETTER_AUTH_SECRET ?? env.BETTER_AUTH_SECRET ?? 'storage-default';
-  return createHash('sha256').update(`storage-proxy:${seed}`).digest('hex');
+  const derived = createHash('sha256').update(`storage-proxy:${seed}`).digest('hex');
+  // Warn once at boot so two processes started with different
+  // `BETTER_AUTH_SECRET` values are observable: tokens minted by one
+  // wouldn't validate on the other otherwise — which surfaces as random
+  // 401s on file downloads in dev.
+  logger.warn(
+    {
+      hint:
+        'Storage proxy HMAC derived from BETTER_AUTH_SECRET. ' +
+        'Multi-process dev setups must share the same secret value.',
+      secretFingerprint: derived.slice(0, 8),
+    },
+    'FilesystemBackend: using DEV HMAC fallback (no storage_proxy_hmac_secret_encrypted set)',
+  );
+  return derived;
 }
 
 async function streamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer> {

src/lib/storage/s3.ts

@@ -107,6 +107,37 @@ export class S3Backend implements StorageBackend {
       secretKey: resolved.secretKey,
       region: resolved.region,
     });
+    // Verify the bucket exists at boot so a typo / missing-bucket admin
+    // error surfaces with a clear message instead of as a vague Minio
+    // error inside the first user-facing request that touches storage.
+    // Logged-not-thrown when MINIO_AUTO_CREATE_BUCKET=true and the bucket
+    // is missing — we'll create it. Otherwise we throw so the boot fails
+    // fast and the deployment-time misconfig is loud.
+    try {
+      const exists = await client.bucketExists(resolved.bucket);
+      if (!exists) {
+        if (process.env.MINIO_AUTO_CREATE_BUCKET === 'true') {
+          await client.makeBucket(resolved.bucket, resolved.region);
+          logger.info(
+            { bucket: resolved.bucket, endpoint: resolved.endpoint },
+            'S3 bucket auto-created (MINIO_AUTO_CREATE_BUCKET=true)',
+          );
+        } else {
+          throw new Error(
+            `S3 bucket "${resolved.bucket}" does not exist on ${resolved.endpoint}. ` +
+              `Create it manually or set MINIO_AUTO_CREATE_BUCKET=true.`,
+          );
+        }
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes('does not exist')) throw err;
+      // Connection / auth errors get re-thrown with extra context.
+      logger.error(
+        { err, bucket: resolved.bucket, endpoint: resolved.endpoint },
+        'S3 bucket existence check failed at backend boot',
+      );
+      throw err;
+    }
     return new S3Backend(client, resolved.bucket);
   }