@ftisindia/create-app 0.1.5 → 0.1.6

package/template/docs/REPORTS_CHECKLIST.md

@@ -0,0 +1,97 @@
+# Reports Module Completion Checklist
+
+The report builder counts as DONE only when every box below holds, on top of
+the generic [`MODULE_COMPLETION_CHECKLIST.md`](./MODULE_COMPLETION_CHECKLIST.md).
+Section references are to `report-builder/report-builder-design.md` (Rev 2).
+
+## Boundary & the standalone guarantee
+
+- [ ] The engine package (`@ftisindia/report-builder`) compiles and unit-tests **without** the template AND **without** `@ftisindia/form-builder` installed (§3.2/§13); only `src/modules/reports` imports template services.
+- [ ] The engine's boundary lint passes: no `@nestjs/*`, `@prisma/*`, `@casl/*`, `@ftisindia/form-builder`, or template imports anywhere in the core; engine errors are engine-typed and mapped to HTTP exceptions only in the glue (`reports-error.mapper.ts`).
+- [ ] **`ReportsModule` imports no FormsModule.** It runs over custom sources with its OWN async-export worker + file storage (no forms outbox / UploadedFile). Form-backed sources and the delegated `editSubmission`/`updateStatus` verbs live in the **optional** `ReportsFormsModule` bridge (`reports-forms.module.ts` + `infrastructure/forms-adapter/`), the ONLY artifact aware of both engines. Dropping the bridge from `app.module.ts` leaves reports fully functional.
+
+## Schema ownership
+
+- [ ] Boot-time schema check proven both ways: green on a freshly migrated app; clear fail-fast message (naming `REPORTS_ENGINE_SCHEMA_VERSION` and the snippet path) on a stale schema.
+- [ ] The check also verifies the two `ReportSavedView` partial unique indexes and prints the raw SQL when they are missing (finding #5).
+- [ ] `prisma/reports.prisma` in the engine matches the models in the app's `schema.prisma`; upgrades follow copy-snippet → `prisma migrate dev`.
+
+## Permissions & registry
+
+- [ ] All 7 report permission keys (+ `formSubmissions.update`) exist in `permissionKeys`, are seeded, and `test/reports-permission-sync.spec.ts` passes (engine ↔ template set equality).
+- [ ] Every report route is in `routePermissionRegistry` (the boot-time registry validator passes); `reports.export` is enforced independently of `reports.read`.
+- [ ] Attach-time gating proven: saving/publishing a definition wiring a row action whose `requiredPermissions` the author lacks is rejected (§6.1); the same keys are re-checked at execute time.
+
+## The SQL boundary (§2.1)
+
+- [ ] A definition column carrying an `sql` property is rejected by the meta-schema; SQL-shaped strings in `path`/`columnId` are rejected by the save lint (`SQL_IN_DEFINITION`).
+- [ ] `$row.*` paths resolve only against the physical columns the source manifest exposes.
+- [ ] Compiled statements carry user values exclusively as bind parameters (compiler snapshot tests assert no value ever lands in SQL text).
+
+## Query semantics (§4/§5)
+
+- [ ] Keyset pagination proven at depth: walking pages by cursor is constant-cost; `OFFSET` appears nowhere; the rowId tiebreaker is always appended.
+- [ ] Cursor integrity: tampered cursors, and valid cursors replayed against a different sort/filter/version, are rejected with the restart message.
+- [ ] Typed operators: `contains` on a number column is a 400; enum values outside the declared set are a 400.
+- [ ] Counts: default none; `estimated` uses the planner; `exact-capped` scans at most cap+1 rows (the subquery-LIMIT shape, finding #2).
+- [ ] Org predicate compiles first on every statement; a source with `rowScope` filters rows for the scoped user (cross-org reads return empty/404, never data).
+- [ ] The statement budget fires as a typed error (408), not a hung connection.
+
+## Tiers & publish lint (§5.2/§8)
+
+- [ ] `live` tier publish fails when the source exceeds `reports.liveTierMaxRows`.
+- [ ] `indexed` tier publish fails on missing generated columns/indexes WITH the exact suggestion SQL (`GENERATED ALWAYS AS`, `COMMENT ON COLUMN`, `CREATE INDEX`, `pg_trgm` extension when searchable); applying the snippet verbatim makes the same publish succeed (§8.1 round-trip proven by test).
+- [ ] Plan lint records plan hashes into `compiled` at publish; queries after publish use the physical `rb_*` columns (not raw JSONB).
+- [ ] `materialized` tier requires the declared relation to exist; responses carry `meta.freshAsOf`.
+
+## Row actions & bulk (§6)
+
+- [ ] Mutations delegate to the owning domain — grep proves the reports module performs no UPDATE/DELETE on source tables; `editSubmission` re-validates through the form engine against the stamped `formVersion` (an invalid patch is rejected by the FORM engine, not the grid).
+- [ ] byFilter without a token is rejected; prepare→execute happy path works; drift beyond tolerance → 409 with `currentCount`; expired token → 410.
+- [ ] Idempotency: a retried execute with the same key returns the recorded outcome (`replayed: true`) without re-running.
+- [ ] byIds capped; cross-org ids resolve to nothing (tenancy).
+
+## Tags (§7)
+
+- [ ] `manageTags` gated by `reportTags.manage`; tags normalized; the org vocabulary setting enforced when non-empty; `label:*` single-valued replacement works.
+- [ ] `$tags` hydration and `hasTag`/`hasAnyTag` filters proven against the `ReportRowTag` table.
+
+## Exports (§9)
+
+- [ ] Sync export streams with `Content-Disposition` and the right MIME; async export creates the job + outbox row in ONE transaction, runs on the worker, lands an org-bound `UploadedFile`, and is pollable.
+- [ ] Both run inside one `REPEATABLE READ` snapshot; the duration bound rejects over-long exports with the tier guidance.
+- [ ] **Every** export writes an audit row with report key, version, filter snapshot, row count, and the exact column list; `exportable: false` columns never appear even when explicitly requested.
+- [ ] XLSX output opens (structurally valid OOXML; CSV carries the formula-injection guard).
+
+## Saved views (§4)
+
+- [ ] Shared-view create/update requires `reports.update`; personal views are invisible to other users; duplicate names rejected per the partial uniques.
+- [ ] Publishing a version that drops/retypes a referenced column turns the view `degraded` (named columns), not a 500.
+
+## Envelope & docs
+
+- [ ] Engine error codes map to the documented HTTP statuses through `reports-error.mapper.ts` only; Swagger documents every route (the frontend contract flows from OpenAPI).
+- [ ] `docs/REPORTS.md` matches reality; examples in `src/modules/reports/examples/` publish and serve.
+
+## Test coverage (current state — keep honest)
+
+**Engine unit tests** (`packages/report-builder`, vitest): compiler SQL shapes
+(keyset OR-ladder, null surrogates, collation, bind ordering), cursor/token
+roundtrip + tamper, typed-operator rejection, count subquery, meta-schema +
+linter (incl. the §2.1 plain-path manifest validation), generated-column
+naming/casting, catalog/plan/tier lint, suggestion-SQL emission, CSV/XLSX,
+and all six services over in-memory port fakes.
+
+**Template e2e** (`test/reports-query.e2e-spec.ts`, `test/reports-advanced.e2e-spec.ts`,
+real Postgres over the org-members CUSTOM source): publish→query, keyset
+paging, typed filter rejection, meta, permission gating, saved views +
+compatibility, tags, sync CSV export; byFilter prepare/execute **token
+protocol + drift (409) + idempotent replay**, the reports-owned **async
+export worker + download**, **XLSX zip validity**, the **PII-egress audit
+row**, **shared-view partial-unique** (409), and **indexed-tier publish
+rejection with the `CREATE INDEX` migration snippet**.
+
+**Not yet covered by e2e (unit-proven only — flag before claiming complete):**
+the `materialized` tier (needs a real materialized view), the indexed-tier
+publish *success* round-trip after applying the suggested migration, and the
+boot schema-check *failure* path (the success path is proven by every boot).

package/template/prisma/migrations/20260612000000_add_form_builder/migration.sql

@@ -0,0 +1,147 @@
+-- CreateEnum
+CREATE TYPE "FormDefinitionStatus" AS ENUM ('DRAFT', 'PUBLISHED', 'ARCHIVED');
+
+-- CreateEnum
+CREATE TYPE "SubmissionStatus" AS ENUM ('DRAFT', 'SUBMITTED');
+
+-- CreateEnum
+CREATE TYPE "FormActionStatus" AS ENUM ('OK', 'ERROR');
+
+-- CreateEnum
+CREATE TYPE "OutboxStatus" AS ENUM ('PENDING', 'PROCESSING', 'DONE', 'FAILED');
+
+-- CreateEnum
+CREATE TYPE "FileStatus" AS ENUM ('TEMPORARY', 'SCANNING', 'CLEAN', 'INFECTED', 'LINKED');
+
+-- CreateTable
+CREATE TABLE "FormDefinition" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "version" INTEGER NOT NULL,
+    "status" "FormDefinitionStatus" NOT NULL DEFAULT 'DRAFT',
+    "schema" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FormDefinition_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "FormSubmission" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "formKey" TEXT NOT NULL,
+    "formVersion" INTEGER NOT NULL,
+    "data" JSONB NOT NULL,
+    "status" "SubmissionStatus" NOT NULL DEFAULT 'DRAFT',
+    "locked" BOOLEAN NOT NULL DEFAULT false,
+    "createdBy" TEXT,
+    "ipAddress" TEXT,
+    "userAgent" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FormSubmission_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "FormActionLog" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "submissionId" TEXT,
+    "formKey" TEXT NOT NULL,
+    "formVersion" INTEGER,
+    "action" TEXT NOT NULL,
+    "status" "FormActionStatus" NOT NULL,
+    "input" JSONB,
+    "output" JSONB,
+    "errorCode" TEXT,
+    "errorMessage" TEXT,
+    "actorId" TEXT,
+    "requestId" TEXT,
+    "durationMs" INTEGER,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "FormActionLog_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "FormOutboxJob" (
+    "id" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "payload" JSONB NOT NULL,
+    "status" "OutboxStatus" NOT NULL DEFAULT 'PENDING',
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "maxAttempts" INTEGER NOT NULL DEFAULT 8,
+    "idempotencyKey" TEXT,
+    "lastError" TEXT,
+    "runAfter" TIMESTAMP(3),
+    "orgId" TEXT,
+    "actorUserId" TEXT,
+    "originRequestId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "FormOutboxJob_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "UploadedFile" (
+    "id" TEXT NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "originalName" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "checksum" TEXT NOT NULL,
+    "ownerId" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "status" "FileStatus" NOT NULL DEFAULT 'TEMPORARY',
+    "submissionId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "UploadedFile_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "FormDefinition_orgId_idx" ON "FormDefinition"("orgId");
+
+-- CreateIndex
+CREATE INDEX "FormDefinition_orgId_status_idx" ON "FormDefinition"("orgId", "status");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "FormDefinition_orgId_key_version_key" ON "FormDefinition"("orgId", "key", "version");
+
+-- CreateIndex
+CREATE INDEX "FormSubmission_orgId_formKey_status_idx" ON "FormSubmission"("orgId", "formKey", "status");
+
+-- CreateIndex
+CREATE INDEX "FormSubmission_orgId_createdAt_idx" ON "FormSubmission"("orgId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "FormSubmission_orgId_formKey_ipAddress_createdAt_idx" ON "FormSubmission"("orgId", "formKey", "ipAddress", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "FormActionLog_orgId_createdAt_idx" ON "FormActionLog"("orgId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "FormActionLog_orgId_formKey_action_status_idx" ON "FormActionLog"("orgId", "formKey", "action", "status");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "FormOutboxJob_idempotencyKey_key" ON "FormOutboxJob"("idempotencyKey");
+
+-- CreateIndex
+CREATE INDEX "FormOutboxJob_status_runAfter_idx" ON "FormOutboxJob"("status", "runAfter");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "UploadedFile_storageKey_key" ON "UploadedFile"("storageKey");
+
+-- CreateIndex
+CREATE INDEX "UploadedFile_orgId_status_idx" ON "UploadedFile"("orgId", "status");
+
+-- CreateIndex
+CREATE INDEX "UploadedFile_ownerId_status_idx" ON "UploadedFile"("ownerId", "status");
+
+-- CreateIndex
+CREATE INDEX "UploadedFile_status_createdAt_idx" ON "UploadedFile"("status", "createdAt");
+

package/template/prisma/migrations/20260613000000_add_report_builder/migration.sql

@@ -0,0 +1,129 @@
+-- CreateEnum
+CREATE TYPE "ReportDefinitionStatus" AS ENUM ('DRAFT', 'PUBLISHED', 'ARCHIVED');
+
+-- CreateEnum
+CREATE TYPE "ReportExportStatus" AS ENUM ('PENDING', 'RUNNING', 'DONE', 'FAILED');
+
+-- CreateEnum
+CREATE TYPE "ReportActionRunStatus" AS ENUM ('RUNNING', 'DONE', 'FAILED');
+
+-- CreateTable
+CREATE TABLE "ReportDefinition" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "version" INTEGER NOT NULL,
+    "status" "ReportDefinitionStatus" NOT NULL DEFAULT 'DRAFT',
+    "schema" JSONB NOT NULL,
+    "compiled" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ReportDefinition_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportSavedView" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "reportKey" TEXT NOT NULL,
+    "reportVersion" INTEGER NOT NULL,
+    "name" TEXT NOT NULL,
+    "spec" JSONB NOT NULL,
+    "ownerId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ReportSavedView_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportExportJob" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "reportKey" TEXT NOT NULL,
+    "reportVersion" INTEGER NOT NULL,
+    "spec" JSONB NOT NULL,
+    "asOf" TIMESTAMP(3),
+    "status" "ReportExportStatus" NOT NULL DEFAULT 'PENDING',
+    "fileId" TEXT,
+    "rowCount" INTEGER,
+    "error" TEXT,
+    "requestedBy" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ReportExportJob_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportBulkActionRun" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "reportKey" TEXT NOT NULL,
+    "reportVersion" INTEGER NOT NULL,
+    "action" TEXT NOT NULL,
+    "idempotencyKey" TEXT NOT NULL,
+    "status" "ReportActionRunStatus" NOT NULL DEFAULT 'RUNNING',
+    "result" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ReportBulkActionRun_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ReportRowTag" (
+    "id" TEXT NOT NULL,
+    "orgId" TEXT NOT NULL,
+    "sourceKind" TEXT NOT NULL,
+    "sourceKey" TEXT NOT NULL,
+    "rowId" TEXT NOT NULL,
+    "tag" TEXT NOT NULL,
+    "createdBy" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ReportRowTag_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ReportDefinition_orgId_key_version_key" ON "ReportDefinition"("orgId", "key", "version");
+
+-- CreateIndex
+CREATE INDEX "ReportDefinition_orgId_idx" ON "ReportDefinition"("orgId");
+
+-- CreateIndex
+CREATE INDEX "ReportDefinition_orgId_status_idx" ON "ReportDefinition"("orgId", "status");
+
+-- CreateIndex
+CREATE INDEX "ReportSavedView_orgId_reportKey_idx" ON "ReportSavedView"("orgId", "reportKey");
+
+-- CreateIndex
+CREATE INDEX "ReportExportJob_orgId_status_idx" ON "ReportExportJob"("orgId", "status");
+
+-- CreateIndex
+CREATE INDEX "ReportExportJob_orgId_createdAt_idx" ON "ReportExportJob"("orgId", "createdAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ReportBulkActionRun_orgId_idempotencyKey_key" ON "ReportBulkActionRun"("orgId", "idempotencyKey");
+
+-- CreateIndex
+CREATE INDEX "ReportBulkActionRun_orgId_reportKey_action_idx" ON "ReportBulkActionRun"("orgId", "reportKey", "action");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ReportRowTag_orgId_sourceKind_sourceKey_rowId_tag_key" ON "ReportRowTag"("orgId", "sourceKind", "sourceKey", "rowId", "tag");
+
+-- CreateIndex
+CREATE INDEX "ReportRowTag_orgId_sourceKind_sourceKey_tag_idx" ON "ReportRowTag"("orgId", "sourceKind", "sourceKey", "tag");
+
+-- CreateIndex
+CREATE INDEX "ReportRowTag_orgId_sourceKind_sourceKey_rowId_idx" ON "ReportRowTag"("orgId", "sourceKind", "sourceKey", "rowId");
+
+-- Partial unique indexes for saved-view names (report design §12, finding #5).
+-- Postgres treats NULLs as distinct, so a plain unique over nullable "ownerId"
+-- would not deduplicate SHARED views. Prisma cannot express partial indexes:
+-- if a later `prisma migrate dev` proposes dropping these, DELETE those DROP
+-- lines — the reports boot check fails fast when they are missing.
+CREATE UNIQUE INDEX "report_view_shared_uq"
+  ON "ReportSavedView" ("orgId", "reportKey", "name") WHERE "ownerId" IS NULL;
+CREATE UNIQUE INDEX "report_view_personal_uq"
+  ON "ReportSavedView" ("orgId", "reportKey", "ownerId", "name") WHERE "ownerId" IS NOT NULL;

package/template/prisma/schema.prisma

@@ -297,3 +297,288 @@ model AuditLog {
   @@index([targetType, targetId])
   @@index([createdAt])
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// @ftisindia/form-builder — canonical Prisma model snippet (ENGINE_SCHEMA_VERSION 1)
+//
+// The APP owns schema.prisma and the migration history (ecosystem guide §10.1).
+// Copy these models into your app's prisma/schema.prisma verbatim and run
+// `prisma migrate dev`. The glue module's boot-time check verifies the live
+// database matches this snippet's tables/columns and fails fast otherwise.
+// Conventions follow the FTIS template: uuid() ids, UPPER_CASE enum values,
+// org-leading hot indexes, explicit orgId on every engine table.
+// ─────────────────────────────────────────────────────────────────────────────
+
+enum FormDefinitionStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+enum SubmissionStatus {
+  DRAFT
+  SUBMITTED
+}
+
+enum FormActionStatus {
+  OK
+  ERROR
+}
+
+enum OutboxStatus {
+  PENDING
+  PROCESSING
+  DONE
+  FAILED
+}
+
+enum FileStatus {
+  TEMPORARY
+  SCANNING
+  CLEAN
+  INFECTED
+  LINKED
+}
+
+model FormDefinition {
+  id     String               @id @default(uuid())
+  orgId  String
+  key    String
+  // Bumped on every published change; published rows are immutable.
+  version Int
+  status  FormDefinitionStatus @default(DRAFT)
+  // The full FormDefinition document (JSONB).
+  schema  Json
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, key, version])
+  @@index([orgId])
+  @@index([orgId, status])
+}
+
+model FormSubmission {
+  id      String @id @default(uuid())
+  orgId   String
+  formKey String
+  // The exact definition version the data was captured under. Non-negotiable.
+  formVersion Int
+  // Nested submission payload (JSONB) — submissions are documents, not rows.
+  data   Json
+  status SubmissionStatus @default(DRAFT)
+  // Set by the lockEditing action; locked submissions reject further edits.
+  locked Boolean @default(false)
+
+  createdBy String?
+  // Stamped only on anonymous/public submissions (abuse-control Tier 1).
+  ipAddress String?
+  userAgent String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([orgId, formKey, status])
+  @@index([orgId, createdAt])
+  @@index([orgId, formKey, ipAddress, createdAt])
+}
+
+model FormActionLog {
+  id           String           @id @default(uuid())
+  orgId        String
+  submissionId String?
+  formKey      String
+  formVersion  Int?
+  action       String
+  status       FormActionStatus
+  // Redacted by the engine before write — sensitive fields never land here.
+  input        Json?
+  output       Json?
+  errorCode    String?
+  errorMessage String?
+  actorId      String?
+  requestId    String?
+  durationMs   Int?
+  createdAt    DateTime         @default(now())
+
+  @@index([orgId, createdAt])
+  @@index([orgId, formKey, action, status])
+}
+
+model FormOutboxJob {
+  id      String       @id @default(uuid())
+  type    String
+  payload Json
+  status  OutboxStatus @default(PENDING)
+
+  attempts    Int @default(0)
+  maxAttempts Int @default(8)
+  // Prevents double-send on retry (e.g. submissionId:type:action).
+  idempotencyKey String?   @unique
+  lastError      String?
+  runAfter       DateTime?
+
+  // Worker-context restoration + audit correlation (ecosystem guide §3).
+  orgId           String?
+  actorUserId     String?
+  originRequestId String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([status, runAfter])
+}
+
+model UploadedFile {
+  id           String @id @default(uuid())
+  storageKey   String @unique
+  originalName String
+  // SERVER-VERIFIED (sniffed) MIME type, never the client-sent Content-Type.
+  mimeType String
+  size     Int
+  // sha256 hex.
+  checksum String
+  // Two-factor ownership: uploader identity AND tenant scope (§10).
+  ownerId String
+  orgId   String
+
+  status       FileStatus @default(TEMPORARY)
+  submissionId String?
+
+  createdAt DateTime @default(now())
+
+  @@index([orgId, status])
+  @@index([ownerId, status])
+  @@index([status, createdAt])
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Report builder (@ftisindia/report-builder) — engine tables
+// (REPORTS_ENGINE_SCHEMA_VERSION 1). Copied from the engine's canonical
+// snippet (@ftisindia/report-builder/prisma/reports.prisma); the glue
+// module's boot check verifies the live database matches it. Sources stay
+// where they live — these are the engine's OWN tables only (report design §12).
+// ─────────────────────────────────────────────────────────────────────────────
+
+enum ReportDefinitionStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+enum ReportExportStatus {
+  PENDING
+  RUNNING
+  DONE
+  FAILED
+}
+
+enum ReportActionRunStatus {
+  RUNNING
+  DONE
+  FAILED
+}
+
+model ReportDefinition {
+  id      String                 @id @default(uuid())
+  orgId   String
+  key     String
+  // Bumped on every published change; published rows are immutable.
+  version Int
+  status  ReportDefinitionStatus @default(DRAFT)
+  // The full ReportDefinition document (JSONB).
+  schema  Json
+  // Set at publish: logical→physical column map + plan hashes (report design §5.2/§8.1).
+  compiled Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, key, version])
+  @@index([orgId])
+  @@index([orgId, status])
+}
+
+model ReportSavedView {
+  id            String   @id @default(uuid())
+  orgId         String
+  reportKey     String
+  // The definition version the view was authored against (report design §4).
+  reportVersion Int
+  name          String
+  // The saved QuerySpec (JSONB).
+  spec          Json
+  // null ⇒ shared with the whole org (creation gated by reports.update).
+  ownerId       String?
+  createdAt     DateTime @default(now())
+
+  @@index([orgId, reportKey])
+  // Uniqueness lives in PARTIAL UNIQUE INDEXES shipped as raw SQL inside the
+  // add_report_builder migration — Postgres treats NULLs as distinct, so a
+  // @@unique over nullable ownerId would NOT deduplicate shared views (report
+  // design §12, finding #5). If a later `prisma migrate dev` proposes
+  // DROP INDEX "report_view_shared_uq" / "report_view_personal_uq", DELETE
+  // those lines — the reports boot check fails fast if they go missing.
+}
+
+model ReportExportJob {
+  id            String             @id @default(uuid())
+  orgId         String
+  reportKey     String
+  // The version the export ran against (report design §9, finding #1).
+  reportVersion Int
+  // FULL export spec {spec, format, columns} — replayable, auditable (not a hash).
+  spec          Json
+  // REPEATABLE READ snapshot timestamp, set when the job runs (finding #8).
+  asOf          DateTime?
+  status        ReportExportStatus @default(PENDING)
+  // UploadedFile id once the async export lands in file storage.
+  fileId        String?
+  rowCount      Int?
+  error         String?
+  requestedBy   String
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([orgId, status])
+  @@index([orgId, createdAt])
+}
+
+model ReportBulkActionRun {
+  id             String                @id @default(uuid())
+  orgId          String
+  reportKey      String
+  reportVersion  Int
+  action         String
+  // Client-supplied; a retried execute with the same key returns the recorded
+  // outcome instead of re-running (report design §6.3, finding #7).
+  idempotencyKey String
+  status         ReportActionRunStatus @default(RUNNING)
+  result         Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([orgId, idempotencyKey])
+  @@index([orgId, reportKey, action])
+}
+
+model ReportRowTag {
+  id         String   @id @default(uuid())
+  orgId      String
+  // 'custom' | 'form' | any registered source-provider kind.
+  sourceKind String
+  // Custom source key or form key.
+  sourceKey  String
+  // The source's declared, STABLE row identity (report design §7).
+  rowId      String
+  // Normalized: lowercased, trimmed. Labels are single-valued by convention
+  // ("label:approved") — one table, one mechanism.
+  tag        String
+  createdBy  String
+  createdAt  DateTime @default(now())
+
+  @@unique([orgId, sourceKind, sourceKey, rowId, tag])
+  @@index([orgId, sourceKind, sourceKey, tag])
+  @@index([orgId, sourceKind, sourceKey, rowId])
+}