feat(notifications): in-app notification center backend (phase d.3)

[axelhamil]

Backend of the in-app notification center. Front (<NotificationBell />, /settings/notifications, createBroadcastChannel promotion) is a separate follow-up plan.

What ships

• notification-map.ts in @packages/events — third projection of the event catalog, after visibility-map (webhooks) and retention-map (purge). 21 of 67 events are notifiable; an absent event produces nothing.
• NotificationFanoutSubscriber — runs inside the outbox dispatch TX beside the audit and webhook subscribers, so a notification is never lost to a best-effort handler. One INSERT ... SELECT joining members, never a loop.
• Capability-based recipients — type Audience = "self" | "actor" | "org:all" | { can: OrgPermissions }. Roles are static code, so rolesWith() resolves at boot and leaves WHERE member.role = ANY($1) at runtime: same query a hardcoded role tuple would have produced, without duplicating a decision owned by @packages/access-control.
• Two tables — notification + notification_preference, with 3 partial indexes (unread count, dedup, email pending).
• Per-channel batching — in-app writes immediately and groups on read; email batches on write through emailPendingAt / emailSentAt. No batch table: we own the storage, so the batch stays a query instead of state that can desync.
• SSE stream — GET /notifications/stream, one LISTEN connection per instance (never per client), heartbeat 25 s, cap 5 streams per user. The stream carries a signal, never data: a reconnect just fires invalidateQueries, which kills Last-Event-ID, replay and merge logic in one stroke.
• 8 HTTP routes, all gated; writes carry denyImpersonated, org preferences carry requireOrgPermission.
• Preference cascade — org lock → user preference → map default, with forced bypassing all three.
• Two crons on the existing /internal/* rail, documented in docs/CRON.md.

Catalog

65 → 67 / 28 public / 39 internal. Notification creation emits nothing (it is a read projection of an already-audited event, and emitting would loop with its own subscriber). Preference mutations do emit — an admin silencing billing alerts for a whole org must leave an audit trail (rule 7).

Notable decisions

• organizationId nullable on notification is a documented exception to org-scoping rule 3: a notification is user-scoped by nature, user.password_changed belongs to no org.
• Raw SQL for the org fan-out path (INSERT ... SELECT + ON CONFLICT on a partial index has no ORM equivalent) — column references stay typed via sql.identifier, all external values are bound parameters.
• Resend Broadcasts/Audiences and Topics rejected: marketing one-to-many, and Topics would hand a product decision to the vendor while covering only one channel.

Verification

• pnpm test (monorepo): 17/17 tasks
• pnpm ci:check: clean (biome, knip, jscpd, type-check)
• apps/api: 688 pass / 0 fail
• Fan-out proven against the real DB: org with 3 members + billing.payment.failed → exactly 2 rows (owner + admin), member excluded

Bugs caught in review that no test would have found

• ownerUserId missing from the actor priority chain — would have notified the wrong account.
• emailPendingAt: forced ? null : ... made the 11 forced notifications invisible to the email cron, including payment failure and password change.
• Idempotency key concatenated every batch id, exceeding the 8191-byte btree index limit past ~221 pending rows: the cron would have broken exactly under load.

Known debt

• Org fan-out path has no permanent unit test (functionally proven, script not kept).
• notification_preference.scope_id is polymorphic, so no FK: orphans after user/org deletion. Risk is nil (unreadable without an authenticated session); fix is two DELETE ... WHERE NOT EXISTS in the retention cron on a later pass.

https://claude.ai/code/session_01SHZVb6cDRHaSNMJwxqQ8ec