@12-apps/prisma 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "1.5.0",
+  "version": "1.7.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-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-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,10 +40,14 @@
     "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",
     "prisma:sync-mcp:check": "node scripts/sync-mcp-schema.mjs --check",
+    "prisma:sync-realtime": "node scripts/sync-realtime-schema.mjs",
+    "prisma:sync-realtime:check": "node scripts/sync-realtime-schema.mjs --check",
     "prisma:sync-audit": "node scripts/sync-audit-schema.mjs",
     "prisma:sync-audit:check": "node scripts/sync-audit-schema.mjs --check"
   },
@@ -61,11 +65,13 @@
     "@12-apps/eslint-config": "^1.20.0",
     "@12-apps/jobs": "^2.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.0",
+    "@12-apps/payments-backend": "^2.0.1",
     "@12-apps/product-research": "^2.0.0",
     "@12-apps/rbac": "^2.0.0",
-    "@12-apps/report-builder": "^3.0.0",
+    "@12-apps/realtime": "^1.19.0",
+    "@12-apps/report-builder": "^3.0.1",
     "@12-apps/shift": "^2.0.0",
     "@12-apps/typescript-config": "^1.20.0",
     "@types/node": "^22.10.6",

package/prisma/migration-files.ts

@@ -11,20 +11,23 @@ import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
-/** The folder holding every committed migration, including symlinked ones. */
+/** The folder holding every committed migration, host-owned and plugin alike. */
 const MIGRATIONS_DIR = join(HERE, 'migrations');
 
 /**
  * Every migration directory under `dir`, in timestamp order.
  *
- * `statSync` rather than `Dirent.isDirectory()` on purpose: a package that OWNS
- * part of the schema contributes its migrations as committed SYMLINKS into this
- * folder (Prisma has no cross-package import), and `Dirent.isDirectory()` is
- * FALSE for a symlink. That silently dropped those migrations and left the
- * package's tables missing from every PGlite-backed run — with nothing failing
- * loudly, because the schema was merely incomplete until something queried
- * them. `statSync` follows the link, so an owned migration replays like any
- * other.
+ * A package that OWNS part of the schema contributes its migrations here as
+ * committed COPIES (Prisma has no cross-package import), and `package.test.ts`
+ * gates that nothing under `prisma/` is a symlink.
+ *
+ * `statSync` rather than `Dirent.isDirectory()` even so, because the two differ
+ * exactly where it hurt: these migrations USED to arrive as symlinks, and
+ * `Dirent.isDirectory()` is FALSE for a symlink even when it resolves. That
+ * silently dropped them and left the package's tables missing from every
+ * PGlite-backed run — nothing failed loudly, because the schema was merely
+ * incomplete until something queried them. `statSync` follows a link, so should
+ * one ever reappear here this replay includes it rather than skipping it.
  */
 export function discoverMigrations(dir: string = MIGRATIONS_DIR): string[] {
   return readdirSync(dir)

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/migrations/20260813180000_add_realtime_outbox/migration.sql

@@ -0,0 +1,75 @@
+-- @12-apps/realtime (12-16): the transactional OUTBOX table, owned by the
+-- package and copied into a host's migrations folder by its plugin-migration
+-- sync. Deliberately NO foreign keys and NO tenant column (the
+-- payments-backend doctrine): a row names a TOPIC, and a topic already carries
+-- whatever scope it has (`tenant:<id>:orders`), so there is nothing here for a
+-- host to reconcile with its own tenancy model.
+--
+-- Runs identically on PostgreSQL + PGlite.
+--
+-- ---------------------------------------------------------------------------
+-- EVERY STATEMENT IS GUARDED, AND THE GUARD IS PER COLUMN — NOT PER TABLE.
+-- ---------------------------------------------------------------------------
+-- `CREATE TABLE IF NOT EXISTS` alone is NOT replay-safe, and the way it fails
+-- is silent. It skips the WHOLE table, so a host that already has
+-- `realtime_outbox_events` from an earlier version of this package — or from
+-- its own hand-rolled outbox — adopts this migration, sees it succeed, and
+-- never gets the columns added since. `claimed_at` / `claimed_by` are exactly
+-- that case: the claim protocol is what makes two concurrent drains safe, and
+-- a host silently missing those columns would have every drain fail on an
+-- unknown column, or (worse, if the code were laxer) publish every row twice.
+--
+-- This hazard was PROVEN on PGlite against a sibling package (review of #156:
+-- a host stopped at an earlier migration adopted a guarded `CREATE TABLE` and
+-- the later column never appeared, so the package's client 500'd on every
+-- call). So each column is added with its own `ADD COLUMN IF NOT EXISTS`, and
+-- each index with `IF NOT EXISTS`. The whole file is idempotent and can be
+-- applied to a fresh database, to a database that already has it, and to one
+-- that has an older shape of it.
+--
+-- The two NOT NULL columns with no permanent default get one temporarily and
+-- then drop it: `ADD COLUMN … NOT NULL` fails outright on a table that already
+-- holds rows, and that is precisely the host this guard is for.
+
+CREATE TABLE IF NOT EXISTS "realtime_outbox_events" (
+    "id" TEXT NOT NULL,
+
+    CONSTRAINT "realtime_outbox_events_pkey" PRIMARY KEY ("id")
+);
+
+-- The event itself.
+ALTER TABLE "realtime_outbox_events" ADD COLUMN IF NOT EXISTS "topic" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "realtime_outbox_events" ALTER COLUMN "topic" DROP DEFAULT;
+ALTER TABLE "realtime_outbox_events" ADD COLUMN IF NOT EXISTS "type" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "realtime_outbox_events" ALTER COLUMN "type" DROP DEFAULT;
+-- Identifiers only, never state — the payload rule the whole bus is built on.
+ALTER TABLE "realtime_outbox_events"
+    ADD COLUMN IF NOT EXISTS "data" JSONB NOT NULL DEFAULT '{}';
+
+ALTER TABLE "realtime_outbox_events"
+    ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+-- Null = still pending. Set once the event reached the bus.
+ALTER TABLE "realtime_outbox_events" ADD COLUMN IF NOT EXISTS "published_at" TIMESTAMP(3);
+
+-- The claim protocol. `claimed_at` null (or older than the drainer's lease) is
+-- what makes a row takeable; the claim is a conditional UPDATE, so PostgreSQL
+-- decides the winner and two drains racing one row cannot both publish it.
+ALTER TABLE "realtime_outbox_events" ADD COLUMN IF NOT EXISTS "claimed_at" TIMESTAMP(3);
+ALTER TABLE "realtime_outbox_events" ADD COLUMN IF NOT EXISTS "claimed_by" TEXT;
+-- Counts CLAIMS, not failures: a drainer that crashes mid-publish records no
+-- failure, so a failure counter would let a poison row retry forever.
+ALTER TABLE "realtime_outbox_events"
+    ADD COLUMN IF NOT EXISTS "attempts" INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE "realtime_outbox_events" ADD COLUMN IF NOT EXISTS "last_error" TEXT;
+
+-- The drain's own read (pending rows, oldest `created_at` first) and the purge's
+-- (published rows past a cutoff): ONE composite serves both, because
+-- `published_at` leads it. A separate index on `published_at` alone would be a
+-- redundant prefix — no query it could serve is unserved here — and it would
+-- cost a write amplification on every insert.
+CREATE INDEX IF NOT EXISTS "realtime_outbox_events_published_at_created_at_idx"
+    ON "realtime_outbox_events"("published_at", "created_at");
+-- Dropped rather than never created: an adopter that already applied an earlier
+-- copy of this migration HAS the redundant index, and `IF EXISTS` makes the
+-- removal replay-safe on a database that never did.
+DROP INDEX IF EXISTS "realtime_outbox_events_published_at_idx";

package/prisma/plugin-migrations.json

@@ -29,6 +29,8 @@
     "20260812150000_add_mcp_oauth_tables",
     "20260812150000_add_onboarding_states",
     "20260813120000_add_audit_log",
-    "20260813120000_add_entity_lifecycle_tables"
+    "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")
+}

