@12-apps/prisma 1.6.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "Prisma host: the multi-file schema folder, the plugin migration seam, and the shared PrismaClient singleton with its audit / append-only extensions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "scripts": {
-    "build": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-realtime-schema.mjs --check && node scripts/sync-audit-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate && tsc",
+    "build": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-notifications-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-realtime-schema.mjs --check && node scripts/sync-audit-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate && tsc",
     "clean": "rm -rf dist node_modules coverage",
     "test": "node ../../scripts/vitest-with-teardown.mjs run",
     "test:watch": "vitest watch",
@@ -20,7 +20,7 @@
     "lint": "pnpm run lint:files .",
     "lint:fix": "bash -c 'eslint \"${@:-.}\" --max-warnings 0 --fix' _",
     "typecheck": "tsc --noEmit",
-    "prisma:generate": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-realtime-schema.mjs --check && node scripts/sync-audit-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate",
+    "prisma:generate": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-notifications-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-realtime-schema.mjs --check && node scripts/sync-audit-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate",
     "prisma:migrate": "prisma migrate dev",
     "prisma:push": "prisma db push",
     "prisma:studio": "prisma studio",
@@ -40,6 +40,8 @@
     "prisma:sync-plugins:check": "node scripts/sync-prisma-plugins.mjs --check",
     "prisma:sync-rbac": "node scripts/sync-rbac-schema.mjs",
     "prisma:sync-rbac:check": "node scripts/sync-rbac-schema.mjs --check",
+    "prisma:sync-notifications": "node scripts/sync-notifications-schema.mjs",
+    "prisma:sync-notifications:check": "node scripts/sync-notifications-schema.mjs --check",
     "prisma:sync-onboarding": "node scripts/sync-onboarding-schema.mjs",
     "prisma:sync-onboarding:check": "node scripts/sync-onboarding-schema.mjs --check",
     "prisma:sync-mcp": "node scripts/sync-mcp-schema.mjs",
