@12-apps/prisma 1.0.0 → 1.2.0

package/README.md

@@ -60,8 +60,15 @@ their own folder, and this package pulls them in:
 | `@12-apps/product-research` | `product-research.prisma` | `scripts/sync-research-schema.mjs` |
 | `@12-apps/shift` | `shift.prisma` | `scripts/sync-shift-schema.mjs` |
 | `@12-apps/jobs` | `jobs.prisma` | `scripts/sync-jobs-schema.mjs` |
-| `@12-apps/payments-backend` | `payments.prisma` | committed symlink |
-| `@12-apps/report-builder` | `report-builder.prisma` | committed symlink |
+| `@12-apps/entitlements` | `entitlements.prisma` | `scripts/sync-entitlements-schema.mjs` |
+| `@12-apps/payments-backend` | `payments.prisma` | `scripts/sync-payments-schema.mjs` |
+| `@12-apps/report-builder` | `report-builder.prisma` | `scripts/sync-report-builder-schema.mjs` |
+
+Every partial is a committed **COPY** — never a symlink, with no exceptions.
+`payments.prisma` and `report-builder.prisma` used to be symlinks, and the
+published tarball shipped without them: `npm pack` silently drops symlinked
+entries, exactly the way Prisma's migration walk skips a linked migration.
+The `--check` syncs and `package.test.ts`'s no-symlink walk keep it true.
 
 Migrations travel separately, through `scripts/sync-prisma-plugins.mjs`, which
 discovers every plugin-owned `migrations` directory **structurally** rather than
@@ -71,11 +78,16 @@ from a hardcoded list.
 deliberately owns no domain models, and no seed command either. The consuming
 application supplies both.
 
-Two rules that came from production incidents, gated by `package.test.ts`:
+Three rules that came from production incidents, gated by `package.test.ts`:
 
 - **Migrations are copied, never symlinked.** Prisma enumerates the migrations
   folder with `lstat`, so a symlinked migration reports `isDirectory() === false`
   and is silently skipped — a green deploy that changed no schema.
+- **Schema partials are copies too — nothing under `prisma/` may be a symlink.**
+  `npm pack` drops symlinked entries from the tarball with no warning, so the
+  published package shipped a schema folder missing three models. A structural
+  walk asserts zero symlinks, and a pack-manifest gate asks `npm pack
+  --dry-run` itself that every partial and migration ships.
 - **A partial's owning package must be a declared workspace dependency.**
   `turbo prune` copies only what the dependency graph reaches; an undeclared
   owner is dropped from the build context, the committed partial's source

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "1.0.0",
+  "version": "1.2.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-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-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-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-prisma-plugins.mjs --check && prisma generate",
     "prisma:migrate": "prisma migrate dev",
     "prisma:push": "prisma db push",
     "prisma:studio": "prisma studio",
@@ -30,8 +30,16 @@
     "prisma:sync-shift:check": "node scripts/sync-shift-schema.mjs --check",
     "prisma:sync-jobs": "node scripts/sync-jobs-schema.mjs",
     "prisma:sync-jobs:check": "node scripts/sync-jobs-schema.mjs --check",
+    "prisma:sync-entitlements": "node scripts/sync-entitlements-schema.mjs",
+    "prisma:sync-entitlements:check": "node scripts/sync-entitlements-schema.mjs --check",
+    "prisma:sync-payments": "node scripts/sync-payments-schema.mjs",
+    "prisma:sync-payments:check": "node scripts/sync-payments-schema.mjs --check",
+    "prisma:sync-report-builder": "node scripts/sync-report-builder-schema.mjs",
+    "prisma:sync-report-builder:check": "node scripts/sync-report-builder-schema.mjs --check",
     "prisma:sync-plugins": "node scripts/sync-prisma-plugins.mjs",
