@12-apps/prisma 1.0.0

package/dist/index.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Prisma client singleton.
+ *
+ * Default mode builds a PostgreSQL-backed `PrismaClient` (the real / production
+ * database, driven by `DATABASE_URL`). When a PGlite flag is present in the
+ * environment the same client is built on the community `pglite-prisma-adapter`
+ * so PGlite (WASM Postgres) becomes the app runtime database for local dev and
+ * Playwright e2e — no Docker Postgres required.
+ *
+ * PGlite mode is selected by ANY of:
+ *   - `USE_FILE_DB=1` (or `true`)            → in-memory, unless a dir is also set
+ *   - `PGLITE_DATA_DIR=<dir>`                → file-backed at <dir>
+ *   - `DATABASE_URL` starting with `pglite:` → `pglite:memory` or `pglite:<dir>`
+ *
+ * Production safety: when `NODE_ENV=production` the database is ALWAYS real
+ * PostgreSQL unless `USE_FILE_DB=1` is set explicitly — so a stray
+ * `PGLITE_DATA_DIR` / `pglite:` URL can never silently point prod at a throwaway
+ * WASM DB. `USE_FILE_DB=0` forces real PostgreSQL everywhere (dev/e2e opt-out).
+ *
+ * The generated `PrismaClient` type is re-exported below so consumers stay fully
+ * typed without any hand-written stub interfaces. Server-only: never import this
+ * (directly or transitively) from middleware or an Edge-runtime route — PGlite
+ * needs Node's filesystem/WASM and Prisma is not Edge-safe.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetPrismaClient = exports.setPrismaClient = exports.getPrismaClient = exports.normalizeSearchText = exports.setActor = exports.runWithActorScope = exports.runWithActor = exports.getActorUserId = exports.getActorAttribution = exports.AppendOnlyViolationError = void 0;
+const append_only_extension_1 = require("./append-only-extension");
+const audit_extension_1 = require("./audit-extension");
+// Append-only guard for the audit log (FUT-209): mutating the AuditLog model
+// throws. Re-exported so tests can assert on the error type.
+var append_only_extension_2 = require("./append-only-extension");
+Object.defineProperty(exports, "AppendOnlyViolationError", { enumerable: true, get: function () { return append_only_extension_2.AppendOnlyViolationError; } });
+// Change-attribution context helpers (FUT-168): the auth layer calls `setActor`
+// once a request is authorized; the audit extension applied below reads it to
+// stamp created_by/updated_by. Re-exported here so consumers import them from
+// the same `@12-apps/prisma` entry point as `getPrismaClient`.
+var actor_context_1 = require("./actor-context");
+Object.defineProperty(exports, "getActorAttribution", { enumerable: true, get: function () { return actor_context_1.getActorAttribution; } });
+Object.defineProperty(exports, "getActorUserId", { enumerable: true, get: function () { return actor_context_1.getActorUserId; } });
+Object.defineProperty(exports, "runWithActor", { enumerable: true, get: function () { return actor_context_1.runWithActor; } });
+Object.defineProperty(exports, "runWithActorScope", { enumerable: true, get: function () { return actor_context_1.runWithActorScope; } });
+Object.defineProperty(exports, "setActor", { enumerable: true, get: function () { return actor_context_1.setActor; } });
+var search_normalize_1 = require("./search-normalize");
+Object.defineProperty(exports, "normalizeSearchText", { enumerable: true, get: function () { return search_normalize_1.normalizeSearchText; } });
+// The singleton and its in-flight init promise live on `globalThis` so that
+// Next dev / Turbopack hot-reload (which re-evaluates this module) never spawns
+// a second PGlite instance against the same dataDir — PGlite holds a single
+// exclusive connection, and a duplicate would deadlock or corrupt the store.
+const globalStore = globalThis;
+/**
+ * Prisma log levels.
+ *
+ * Full `query` logging prints every SQL statement (table/column names) to the
+ * server console, so it is OFF by default — even in development — to avoid
+ * surfacing schema details and noise. Opt in locally with `PRISMA_LOG_QUERIES=1`.
+ * Production logs errors only.
+ */
+const prismaLog = () => {
+    if (process.env.NODE_ENV === 'production')
+        return ['error'];
+    return process.env.PRISMA_LOG_QUERIES === '1'
+        ? ['query', 'error', 'warn']
+        : ['error', 'warn'];
+};
+/**
+ * Whether the environment selects PGlite over PostgreSQL. Production is
+ * PostgreSQL unless a file DB is DELIBERATELY forced on; an explicit
+ * `USE_FILE_DB=0` always wins.
+ */
+const isPgliteSelected = (env) => {
+    if (env.forcedOff)
+        return false;
+    if (process.env.NODE_ENV === 'production')
+        return env.forcedOn;
+    return env.forcedOn || env.explicitDir !== undefined || env.urlIsPglite;
+};
+/**
+ * Resolve the PGlite target once selected: an explicit dir wins, else a
+ * `pglite:` URL (`pglite:memory` / `pglite://memory` ⇒ in-memory; `pglite:./dir`
+ * ⇒ file), else `USE_FILE_DB` with no directory ⇒ in-memory.
+ */
+const pgliteTarget = (env) => {
+    if (env.explicitDir)
+        return { dataDir: env.explicitDir };
+    if (env.urlIsPglite) {
+        const raw = env.url.replace(/^pglite:(\/\/)?/, '');
+        return raw === '' || raw === 'memory' ? {} : { dataDir: raw };
+    }
+    return {};
+};
+const resolvePglite = () => {
+    const url = process.env.DATABASE_URL ?? '';
+    const flag = (process.env.USE_FILE_DB ?? '').toLowerCase();
+    const env = {
+        url,
+        explicitDir: process.env.PGLITE_DATA_DIR,
+        forcedOn: flag === '1' || flag === 'true',
+        forcedOff: flag === '0' || flag === 'false',
+        urlIsPglite: url.startsWith('pglite:'),
+    };
+    return isPgliteSelected(env) ? pgliteTarget(env) : null;
+};
+/** Build a PGlite-backed `PrismaClient` via the community driver adapter. */
+const createPgliteClient = async (dataDir) => {
+    const { PGlite } = await Promise.resolve().then(() => __importStar(require('@electric-sql/pglite')));
+    // `pglite-prisma-adapter` is `exports`-only; type the dynamic import locally
+    // so it resolves under this package's classic ("Node") module resolution
+    // without a static type dependency on the package.
+    const { PrismaPGlite } = (await Promise.resolve().then(() => __importStar(require('pglite-prisma-adapter'))));
+    const { PrismaClient: GeneratedPrismaClient } = await Promise.resolve().then(() => __importStar(require('@prisma/client')));
+    const client = dataDir ? new PGlite(dataDir) : new PGlite();
+    await client.waitReady;
+    const adapter = new PrismaPGlite(client);
+    return (0, append_only_extension_1.applyAppendOnlyGuard)((0, audit_extension_1.applyAuditStamps)(new GeneratedPrismaClient({ adapter, log: prismaLog() })));
+};
+/** Build the default PostgreSQL-backed `PrismaClient` (real / production DB). */
+const createPostgresClient = async () => {
+    const { PrismaPg } = await Promise.resolve().then(() => __importStar(require('@prisma/adapter-pg')));
+    const { PrismaClient: GeneratedPrismaClient } = await Promise.resolve().then(() => __importStar(require('@prisma/client')));
+    const connectionString = process.env.DATABASE_URL;
+    if (!connectionString) {
+        throw new Error('DATABASE_URL is required for the PostgreSQL Prisma client. Set it, or ' +
+            'enable PGlite mode (USE_FILE_DB=1 / PGLITE_DATA_DIR / a "pglite:" URL).');
+    }
+    // Prisma 7 makes a driver adapter mandatory — PrismaClient no longer reads
+    // DATABASE_URL itself, and `new PrismaClient()` without an adapter throws at
+    // construction. PrismaPg takes a pg.PoolConfig and owns the pool internally.
+    const adapter = new PrismaPg({
+        connectionString,
+    });
+    return (0, append_only_extension_1.applyAppendOnlyGuard)((0, audit_extension_1.applyAuditStamps)(new GeneratedPrismaClient({ adapter, log: prismaLog() })));
+};
+/**
+ * Get or create the Prisma client instance.
+ *
+ * Lazy and memoised: concurrent callers share a single in-flight init promise,
+ * so only one client (and at most one PGlite instance) is ever created. A
+ * missing generated client surfaces an actionable error rather than a hard
+ * module-load failure.
+ */
+const getPrismaClient = async () => {
+    if (globalStore.__futurePayPrisma)
+        return globalStore.__futurePayPrisma;
+    if (globalStore.__futurePayPrismaInit)
+        return globalStore.__futurePayPrismaInit;
+    const pglite = resolvePglite();
+    const init = (pglite ? createPgliteClient(pglite.dataDir) : createPostgresClient())
+        .then((client) => {
+        globalStore.__futurePayPrisma = client;
+        globalStore.__futurePayPrismaInit = undefined;
+        return client;
+    })
+        .catch((error) => {
+        globalStore.__futurePayPrismaInit = undefined;
+        throw new Error(`Prisma client not available (${pglite ? 'PGlite' : 'PostgreSQL'} mode). ` +
+            'Run "pnpm --filter @12-apps/prisma prisma generate" from the ' +
+            'monorepo root, or "pnpm prisma generate" from packages/prisma. ' +
+            `Cause: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    });
+    globalStore.__futurePayPrismaInit = init;
+    return init;
+};
+exports.getPrismaClient = getPrismaClient;
+/**
+ * Set a custom Prisma client instance (for testing).
+ */
+const setPrismaClient = (client) => {
+    globalStore.__futurePayPrisma = client;
+    globalStore.__futurePayPrismaInit = undefined;
+};
+exports.setPrismaClient = setPrismaClient;
+/**
+ * Reset the Prisma client instance (for testing).
+ */
+const resetPrismaClient = () => {
+    globalStore.__futurePayPrisma = undefined;
+    globalStore.__futurePayPrismaInit = undefined;
+};
+exports.resetPrismaClient = resetPrismaClient;

package/dist/search-normalize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Accent- and case-insensitive search normalization (FUT-168). Used to keep a
+ * denormalized `search_name` column on searchable models (maintained by the
+ * audit extension) and to normalize the query at read time, so "sabao" matches
+ * "Sabão". DB-agnostic: plain lowercased, diacritic-stripped text works
+ * identically on PostgreSQL and PGlite (no `unaccent` extension needed).
+ */
+/**
+ * Strip diacritics and lowercase. NFD splits accented letters into base +
+ * combining mark, then the marks are removed. Using the explicit code-point
+ * range (not `\p{Diacritic}`) keeps it valid under the package's compile target.
+ */
+export declare function normalizeSearchText(value: string): string;

package/dist/search-normalize.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Accent- and case-insensitive search normalization (FUT-168). Used to keep a
+ * denormalized `search_name` column on searchable models (maintained by the
+ * audit extension) and to normalize the query at read time, so "sabao" matches
+ * "Sabão". DB-agnostic: plain lowercased, diacritic-stripped text works
+ * identically on PostgreSQL and PGlite (no `unaccent` extension needed).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSearchText = normalizeSearchText;
+/** Unicode combining diacritical marks (U+0300–U+036F), split out by NFD. */
+const COMBINING_MARKS = /[̀-ͯ]/g;
+/**
+ * Strip diacritics and lowercase. NFD splits accented letters into base +
+ * combining mark, then the marks are removed. Using the explicit code-point
+ * range (not `\p{Diacritic}`) keeps it valid under the package's compile target.
+ */
+function normalizeSearchText(value) {
+    return value.normalize('NFD').replace(COMBINING_MARKS, '').toLowerCase();
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@12-apps/prisma",
+  "version": "1.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "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",
+    "clean": "rm -rf dist node_modules coverage",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest watch",
+    "lint:files": "bash -c 'eslint \"${@:-.}\" --max-warnings 0' _",
+    "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:migrate": "prisma migrate dev",
+    "prisma:push": "prisma db push",
+    "prisma:studio": "prisma studio",
+    "prisma:sync-lifecycle": "node scripts/sync-lifecycle-schema.mjs",
+    "prisma:sync-research": "node scripts/sync-research-schema.mjs",
+    "prisma:sync-shift": "node scripts/sync-shift-schema.mjs",
+    "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-plugins": "node scripts/sync-prisma-plugins.mjs",
+    "prisma:sync-plugins:check": "node scripts/sync-prisma-plugins.mjs --check"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "0.2.17",
+    "@prisma/adapter-pg": "7.8.0",
+    "@prisma/client": "7.8.0",
+    "dotenv": "^16.4.7",
+    "pglite-prisma-adapter": "0.7.2"
+  },
+  "devDependencies": {
+    "@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/report-builder": "^3.0.0",
+    "@12-apps/shift": "^2.0.0",
+    "@12-apps/typescript-config": "^1.20.0",
+    "@types/node": "^22.10.6",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.39.1",
+    "eslint-plugin-test-flakiness": "^1.4.0",
+    "prisma": "7.8.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "prisma",
+    "migrations",
+    "postgres",
+    "pglite",
+    "typescript"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/prisma"
+  },
+  "files": [
+    "src",
+    "dist",
+    "prisma",
+    "*.js",
+    "*.mjs",
+    "*.md",
+    "!eslint.config.js",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/*.test.*",
+    "!**/*.spec.*"
+  ]
+}

package/prisma/migration-files.ts

@@ -0,0 +1,33 @@
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Which committed migrations exist, and in what order to replay them.
+ *
+ * Its own module — with NO side effects — so both the provisioning script and
+ * its test can use it. (`pglite-setup.ts` provisions a database on import.)
+ */
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The folder holding every committed migration, including symlinked ones. */
+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.
+ */
+export function discoverMigrations(dir: string = MIGRATIONS_DIR): string[] {
+  return readdirSync(dir)
+    .filter((name) => /^\d/.test(name) && statSync(join(dir, name)).isDirectory())
+    .sort();
+}

package/prisma/migrations/20260725150000_payments_platform_core/migration.sql

@@ -0,0 +1,98 @@
+-- @12-apps/payments-backend owned migration: the three self-contained payment
+-- tables (provider configs, charges, webhook inbox). No FK into host tables —
+-- merchant scope is (merchant_kind, merchant_id). Copy this file into the
+-- host's prisma/migrations folder (keep the timestamp ordering) after running
+-- `prisma:sync`; CHECK constraints carry the String-over-enum closed sets.
+
+CREATE TABLE "payment_provider_configs" (
+    "id" TEXT NOT NULL,
+    "merchant_kind" TEXT NOT NULL,
+    "merchant_id" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "enabled" BOOLEAN NOT NULL DEFAULT false,
+    "environment" TEXT NOT NULL DEFAULT 'SANDBOX',
+    "status" TEXT NOT NULL DEFAULT 'UNVERIFIED',
+    "last_verified_at" TIMESTAMP(3),
+    "stub" BOOLEAN NOT NULL DEFAULT false,
+    "credentials" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "payment_provider_configs_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "payment_provider_configs_merchant_kind_check"
+        CHECK ("merchant_kind" IN ('PLATFORM', 'TENANT')),
+    CONSTRAINT "payment_provider_configs_environment_check"
+        CHECK ("environment" IN ('SANDBOX', 'PRODUCTION')),
+    CONSTRAINT "payment_provider_configs_status_check"
+        CHECK ("status" IN ('UNVERIFIED', 'VERIFIED', 'FAILED'))
+);
+
+CREATE UNIQUE INDEX "payment_provider_configs_merchant_kind_merchant_id_provider_key"
+    ON "payment_provider_configs"("merchant_kind", "merchant_id", "provider");
+CREATE INDEX "payment_provider_configs_merchant_kind_merchant_id_idx"
+    ON "payment_provider_configs"("merchant_kind", "merchant_id");
+-- SINGLE ACTIVE PROVIDER, enforced by the database rather than by app code:
+-- at most one enabled config per merchant. A racing "enable" now fails loudly
+-- on this constraint instead of silently leaving two providers enabled (which
+-- would make charge routing depend on row order). Partial indexes are not
+-- expressible in the Prisma schema — same migration-only pattern the repo
+-- already uses for its CHECK constraints.
+CREATE UNIQUE INDEX "payment_provider_configs_one_enabled_per_merchant"
+    ON "payment_provider_configs"("merchant_kind", "merchant_id") WHERE "enabled";
+
+CREATE TABLE "payment_charges" (
+    "id" TEXT NOT NULL,
+    "merchant_kind" TEXT NOT NULL,
+    "merchant_id" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "provider_charge_id" TEXT NOT NULL,
+    "reference" TEXT NOT NULL,
+    "idempotency_key" TEXT,
+    "status" TEXT NOT NULL DEFAULT 'PENDING',
+    "method" TEXT NOT NULL,
+    "amount_cents" INTEGER NOT NULL,
+    "currency" TEXT NOT NULL DEFAULT 'BRL',
+    "snapshot" JSONB NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "payment_charges_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "payment_charges_merchant_kind_check"
+        CHECK ("merchant_kind" IN ('PLATFORM', 'TENANT')),
+    CONSTRAINT "payment_charges_status_check"
+        CHECK ("status" IN ('PENDING', 'AUTHORIZED', 'PAID', 'DECLINED', 'CANCELED', 'EXPIRED', 'REFUNDED', 'PARTIALLY_REFUNDED')),
+    CONSTRAINT "payment_charges_method_check"
+        CHECK ("method" IN ('PIX', 'CARD', 'BOLETO'))
+);
+
+CREATE UNIQUE INDEX "payment_charges_provider_provider_charge_id_key"
+    ON "payment_charges"("provider", "provider_charge_id");
+CREATE UNIQUE INDEX "payment_charges_merchant_kind_merchant_id_idempotency_key_key"
+    ON "payment_charges"("merchant_kind", "merchant_id", "idempotency_key");
+CREATE INDEX "payment_charges_merchant_kind_merchant_id_created_at_idx"
+    ON "payment_charges"("merchant_kind", "merchant_id", "created_at");
+CREATE INDEX "payment_charges_reference_idx" ON "payment_charges"("reference");
+
+CREATE TABLE "payment_webhook_events" (
+    "id" TEXT NOT NULL,
+    "merchant_kind" TEXT NOT NULL,
+    "merchant_id" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "event_id" TEXT NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'PENDING',
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "last_error" TEXT,
+    "headers" TEXT,
+    "payload" TEXT NOT NULL,
+    "received_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "processed_at" TIMESTAMP(3),
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "payment_webhook_events_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "payment_webhook_events_status_check"
+        CHECK ("status" IN ('PENDING', 'PROCESSED', 'FAILED'))
+);
+
+CREATE UNIQUE INDEX "payment_webhook_events_merchant_provider_event_key"
+    ON "payment_webhook_events"("merchant_kind", "merchant_id", "provider", "event_id");
+CREATE INDEX "payment_webhook_events_status_idx" ON "payment_webhook_events"("status");

package/prisma/migrations/20260725160000_payments_oauth_connections/migration.sql

@@ -0,0 +1,25 @@
+-- @12-apps/payments-backend owned migration: OAuth connection support.
+--
+-- `expires_at` is a first-class column rather than another key inside the
+-- encrypted `credentials` blob, precisely so it is QUERYABLE: a background
+-- job asks "which connections expire in the next hour" and refreshes them.
+-- Nothing inside the ciphertext can be indexed or compared in SQL.
+--
+-- The status CHECK is widened with RECONNECT_REQUIRED, which is deliberately
+-- distinct from FAILED: the remedy is reauthorizing (a button), not fixing
+-- credentials (a form).
+
+ALTER TABLE "payment_provider_configs"
+    ADD COLUMN "expires_at" TIMESTAMP(3);
+
+ALTER TABLE "payment_provider_configs"
+    DROP CONSTRAINT "payment_provider_configs_status_check";
+
+ALTER TABLE "payment_provider_configs"
+    ADD CONSTRAINT "payment_provider_configs_status_check"
+        CHECK ("status" IN ('UNVERIFIED', 'VERIFIED', 'FAILED', 'RECONNECT_REQUIRED'));
+
+-- Drives the refresh sweep: only connections that actually expire (OAuth)
+-- have a non-null value, so this index stays small.
+CREATE INDEX "payment_provider_configs_expires_at_idx"
+    ON "payment_provider_configs"("expires_at") WHERE "expires_at" IS NOT NULL;

package/prisma/migrations/20260725170000_add_saved_reports/migration.sql

@@ -0,0 +1,22 @@
+-- FUT-138: tenant-authored custom reports — the report-builder JSON ReportSpec
+-- persisted as data. Owned by @12-apps/report-builder (this migration reaches the
+-- host's migrations folder as a committed symlink). Unique per (client, name)
+-- so MCP authoring can upsert by name. Deliberately NO foreign key into host
+-- tables (self-contained package schema, payments-backend doctrine): the host
+-- repository layer scopes every read/write by client_id.
+CREATE TABLE "saved_reports" (
+    "id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "spec" JSONB NOT NULL,
+    "created_by" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "saved_reports_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "saved_reports_client_id_name_key" ON "saved_reports"("client_id", "name");
+
+CREATE INDEX "saved_reports_client_id_idx" ON "saved_reports"("client_id");

package/prisma/migrations/20260726090000_payments_multi_provider_failover/migration.sql

@@ -0,0 +1,67 @@
+-- @12-apps/payments-backend owned migration: priority list + failover ledger.
+--
+-- This retires the SINGLE ACTIVE PROVIDER invariant. Until now the database
+-- itself guaranteed at most one enabled config per merchant; a merchant may
+-- now enable several and RANK them, and checkout walks that ranking when a
+-- provider fails. The guarantee is not dropped so much as replaced: ranks
+-- among a merchant's enabled rows must stay DISTINCT, or routing order would
+-- again depend on row order — exactly the ambiguity the old index existed to
+-- prevent.
+
+ALTER TABLE "payment_provider_configs"
+    ADD COLUMN "priority" INTEGER NOT NULL DEFAULT 0;
+
+-- Backfill is a no-op by construction: the index being dropped below allowed
+-- at most ONE enabled row per merchant, so every pre-existing chain has
+-- exactly one member and rank 0 is already correct for it. Disabled rows also
+-- carry 0, which the partial index below simply ignores.
+
+DROP INDEX "payment_provider_configs_one_enabled_per_merchant";
+
+-- The replacement invariant: two ENABLED providers can never share a rank, so
+-- a merchant's chain is a total order. A racing reorder fails loudly here
+-- rather than silently producing a chain whose order depends on which row the
+-- planner returned first.
+CREATE UNIQUE INDEX "payment_provider_configs_enabled_priority_key"
+    ON "payment_provider_configs"("merchant_kind", "merchant_id", "priority")
+    WHERE "enabled";
+
+-- One row per ATTEMPT in a failover walk. This is the evidence trail for the
+-- proof-of-failure rule: it records not just that a provider failed but which
+-- BUCKET the failure fell into and, when the outcome was ambiguous, what the
+-- reconciliation probe concluded. A double charge and a stranded charge look
+-- identical in provider dashboards; they do not look identical here.
+CREATE TABLE "payment_charge_attempts" (
+    "id" TEXT NOT NULL,
+    "merchant_kind" TEXT NOT NULL,
+    "merchant_id" TEXT NOT NULL,
+    "idempotency_key" TEXT,
+    "reference" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "attempt_no" INTEGER NOT NULL,
+    "outcome" TEXT NOT NULL,
+    "failure_bucket" TEXT,
+    "probe_result" TEXT,
+    "provider_charge_id" TEXT,
+    "error" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "payment_charge_attempts_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "payment_charge_attempts_merchant_kind_check"
+        CHECK ("merchant_kind" IN ('PLATFORM', 'TENANT')),
+    CONSTRAINT "payment_charge_attempts_outcome_check"
+        CHECK ("outcome" IN ('SUCCEEDED', 'ADOPTED', 'FAILED_OVER', 'STOPPED', 'DECLINED', 'SKIPPED')),
+    CONSTRAINT "payment_charge_attempts_failure_bucket_check"
+        CHECK ("failure_bucket" IS NULL OR "failure_bucket" IN ('DEFINITELY_NOT_CHARGED', 'AMBIGUOUS', 'BUSINESS_OUTCOME')),
+    CONSTRAINT "payment_charge_attempts_probe_result_check"
+        CHECK ("probe_result" IS NULL OR "probe_result" IN ('NOT_CHARGED', 'CHARGE_FOUND', 'PROBE_FAILED', 'UNSUPPORTED'))
+);
+
+-- Resume lookup: "what has this idempotency key already tried?" — so a
+-- retried charge continues the walk instead of restarting it.
+CREATE INDEX "payment_charge_attempts_merchant_idempotency_key_idx"
+    ON "payment_charge_attempts"("merchant_kind", "merchant_id", "idempotency_key");
+CREATE INDEX "payment_charge_attempts_reference_idx"
+    ON "payment_charge_attempts"("reference");
+CREATE INDEX "payment_charge_attempts_merchant_created_at_idx"
+    ON "payment_charge_attempts"("merchant_kind", "merchant_id", "created_at");

package/prisma/migrations/20260726120000_payments_failover_policy/migration.sql

@@ -0,0 +1,29 @@
+-- @12-apps/payments-backend owned migration: merchant-level failover policy.
+--
+-- FUT-303 shipped `failoverPolicy` as a construction-time gateway option, which
+-- meant a merchant could not actually choose it — the ticket asks for a policy,
+-- and a constant no store owner can reach is not one. This gives it a home.
+--
+-- It is merchant-level rather than per-provider on purpose: "may a decline
+-- cascade to the next acquirer" is a decision about the CHAIN, and hanging it
+-- off each provider row would let one merchant hold two contradictory answers.
+
+CREATE TABLE "payment_merchant_settings" (
+    "id" TEXT NOT NULL,
+    "merchant_kind" TEXT NOT NULL,
+    "merchant_id" TEXT NOT NULL,
+    -- TECHNICAL is the default everywhere, including for merchants who never
+    -- get a row: cascading a declined card is opt-in, never inherited.
+    "failover_policy" TEXT NOT NULL DEFAULT 'TECHNICAL',
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "payment_merchant_settings_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "payment_merchant_settings_merchant_kind_check"
+        CHECK ("merchant_kind" IN ('PLATFORM', 'TENANT')),
+    CONSTRAINT "payment_merchant_settings_failover_policy_check"
+        CHECK ("failover_policy" IN ('TECHNICAL', 'TECHNICAL_AND_DECLINE'))
+);
+
+CREATE UNIQUE INDEX "payment_merchant_settings_merchant_key"
+    ON "payment_merchant_settings"("merchant_kind", "merchant_id");

package/prisma/migrations/20260726130000_add_report_lifecycle/migration.sql

@@ -0,0 +1,18 @@
+-- Report lifecycle & sharing (FUT-307): status (draft | published), visibility
+-- (tenant | roles | private) and the role-id allowlist for visibility='roles'.
+-- String + DB CHECK, the house style (no Prisma enums).
+ALTER TABLE "saved_reports"
+  ADD COLUMN "status" TEXT NOT NULL DEFAULT 'draft',
+  ADD COLUMN "visibility" TEXT NOT NULL DEFAULT 'tenant',
+  ADD COLUMN "visibility_roles" JSONB NOT NULL DEFAULT '[]';
+
+ALTER TABLE "saved_reports"
+  ADD CONSTRAINT "saved_reports_status_check"
+    CHECK ("status" IN ('draft', 'published'));
+ALTER TABLE "saved_reports"
+  ADD CONSTRAINT "saved_reports_visibility_check"
+    CHECK ("visibility" IN ('tenant', 'roles', 'private'));
+
+-- Every pre-lifecycle report is live today: backfill as published so nothing
+-- disappears from any tenant's Relatórios area (new rows default to draft).
+UPDATE "saved_reports" SET "status" = 'published';

package/prisma/migrations/20260727120000_add_report_archived_status/migration.sql

@@ -0,0 +1,9 @@
+-- Archived reports (FUT-391): the Relatórios area retires a report instead of
+-- deleting it — the picker stops offering it, the document (and every block
+-- spec in it) survives for restore. Widen the lifecycle CHECK to admit it.
+ALTER TABLE "saved_reports"
+  DROP CONSTRAINT IF EXISTS "saved_reports_status_check";
+
+ALTER TABLE "saved_reports"
+  ADD CONSTRAINT "saved_reports_status_check"
+    CHECK ("status" IN ('draft', 'published', 'archived'));