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),
 }));