@@ -57,18 +59,19 @@
     "pglite-prisma-adapter": "0.7.2"
   },
   "devDependencies": {
-    "@12-apps/audit": "^1.0.0",
-    "@12-apps/entitlements": "^1.20.1",
+    "@12-apps/audit": "^2.0.0",
+    "@12-apps/entitlements": "^2.0.0",
     "@12-apps/entity-lifecycle": "^2.1.0",
     "@12-apps/eslint-config": "^1.20.0",
-    "@12-apps/jobs": "^2.0.0",
+    "@12-apps/jobs": "^3.0.0",
     "@12-apps/mcp": "^1.20.0",
+    "@12-apps/notifications": "^1.0.0",
     "@12-apps/onboarding": "^1.20.0",
-    "@12-apps/payments-backend": "^2.0.1",
+    "@12-apps/payments-backend": "^2.1.0",
     "@12-apps/product-research": "^2.0.0",
-    "@12-apps/rbac": "^2.0.0",
+    "@12-apps/rbac": "^3.0.0",
     "@12-apps/realtime": "^1.19.0",
-    "@12-apps/report-builder": "^3.0.1",
+    "@12-apps/report-builder": "^4.0.0",
     "@12-apps/shift": "^2.0.0",
     "@12-apps/typescript-config": "^1.20.0",
     "@types/node": "^22.10.6",

package/prisma/migrations/20260813140000_add_notification_tables/migration.sql

@@ -0,0 +1,218 @@
+-- @12-apps/notifications (12-15): the four generic notification tables, owned
+-- by the package and copied into a host's migrations folder by its
+-- plugin-migration sync. Runs identically on PostgreSQL + PGlite.
+--
+-- NO foreign keys into host tables (the payments-backend doctrine): `user_id`
+-- and `client_id` are by-value scalars, and the host's own migration may add FK
+-- constraints (recommended: both ON DELETE CASCADE). The relation INTERNAL to
+-- the partial — notification_deliveries -> notifications — IS constrained, with
+-- a cascade, so a purged notification can never leave orphan delivery rows.
+--
+-- `channel` and `status` carry CHECKs: those are the LIBRARY's own closed sets,
+-- and a row outside them is a row no transport can carry. `category` does NOT,
+-- for the reason `@12-apps/rbac` gives for `role`: the category set is host
+-- vocabulary (`categories` on the server config), so a closed set here would be
+-- wrong for every host but the first. A host that wants its own CHECK adds one.
+--
+-- The `status` set is QUEUED | SENDING | SENT | FAILED | DEAD. `SENDING` is the
+-- dispatcher's CLAIM and `DEAD` is terminal (see `src/server/dispatch.ts`), and
+-- both are newer than the first adopters' hand-made tables — which is why the
+-- status CHECK below is DROPPED and re-added rather than guarded by a
+-- `pg_constraint` lookup like the others. An existence guard would find the
+-- three-value constraint an early adopter already has, skip, and leave the claim
+-- rejected at runtime by a CHECK that predates it.
+--
+-- ============================ REPLAY SAFETY ================================
+-- Every statement is guarded, because the first adopters ALREADY HAVE these
+-- tables: future-pay created them by hand before the package existed, so this
+-- migration must be a no-op there and correct on an empty database.
+--
+-- The guards are per COLUMN, not per table. `CREATE TABLE IF NOT EXISTS` alone
+-- is the trap: it skips the whole table, so a host whose table predates a
+-- column silently never gets that column and the failure surfaces later as a
+-- missing-column error in production. So each table is followed by one
+-- `ADD COLUMN IF NOT EXISTS` per column, and every NOT NULL column carries a
+-- DEFAULT — a NOT NULL column with no default cannot be added to a table that
+-- already holds rows.
+--
+-- CHECK constraints have no `IF NOT EXISTS` form, so they are guarded by a
+-- `pg_constraint` lookup instead (plpgsql, which PGlite has) — EXCEPT the
+-- delivery status CHECK, which must CONVERGE rather than be skipped and so is
+-- `DROP CONSTRAINT IF EXISTS` + `ADD`. Same for the sweep's index, which moved
+-- key: `DROP INDEX IF EXISTS` + `CREATE INDEX IF NOT EXISTS`. Both are
+-- idempotent, which is the property replay safety actually needs — "guarded" was
+-- only ever the usual way to get it, and it is the wrong way when the definition
+-- itself has changed under an existing adopter.
+
+-- ---------------------------------------------------------------------------
+-- notifications — the always-on inbox. One row per emit, written before any
+-- transport is consulted.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "notifications" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "client_id" TEXT,
+    "type" TEXT NOT NULL,
+    "category" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "body" TEXT NOT NULL,
+    "link" TEXT,
+    "data" JSONB NOT NULL DEFAULT '{}',
+    "read_at" TIMESTAMP(3),
+    "deleted_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notifications_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "user_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "client_id" TEXT;
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "type" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "category" TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "title" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "body" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "link" TEXT;
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "data" JSONB NOT NULL DEFAULT '{}';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "read_at" TIMESTAMP(3);
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "deleted_at" TIMESTAMP(3);
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+-- Inbox list (owner, not-deleted, newest first) + the unread badge count.
+CREATE INDEX IF NOT EXISTS "notifications_user_id_deleted_at_created_at_idx"
+    ON "notifications"("user_id", "deleted_at", "created_at");
+CREATE INDEX IF NOT EXISTS "notifications_user_id_deleted_at_read_at_idx"
+    ON "notifications"("user_id", "deleted_at", "read_at");
+
+-- ---------------------------------------------------------------------------
+-- notification_deliveries — one row per channel the router fanned out to.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "notification_deliveries" (
+    "id" TEXT NOT NULL,
+    "notification_id" TEXT NOT NULL,
+    "channel" TEXT NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'QUEUED',
+    "error" TEXT,
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "sent_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notification_deliveries_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "notification_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "channel" TEXT NOT NULL DEFAULT 'EMAIL';
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "status" TEXT NOT NULL DEFAULT 'QUEUED';
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "error" TEXT;
+-- The retry ceiling's counter (12-15). An adopter whose table predates it gets
+-- it at 0, which reads as "never claimed" — the correct starting point for a row
+-- that has, in the new lifecycle's terms, spent no attempts.
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "attempts" INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "sent_at" TIMESTAMP(3);
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+-- The library's own closed sets. A delivery outside them is a delivery no
+-- transport can carry, so the schema refuses it rather than the router.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'notification_deliveries_channel_check'
+  ) THEN
+    ALTER TABLE "notification_deliveries"
+      ADD CONSTRAINT "notification_deliveries_channel_check"
+      CHECK ("channel" IN ('EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'));
+  END IF;
+END $$;
+
+-- The status set, DROP-and-re-ADD rather than guarded (see the header): the
+-- values widened in 12-15, so an adopter already holding a constraint under this
+-- name holds the OLD three, and a guard would keep it — rejecting the claim's
+-- own UPDATE. Idempotent, and re-running it converges rather than accumulating.
+ALTER TABLE "notification_deliveries"
+    DROP CONSTRAINT IF EXISTS "notification_deliveries_status_check";
+ALTER TABLE "notification_deliveries"
+    ADD CONSTRAINT "notification_deliveries_status_check"
+    CHECK ("status" IN ('QUEUED', 'SENDING', 'SENT', 'FAILED', 'DEAD'));
+
+-- Idempotent fan-out: re-dispatching a notification can never duplicate a
+-- channel's delivery row. This is what makes transport sends retry-safe.
+CREATE UNIQUE INDEX IF NOT EXISTS "notification_deliveries_notification_id_channel_key"
+    ON "notification_deliveries"("notification_id", "channel");
+-- Serves the retry sweep, which selects `status IN (…) AND updated_at < cutoff`.
+-- On `updated_at`, not `created_at`: the sweep asks "has this row moved lately",
+-- and `created_at` cannot answer that — a row re-queued a second ago still
+-- carries a `created_at` from days back, so it reads as stale again immediately.
+-- The `(status, created_at)` index this replaces served the earlier, wrong
+-- predicate and is dropped rather than left behind to cost every write.
+DROP INDEX IF EXISTS "notification_deliveries_status_created_at_idx";
+CREATE INDEX IF NOT EXISTS "notification_deliveries_status_updated_at_idx"
+    ON "notification_deliveries"("status", "updated_at");
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'notification_deliveries_notification_id_fkey'
+  ) THEN
+    ALTER TABLE "notification_deliveries"
+      ADD CONSTRAINT "notification_deliveries_notification_id_fkey"
+      FOREIGN KEY ("notification_id") REFERENCES "notifications"("id")
+      ON DELETE CASCADE ON UPDATE CASCADE;
+  END IF;
+END $$;
+
+-- ---------------------------------------------------------------------------
+-- notification_preferences — EXPLICIT choices only; no row means the defaults.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "notification_preferences" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "category" TEXT NOT NULL,
+    "channels" JSONB NOT NULL DEFAULT '{}',
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notification_preferences_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "user_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "category" TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "channels" JSONB NOT NULL DEFAULT '{}';
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+CREATE UNIQUE INDEX IF NOT EXISTS "notification_preferences_user_id_category_key"
+    ON "notification_preferences"("user_id", "category");
+
+-- ---------------------------------------------------------------------------
+-- push_subscriptions — the Web Push destination, one row per browser.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "push_subscriptions" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "endpoint" TEXT NOT NULL,
+    "p256dh" TEXT NOT NULL,
+    "auth" TEXT NOT NULL,
+    "user_agent" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "push_subscriptions_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "user_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "endpoint" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "p256dh" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "auth" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "user_agent" TEXT;
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+-- The push-service endpoint is globally unique per subscription — registering
+-- the same browser again upserts rather than duplicates.
+CREATE UNIQUE INDEX IF NOT EXISTS "push_subscriptions_endpoint_key"
+    ON "push_subscriptions"("endpoint");
+CREATE INDEX IF NOT EXISTS "push_subscriptions_user_id_idx"
+    ON "push_subscriptions"("user_id");