-    "prisma:sync-plugins:check": "node scripts/sync-prisma-plugins.mjs --check"
+    "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"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.2.17",
@@ -41,11 +49,13 @@
     "pglite-prisma-adapter": "0.7.2"
   },
   "devDependencies": {
+    "@12-apps/entitlements": "^1.20.1",
     "@12-apps/entity-lifecycle": "^2.0.0",
     "@12-apps/eslint-config": "^1.20.0",
     "@12-apps/jobs": "^2.0.0",
     "@12-apps/payments-backend": "^2.0.0",
     "@12-apps/product-research": "^2.0.0",
+    "@12-apps/rbac": "^1.19.0",
     "@12-apps/report-builder": "^3.0.0",
     "@12-apps/shift": "^2.0.0",
     "@12-apps/typescript-config": "^1.20.0",

package/prisma/migrations/20260812120000_add_rbac_tables/migration.sql

@@ -0,0 +1,113 @@
+-- @12-apps/rbac (12-13): the five generic RBAC tables, owned by the package
+-- and copied into a host's migrations folder by its plugin-migration sync.
+-- Deliberately NO foreign keys into host tables (self-contained package
+-- schema, the payments-backend doctrine): `user_id` and `client_id` are
+-- by-value scalars, and the host's own migration may add FK constraints.
+-- Relations INTERNAL to the partial (membership_roles -> memberships/roles)
+-- ARE constrained, with cascades, so a removed membership or deleted role can
+-- never leave a dangling grant. `role`/`kind` carry no CHECK here: the role
+-- catalog is host config, so a closed set would be wrong for every host but
+-- the first.
+
+CREATE TABLE "memberships" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "role" TEXT NOT NULL DEFAULT 'CUSTOMER',
+    "active" BOOLEAN NOT NULL DEFAULT true,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "memberships_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "memberships_user_id_client_id_key" ON "memberships"("user_id", "client_id");
+CREATE INDEX "memberships_client_id_idx" ON "memberships"("client_id");
+CREATE INDEX "memberships_user_id_idx" ON "memberships"("user_id");
+
+CREATE TABLE "roles" (
+    "id" TEXT NOT NULL,
+    "client_id" TEXT,
+    "name" TEXT NOT NULL,
+    "permissions" TEXT NOT NULL,
+    "description" TEXT,
+    "is_template" BOOLEAN NOT NULL DEFAULT true,
+    "kind" TEXT NOT NULL DEFAULT 'CUSTOM',
+    "locked" BOOLEAN NOT NULL DEFAULT false,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "archived_at" TIMESTAMP(3),
+    "published_version" INTEGER NOT NULL DEFAULT 0,
+
+    CONSTRAINT "roles_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "roles_client_id_name_key" ON "roles"("client_id", "name");
+CREATE INDEX "roles_client_id_idx" ON "roles"("client_id");
+CREATE INDEX "roles_client_id_archived_at_idx" ON "roles"("client_id", "archived_at");
+-- Postgres treats NULL client_id as distinct in the unique above, so TEMPLATE
+-- (platform) role names need their own partial unique index — Prisma cannot
+-- express a filtered index, hence raw SQL.
+CREATE UNIQUE INDEX "roles_template_name_key" ON "roles"("name") WHERE "client_id" IS NULL;
+
+CREATE TABLE "membership_roles" (
+    "id" TEXT NOT NULL,
+    "membership_id" TEXT NOT NULL,
+    "role_id" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "membership_roles_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "membership_roles_membership_id_role_id_key" ON "membership_roles"("membership_id", "role_id");
+CREATE INDEX "membership_roles_membership_id_idx" ON "membership_roles"("membership_id");
+CREATE INDEX "membership_roles_role_id_idx" ON "membership_roles"("role_id");
+
+ALTER TABLE "membership_roles"
+  ADD CONSTRAINT "membership_roles_membership_id_fkey"
+    FOREIGN KEY ("membership_id") REFERENCES "memberships"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "membership_roles"
+  ADD CONSTRAINT "membership_roles_role_id_fkey"
+    FOREIGN KEY ("role_id") REFERENCES "roles"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+CREATE TABLE "role_assignments" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "role_name" TEXT NOT NULL,
+    "scope" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "role_assignments_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "role_assignments_user_id_role_name_scope_key" ON "role_assignments"("user_id", "role_name", "scope");
+CREATE INDEX "role_assignments_user_id_idx" ON "role_assignments"("user_id");
+CREATE INDEX "role_assignments_scope_idx" ON "role_assignments"("scope");
+
+CREATE TABLE "resource_assignments" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "resource_type" TEXT NOT NULL,
+    "resource_id" TEXT NOT NULL,
+    "valid_from" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "valid_to" TIMESTAMP(3),
+
+    CONSTRAINT "resource_assignments_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX "resource_assignments_user_id_resource_type_idx" ON "resource_assignments"("user_id", "resource_type") WHERE "valid_to" IS NULL;
+CREATE INDEX "resource_assignments_client_id_resource_type_resource_id_idx" ON "resource_assignments"("client_id", "resource_type", "resource_id");
+
+-- At most ONE active assignment per (user, tenant, resource). Two concurrent
+-- requests could each INSERT a new active row; a partial UNIQUE index over the
+-- ACTIVE rows makes the second concurrent insert fail at the DB rather than
+-- relying on a racy app-level check-then-insert. Added while the table is
+-- EMPTY (free) -- it is much harder to add later once live data may already
+-- contain duplicates. Prisma cannot express a filtered index, hence raw SQL
+-- (the same reason as roles_template_name_key above). Revocation stamps
+-- valid_to, so historical rows never collide.
+CREATE UNIQUE INDEX "resource_assignments_active_unique_idx"
+  ON "resource_assignments"("user_id", "client_id", "resource_type", "resource_id")
+  WHERE "valid_to" IS NULL;

package/prisma/migrations/20260812120000_add_retention_watermarks/migration.sql

@@ -0,0 +1,18 @@
+-- The "downgrade never deletes" anchor for retention quotas: one row per
+-- (tenant, retention feature) recording when the CURRENT window took effect.
+-- The retention sweep only prunes rows written after "since", so a shrinking
+-- window never retroactively destroys history accumulated while the tenant
+-- was entitled to keep it longer.
+--
+-- No foreign key into any host table on purpose (the payments doctrine):
+-- tenant scoping is a plain client_id column, and the host repository layer
+-- is the tenant boundary.
+CREATE TABLE "retention_watermarks" (
+    "client_id" TEXT NOT NULL,
+    "feature" TEXT NOT NULL,
+    "window_days" INTEGER NOT NULL,
+    "since" TIMESTAMP(3) NOT NULL,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "retention_watermarks_pkey" PRIMARY KEY ("client_id", "feature")
+);

package/prisma/plugin-migrations.json

@@ -23,6 +23,8 @@
     "20260731210000_shift_delete_guard",
     "20260810120000_add_report_default_range",
     "20260810160000_report_default_range_month",
-    "20260810180000_add_report_working_copy"
+    "20260810180000_add_report_working_copy",
+    "20260812120000_add_rbac_tables",
+    "20260812120000_add_retention_watermarks"
   ]
 }

package/prisma/schema/entitlements.prisma

@@ -0,0 +1,35 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// OWNED BY @12-apps/entitlements — the host's multi-file schema folder holds
+// only a copy/symlink of this file (created/verified by `pnpm --filter
+// @12-apps/entitlements prisma:sync`): the retention persistence model lives
+// here, in the package, never in the application.
+//
+// Deliberately self-contained (the payments-backend doctrine): tenant scoping
+// is a `client_id` String column — NO foreign key into any host table — so the
+// model works in every repo without schema coupling. The host repository layer
+// is the tenant boundary: every read/write is `clientId`-scoped.
+//
+// Note what is NOT here: Plan, Subscription, PlanChangeRequest. Those are
+// BILLING models and stay in the host — this package must not learn about
+// money. The only table the entitlement machinery itself needs is the
+// retention watermark below.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The "downgrade never deletes" anchor for retention quotas: one row per
+// (tenant, retention feature) recording when the CURRENT window took effect.
+// The retention sweep only prunes rows written after `since`, so a shrinking
+// window never retroactively destroys history accumulated while the tenant
+// was entitled to keep it longer (see src/server/retention.ts).
+model RetentionWatermark {
+  clientId   String   @map("client_id")
+  /// The quota feature key, e.g. "audit.retention_days".
+  feature    String
+  /// The window (days) in force since `since`.
+  windowDays Int      @map("window_days")
+  /// When the sweep first observed the current window for this tenant.
+  since      DateTime
+  updatedAt  DateTime @updatedAt @map("updated_at")
+
+  @@id([clientId, feature])
+  @@map("retention_watermarks")
+}

package/prisma/schema/payments.prisma

@@ -0,0 +1,218 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// OWNED BY @12-apps/payments-backend — the host's multi-file schema folder holds
+// only a SYMLINK to this file (created/verified by `pnpm --filter
+// @12-apps/payments-backend prisma:sync`): every payment model lives here, in
+// the package, never in the application.
+//
+// Deliberately self-contained: merchant scoping is (merchant_kind,
+// merchant_id) String columns — NO foreign key into any host table — so the
+// same three models work in every repo (and in a future standalone payments
+// service) without schema coupling. String-over-enum house style; the CHECK
+// constraints live in the migration.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// One (merchant, provider) connection: enablement, rank in the failover
+// chain, active environment, verification state, and the AES-encrypted
+// credential blob (both environments' decrypted shape is
+// `StoredProviderConfig.environments`, ciphered as ONE JSON blob by the
+// host's cipher — never plaintext at rest).
+model PaymentProviderConfig {
+  id             String    @id @default(uuid())
+  // PLATFORM | TENANT (CHECK in migration).
+  merchantKind   String    @map("merchant_kind")
+  merchantId     String    @map("merchant_id")
+  provider       String
+  // In the failover chain (enabled) vs merely configured. A merchant may
+  // keep credentials for a provider it has taken out of rotation.
+  enabled        Boolean   @default(false)
+  // Rank in the failover chain, ASCENDING — 0 is tried first. Meaningful
+  // only while `enabled`; the migration's partial unique index keeps ranks
+  // distinct among a merchant's enabled rows so routing is never ambiguous.
+  priority       Int       @default(0)
+  // SANDBOX | PRODUCTION (CHECK in migration).
+  environment    String    @default("SANDBOX")
+  // UNVERIFIED | VERIFIED | FAILED | RECONNECT_REQUIRED (CHECK in migration).
+  status         String    @default("UNVERIFIED")
+  lastVerifiedAt DateTime? @map("last_verified_at")
+  // When a real charge through THIS connection last succeeded — the only
+  // thing that may put the row in the failover chain (FUT-463).
+  //
+  // Distinct from `lastVerifiedAt`, which the credential PROBE stamps: the
+  // probe asks "do these keys authenticate", and a PagBank connection answers
+  // yes while refusing every real charge with `403 ACCESS_DENIED` until the
+  // integration is homologated. A store read `VERIFIED`, was switched on by
+  // hand, and every shopper was declined.
+  //
+  // Its own nullable column rather than being inferred from `enabled`, because
+  // the two answer different questions: this one is "was it ever proven",
+  // which must SURVIVE an owner switching the provider off and back on.
+  chargeVerifiedAt DateTime? @map("charge_verified_at")
+  // The activation charge currently OUTSTANDING: `{ reference, checkoutUrl,
+  // slug, startedAt }`, or null when none is in flight (FUT-463).
+  //
+  // It has to be durable, and the reason is money. The attempt used to live in
+  // React state, so a refresh — or simply coming back to the tab after paying
+  // on the provider's site — erased it and offered to "generate a charge"
+  // again. That mints a SECOND real charge on the owner's own card, and the
+  // first one, already paid, is never looked at again.
+  //
+  // It also carries what confirmation needs and creation is the only chance to
+  // learn: InfinitePay's `payment_check` wants `slug` (the invoice code, in the
+  // link response) alongside `order_nsu`, and asking with the reference alone
+  // answers "not paid" forever — which is exactly what it did to a genuinely
+  // paid R$ 1,01, right up to the ten-minute timeout that then blamed the owner
+  // for not paying in time.
+  pendingVerification Json? @map("pending_verification")
+  // When an OAuth connection stops working. Its own column (not inside the
+  // encrypted blob) so a refresh sweep can query it; null for credential-mode
+  // providers, which never expire.
+  expiresAt      DateTime? @map("expires_at")
+  stub           Boolean   @default(false)
+  // Cipher text of the JSON environments blob (host cipher, AES-256-GCM).
+  credentials    String
+  createdAt      DateTime  @default(now()) @map("created_at")
+  updatedAt      DateTime  @updatedAt @map("updated_at")
+
+  @@unique([merchantKind, merchantId, provider])
+  @@index([merchantKind, merchantId])
+  // The migration also carries a PARTIAL unique index on
+  // (merchant_kind, merchant_id, priority) WHERE enabled — two enabled
+  // providers can never share a rank, so the chain order is total. Partial
+  // indexes cannot be expressed here, same as the CHECK constraints above.
+  @@map("payment_provider_configs")
+}
+
+// Merchant-level payment settings — the things that belong to the STORE
+// rather than to any one provider connection.
+//
+// Currently just the failover policy. It lives here and not on
+// PaymentProviderConfig because "may a decline cascade to the next acquirer"
+// is a decision about the chain as a whole; putting it on each provider row
+// would let a merchant hold two contradictory answers at once.
+model PaymentMerchantSettings {
+  id             String   @id @default(uuid())
+  merchantKind   String   @map("merchant_kind")
+  merchantId     String   @map("merchant_id")
+  // TECHNICAL | TECHNICAL_AND_DECLINE (CHECK in migration).
+  //
+  // Defaults to TECHNICAL: technical failures fail over, declines do not.
+  // Cascading a declined card onto a second acquirer is a real practice and a
+  // real fraud-and-interchange risk, so it is never the silent default.
+  failoverPolicy String   @default("TECHNICAL") @map("failover_policy")
+  createdAt      DateTime @default(now()) @map("created_at")
+  updatedAt      DateTime @updatedAt @map("updated_at")
+
+  @@unique([merchantKind, merchantId])
+  @@map("payment_merchant_settings")
+}
+
+// One charge as the gateway persists it. `(provider, provider_charge_id)`
+// UNIQUE is the cross-system idempotency key (insert-or-ignore, never
+// check-then-insert); `(merchant, idempotency_key)` UNIQUE closes the
+// concurrent-retry window at the row level.
+model PaymentCharge {
+  id               String   @id @default(uuid())
+  merchantKind     String   @map("merchant_kind")
+  merchantId       String   @map("merchant_id")
+  provider         String
+  providerChargeId String   @map("provider_charge_id")
+  // Host-side reference (order id, invoice id, ...) — correlation only.
+  reference        String
+  idempotencyKey   String?  @map("idempotency_key")
+  // Normalized ChargeStatus (CHECK in migration).
+  status           String   @default("PENDING")
+  // PIX | CARD | BOLETO (CHECK in migration).
+  method           String
+  amountCents      Int      @map("amount_cents")
+  currency         String   @default("BRL")
+  // The full normalized ChargeSnapshot (client-safe fields + raw audit).
+  snapshot         Json
+  createdAt        DateTime @default(now()) @map("created_at")
+  updatedAt        DateTime @updatedAt @map("updated_at")
+
+  @@unique([provider, providerChargeId])
+  @@unique([merchantKind, merchantId, idempotencyKey])
+  @@index([merchantKind, merchantId, createdAt])
+  @@index([reference])
+  @@map("payment_charges")
+}
+
+// Durable webhook inbox (transactional-inbox): persist first, process off
+// the response path, dedup on the (merchant, provider, event_id) triple.
+model PaymentWebhookEvent {
+  id          String    @id @default(uuid())
+  merchantKind String   @map("merchant_kind")
+  merchantId  String    @map("merchant_id")
+  provider    String
+  eventId     String    @map("event_id")
+  // PENDING | PROCESSED | FAILED (CHECK in migration).
+  status      String    @default("PENDING")
+  // Every processing attempt, live deliveries and replays together. Support
+  // telemetry: "how many times has anything tried this row".
+  attempts    Int       @default(0)
+  // Attempts made by the RETRY DRAIN, and only by it. Separate from `attempts`
+  // because it is a BUDGET, not a count: the drain stops listing a row once
+  // this reaches the cap. A provider redelivering a broken handler every few
+  // minutes would exhaust a shared counter on the live path alone, and the row
+  // would drop out of the drain's work list having never been replayed once —
+  // the recovery mechanism switching itself off for the rows that needed it
+  // most, invisibly, since an unlisted row moves no counter.
+  replayAttempts Int    @default(0) @map("replay_attempts")
+  lastError   String?   @map("last_error")
+  headers     String?
+  payload     String
+  receivedAt  DateTime  @default(now()) @map("received_at")
+  processedAt DateTime? @map("processed_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
+
+  @@unique([merchantKind, merchantId, provider, eventId])
+  @@index([status])
+  // The drain's own query: unsettled rows, one branch per eligible
+  // `replay_attempts` count, each with its own `updated_at` cutoff, ordered by
+  // `updated_at`. Leading with status keeps it off the PROCESSED rows, which
+  // are the overwhelming majority of the table.
+  @@index([status, replayAttempts, updatedAt], map: "payment_webhook_events_replay_idx")
+  @@map("payment_webhook_events")
+}
+
+// One ATTEMPT within a failover walk — the audit trail behind every routing
+// decision. Written whether the attempt succeeded, was failed over, or
+// stopped the walk, so "why did this order go to Stone instead of PagBank"
+// is answerable from data rather than from logs.
+//
+// It is also load-bearing, not merely observational: a retried charge reads
+// its own prior attempts and resumes AFTER them instead of re-walking the
+// chain from the top, which would re-hit a provider that already refused.
+model PaymentChargeAttempt {
+  id             String   @id @default(uuid())
+  merchantKind   String   @map("merchant_kind")
+  merchantId     String   @map("merchant_id")
+  // Null for charges raised without one: still audited, never resumable
+  // (there is no key to correlate a retry to this walk).
+  idempotencyKey String?  @map("idempotency_key")
+  // Host-side reference (order id) — the column support actually searches by.
+  reference      String
+  provider       String
+  // 1-based position within THIS walk, not a global counter.
+  attemptNo      Int      @map("attempt_no")
+  // SUCCEEDED | ADOPTED | FAILED_OVER | STOPPED | DECLINED | SKIPPED
+  // (CHECK in migration).
+  outcome        String
+  // DEFINITELY_NOT_CHARGED | AMBIGUOUS | BUSINESS_OUTCOME (CHECK in
+  // migration); null when the attempt did not fail.
+  failureBucket  String?  @map("failure_bucket")
+  // NOT_CHARGED | CHARGE_FOUND | PROBE_FAILED | UNSUPPORTED (CHECK in
+  // migration); null when no reconciliation probe was needed.
+  probeResult    String?  @map("probe_result")
+  // The provider charge id, once one is known (success or adopted).
+  providerChargeId String? @map("provider_charge_id")
+  // Operator-facing failure text. Never carries credentials or PAN data.
+  error          String?
+  createdAt      DateTime @default(now()) @map("created_at")
+
+  // Resume lookup: "what has this idempotency key already tried?"
+  @@index([merchantKind, merchantId, idempotencyKey])
+  @@index([reference])
+  @@index([merchantKind, merchantId, createdAt])
+  @@map("payment_charge_attempts")
+}

package/prisma/schema/rbac.prisma

@@ -0,0 +1,157 @@
+// ---------------------------------------------------------------------------
+// @12-apps/rbac — CANONICAL Prisma model partial (plug-and-play).
+//
+// This file is the single source of truth for the five generic RBAC tables. A
+// host project does NOT copy these models into its main schema by hand: it
+// uses Prisma's multi-file schema folder and SYNCS this file into it with this
+// package's `prisma:sync` script (a byte-for-byte COPY — never a symlink; see
+// scripts/sync-rbac-schema.mjs for why).
+//
+// Host-agnostic by design (the entity-lifecycle / report-builder doctrine):
+//   - The tenant is a by-value `client_id` scalar — no relation to the host's
+//     tenant model (whose name this package cannot know). The host's SQL
+//     migration may add the FK constraint (recommended: ON DELETE CASCADE).
+//   - The user is a by-value `user_id` scalar for the same reason.
+//   - Relations INTERNAL to the partial (Membership <-> Role via
+//     MembershipRole) are kept: both ends live in this file.
+//   - `role` / `kind` are Strings; a host migration may add CHECK constraints
+//     for its own closed role sets (this package's role catalog is config).
+// ---------------------------------------------------------------------------
+
+// A user's membership in a tenant. One row per (user, tenant); this row is
+// what scopes a user to a tenant — a user shows up in tenant A's roster iff a
+// Membership exists there. `role` is the member's PRIMARY role name (a
+// display/coarse-gate mirror); the authoritative permission assignment is the
+// `membership_roles` n:m join below. `active` is the reversible soft-disable:
+// a disabled member keeps its row + role but resolves to zero permissions.
+model Membership {
+  id        String   @id @default(uuid())
+  userId    String   @map("user_id")
+  clientId  String   @map("client_id")
+  role      String   @default("CUSTOMER")
+  active    Boolean  @default(true)
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  // The tenant roles this membership holds — the authoritative
+  // permission-assignment surface (a membership may hold 0..n roles).
+  roles MembershipRole[]
+
+  @@unique([userId, clientId])
+  @@index([clientId])
+  @@index([userId])
+  @@map("memberships")
+}
+
+// A named RBAC role and its permission catalog. Every tenant staff role is a
+// first-class per-tenant `Role` row (`client_id` set): on tenant creation the
+// catalog is seeded from the host's role templates into per-tenant rows, so a
+// tenant's roles are managed entirely from the DB. `client_id` NULL marks a
+// PLATFORM/global TEMPLATE row (e.g. a platform-only SUPERADMIN the engine
+// resolves by name for GLOBAL grants). `permissions` is a String holding a
+// JSON array of permission strings or the literal '*' for all. `kind`
+// (SYSTEM | CUSTOM) tells a seeded catalog role apart from a free-form tenant
+// role; `locked` marks an Owner role that is never editable/deletable.
+// `@@unique([clientId, name])` gives each tenant its own name namespace, but
+// does NOT keep TEMPLATE names unique: Postgres treats NULL `client_id` as
+// distinct, so template uniqueness is enforced by a raw partial unique index
+// (`roles_template_name_key ON (name) WHERE client_id IS NULL`) in this
+// package's migration — Prisma can't express a filtered index here.
+model Role {
+  id          String  @id @default(uuid())
+  clientId    String? @map("client_id")
+  name        String
+  // JSON array of permission strings, or the literal '*' for all permissions.
+  permissions String
+  description String?
+  isTemplate  Boolean @default(true) @map("is_template")
+  kind        String  @default("CUSTOM")
+  locked      Boolean @default(false)
+  createdAt   DateTime @default(now()) @map("created_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+  // Soft-delete: a non-null timestamp hides a CUSTOM role from the admin grid
+  // AND stops it granting at runtime (the resolver filters
+  // `archived_at IS NULL`). Null = active. SYSTEM rows are reset, never
+  // archived.
+  archivedAt DateTime? @map("archived_at")
+  // The version of this role currently live/published (an entity-lifecycle
+  // hook — NOT the schema-migration version). 0 = never versioned.
+  publishedVersion Int @default(0) @map("published_version")
+
+  // Memberships assigned this role. Cascades: deleting the role detaches its
+  // assignments (members fall back to their remaining roles).
+  memberRoles MembershipRole[]
+
+  @@unique([clientId, name])
+  @@index([clientId])
+  @@index([clientId, archivedAt])
+  @@map("roles")
+}
+
+// The n:m assignment join between a tenant membership and a `Role`. This is
+// the authoritative role-assignment surface: a membership holds 0..n roles, a
+// role is held by many memberships, and the RBAC resolver derives a member's
+// effective permissions from these rows (each role's `permissions` attached
+// inline). Unique `(membership_id, role_id)` makes a grant idempotent; both
+// FKs cascade so a removed membership or a deleted role takes its assignments
+// with it — never a dangling grant.
+model MembershipRole {
+  id           String   @id @default(uuid())
+  membershipId String   @map("membership_id")
+  roleId       String   @map("role_id")
+  createdAt    DateTime @default(now()) @map("created_at")
+
+  membership Membership @relation(fields: [membershipId], references: [id], onDelete: Cascade)
+  role       Role       @relation(fields: [roleId], references: [id], onDelete: Cascade)
+
+  @@unique([membershipId, roleId])
+  @@index([membershipId])
+  @@index([roleId])
+  @@map("membership_roles")
+}
+
+// A grant of a role to a user at a given scope. This carries PLATFORM-level
+// grants (e.g. SUPERADMIN at scope 'GLOBAL') and any assignment not
+// expressible as a per-tenant `Membership.role` (an `'org:<id>'` scope, or a
+// tenant custom-role grant). `roleName` references a `Role.name` resolved in
+// the engine's resolver — NOT a hard FK — so GLOBAL/platform roles (whose Role
+// row has a NULL client) can be granted without a composite FK. `scope` is the
+// scope key: a tenant id for a tenant-scoped grant, or the literal 'GLOBAL'.
+// `@@unique([userId, roleName, scope])` makes granting an idempotent upsert.
+model RoleAssignment {
+  id        String   @id @default(uuid())
+  userId    String   @map("user_id")
+  roleName  String   @map("role_name")
+  scope     String
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([userId, roleName, scope])
+  @@index([userId])
+  // Scope-first reads: "who holds a grant AT this tenant". `scope` is the
+  // THIRD column of the unique above, so a bare `scope =` predicate cannot use
+  // it and would seq-scan every tenant's grants.
+  @@index([scope])
+  @@map("role_assignments")
+}
+
+// A GENERIC assignment of a user to a scoped resource within a tenant — the
+// relation that backs "assign a waiter to table 12". `resourceType` + a
+// by-value `resourceId` name the resource (not a hard FK), so any resource
+// kind reuses this one relation. `clientId` scopes the assignment to a tenant.
+// `validFrom`/`validTo` are the active window: `validTo` NULL means the
+// assignment is STILL ACTIVE — revocation stamps `validTo` (filter-not-delete)
+// rather than deleting the row, so the audit trail is never lost.
+model ResourceAssignment {
+  id           String    @id @default(uuid())
+  userId       String    @map("user_id")
+  clientId     String    @map("client_id")
+  resourceType String    @map("resource_type")
+  resourceId   String    @map("resource_id")
+  validFrom    DateTime  @default(now()) @map("valid_from")
+  validTo      DateTime? @map("valid_to")
+
+  @@index([userId, resourceType])
+  @@index([clientId, resourceType, resourceId])
+  @@map("resource_assignments")
+}

package/prisma/schema/report-builder.prisma

@@ -0,0 +1,69 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// OWNED BY @12-apps/report-builder — the host's multi-file schema folder holds
+// only a SYMLINK to this file (created/verified by `pnpm --filter
+// @12-apps/report-builder prisma:sync`): the report persistence model lives here,
+// in the package, never in the application.
+//
+// Deliberately self-contained (the payments-backend doctrine): tenant scoping
+// is a `client_id` String column — NO foreign key into any host table — so the
+// model works in every repo without schema coupling. The host repository layer
+// is the tenant boundary: every read/write is `clientId`-scoped.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// A tenant-authored custom report (FUT-138): the report-builder JSON
+// `ReportSpec` persisted as DATA. Authored by the admin builder UI or by LLMs
+// over MCP; the stored JSON is untrusted input, re-validated against the host's
+// field catalog on EVERY write and EVERY run — it can only name allowlisted
+// catalog fields, never SQL. Name is unique per tenant (upsert-friendly for
+// MCP authoring). `createdBy` is the host's user id, kept as an opaque scalar.
+model SavedReport {
+  id          String   @id @default(uuid())
+  clientId    String   @map("client_id")
+  name        String
+  description String?
+  spec        Json
+  // Lifecycle (FUT-307): draft | published (String + DB CHECK, house style).
+  // A draft is visible/runnable only by its author and tenant admins; the API
+  // layer decides — this model stays host-agnostic data.
+  status      String   @default("draft")
+  // Sharing (FUT-307): tenant (everyone in the entity's permission tier) |
+  // roles (the ids in visibilityRoles, plus author + admins) | private
+  // (author + admins). String + DB CHECK.
+  visibility  String   @default("tenant")
+  // Opaque HOST role ids granted access when visibility = 'roles' (JSON array
+  // of strings). No FK by design (the payments doctrine): a stale id simply
+  // matches no actor. Bounded by the wire contract (≤20 ids).
+  visibilityRoles Json @default("[]") @map("visibility_roles")
+  // The period the report OPENS on (FUT-755): today | 7d | 30d | month — the
+  // presets in `react/reports-api.ts` MINUS `custom`, which names explicit
+  // dates this column has nowhere to keep and would freeze the report on a
+  // window that ages badly. Nullable on purpose — NULL means "no preference",
+  // which the reader resolves to the pre-existing default of 30d, so every row
+  // that predates this column keeps behaving exactly as it did. String + DB
+  // CHECK, house style.
+  defaultRange String? @map("default_range")
+  // Unpublished changes to a PUBLISHED report (FUT-755): the author's
+  // in-progress edit, stored BESIDE the live document rather than over it.
+  //
+  // Deliberately NOT `status: 'draft'`. That column says the report has never
+  // been published; flipping it while someone edits would unpublish a report
+  // its readers are reading right now. So the whole editable payload — name,
+  // description, spec, sharing, default range — is parked here as JSON, `spec`
+  // is left untouched, and readers keep getting the published document until
+  // the author publishes. NULL = no unpublished changes, which is every row
+  // that predates this column.
+  //
+  // A COLUMN, not a side table: one working copy per report is then a
+  // structural fact rather than a partial unique index a host has to remember
+  // to create, publish is a single row update that cannot half-apply, and
+  // discard is setting it back to NULL. Untrusted JSON like `spec` —
+  // re-validated against the field catalog on write and again on publish.
+  workingCopy Json?   @map("working_copy")
+  createdBy   String?  @map("created_by")
+  createdAt   DateTime @default(now()) @map("created_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  @@unique([clientId, name])
+  @@index([clientId])
+  @@map("saved_reports")
+}