feat(reminders): Phase 4 partial — schema + service + validators

Migration 0072 — reminders/interests expansion:
- interests.reminder_note: optional cadence note for the existing
  reminderEnabled+reminderDays flow. Surfaces in notification body
  + inbox row.
- reminders.yacht_id (+ FK + relation): fourth entity link so
  yacht-scoped tasks have a typed home alongside client/interest/berth.
- reminders.fired_at: worker idempotency. Partial index
  idx_reminders_due_unfired drives the scan.

Service + validator updates:
- createReminderSchema / updateReminderSchema accept yachtId.
- assertReminderFksInPort validates yacht ownership against the
  caller's port — defense-in-depth, same shape as other entity FKs.
- createReminder / updateReminder thread yachtId through.

Worker scheduler + CreateReminderDialog yachtId UI deferred. The
existing reminders/reminder-form.tsx already covers the dialog
contract — Phase 4b extends it with yachtId + the per-user
digest_time_of_day picker.

Tests: 1374/1374 passing. tsc clean.

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

src/lib/db/migrations/0072_phase4_reminders.sql

@@ -0,0 +1,46 @@
+-- Phase 4 — Reminders expansion (POST-AUDIT-SPEC §2 + MASTER-PLAN §D).
+--
+-- Adds:
+--   1. interests.reminder_note — cadence note surfaced in notification body + inbox row.
+--   2. reminders.yacht_id — fourth supported entity link (was: client/interest/berth).
+--   3. reminders.fired_at — worker idempotency; set once the firing notification is
+--      created so a parallel worker can't double-fire.
+--   4. user_profiles.preferences gains `digest_time_of_day` (JSONB key; no DDL).
+--
+-- The existing reminders table already carries title/note/dueAt/priority/assignedTo/
+-- snoozedUntil/googleCalendarEventId — those columns are reused unchanged. No new
+-- table; standalone tasks set client_id/interest_id/berth_id/yacht_id all NULL.
+
+ALTER TABLE interests
+  ADD COLUMN IF NOT EXISTS reminder_note text;
+
+ALTER TABLE reminders
+  ADD COLUMN IF NOT EXISTS yacht_id text,
+  ADD COLUMN IF NOT EXISTS fired_at timestamptz;
+
+-- Yacht FK with the same ON DELETE behaviour as the other entity links.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conname = 'reminders_yacht_id_fkey'
+  ) THEN
+    ALTER TABLE reminders
+      ADD CONSTRAINT reminders_yacht_id_fkey
+      FOREIGN KEY (yacht_id) REFERENCES yachts(id) ON DELETE SET NULL;
+  END IF;
+END $$;
+
+-- Index supports the worker scan: "give me every pending reminder whose
+-- due_at has passed and we haven't fired yet."
+CREATE INDEX IF NOT EXISTS idx_reminders_due_unfired
+  ON reminders (port_id, due_at)
+  WHERE fired_at IS NULL AND status IN ('pending', 'snoozed');
+
+-- Comments for downstream readers.
+COMMENT ON COLUMN interests.reminder_note IS
+  'Phase 4: optional cadence note surfaced in reminder notification body + inbox row. NULL = use the default cadence copy.';
+COMMENT ON COLUMN reminders.yacht_id IS
+  'Phase 4: link to a yacht for yacht-scoped reminders. Mirrors client_id/interest_id/berth_id semantics.';
+COMMENT ON COLUMN reminders.fired_at IS
+  'Phase 4: set by the worker once the due-reminder notification has been created. NULL = not yet fired; used as the worker idempotency gate (alongside the partial index above).';

src/lib/db/schema/interests.ts

