@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/host/prisma/schema/platform.notifications.prisma

@@ -0,0 +1,641 @@
+// GENERATED by platform db compose — do not edit
+// source: package:notifications.prisma
+
+// =============================================================================
+// Notification Deliveries (issue #125, epic #109)
+// =============================================================================
+//
+// One row per delivery ATTEMPT of an event (#121, `notification-events.ts`)
+// over a channel, to a recipient. This is the answer to "did the user
+// actually get it?" — the first question asked when something goes wrong,
+// and epic #109's own success criterion 7: a delivery record exists for
+// every attempt, with the provider's message id or error.
+//
+// -----------------------------------------------------------------------------
+// eventKey — plain string, NOT a foreign key
+// -----------------------------------------------------------------------------
+// Events are declared in code (`notification-events.ts`, #121), not in a
+// database table — `findEvent()` there returns `undefined` rather than
+// throwing for a key it doesn't recognize, precisely because callers may be
+// holding a key that came from persisted data written before the event was
+// renamed or removed. An FK into an "events" table would force a migration
+// (and a backfill, or a placeholder row) every time the registry changes,
+// which is exactly the coupling #121 built the registry to avoid. A delivery
+// record must outlive the event definition that produced it.
+//
+// -----------------------------------------------------------------------------
+// channel — ALSO a plain string, not a Prisma enum (deliberately asymmetric
+// with `status` below)
+// -----------------------------------------------------------------------------
+// `NotificationChannel` in `notification-events.ts` is explicitly derived
+// from a plain array (`NOTIFICATION_CHANNELS`) so that adding `'push'` later
+// (epic #109 reserves it) costs one edit to that array, not a migration. A
+// Postgres enum on this column would quietly reintroduce that migration: the
+// set of valid channels would live in two places — the code registry and
+// this column's type — and adding one would require updating both. The
+// registry is the single source of truth for what channels exist; this
+// column just records which one a given attempt used.
+//
+// -----------------------------------------------------------------------------
+// status — IS a Prisma enum
+// -----------------------------------------------------------------------------
+// Unlike eventKey/channel, `status` is not registry data — it is this
+// table's own delivery state machine, owned entirely by the dispatcher, and
+// nothing outside this table grows it. It follows the convention this schema
+// already uses for exactly this shape of field (`DeviceCodeStatus`,
+// `StorageObjectStatus`): a small, closed, code-owned set of states is a
+// Postgres enum here, so the database itself rejects a delivery row written
+// with anything other than queued/sent/failed.
+//
+// -----------------------------------------------------------------------------
+// userId — nullable; recipient — the actual destination used
+// -----------------------------------------------------------------------------
+// `allowlist.invitation` (#121) is sent to an email address with no user
+// account yet (#128) — there is no user row to point to, so `userId` must be
+// nullable. `recipient` is what makes that case complete: it is the actual
+// destination address used for THIS delivery, captured independently of the
+// user relation, so the record stands on its own with `userId` null, and
+// stays historically accurate even if the user's email later changes.
+//
+// -----------------------------------------------------------------------------
+// onDelete: SetNull on the user relation
+// -----------------------------------------------------------------------------
+// Matches the audit-trail precedent this schema already sets for
+// `AuditEvent.actorUserId` and `Credential.updatedByUser`: a delivery record
+// is a history of what the application sent, and deleting a user account
+// should not retroactively erase the evidence of what was sent to them —
+// particularly for `security.*` events (#121), which are exactly the ones an
+// incident review is most likely to need after the account in question no
+// longer exists. Nothing is lost by nulling the FK: `recipient` already
+// carries the actual destination independently of it. A GDPR-style request
+// to purge one user's PII is a deliberate, targeted scrub of these rows (and
+// `recipient` specifically) — not something an ON DELETE clause should do
+// silently and irreversibly as a side effect of an unrelated user-deletion
+// path elsewhere in the app.
+//
+// -----------------------------------------------------------------------------
+// Indexes — exactly the two queries this table is known to serve
+// -----------------------------------------------------------------------------
+// Every index is a write cost on a table that grows with every notification
+// sent, so nothing speculative is added beyond what #125 itself names:
+//   - [userId, eventKey]: "did this user get this event?" — an equality
+//     filter on both columns, from an account's delivery history view.
+//   - [status, createdAt]: "what failed recently?" — status = 'failed'
+//     filtered and ordered by recency, for on-call triage.
+// @extensible — back-relations only, added with "extend model NotificationDelivery { ... }" in a
+// fragment (an app's own delivery annotations, for example a provider-specific receipt).
+// The delivery ledger itself (status, error, provider id) stays the platform's.
+model NotificationDelivery {
+  id                String                     @id @default(uuid()) @db.Uuid
+  eventKey          String                     @map("event_key")
+  userId            String?                    @map("user_id") @db.Uuid
+  recipient         String
+  channel           String
+  status            NotificationDeliveryStatus @default(queued)
+  providerMessageId String?                    @map("provider_message_id")
+  // Provider errors (SMTP rejections, SES API errors, ...) have no useful
+  // length bound — @db.Text, same reasoning as Credential.secret above.
+  error             String?                    @db.Text
+  createdAt         DateTime                   @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt         DateTime                   @updatedAt @map("updated_at") @db.Timestamptz
+
+  // Relations
+  user User? @relation("UserNotificationDeliveries", fields: [userId], references: [id], onDelete: SetNull)
+
+  @@index([userId, eventKey])
+  @@index([status, createdAt])
+  // The retention sweep (`notifications.deliveries.purge`, #681): "oldest
+  // first, older than the cutoff", which the status-leading index above
+  // serves only one status at a time.
+  @@index([createdAt])
+  @@map("notification_deliveries")
+}
+
+enum NotificationDeliveryStatus {
+  queued
+  sent
+  failed
+}
+
+// =============================================================================
+// Notifications — the in-app notification centre store (issue #127, epic #109)
+// =============================================================================
+//
+// THE PRIMARY SURFACE OF THE BROWSER CHANNEL, NOT A CACHE OF WHAT SSE SENT.
+//
+// That ordering is the whole reason this table exists. `Notification`
+// permission is denied by a large share of users, and once denied it is
+// effectively permanent — the page cannot re-prompt. A browser channel that
+// existed only as an OS toast would therefore not exist at all for those
+// accounts. So the durable, per-user list is the feature; the SSE stream
+// (`notification-stream.service.ts`) makes it live, and the native toast is a
+// decoration on top that degrades to nothing.
+//
+// Read the second consequence too: SSE IS NOT A DELIVERY GUARANTEE. Events
+// published while a tab is disconnected are lost — `EventSource` reconnects
+// but replays nothing, and the per-process subscriber registry does not fan
+// out across replicas. Because rows land here first and the stream is
+// published second, a client that refetches this table on (re)connect sees
+// everything regardless. That is the designed recovery path, and it is why
+// there is no event-replay machinery anywhere in #127.
+//
+// -----------------------------------------------------------------------------
+// HOW THIS DIFFERS FROM `notification_deliveries` (#125), WHICH IS NOT THE SAME
+// TABLE WITH A DIFFERENT NAME
+// -----------------------------------------------------------------------------
+//
+// `notification_deliveries` is the OPERATOR's record: one row per ATTEMPT, per
+// channel, answering "did we try, and what did the provider say?". It records
+// email attempts too, it keeps rows for recipients with no account, and it is
+// never shown to the user it is about.
+//
+// `notifications` is the USER's inbox: one row per thing they should see, only
+// for the browser channel, only for real accounts, with read state they own.
+// An email send writes a delivery row and no row here — there is nothing for
+// the bell to show about a message that went to their mailbox.
+//
+// Merging the two would mean either showing users provider error strings, or
+// filtering an operator table by channel on every bell render. They answer
+// different questions for different audiences and are kept apart.
+// =============================================================================
+
+// @extensible — back-relations only, added with "extend model Notification { ... }" in a
+// fragment (an app's own side table keyed by a notification, for example a per-notification
+// follow-up). A user-owned row: the table has no organization column, so a plain foreign
+// key on `id` is the right shape. `onDelete: Cascade` on the app side keeps the retention
+// sweep (`notifications.inbox.purge`) working.
+model Notification {
+  id     String @id @default(uuid()) @db.Uuid
+  // NOT NULL, unlike NotificationDelivery.userId. An inbox belongs to an
+  // account by definition; there is no "notification centre" for a recipient
+  // with no login (#128's `allowlist.invitation` case), which is exactly why
+  // the browser channel's resolveTo returns null for them.
+  userId String @map("user_id") @db.Uuid
+
+  // Plain string, NOT a foreign key — the same reasoning written out at length
+  // on NotificationDelivery.eventKey. Events are declared in code
+  // (`notification-events.ts`, #121) and `findEvent` returns undefined rather
+  // than throwing precisely because persisted rows outlive their definitions.
+  // An FK would force a migration every time the registry changed.
+  eventKey String @map("event_key")
+
+  // RENDERED AT WRITE TIME, not at read time. The alternative — store the
+  // event payload as JSONB and render in the bell — means an old row renders
+  // through today's template, so editing copy silently rewrites history and a
+  // removed event's rows become unrenderable. What the user was told is a
+  // fact; it is frozen here.
+  title String
+  // @db.Text for the same reason as Credential.secret and
+  // NotificationDelivery.error: a rendered body has no meaningful length
+  // bound, and silently truncating what a user was told is worse than storing
+  // a long string. (Postgres `text` has no performance penalty over `varchar`.)
+  body  String @db.Text
+
+  // Where the bell should send the user, as a ROOT-RELATIVE PATH ("/settings",
+  // "/admin/users?id=…"), never an absolute URL.
+  //
+  // THIS IS A SECURITY BOUNDARY, ENFORCED IN CODE AT WRITE TIME
+  // (`browser-notification.channel.ts`). The web client will put this value in
+  // an href or a router navigation; an absolute URL makes every notification a
+  // potential open redirect, and a `javascript:` scheme makes it script
+  // execution in the app's own origin. The column cannot express that
+  // constraint, so the writer enforces it and drops a link it cannot vouch
+  // for rather than storing it and hoping the client is careful.
+  //
+  // Nullable: most notifications have nowhere specific to go.
+  link String?
+
+  // A TIMESTAMP, NOT A BOOLEAN. `readAt IS NULL` answers "is it unread?" just
+  // as well as `read = false` does, and additionally answers "when did they
+  // see it?" — which is the question asked when someone reports acting late on
+  // a security alert. A boolean would have to grow this column later anyway.
+  readAt DateTime? @map("read_at") @db.Timestamptz
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  // NO `updatedAt`. The only mutation this row ever undergoes is being marked
+  // read, and `readAt` already timestamps that with more precision than an
+  // `updatedAt` would carry. A second, redundant answer to "when did this
+  // change?" is a second thing to keep consistent for no reader.
+
+  // Relations
+  //
+  // onDelete: Cascade — deliberately the OPPOSITE of
+  // NotificationDelivery.user's SetNull, and the contrast is the point. A
+  // delivery record is an audit trail that must outlive the account it
+  // describes ("did we email this person before they were offboarded?"). An
+  // inbox is personal data with no reader once the account is gone: keeping
+  // orphaned rows would retain rendered titles and bodies about a deleted user
+  // forever, and `userId` is NOT NULL here so SetNull is not even expressible.
+  user User @relation("UserNotifications", fields: [userId], references: [id], onDelete: Cascade)
+
+  // The two queries this table actually serves, and nothing speculative.
+  //
+  // 1. THE UNREAD BADGE: `where { userId, readAt: null }`, run on every bell
+  //    render and on every SSE (re)connect — by far the hottest query here.
+  //    (Ideally a partial index `WHERE read_at IS NULL`, which Prisma cannot
+  //    express declaratively; the composite covers the same predicate and
+  //    stays in one place the schema owns.)
+  @@index([userId, readAt])
+  // 2. THE RECENT LIST: `where { userId } orderBy { createdAt: desc }`.
+  //    `sort: Desc` matters — a plain ascending index makes Postgres walk it
+  //    backwards for the newest page, which is the only page anyone loads.
+  @@index([userId, createdAt(sort: Desc)])
+  // The retention sweep (`notifications.inbox.purge`, #681): "oldest first,
+  // older than the cutoff" across every user, which neither index above serves.
+  @@index([createdAt])
+  @@map("notifications")
+}
+
+// =============================================================================
+// Push Subscriptions (issue #229, epic #215)
+// =============================================================================
+//
+// Storage for the browser's `PushSubscription` object — the endpoint URL plus
+// the two keys (`p256dh`, `auth`) needed to encrypt a Web Push payload to that
+// specific device — so the server has something to sign and send to when a
+// notification's `browser` channel wants to reach a tab that isn't open.
+//
+// THIS SHIPS DISABLED BY DEFAULT (per #215). This table, and the endpoints the
+// next pass builds on top of it, exist regardless; what makes push actually
+// fire is a downstream deployment setting `VAPID_PUBLIC_KEY` /
+// `VAPID_PRIVATE_KEY` in its own environment. A repo that never sets those
+// vars has this table sitting empty and unused — generating keys, not writing
+// code, is the enable step. Nothing here should ever require a schema change
+// to turn push on.
+//
+// -----------------------------------------------------------------------------
+// endpoint — @unique, not part of a composite key with userId
+// -----------------------------------------------------------------------------
+// The endpoint URL (assigned by the browser's push service — FCM, Mozilla's
+// autopush, ...) already uniquely identifies one subscribed device/browser
+// instance; it cannot simultaneously be valid for two different users. Making
+// it @unique on its own, rather than @@unique([userId, endpoint]), is what
+// lets the service layer `upsert` on `endpoint` alone (#229's acceptance
+// criterion: "Re-subscribing the same endpoint upserts instead of creating a
+// duplicate row") — including the case where the same browser subscription
+// re-registers under a different signed-in user, which should move the row,
+// not fork it.
+//
+// -----------------------------------------------------------------------------
+// userId — onDelete: Cascade, the OPPOSITE of NotificationDelivery.user's
+// SetNull right above, and deliberately so
+// -----------------------------------------------------------------------------
+// NotificationDelivery keeps its user relation nullable-with-SetNull because a
+// delivery row is an audit trail with standalone value ("did we send this
+// before the account was offboarded?") even once the account is gone — it
+// carries its own `recipient` and stands on its own. A push subscription has
+// no such standalone meaning: it is nothing but a live credential for pushing
+// to one specific person's device. Once that person's account is deleted
+// there is no one left to authorize a push, no one left to act on it, and no
+// audit value in keeping an endpoint + key material around — it is simply
+// dead. Cascade is correct here for the same reason `Notification.user` above
+// is Cascade rather than SetNull: this is live, personal state with no reader
+// once the account is gone, not history.
+//
+// -----------------------------------------------------------------------------
+// failureCount / lastSuccessAt — written by #230, columns exist now
+// -----------------------------------------------------------------------------
+// Web Push endpoints go stale silently (uninstalled browser, revoked
+// permission, expired subscription) and the push service reports this as a
+// 404/410 (gone) or persistent 429/5xx on send, never as an explicit
+// unsubscribe call. `failureCount` is incremented by the not-yet-built sender
+// (#230) on each such failure so a pruning job can drop subscriptions that
+// have stopped working, and `lastSuccessAt` is its complement — updated on
+// every successful send — so "why did this stop working" has an answer
+// (compare `failureCount`'s growth against how long ago `lastSuccessAt` was)
+// without needing delivery-log archaeology. Neither column is written by
+// anything in this migration; they exist now so #230 needs no schema change.
+model PushSubscription {
+  id String @id @default(uuid()) @db.Uuid
+
+  userId String @map("user_id") @db.Uuid
+
+  // The push service URL the browser gave us (e.g.
+  // `https://fcm.googleapis.com/fcm/send/...`). @unique — see block comment
+  // above for why this, not a composite key, is what the upsert relies on.
+  endpoint String @unique
+
+  // The two halves of the browser's subscription keys
+  // (`PushSubscription.getKey('p256dh'|'auth')`, base64url-encoded), together
+  // sufficient to encrypt a payload to this device per the Web Push
+  // encryption spec (RFC 8291). Neither is secret in the same sense as
+  // `Credential.secret` — they are meaningless without also knowing the
+  // corresponding endpoint and the server's VAPID private key — so they are
+  // stored plain, matching how every Web Push library (including `web-push`,
+  // which the next pass will use) expects to read them back out.
+  p256dh String
+  auth   String
+
+  // From the browser's `PushSubscription.expirationTime`, when the push
+  // service supplies one (most don't). Nullable because absence is the
+  // common case, not an error.
+  expirationTime DateTime? @map("expiration_time") @db.Timestamptz
+
+  // For diagnosing "why did this stop working" alongside failureCount/
+  // lastSuccessAt below. Nullable: not always available, and never required.
+  userAgent String? @map("user_agent")
+
+  // Incremented by #230's sender on delivery failure (429/5xx from the push
+  // service); read by its not-yet-built pruning logic to drop dead
+  // subscriptions. Starts at 0 and is reset to 0 on the next successful send.
+  failureCount Int @default(0) @map("failure_count")
+
+  // Updated on every successful send by #230. Nullable: a freshly created
+  // subscription has never had one.
+  lastSuccessAt DateTime? @map("last_success_at") @db.Timestamptz
+
+  // Which surface registered this subscription (#746, PP-9.4; harvested from
+  // EvoPath #312): `browser` (a browser tab or installed PWA) or `android_app`
+  // (the Android companion's Trusted Web Activity). The `android_app`
+  // notification channel pushes to these rows alone; `push` keeps meaning
+  // every subscription. A re-post of the same endpoint as `android_app`
+  // re-tags a `browser` row, a `browser` re-post never downgrades an
+  // `android_app` row (push-subscription.service.ts). The CHECK constraint
+  // `push_subscriptions_platform_check` lives in the migration SQL only
+  // (Prisma cannot express one; see PUSH_SUBSCRIPTION_PLATFORMS in the
+  // notifications contract).
+  platform String @default("browser")
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // Relations
+  //
+  // onDelete: Cascade — see block comment above for why this reverses the
+  // SetNull precedent set by NotificationDelivery.user just above.
+  user User @relation("UserPushSubscriptions", fields: [userId], references: [id], onDelete: Cascade)
+
+  // The one query this table is known to serve: "give me this user's
+  // subscriptions to push to" (#229's subscribe/unsubscribe endpoints and
+  // #230's send fan-out both key off userId; endpoint's own @unique index
+  // already covers lookup/upsert by endpoint).
+  @@index([userId])
+  @@map("push_subscriptions")
+}
+
+// =============================================================================
+// Notification Broadcasts (issue #320, epic #319)
+// =============================================================================
+//
+// One row per admin-composed message announced to every user in the
+// deployment — "we're doing maintenance Saturday", "new feature shipped" —
+// scheduled, sent (or canceled), and never re-editable once it has started.
+// This issue is schema only: the compose/schedule/cancel endpoints, the job
+// handler that actually fans a broadcast out over `notify()`, and the admin
+// UI all arrive in later issues of #319. What is here is the row a later
+// issue's job reads from and writes progress back to.
+//
+// -----------------------------------------------------------------------------
+// WHY A TABLE AT ALL — REJECTED: living entirely inside `Job.payload`
+// -----------------------------------------------------------------------------
+// The obvious shortcut is to skip this table and let a broadcast be nothing
+// but the `payload` JSON of a `'broadcast.send'` job (#255 already gives
+// every job a JSONB payload for free). Two things rule that out:
+//
+//   - Job history is pruned INDEPENDENTLY of this table's business value.
+//     `job-history-purge` (#263) deletes old `jobs` rows on a retention
+//     schedule that exists to keep the QUEUE small, not to preserve what an
+//     admin once announced. A broadcast composed ninety days ago is still
+//     something "what did we tell our users, and when" needs to answer long
+//     after the job that sent it has aged out — living only in `payload`
+//     means that answer silently disappears on a retention sweep nobody
+//     doing the asking even knows runs.
+//   - The admin broadcast list page (a later issue in #319) would be
+//     QUERYING THE QUEUE FOR BUSINESS DATA — filtering and paging `jobs` by a
+//     `type` string and reading business fields back out of an opaque JSONB
+//     blob never meant to be a list-page's row shape. `jobs` is
+//     infrastructure for background work in general; a broadcast is a
+//     first-class thing the product has, with its own status, its own
+//     progress counters, and its own list page. It gets its own table for the
+//     same reason `notifications` (#127) is not "SSE events kept in a JSONB
+//     column somewhere" — the durable record IS the feature, not a
+//     side-effect of how the delivery mechanism happens to be implemented.
+//
+// A `'broadcast.send'` job still exists and still references one of these
+// rows (by id, in its `payload`) to actually run the fan-out — this table is
+// not a replacement for the queue, only for using the queue's own history as
+// the system of record.
+//
+// -----------------------------------------------------------------------------
+// channels — String[], not a Prisma enum
+// -----------------------------------------------------------------------------
+// Mirrors `NotificationDelivery.channel`'s deliberate plain-string choice
+// (see that column's own block comment above), one level up: a broadcast can
+// target more than one channel at once, so this is `channels String[]`
+// rather than a single string, but the "why not an enum" reasoning is
+// identical. `NOTIFICATION_CHANNELS` (`notification-events.ts`) is a
+// code-owned, growing array specifically so adding `'push'`-style channels
+// later costs one edit to that array. A Postgres enum on this column would
+// reintroduce exactly the migration that array exists to avoid, and would
+// leave the set of valid channels living in two places that could disagree.
+//
+// -----------------------------------------------------------------------------
+// title / body — composed and frozen at write time, not templated at read
+// time
+// -----------------------------------------------------------------------------
+// Same contract as `Notification.title`/`.body` (#127): what an admin typed
+// (or the compose form rendered from it) is a fact about what was announced,
+// stored as that fact, not as a template reference re-rendered later. The
+// alternative — store a template key plus a data blob and render in the
+// list page — means editing copy elsewhere in the app silently rewrites what
+// this broadcast is remembered as having said, and a broadcast survives any
+// future rename or removal of whatever generated its text.
+//
+// -----------------------------------------------------------------------------
+// status — `NotificationBroadcastStatus`, matching `NotificationDeliveryStatus`'s
+// naming, and carrying one member NOTHING IN THIS EPIC CAN REACH YET
+// -----------------------------------------------------------------------------
+// The enum is prefixed `NotificationBroadcast…` rather than plain
+// `BroadcastStatus` to match the existing `NotificationDeliveryStatus`
+// naming convention on the sibling tables in this section, rather than
+// inventing a shorter name unique to this model.
+//
+// `draft` IS NOT REACHABLE BY ANY ROUTE #319 BUILDS. No compose endpoint in
+// this epic writes a row with that status, and no later issue's handler
+// reads one. It is here anyway, on purpose, because adding a value to a
+// Postgres enum type is a migration, and `ALTER TYPE ... ADD VALUE` cannot
+// run inside the same transaction Prisma wraps a migration in (Postgres
+// forbids using a freshly added enum value in the transaction that added
+// it). A future "save and finish composing later" feature is a one-line
+// product ask that would otherwise cost a migration on a table with live
+// data; paying for the enum slot now, while it is free, buys that escape
+// hatch later for nothing. DO NOT DELETE `draft` AS "unused" — it is
+// deliberately dead code, not leftover code.
+//
+// -----------------------------------------------------------------------------
+// cursorUserId / audienceCutoff — the resume point AND the frozen audience
+// for a chunked, cursor-resumable fan-out
+// -----------------------------------------------------------------------------
+// A broadcast fans out to every user in the deployment, which can be far
+// more than one job execution should hold open in a single transaction or a
+// single lease window. #323's handler processes users in chunks and, after
+// each chunk commits, writes that chunk's last id to `cursorUserId` so a
+// retried or resumed run picks up exactly where the previous attempt left
+// off instead of restarting from user zero (or, worse, re-sending to
+// everyone already done).
+//
+// `audienceCutoff` IS THE MOST IMPORTANT FIELD ON THIS MODEL, because a
+// cursor alone does not define a stable audience to page through — it only
+// defines a position. Stamped ONCE, when the fan-out starts (`status` moves
+// to `sending`), it is the timestamp every chunk's query filters
+// `users.createdAt` against (`createdAt <= audienceCutoff`), combined with
+// `WHERE id > cursorUserId ORDER BY id ASC` for the page itself. That
+// combination buys two things at once, with no new index on `users`:
+//
+//   - A FROZEN AUDIENCE. Without a cutoff, a fan-out that takes long enough
+//     for new signups to land mid-run would keep discovering new rows to
+//     page through — the query keeps changing under it. A broadcast could
+//     then fail to terminate under sustained signups, or (worse) a user who
+//     signed up during the run could receive it depending on exactly when
+//     their row was inserted relative to the currently-processing chunk.
+//     Freezing the boundary at start time makes the set of eligible users
+//     fixed the moment sending begins.
+//   - A REPLAYABLE "WHO GOT THIS" QUERY. `users.id ASC` is the only
+//     ordering that is both STABLE and TOTAL — the primary key never
+//     changes for a row and no two rows share a value — so re-running
+//     `WHERE createdAt <= audienceCutoff ORDER BY id ASC` after the fact
+//     reproduces the exact same page sequence the fan-out actually walked,
+//     which `cursorUserId` alone (paging on a column with no recorded
+//     boundary) cannot promise once the run has finished. `createdAt` is
+//     deliberately NOT used as the paging column for this same reason in
+//     reverse: two users can share a timestamp (a bulk import, an unlucky
+//     race), and a page boundary drawn on a non-unique column can silently
+//     skip or repeat a user at that boundary.
+//
+// This defines two windows precisely, and both are intentional, not edge
+// cases to patch later:
+//   - A user created between the broadcast's `createdAt` (composed/
+//     scheduled) and `startedAt` (fan-out begins) IS INCLUDED — the rule
+//     this model implements is "everyone who exists once sending starts",
+//     not "everyone who existed when an admin clicked compose".
+//   - A user created between `startedAt` and the run's last chunk is
+//     EXCLUDED — they signed up after the audience was frozen, and by
+//     definition are not behind the cursor a resumed run would recheck.
+//
+// -----------------------------------------------------------------------------
+// createdById — onDelete: SetNull (and the one-line cost of adding this FK)
+// -----------------------------------------------------------------------------
+// Same reasoning as `AuditEvent.actorUserId` (and `NotificationDelivery
+// .user`, and `Credential.updatedByUser`): this column is an audit trail,
+// not a live reference. Deleting the admin who composed a broadcast must not
+// delete the record of what they announced to every user in the deployment
+// — if anything, that is exactly the record an incident review is most
+// likely to need after the admin account in question no longer exists.
+// Nothing about the broadcast's own meaning depends on the admin row still
+// existing, so the FK is nulled, never cascaded. Worth naming plainly: adding
+// a foreign key to `users` takes a brief `ACCESS SHARE`-class lock on that
+// table while the constraint is validated. At this schema's scale that is
+// not something an operator needs to plan a maintenance window around, but
+// it is a real, if trivial, cost of this migration and not a free action.
+//
+// -----------------------------------------------------------------------------
+// Indexes — exactly the two queries this table is known to serve
+// -----------------------------------------------------------------------------
+//   - [status, scheduledFor]: "WHAT IS PENDING" — the scheduler's own query,
+//     equality on `status = 'scheduled'` ordered/filtered by `scheduledFor`,
+//     for finding due broadcasts to start and upcoming ones to display.
+//   - [createdAt desc]: the admin list page's default order, "most recently
+//     composed first" — same reasoning as `Job`'s and `Notification`'s own
+//     `createdAt(sort: Desc)` indexes, for the same reason: a plain ascending
+//     index makes Postgres walk it backwards for the only page anyone loads.
+//
+// -----------------------------------------------------------------------------
+// REJECTED: a `notification_broadcast_recipients` join table
+// -----------------------------------------------------------------------------
+// The exact-tracking alternative — one row per (broadcast, user) pair,
+// recording per-recipient delivery outcome the way `notification_deliveries`
+// does per (event, user) — was considered and rejected for this issue.  It is
+// UNBOUNDED GROWTH keyed to the size of the user base on every single
+// broadcast sent (a deployment with 50,000 users sending one broadcast a
+// week is 2.6 million new rows a year for that feature alone), for a
+// marginal gain over what `cursorUserId`/`audienceCutoff` plus the two
+// counters below already give: the queue's own at-least-once contract (see
+// `JobHandler`'s own block comment) already bounds a replay to AT MOST ONE
+// CHUNK — the fan-out resumes from the last committed cursor, so
+// re-processing is inherently limited to users near the boundary, not the
+// whole broadcast. `recipientsTargeted`/`recipientsDispatched` answer "how
+// many were meant to get this, how many did we attempt" at the aggregate
+// level a broadcast's own admin view actually needs; per-recipient
+// per-channel success/failure already lives in `notification_deliveries` —
+// this table must not become a second, weaker copy of that record — and
+// per-recipient READ-RECEIPT tracking is a different, much heavier feature
+// that nothing in #319 asks for.
+// =============================================================================
+
+model NotificationBroadcast {
+  id       String   @id @default(uuid()) @db.Uuid
+  title    String
+  body     String   @db.Text
+  link     String?
+  ctaLabel String?  @map("cta_label")
+  eventKey String   @map("event_key")
+  channels String[]
+
+  status NotificationBroadcastStatus @default(scheduled)
+
+  scheduledFor DateTime? @map("scheduled_for") @db.Timestamptz
+  startedAt    DateTime? @map("started_at") @db.Timestamptz
+  finishedAt   DateTime? @map("finished_at") @db.Timestamptz
+  canceledAt   DateTime? @map("canceled_at") @db.Timestamptz
+
+  // The frozen audience boundary and the paging cursor into it — see the
+  // block comment above for the full mechanism; the two are read together.
+  audienceCutoff DateTime? @map("audience_cutoff") @db.Timestamptz
+  cursorUserId   String?   @map("cursor_user_id") @db.Uuid
+
+  // A snapshot, not a live count: how many users matched `audienceCutoff`
+  // the moment the fan-out started. Nullable because it does not exist
+  // until sending begins (a `scheduled`/`draft` broadcast has no audience
+  // yet). It can legitimately end up HIGHER than `recipientsDispatched` if
+  // users are deactivated mid-flight and the handler skips them — this
+  // column means "targeted at send time", never "should have received it".
+  recipientsTargeted Int? @map("recipients_targeted")
+
+  // How many recipients the fan-out has ATTEMPTED so far — incremented per
+  // dispatch attempt, not per success. Per-channel success/failure is
+  // already recorded, per attempt, in `notification_deliveries`; this
+  // column exists only so the admin list/detail view has a cheap aggregate
+  // progress number without joining or scanning that table, not as a
+  // second, weaker copy of what it already tracks.
+  recipientsDispatched Int @default(0) @map("recipients_dispatched")
+
+  lastError String? @map("last_error") @db.Text
+
+  createdById String?  @map("created_by_id") @db.Uuid
+  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // The audience's organization (#738, PP-8.5). NULL = every active user of
+  // the deployment (a system broadcast, as before #738); set = the ACTIVE
+  // members of that organization only. Read by the start and chunk handlers
+  // from the row (the job payloads carry only the broadcast id, unchanged), so
+  // `audienceWhere(cutoff, targetOrgId)` and the keyset cursor stay one query.
+  // No row-level security on this table: a system broadcast belongs to no
+  // organization, and RLS would hide it from the job that delivers it; the
+  // API authorizes `targetOrgId` instead (`broadcasts:*` may name any org,
+  // `org_broadcasts:*` only the caller's active org). CASCADE: an
+  // organization's broadcasts have no audience once it is deleted.
+  targetOrgId String? @map("target_org_id") @db.Uuid
+
+  // Relations
+  createdBy User?         @relation("BroadcastAuthor", fields: [createdById], references: [id], onDelete: SetNull)
+  targetOrg Organization? @relation("BroadcastTargetOrg", fields: [targetOrgId], references: [id], onDelete: Cascade)
+
+  @@index([status, scheduledFor])
+  @@index([createdAt(sort: Desc)])
+  // A holder of only `org_broadcasts:read` lists its organization's broadcasts.
+  @@index([targetOrgId])
+  @@map("notification_broadcasts")
+}
+
+enum NotificationBroadcastStatus {
+  // Not reachable by any route in #319 — see the block comment above for why
+  // this dead value exists on purpose. Do not remove it as unused.
+  draft
+  scheduled
+  sending
+  sent
+  canceled
+  failed
+}