package/prisma/schema/realtime.prisma

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// @12-apps/realtime — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the transactional OUTBOX table.
+// A host project does NOT copy this model into its main schema by hand: it uses
+// Prisma's multi-file schema folder and SYNCS this file into it (see
+// scripts/sync-realtime-schema.mjs beside this folder, and
+// packages/prisma/scripts/sync-realtime-schema.mjs in this repo for the host
+// side — run before `prisma generate`). The migration ships alongside, in
+// prisma/migrations/, and is COPIED into the host's migrations folder — never
+// symlinked, because Prisma enumerates that folder with lstat and silently
+// skips a linked directory.
+//
+// Host-agnostic by design: a row names a TOPIC, and a topic already carries
+// whatever scope it has (`tenant:<id>:orders`, `user:<id>:notifications`). So
+// there is no `client_id`, no relation to any host table, and nothing here for
+// a host to reconcile with its own tenancy model.
+// ---------------------------------------------------------------------------
+
+/// One domain event awaiting publication onto the realtime bus.
+///
+/// Written INSIDE the same transaction as the domain write it describes, so the
+/// event cannot exist without its cause nor the cause without its event, and
+/// drained afterwards by a worker (`createRealtimeOutbox({ db }).drain()`).
+/// That closes the window an inline `publishRealtimeEvent` leaves open: a
+/// process that dies between the commit and the publish loses the event with no
+/// trace at all.
+///
+/// The delivery guarantee is AT-LEAST-ONCE publication with idempotent
+/// consumers, and it is stated that way rather than dressed up: a drainer that
+/// dies after publishing but before marking will publish again once its claim
+/// lease expires. Duplicates are harmless by construction because an event
+/// carries identifiers rather than state — acting on it twice means re-reading
+/// twice — and `id` travels as the emission id so a consumer that wants
+/// explicit de-duplication has a stable key.
+model RealtimeOutboxEvent {
+  id    String @id @default(uuid())
+  /// Fully-qualified topic name, e.g. `tenant:<clientId>:orders`.
+  topic String
+  /// Dot-namespaced event type, stable on the wire: `orders.changed`.
+  type  String
+  /// Identifiers only, never state — the payload rule the whole bus is built on.
+  data  Json   @default("{}")
+
+  createdAt DateTime @default(now()) @map("created_at")
+  /// Set once the event reached the bus. Null = still pending.
+  publishedAt DateTime? @map("published_at")
+
+  /// When a drainer took ownership. Null = free to claim.
+  ///
+  /// A LEASE, not a lock: the holder may have died and nothing can tell the
+  /// difference from outside, so a claim older than the configured lease is
+  /// takeable. The claim itself is a conditional UPDATE, so the database
+  /// decides the winner — two drains racing one row cannot both publish it.
+  claimedAt DateTime? @map("claimed_at")
+  /// Which drainer holds the claim; the mark only ever matches its own holder.
+  claimedBy String?   @map("claimed_by")
+  /// How many times this row has been CLAIMED (not how many times it failed).
+  ///
+  /// Counting claims rather than failures is what bounds a poison row: a
+  /// drainer that crashes mid-publish records no failure, so a failure counter
+  /// would let a row that kills the process be retried forever.
+  attempts  Int       @default(0)
+  /// Why the last publish did not reach the bus, for the operator reading a
+  /// row that ran out of attempts.
+  lastError String?   @map("last_error")
+
+  /// The drain's own read (pending rows oldest first), and the purge's
+  /// (published rows past a cutoff) — one composite serves both, because
+  /// `published_at` leads it. A separate `@@index([publishedAt])` is a
+  /// redundant PREFIX of this one: no query it could serve is unserved here,
+  /// and it costs a write amplification on every insert.
+  @@index([publishedAt, createdAt])
+  @@map("realtime_outbox_events")
+}