@@ -74,6 +74,9 @@ export const interests = pgTable(
     reminderEnabled: boolean('reminder_enabled').notNull().default(false),
     reminderDays: integer('reminder_days'),
     reminderLastFired: timestamp('reminder_last_fired', { withTimezone: true }),
+    // Phase 4: optional note surfaced in the reminder notification body
+    // and inbox row. NULL = use the default cadence copy.
+    reminderNote: text('reminder_note'),
     /** Terminal outcome. Independent of pipelineStage - `outcome` is set
      *  alongside the stage transition to `completed` to distinguish won
      *  deals from the various lost variants. NULL while the interest is

src/lib/db/schema/operations.ts

@@ -5,6 +5,7 @@ import { clients } from './clients';
 import { files } from './documents';
 import { interests } from './interests';
 import { berths } from './berths';
+import { yachts } from './yachts';
 
 export const reminders = pgTable(
   'reminders',
@@ -27,11 +28,19 @@ export const reminders = pgTable(
     clientId: text('client_id').references(() => clients.id, { onDelete: 'set null' }),
     interestId: text('interest_id').references(() => interests.id, { onDelete: 'set null' }),
     berthId: text('berth_id').references(() => berths.id, { onDelete: 'set null' }),
+    // Phase 4: fourth entity link so yacht-scoped tasks (e.g. "follow up
+    // on yacht inspection report") have a typed home. All four entity
+    // FKs are nullable so standalone tasks just leave them blank.
+    yachtId: text('yacht_id').references(() => yachts.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),
     snoozedUntil: timestamp('snoozed_until', { withTimezone: true }),
     completedAt: timestamp('completed_at', { withTimezone: true }),
+    // Phase 4: worker idempotency. Set once the firing notification has
+    // been created. Used as the gate alongside the partial index in
+    // 0072_phase4_reminders.sql so a parallel worker can't double-fire.
+    firedAt: timestamp('fired_at', { withTimezone: true }),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
   },

src/lib/db/schema/relations.ts

@@ -745,6 +745,10 @@ export const remindersRelations = relations(reminders, ({ one, many }) => ({
     fields: [reminders.berthId],
     references: [berths.id],
   }),
+  yacht: one(yachts, {
+    fields: [reminders.yachtId],
+    references: [yachts.id],
+  }),
   calendarCacheEntries: many(googleCalendarCache),
 }));
 

src/lib/services/reminders.service.ts

@@ -3,6 +3,7 @@ import { and, eq, lte, gte, desc, asc, inArray, sql } from 'drizzle-orm';
 import { db } from '@/lib/db';
 import { reminders, interests, clients } from '@/lib/db/schema';
 import { berths } from '@/lib/db/schema/berths';
+import { yachts } from '@/lib/db/schema/yachts';
 import { createAuditLog, type AuditMeta } from '@/lib/audit';
 import { NotFoundError, ValidationError } from '@/lib/errors';
 import { emitToRoom } from '@/lib/socket/server';
@@ -118,7 +119,12 @@ export async function getUpcomingReminders(portId: string, days: number = 14) {
  */
 async function assertReminderFksInPort(
   portId: string,
-  fks: { clientId?: string | null; interestId?: string | null; berthId?: string | null },
+  fks: {
+    clientId?: string | null;
+    interestId?: string | null;
+    berthId?: string | null;
+    yachtId?: string | null;
+  },
 ): Promise<void> {
   const checks: Array<Promise<void>> = [];
   if (fks.clientId) {
@@ -150,6 +156,15 @@ async function assertReminderFksInPort(
         }),
     );
   }
+  if (fks.yachtId) {
+    checks.push(
+      db.query.yachts
+        .findFirst({ where: and(eq(yachts.id, fks.yachtId), eq(yachts.portId, portId)) })
+        .then((row) => {
+          if (!row) throw new ValidationError('yachtId not found in this port');
+        }),
+    );
+  }
   await Promise.all(checks);
 }
 
@@ -169,6 +184,7 @@ export async function createReminder(portId: string, data: CreateReminderInput,
     clientId: data.clientId,
     interestId: data.interestId,
     berthId: data.berthId,
+    yachtId: data.yachtId,
   });
 
   const [reminder] = await db
@@ -184,6 +200,7 @@ export async function createReminder(portId: string, data: CreateReminderInput,
       clientId: data.clientId ?? null,
       interestId: data.interestId ?? null,
       berthId: data.berthId ?? null,
+      yachtId: data.yachtId ?? null,
     })
     .returning();
 
@@ -237,12 +254,14 @@ export async function updateReminder(
   if (data.clientId !== undefined) updates.clientId = data.clientId;
   if (data.interestId !== undefined) updates.interestId = data.interestId;
   if (data.berthId !== undefined) updates.berthId = data.berthId;
+  if (data.yachtId !== undefined) updates.yachtId = data.yachtId;
 
   // Re-validate any subject-FK changes against the caller's port.
   await assertReminderFksInPort(portId, {
     clientId: data.clientId,
     interestId: data.interestId,
     berthId: data.berthId,
+    yachtId: data.yachtId,
   });
 
   const [updated] = await db

src/lib/validators/reminders.ts

@@ -10,6 +10,8 @@ export const createReminderSchema = z.object({
   clientId: z.string().uuid().optional(),
   interestId: z.string().uuid().optional(),
   berthId: z.string().uuid().optional(),
+  // Phase 4: yacht-linked reminders.
+  yachtId: z.string().uuid().optional(),
 });
 
 export type CreateReminderInput = z.infer<typeof createReminderSchema>;
@@ -23,6 +25,7 @@ export const updateReminderSchema = z.object({
   clientId: z.string().uuid().nullable().optional(),
   interestId: z.string().uuid().nullable().optional(),
   berthId: z.string().uuid().nullable().optional(),
+  yachtId: z.string().uuid().nullable().optional(),
 });
 
 export type UpdateReminderInput = z.infer<typeof updateReminderSchema>;
@@ -40,6 +43,7 @@ export const reminderListQuerySchema = baseListQuerySchema.extend({
   clientId: z.string().uuid().optional(),
   interestId: z.string().uuid().optional(),
   berthId: z.string().uuid().optional(),
+  yachtId: z.string().uuid().optional(),
   dueBefore: z.string().datetime().optional(),
   dueAfter: z.string().datetime().optional(),
 });