@12-apps/prisma 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "1.5.0",
+  "version": "1.6.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-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-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",
@@ -44,6 +44,8 @@
     "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"
   },
@@ -62,10 +64,11 @@
     "@12-apps/jobs": "^2.0.0",
     "@12-apps/mcp": "^1.20.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/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,7 @@
     "20260812150000_add_mcp_oauth_tables",
     "20260812150000_add_onboarding_states",
     "20260813120000_add_audit_log",
-    "20260813120000_add_entity_lifecycle_tables"
+    "20260813120000_add_entity_lifecycle_tables",
+    "20260813180000_add_realtime_outbox"
   ]
 }

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")
+}