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/lib/db/schema/berths.ts

@@ -13,6 +13,7 @@ import {
 } from 'drizzle-orm/pg-core';
 import { ports } from './ports';
 import { clients } from './clients';
+import { yachts } from './yachts';
 
 export const berths = pgTable(
   'berths',
@@ -158,7 +159,7 @@ export const berthWaitingList = pgTable(
     clientId: text('client_id')
       .notNull()
       .references(() => clients.id, { onDelete: 'cascade' }),
-    yachtId: text('yacht_id'), // FK added via relation; nullable (waiting for this yacht)
+    yachtId: text('yacht_id').references(() => yachts.id, { onDelete: 'set null' }),
     position: integer('position').notNull(),
     priority: text('priority').notNull().default('normal'), // normal, high
     notifyPref: text('notify_pref').default('email'), // email, in_app, both

src/lib/db/schema/clients.ts

@@ -34,7 +34,10 @@ export const clients = pgTable(
     /** When this client was merged into another (the "loser" of a dedup
      *  merge), this points at the surviving client. Used by the
      *  /admin/duplicates review queue to redirect any stragglers, and by
-     *  the unmerge flow to restore. Null for live clients. */
+     *  the unmerge flow to restore. Null for live clients. The Postgres
+     *  self-FK is installed via migration 0042; Drizzle's table builder
+     *  doesn't accept self-references in the column factory so the
+     *  constraint isn't reflected here in `.references(...)`. */
     mergedIntoClientId: text('merged_into_client_id'),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),

src/lib/db/schema/documents.ts

@@ -12,6 +12,10 @@ import {
 import { sql } from 'drizzle-orm';
 import { ports } from './ports';
 import { clients } from './clients';
+import { yachts } from './yachts';
+import { companies } from './companies';
+import { interests } from './interests';
+import { berthReservations } from './reservations';
 
 export const files = pgTable(
   'files',
@@ -23,8 +27,8 @@ export const files = pgTable(
       .notNull()
       .references(() => ports.id),
     clientId: text('client_id').references(() => clients.id),
-    yachtId: text('yacht_id'), // FK wired in relations.ts
-    companyId: text('company_id'), // FK wired in relations.ts
+    yachtId: text('yacht_id').references(() => yachts.id, { onDelete: 'set null' }),
+    companyId: text('company_id').references(() => companies.id, { onDelete: 'set null' }),
     filename: text('filename').notNull(),
     originalName: text('original_name').notNull(),
     mimeType: text('mime_type'),
@@ -52,11 +56,13 @@ export const documents = pgTable(
     portId: text('port_id')
       .notNull()
       .references(() => ports.id),
-    interestId: text('interest_id'), // references interests.id
+    interestId: text('interest_id').references(() => interests.id, { onDelete: 'set null' }),
     clientId: text('client_id').references(() => clients.id),
-    yachtId: text('yacht_id'), // FK wired in relations.ts
-    companyId: text('company_id'), // FK wired in relations.ts
-    reservationId: text('reservation_id'), // FK wired in relations.ts
+    yachtId: text('yacht_id').references(() => yachts.id, { onDelete: 'set null' }),
+    companyId: text('company_id').references(() => companies.id, { onDelete: 'set null' }),
+    reservationId: text('reservation_id').references(() => berthReservations.id, {
+      onDelete: 'set null',
+    }),
     documentType: text('document_type').notNull(), // eoi, contract, nda, reservation_agreement, other
     title: text('title').notNull(),
     status: text('status').notNull().default('draft'), // draft, sent, partially_signed, completed, expired, cancelled
@@ -220,7 +226,7 @@ export const formSubmissions = pgTable(
       .notNull()
       .references(() => formTemplates.id),
     clientId: text('client_id').references(() => clients.id),
-    interestId: text('interest_id'), // references interests.id
+    interestId: text('interest_id').references(() => interests.id, { onDelete: 'set null' }),
     token: text('token').notNull().unique(),
     prefilledData: jsonb('prefilled_data').default({}),
     submittedData: jsonb('submitted_data'),

src/lib/db/schema/interests.ts

@@ -13,6 +13,7 @@ import { sql } from 'drizzle-orm';
 import { ports } from './ports';
 import { clients } from './clients';
 import { berths } from './berths';
+import { yachts } from './yachts';
 
 // Pipeline stages: open, details_sent, in_communication, eoi_sent, eoi_signed, deposit_10pct, contract_sent, contract_signed, completed
 
@@ -28,7 +29,7 @@ export const interests = pgTable(
     clientId: text('client_id')
       .notNull()
       .references(() => clients.id),
-    yachtId: text('yacht_id'), // FK added via relation; nullable until pipeline leaves 'open'
+    yachtId: text('yacht_id').references(() => yachts.id, { onDelete: 'set null' }),
     pipelineStage: text('pipeline_stage').notNull().default('open'),
     leadCategory: text('lead_category'), // general_interest, specific_qualified, hot_lead
     source: text('source'), // website, manual, referral, broker

src/lib/db/schema/operations.ts

@@ -1,21 +1,17 @@
-import {
-  pgTable,
-  text,
-  boolean,
-  timestamp,
-  jsonb,
-  index,
-  uniqueIndex,
-} from 'drizzle-orm/pg-core';
+import { pgTable, text, boolean, timestamp, jsonb, index, uniqueIndex } from 'drizzle-orm/pg-core';
 import { sql } from 'drizzle-orm';
 import { ports } from './ports';
 import { clients } from './clients';
 import { files } from './documents';
+import { interests } from './interests';
+import { berths } from './berths';
 
 export const reminders = pgTable(
   'reminders',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     portId: text('port_id')
       .notNull()
       .references(() => ports.id),
@@ -27,8 +23,8 @@ export const reminders = pgTable(
     assignedTo: text('assigned_to'), // user ID
     createdBy: text('created_by').notNull(),
     clientId: text('client_id').references(() => clients.id),
-    interestId: text('interest_id'), // references interests.id
-    berthId: text('berth_id'), // references berths.id
+    interestId: text('interest_id').references(() => interests.id, { onDelete: 'set null' }),
+    berthId: text('berth_id').references(() => berths.id, { onDelete: 'set null' }),
     autoGenerated: boolean('auto_generated').notNull().default(false),
     googleCalendarEventId: text('google_calendar_event_id'),
     googleCalendarSynced: boolean('google_calendar_synced').notNull().default(false),
@@ -40,16 +36,18 @@ export const reminders = pgTable(
   (table) => [
     index('idx_reminders_port').on(table.portId),
     index('idx_reminders_assigned').on(table.assignedTo, table.status),
-    index('idx_reminders_due').on(table.portId, table.dueAt).where(
-      sql`${table.status} IN ('pending', 'snoozed')`
-    ),
+    index('idx_reminders_due')
+      .on(table.portId, table.dueAt)
+      .where(sql`${table.status} IN ('pending', 'snoozed')`),
   ],
 );
 
 export const googleCalendarTokens = pgTable(
   'google_calendar_tokens',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     userId: text('user_id').notNull().unique(),
     accessToken: text('access_token').notNull(), // encrypted
     refreshToken: text('refresh_token').notNull(), // encrypted
@@ -67,7 +65,9 @@ export const googleCalendarTokens = pgTable(
 export const googleCalendarCache = pgTable(
   'google_calendar_cache',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     userId: text('user_id').notNull(),
     eventId: text('event_id').notNull(), // Google Calendar event ID
     title: text('title').notNull(),
@@ -88,7 +88,9 @@ export const googleCalendarCache = pgTable(
 export const notifications = pgTable(
   'notifications',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     portId: text('port_id')
       .notNull()
       .references(() => ports.id),
@@ -114,7 +116,9 @@ export const notifications = pgTable(
 export const scheduledReports = pgTable(
   'scheduled_reports',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     portId: text('port_id')
       .notNull()
       .references(() => ports.id),
@@ -135,7 +139,9 @@ export const scheduledReports = pgTable(
 export const reportRecipients = pgTable(
   'report_recipients',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     reportId: text('report_id')
       .notNull()
       .references(() => scheduledReports.id, { onDelete: 'cascade' }),
@@ -151,7 +157,9 @@ export const reportRecipients = pgTable(
 export const generatedReports = pgTable(
   'generated_reports',
   {
-    id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
     portId: text('port_id')
       .notNull()
       .references(() => ports.id),
@@ -171,9 +179,9 @@ export const generatedReports = pgTable(
   (table) => [
     index('idx_gr_port_created').on(table.portId, table.createdAt),
     index('idx_gr_port_status').on(table.portId, table.status),
-    index('idx_gr_scheduled').on(table.scheduledReportId).where(
-      sql`${table.scheduledReportId} IS NOT NULL`
-    ),
+    index('idx_gr_scheduled')
+      .on(table.scheduledReportId)
+      .where(sql`${table.scheduledReportId} IS NOT NULL`),
   ],
 );