fix(audit-tier-1): timeouts, lifecycle, per-port Documenso, FK constraints

Closes the second wave of HIGH-priority audit findings:

* fetchWithTimeout helper (new src/lib/fetch-with-timeout.ts) wraps
  Documenso, OCR, currency, Umami, IMAP, etc. — a hung upstream can
  no longer pin a worker concurrency slot indefinitely.  OpenAI client
  passes timeout: 30_000.  ImapFlow gets socket / greeting / connection
  timeouts.
* SIGTERM / SIGINT handler in src/server.ts drains in-flight HTTP,
  closes Socket.io, and disconnects Redis before exit; compose
  stop_grace_period bumped to 30s.  Adds closeSocketServer() helper.
* env.ts gains zod-validated PORT and MULTI_NODE_DEPLOYMENT, and
  filesystem.ts now reads from env (a typo can no longer silently
  disable the multi-node guard).
* Per-port Documenso template + recipient IDs land in system_settings
  with env fallback (PortDocumensoConfig now exposes eoiTemplateId,
  clientRecipientId, developerRecipientId, approvalRecipientId).
  document-templates.ts uses the per-port config and threads portId
  into documensoGenerateFromTemplate().
* Migration 0042 wires the eleven HIGH-tier missing FK constraints
  (documents/files/interests/reminders/berth_waiting_list/
  form_submissions) plus polymorphic CHECK round 2
  (yacht_ownership_history.owner_type, document_sends.document_kind),
  invoices.billing_entity_id NOT EMPTY, and clients.merged_into self-FK.
  Drizzle schema columns updated to .references(...) where possible
  so the misleading "FK wired in relations.ts" comments are gone.

Test status: 1168/1168 vitest, tsc clean.

Refs: docs/audit-comprehensive-2026-05-05.md HIGH §§5,6,7,8,9,10 +
MED §§14,15,16,18.

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

src/server.ts

@@ -9,18 +9,45 @@
  * → dist/worker.js) and this file only handles Next.js + Socket.io.
  */
 
-import { createServer } from 'node:http';
+import { createServer, type Server as HttpServer } from 'node:http';
 
 import next from 'next';
 
-import { initSocketServer } from '@/lib/socket/server';
+import { initSocketServer, closeSocketServer } from '@/lib/socket/server';
 import { logger } from '@/lib/logger';
+import { env } from '@/lib/env';
+import { redis } from '@/lib/redis';
 
-const dev = process.env.NODE_ENV !== 'production';
-const port = parseInt(process.env.PORT ?? '3000', 10);
+const dev = env.NODE_ENV !== 'production';
+
+async function gracefulShutdown(signal: string, httpServer: HttpServer): Promise<void> {
+  logger.info({ signal }, 'Shutdown signal received; closing connections');
+
+  // Stop accepting new HTTP connections, then drain in-flight ones.
+  await new Promise<void>((resolve) => {
+    httpServer.close((err) => {
+      if (err) logger.warn({ err }, 'httpServer.close emitted error');
+      resolve();
+    });
+    // Hard timeout — `httpServer.close` waits for ALL keep-alive sockets
+    // to drain on their own, which can stretch much longer than the
+    // compose stop_grace_period. 25s leaves headroom under a 30s grace.
+    setTimeout(() => resolve(), 25_000).unref();
+  });
+
+  await closeSocketServer().catch((err) => logger.warn({ err }, 'closeSocketServer error'));
+
+  try {
+    redis.disconnect();
+  } catch (err) {
+    logger.warn({ err }, 'redis.disconnect error');
+  }
+
+  logger.info({ signal }, 'Shutdown complete');
+}
 
 async function main(): Promise<void> {
-  const app = next({ dev, port });
+  const app = next({ dev, port: env.PORT });
   const handle = app.getRequestHandler();
 
   await app.prepare();
@@ -49,9 +76,20 @@ async function main(): Promise<void> {
     void [emailWorker, documentsWorker, notificationsWorker, importWorker, exportWorker];
   }
 
-  httpServer.listen(port, () => {
-    logger.info({ port, env: process.env.NODE_ENV }, 'Port Nimara CRM server listening');
+  httpServer.listen(env.PORT, () => {
+    logger.info({ port: env.PORT, env: env.NODE_ENV }, 'Port Nimara CRM server listening');
   });
+
+  // Graceful stop on container restart / deploy. Without this, every
+  // `docker compose up -d` rolling restart drops in-flight uploads, EOI
+  // generation, Documenso requests, and Socket.io frames mid-statement.
+  // Match docker-compose `stop_grace_period: 30s` (or longer) so the
+  // 25s drain inside gracefulShutdown can complete before SIGKILL.
+  for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+    process.once(sig, () => {
+      void gracefulShutdown(sig, httpServer).finally(() => process.exit(0));
+    });
+  }
 }
 
 main().catch((err) => {