Round twelve: “tell the customer”

// resolved in strict precedence order. the first four are not
// customer preferences at all: they are obligations.
function resolveChannels(ev: Event, cust: Customer): Channel[] {
  // 1. MANDATORY: regulatory or security. no opt-out exists.
  if (ev.type === 'security.credential_changed') return ['sms', 'email'];
  if (ev.type === 'account.restricted')         return ['sms', 'email'];

  // 2. LEGAL SUPPRESSION: deceased, closed, or a DND registry entry.
  if (cust.legalSuppression) return [];

  // 3. GLOBAL OPT-OUT, for non-mandatory only.
  if (cust.optedOutAll) return ['in_app'];   // still visible if they look

  // 4. PER-EVENT-TYPE preference, the actual customer choice.
  let chans = cust.prefs[ev.type] ?? defaultsFor(ev.type);

  // 5. QUIET HOURS, in THEIR timezone, and only for deferrable events.
  if (inQuietHours(cust) && !ev.urgent) {
    chans = chans.filter(c => c === 'in_app');   // silent channels only
    scheduleDigest(cust, ev);                    // batch it for the morning
  }

  // 6. CAPABILITY: no point queueing push with no registered device.
  return chans.filter(c => cust.canReceive(c));
}

-- technical dedup: keyed on the event id, which is unique per event.
-- NEVER key on (customer, amount, beneficiary): two genuine transfers
-- of the same amount to the same person would collapse into one, and
-- the customer would never learn about the second.
CREATE TABLE notification_sent (
  event_id   TEXT NOT NULL,
  channel    TEXT NOT NULL,
  recipient  TEXT NOT NULL,
  sent_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  -- the uniqueness that does the work. one send per event per
  -- channel per recipient, enforced by the database.
  PRIMARY KEY (event_id, channel, recipient)
) PARTITION BY RANGE (sent_at);   -- DROP old partitions, no mass DELETE

// each is real and must be reported. the FORM changes, not the fact.
if (await rate.exceeded(customer, ev.type, { window: '1h', max: 20 })) {
  // switch to a rolling digest rather than dropping anything
  await digest.add(customer, ev);
  return { deferred: true, reason: 'rate_limited_to_digest' };
}

interface NotificationProvider {
  readonly id: string;
  readonly channel: Channel;
  readonly costPerMessage: bigint;   // minor units, for routing
  readonly rateLimit: number;

  send(m: RenderedMessage): Promise<SendResult>;
  parseReceipt(raw: Buffer, h: Headers): DeliveryReceipt | null;
}

type SendResult =
  | { state: 'accepted'; providerRef: string }   // accepted ≠ delivered
  | { state: 'rejected'; retryable: boolean }
  | { state: 'unknown' };

// receipts arrive as webhooks, so they get the full Part 6 treatment:
// verify the signature over raw bytes, bound replay by timestamp,
// deduplicate on the provider's event id, and confirm the message is
// one we actually sent before trusting anything in it.
CREATE TABLE delivery_receipts (
  notification_id UUID NOT NULL,
  provider_ref    TEXT NOT NULL,
  state           TEXT NOT NULL,   -- sent|delivered|failed|read
  failure_code    TEXT,               -- drives token retirement
  cost_minor      BIGINT,             -- what it actually cost
  received_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (notification_id, provider_ref, state)
);