package/prisma/plugin-migrations.json

@@ -30,6 +30,7 @@
     "20260812150000_add_onboarding_states",
     "20260813120000_add_audit_log",
     "20260813120000_add_entity_lifecycle_tables",
+    "20260813140000_add_notification_tables",
     "20260813180000_add_realtime_outbox"
   ]
 }

package/prisma/schema/notifications.prisma

@@ -0,0 +1,141 @@
+// @12-apps/notifications (12-15) — the four models the notification system
+// owns, COPIED into a host's schema folder by
+// `pnpm --filter @12-apps/notifications prisma:sync` (never symlinked: Prisma
+// lstats a migration directory, so a symlinked migration is silently skipped
+// and a green deploy applies no schema).
+//
+// Deliberately NO foreign keys into host tables (the payments-backend
+// doctrine): `user_id` and `client_id` are by-value scalars, and the host's own
+// migration may add FK constraints (recommended: both ON DELETE CASCADE, so a
+// deleted account takes its inbox with it). The relation INTERNAL to the
+// partial — notification_deliveries -> notifications — IS constrained, with a
+// cascade, so a purged notification can never leave orphan delivery rows.
+//
+// Do not edit a synced copy by hand: the next sync reverts it and
+// `prisma:sync:check` goes red in CI.
+
+// One inbox entry — the always-on channel. Written for EVERY emit, before any
+// transport is consulted, which is what makes "the user was told" true even
+// when every provider is down. `type` is an open dot-namespaced set validated
+// by the generator registry at the emit site (deliberately no CHECK, so a new
+// notification type ships without a migration). `category` has NO CHECK either,
+// and for a stronger reason: the category set is HOST vocabulary (`categories`
+// on the server config), so a closed set in the schema would be wrong for every
+// adopter but the first. A host that wants its own taxonomy enforced adds the
+// CHECK in a migration of its own — future-pay does. Only `channel` and `status`
+// on the delivery row are closed here, because those two are the LIBRARY's.
+model Notification {
+  id        String    @id @default(uuid())
+  userId    String    @map("user_id")
+  clientId  String?   @map("client_id")
+  type      String
+  category  String
+  title     String
+  body      String
+  link      String?
+  data      Json      @default("{}")
+  readAt    DateTime? @map("read_at")
+  deletedAt DateTime? @map("deleted_at")
+  createdAt DateTime  @default(now()) @map("created_at")
+  updatedAt DateTime  @updatedAt @map("updated_at")
+
+  deliveries NotificationDelivery[]
+
+  // The inbox list (owner, not-deleted, newest first) and the unread-count
+  // badge (owner, not-deleted, unread) — both single-index scans.
+  @@index([userId, deletedAt, createdAt])
+  @@index([userId, deletedAt, readAt])
+  @@map("notifications")
+}
+
+// Per-channel delivery tracking for one Notification: one row per transport
+// channel the router fanned out to, carrying the channel lifecycle and the
+// provider error when a send fails. `channel` is EMAIL | SMS | WHATSAPP |
+// WEB_PUSH (CHECK in the migration).
+//
+// The lifecycle is QUEUED -> SENDING -> SENT | FAILED | DEAD (String + DB
+// CHECK), and the two states beyond the obvious three each remove a way to send
+// somebody a duplicate paid message:
+//
+//   - SENDING is the CLAIM. A dispatcher moves the row out of QUEUED with one
+//     conditional UPDATE and sends only if it moved exactly one row, so two
+//     dispatchers racing the same delivery make exactly one provider call.
+//     `attempts` is incremented by that same claim.
+//   - DEAD is TERMINAL, reached at the `attempts` ceiling. Without it a
+//     permanently invalid destination is a billed provider call on every sweep
+//     for the life of the row.
+//
+// `@@unique([notificationId, channel])` makes fan-out idempotent — re-dispatching
+// a notification can never enqueue a duplicate delivery. Failures are isolated
+// per row: one channel failing never blocks the inbox record or the others.
+model NotificationDelivery {
+  id             String    @id @default(uuid())
+  notificationId String    @map("notification_id")
+  channel        String
+  status         String    @default("QUEUED")
+  error          String?
+  /// Claims spent on this row. The retry ceiling counts these, not failures, so
+  /// a dispatcher that dies mid-send still spends one and cannot loop forever.
+  attempts       Int       @default(0)
+  sentAt         DateTime? @map("sent_at")
+  createdAt      DateTime  @default(now()) @map("created_at")
+  updatedAt      DateTime  @updatedAt @map("updated_at")
+
+  notification Notification @relation(fields: [notificationId], references: [id], onDelete: Cascade)
+
+  @@unique([notificationId, channel])
+  // Serves the retry sweep: `status IN (…) AND updated_at < cutoff`. On
+  // `updatedAt`, because "stale" is a question about the last write and
+  // `createdAt` cannot answer it — a row re-queued a second ago has an ancient
+  // `created_at` and would read as stale again immediately.
+  @@index([status, updatedAt])
+  @@map("notification_deliveries")
+}
+
+// A user's channel choices for ONE notification category: which of the
+// transport channels may carry notifications of that category to them. One row
+// per (user, category); NO row = the code-level defaults apply (email + web
+// push on, the paid per-message channels off), so the table only ever stores
+// EXPLICIT choices. The inbox is NOT a channel here — it is always on and not
+// preference-gated.
+//
+// `channels` is a JSON map { "EMAIL": true, "SMS": false, … } rather than one
+// boolean column per channel: the channel set is open-ended, and a new
+// transport must not need a schema change — the open/closed rule the whole
+// pipeline is built on. A stored row missing a channel key falls back to that
+// channel's default, which is what makes the arrival of a channel a no-op for
+// every existing row.
+model NotificationPreference {
+  id        String   @id @default(uuid())
+  userId    String   @map("user_id")
+  category  String
+  channels  Json     @default("{}")
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([userId, category])
+  @@map("notification_preferences")
+}
+
+// One browser push subscription registered by a user's device — the Web Push
+// transport's destination, exactly as `PushManager.subscribe()` returns it: the
+// push-service `endpoint` (globally unique per subscription, hence @unique —
+// re-registering the same browser upserts rather than duplicates) plus the
+// `p256dh`/`auth` client keys the RFC 8291 payload encryption needs. A user may
+// hold many rows (one per browser/device); the transport sends to all of them.
+// A subscription the push service reports GONE (404/410) is pruned by the
+// transport, so the table self-heals as browsers expire subscriptions.
+model PushSubscription {
+  id        String   @id @default(uuid())
+  userId    String   @map("user_id")
+  endpoint  String   @unique
+  p256dh    String
+  auth      String
+  // Free-form browser/device hint ("Chrome · Linux") for a device list.
+  userAgent String?  @map("user_agent")
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@index([userId])
+  @@map("push_subscriptions")
+}