@ftisindia/create-app 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftisindia/create-app",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "One-command scaffolder for the Phase 1 NestJS foundation starter.",
   "type": "module",
   "bin": {

package/template/.env.example

@@ -13,6 +13,10 @@ AUTH_GOOGLE_ENABLED=false
 AUTH_GOOGLE_CLIENT_ID=
 AUTH_GOOGLE_CLIENT_SECRET=
 AUTH_GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback
+# The backend redirects the browser here with a one-time ?code= after Google
+# login. When a frontend app consumes this API (for example one scaffolded with
+# @ftisindia/create-frontend), point this at the frontend's login route, e.g.
+# AUTH_GOOGLE_SUCCESS_REDIRECT_URL=http://localhost:4200/login
 AUTH_GOOGLE_SUCCESS_REDIRECT_URL=http://localhost:3000/auth/google/success
 AUTH_GOOGLE_ERROR_REDIRECT_URL=http://localhost:3000/auth/google/error
 # Required when AUTH_GOOGLE_ENABLED=true. Use at least 32 random characters.
@@ -21,6 +25,12 @@ AUTH_FACEBOOK_ENABLED=false
 AUTH_MOBILE_OTP_ENABLED=false
 AUTH_MAGIC_LINK_ENABLED=false
 
+CORS_ENABLED=false
+# Comma-separated exact browser origins, for example:
+# CORS_ORIGINS=http://localhost:5173,https://app.example.com
+CORS_ORIGINS=
+CORS_CREDENTIALS=false
+
 RBAC_CACHE_TTL_SECONDS=60
 # Path is the only supported mode in this starter phase.
 ORG_CONTEXT_MODE=path
@@ -34,3 +44,24 @@ TEST_USER_PASSWORD=
 TEST_USER_DISPLAY_NAME=Starter Owner
 TEST_ORG_NAME=Demo Organisation
 TEST_ORG_SLUG=demo
+
+# Form builder (@ftisindia/form-builder)
+FORMS_OUTBOX_ENABLED=true
+FORMS_OUTBOX_POLL_MS=5000
+FORMS_FILE_GC_INTERVAL_MS=3600000
+FORMS_FILE_TEMP_TTL_HOURS=24
+FORMS_MAX_UPLOAD_MB=25
+FORMS_FILE_STORAGE_DIR=./var/uploads
+# Set to off only to bypass the boot-time engine schema check (not recommended).
+FORMS_SCHEMA_CHECK=on
+
+# Report builder (@ftisindia/report-builder)
+# Boot-time schema check for the engine tables (set off only to bypass temporarily).
+REPORTS_SCHEMA_CHECK=on
+# Optional HMAC secret for report cursors/bulk-action tokens (min 32 chars).
+# When empty, a dedicated key is derived from JWT_SECRET via HKDF.
+REPORTS_TOKEN_SECRET=
+# Reports-owned async export worker + file storage (no forms dependency).
+REPORTS_EXPORT_WORKER_ENABLED=true
+REPORTS_EXPORT_POLL_MS=5000
+REPORTS_EXPORT_STORAGE_DIR=./var/report-exports

package/template/README.md

@@ -78,6 +78,7 @@ GET  /auth/google
 GET  /auth/google/callback
 GET  /auth/me
 POST /organisations
+GET  /organisations/mine
 GET  /organisations/:orgId/memberships/me
 GET  /organisations/:orgId/memberships
 PATCH /organisations/:orgId/memberships/:membershipId/status
@@ -91,6 +92,7 @@ POST /organisations/:orgId/invitations/:invitationId/revoke
 POST /organisations/:orgId/invitations/:invitationId/resend
 POST /invitations/accept
 POST /invitations/decline
+GET  /organisations/:orgId/access-control/me
 GET  /organisations/:orgId/access-control/permissions
 GET  /organisations/:orgId/access-control/route-permissions
 GET  /organisations/:orgId/access-control/roles
@@ -107,6 +109,36 @@ GET  /organisations/:orgId/sample/status
 POST /organisations/:orgId/sample/echo
 ```
 
+## Frontend Bootstrap
+
+After login, call `GET /organisations/mine` to populate the organisation picker,
+store the selected `orgId`, then call
+`GET /organisations/:orgId/access-control/me`. Use the returned
+`permissionKeys` for route, menu, and button visibility in the frontend. Backend
+guards remain the source of truth for access control.
+
+A companion frontend starter exists: `npx @ftisindia/create-frontend my-app`
+scaffolds an Angular app already wired to these endpoints.
+
+### Google OAuth with a frontend
+
+`GET /auth/google/callback` redirects the browser to
+`AUTH_GOOGLE_SUCCESS_REDIRECT_URL` with a one-time `?code=` that the frontend
+must exchange via `POST /auth/oauth/exchange`. The default value points at the
+backend's own origin, so set it to the frontend's login route (for example
+`http://localhost:4200/login`) or the code never reaches the frontend.
+
+### Exporting the OpenAPI document
+
+Frontend tooling can consume the API contract without a running server:
+
+```bash
+npm run export:openapi
+```
+
+This writes `docs-json.json` (the same document served at `/docs-json`) to the
+project root. No database connection is required.
+
 ## Architecture Rules
 
 - JWTs contain identity only. Organisation membership, roles, and permissions are read per request.
@@ -116,6 +148,35 @@ POST /organisations/:orgId/sample/echo
 - Mutating business flows should write audit rows.
 - Setup and CI commands are non-destructive. Use `npm run db:reset` only when you explicitly want to reset a local database.
 
+## Dynamic Forms
+
+The app ships with a definition-driven form engine (`@ftisindia/form-builder`
+plus the `src/modules/forms` glue module). Form definitions are versioned JSON
+documents created over the API; submissions run a validated, transactional
+action pipeline with a reliable outbox for emails/webhooks. Most new forms
+need zero backend code — register a field type, action, or data source only
+when you need genuinely new behavior.
+
+- Guide: `docs/FORMS.md` (endpoints, extension story, webhooks, public forms, files, upgrades)
+- Completion standard: `docs/FORMS_CHECKLIST.md`
+- Example definitions: `src/modules/forms/examples/` (registration, abstract submission, login-as-a-form)
+- Definitions as code: `npm run gen:form -- <key>` scaffolds a definition + lint spec; `npm run forms:push` loads it into an org (linted, versioned, audited)
+
+## Dynamic Reports
+
+The app also ships with a definition-driven report engine
+(`@ftisindia/report-builder` plus the `src/modules/reports` glue module).
+Report definitions are versioned JSON views over registered data sources —
+form submissions are one convenient kind, any table/join is another — with
+filtering, sorting, search, keyset pagination, drift-safe bulk row actions,
+tags, saved views, and snapshot-consistent CSV/XLSX exports through one
+declarative API. Performance is enforced at publish time: unindexed shapes
+fail to publish and the error carries the exact migration SQL to fix them.
+
+- Guide: `docs/REPORTS.md` (QuerySpec, sources, tiers, actions, exports, upgrades)
+- Completion standard: `docs/REPORTS_CHECKLIST.md`
+- Example definitions: `src/modules/reports/examples/` (org-members over a custom source, abstract-review-board over a form)
+
 ## Adding Features
 
 Use the sample module as the copy-paste reference:

package/template/_gitignore

@@ -5,3 +5,9 @@ coverage/
 .env
 .env.*
 !.env.example
+
+# Generated by npm run export:openapi
+docs-json.json
+
+# Form-builder local file storage
+var/

package/template/_package.json

@@ -6,8 +6,11 @@
   "scripts": {
     "build": "nest build",
     "db:create": "node scripts/db-create.mjs",
+    "export:openapi": "ts-node scripts/export-openapi.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "forms:push": "ts-node scripts/push-form.ts",
+    "gen:form": "node scripts/gen-form.mjs",
     "gen:module": "node scripts/gen-module.mjs",
     "lint": "eslint .",
     "prepare": "husky || true",
@@ -30,6 +33,8 @@
   },
   "dependencies": {
     "@casl/ability": "6.8.1",
+    "@ftisindia/form-builder": "^0.1.0",
+    "@ftisindia/report-builder": "^0.1.0",
     "@nestjs/common": "11.1.24",
     "@nestjs/config": "4.0.4",
     "@nestjs/core": "11.1.24",
@@ -56,6 +61,7 @@
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.1.24",
     "@types/jest": "30.0.0",
+    "@types/multer": "1.4.13",
     "@types/node": "20.19.41",
     "@types/passport": "1.0.17",
     "@types/passport-google-oauth20": "2.0.17",

package/template/docs/FORMS.md

@@ -0,0 +1,169 @@
+# Forms Module (`@ftisindia/form-builder`)
+
+This app ships with a definition-driven dynamic form engine. Form definitions
+are versioned JSON documents in the database; behavior — field types, button
+actions, data sources — is code this app registers. New forms are **data**:
+most ship with zero backend code.
+
+- Engine architecture: the `form-builder-design.md` / ecosystem guide pair in
+  the starter repository.
+- Completion standard: [`FORMS_CHECKLIST.md`](./FORMS_CHECKLIST.md) on top of
+  [`MODULE_COMPLETION_CHECKLIST.md`](./MODULE_COMPLETION_CHECKLIST.md).
+
+## The 60-second tour
+
+```text
+POST   /organisations/:orgId/forms                                  forms.create   (new draft version)
+PATCH  /organisations/:orgId/forms/:key/versions/:v                 forms.update   (drafts only)
+POST   /organisations/:orgId/forms/:key/versions/:v/publish         forms.publish  (lints, freezes, archives prior)
+POST   /organisations/:orgId/forms/:key/versions/:v/public-access   forms.managePublicAccess (audited)
+GET    /organisations/:orgId/forms/:key/render                      formSubmissions.create (definition + options)
+POST   /organisations/:orgId/forms/:key/submissions                 formSubmissions.create { mode, data, ... }
+POST   /organisations/:orgId/forms/:key/files?field=<name>          formSubmissions.create (upload before submit)
+GET    /organisations/:orgId/forms/:key/submissions/export          formSubmissions.export (audited PII egress)
+GET    /public/organisations/:orgId/forms/:key/render|submissions   (anonymous, public forms only)
+```
+
+Example definitions live in `src/modules/forms/examples/` — registration
+(plain persist), abstract-submission (nested repeatable groups, data source,
+rules, file upload), and login (public form whose submit action delegates to
+the real `AuthService`).
+
+## How it executes
+
+A submit runs: coerce → overwrite `source: 'context'` hidden fields from the
+request context (client values for them are always discarded) → lifecycle
+hooks → full validation (JSON Schema in draft or submit mode + bounded
+json-logic rules + data-source membership + file references) → the action
+pipeline: validation actions, then **all transactional actions in ONE
+database transaction** (submission, action logs, audit rows, outbox rows
+commit or roll back together), then post-commit side effects via the
+**transactional outbox** (in-process poller, retries with backoff, parks as
+FAILED after max attempts; delivery writes an audit row). A failed email
+never rolls back a valid submission; a failed transactional step rolls back
+everything.
+
+## Adding behavior (the three registries)
+
+Implement the engine interface, decorate the provider, list it in a module —
+the registry bootstrap finds it at startup:
+
+```ts
+import { FormDataSource } from './modules/forms/infrastructure/registry/form-extension.decorators';
+import type { DataSourceDef, DataSourceContext, DataSourceOption } from '@ftisindia/form-builder';
+
+@Injectable()
+@FormDataSource()
+export class TrackSource implements DataSourceDef {
+  key = 'conference-tracks';
+  constructor(private readonly prisma: PrismaService) {}
+  async fetch(_params: Record<string, unknown>, ctx: DataSourceContext): Promise<DataSourceOption[]> {
+    return this.prisma.track.findMany({
+      where: { orgId: ctx.orgId, active: true },
+      select: { id: true, name: true },
+    }).then((rows) => rows.map((row) => ({ value: row.id, label: row.name })));
+  }
+}
+```
+
+Same pattern with `@FormFieldType()` (implement `FieldTypeDef`),
+`@FormActionHandler()` (implement `FormAction`), `@FormLifecycleHook()`
+(implement `FormLifecycle`). Builtin actions: `validateAll`, `persist`,
+`persistDraft`, `lockEditing`; shipped app actions: `sendConfirmationEmail`
+(post-commit, enqueues email), `authenticate` (dangerous, delegates to
+`AuthService.login`).
+
+## Dangerous actions
+
+An action with `dangerous: true` (payments, auth, anything with teeth) is
+triple-gated: wiring it into a definition requires `forms.wireDangerous` AND
+membership in the org's `forms.allowedDangerousActions` typed setting (both
+checked at save/publish); at execute time the allowlist is re-checked. The
+linter also refuses pipelines combining `authenticate` with `persist` —
+credentials are never stored, and dangerous actions' input/output are logged
+as `[REDACTED]`.
+
+## Public forms
+
+Flip a published definition with `POST .../public-access { "access": "public" }`
+(requires `forms.managePublicAccess`, writes an audit row). Public routes are
+throttled tighter than the app default; the engine enforces the per-IP/day
+cap (`forms.maxSubmissionsPerIpPerDay` setting, per-form override in the
+definition's `settings`) and the captcha seam (`settings.captcha: true` —
+publish fails closed unless a `CaptchaVerifier` is bound to the
+`FORMS_CAPTCHA_VERIFIER` token). Public forms cannot contain file fields.
+
+## Files
+
+Upload before submit (`POST .../files?field=<name>`); the submission carries
+only `{ "fieldName": { "fileId": "..." } }`. The server sniffs the MIME type
+from content, enforces field + org size caps, computes a sha256, and binds
+the file to uploader AND org. Submit-time linking re-verifies ownership
+in-transaction and promotes TEMPORARY → LINKED; orphans are garbage-collected
+after `FORMS_FILE_TEMP_TTL_HOURS`. Bytes live under `FORMS_FILE_STORAGE_DIR`
+(swap `LocalDiskStorageAdapter` for S3/GCS without engine changes).
+
+## Webhooks
+
+A definition can declare webhook destinations that fire when a submission is
+**submitted** (never for drafts, never for pipelines without `persist`):
+
+```jsonc
+"settings": {
+  "webhooks": [
+    { "url": "https://hooks.example.com/forms", "secret": "rotate-me", "includeData": true }
+  ]
+}
+```
+
+- **Reliable by construction:** the job is written to the transactional outbox
+  inside the same transaction as the submission, then delivered post-commit
+  with retries/backoff (parks as FAILED after max attempts; success writes a
+  `forms.outbox.delivered` audit row). Idempotency key: `<submissionId>:webhook:<index>`.
+- **SSRF-gated:** the destination host must be in the org's audited
+  `forms.webhookAllowedHosts` typed setting (default empty = webhooks
+  disabled), and the URL must be `https` — `http` is allowed for loopback
+  hosts only (local development). Enforced at save AND publish lint
+  (`WEBHOOK_HOST_NOT_ALLOWED`, `WEBHOOK_URL_INSECURE`, …).
+- **Payload:** `{ event: 'submitted', orgId, formKey, formVersion, submissionId,
+  occurredAt, data? }` — `data` passes sensitive-field redaction; set
+  `includeData: false` to send a pure notification.
+- **Signed:** with a `secret`, deliveries carry
+  `x-forms-signature: sha256=<hmac-sha256(rawBody)>`. The secret lives in the
+  definition document (DB) — treat it as a rotatable shared token, not a
+  master credential. Max 5 webhooks per definition.
+
+## Definitions as code (`gen:form` + `forms:push`)
+
+```bash
+npm run gen:form -- customer-feedback            # scaffolds definition + lint spec
+npm test                                         # spec lints the JSON, no DB needed
+npm run forms:push -- --file src/modules/forms/definitions/customer-feedback.form.json \
+    --org demo --user owner@example.com --publish
+```
+
+`gen:form` writes `src/modules/forms/definitions/<key>.form.json` and
+`test/<key>.form.spec.ts` (meta-schema + publish-stage lint — fails `npm test`
+the moment the definition would be rejected by the API). `forms:push` loads a
+definition file into an org through the real engine path: it impersonates an
+existing member (their RBAC applies), so every push is linted, versioned, and
+audited exactly like an HTTP call. Re-pushing an unchanged file is a no-op;
+changed content creates the next version (add `--publish` to go live).
+
+## Org settings & env
+
+Typed settings: `forms.allowedDangerousActions` (string[]),
+`forms.maxFileSizeMb`, `forms.enableRuleIteration`, `forms.virusScanRequired`
+(seam only — no scanner shipped), `forms.maxSubmissionsPerIpPerDay`.
+Env knobs (see `.env.example`): `FORMS_OUTBOX_ENABLED`, `FORMS_OUTBOX_POLL_MS`,
+`FORMS_FILE_GC_INTERVAL_MS`, `FORMS_FILE_TEMP_TTL_HOURS`, `FORMS_MAX_UPLOAD_MB`,
+`FORMS_FILE_STORAGE_DIR`, `FORMS_SCHEMA_CHECK`.
+
+## Engine upgrades (schema ownership)
+
+This app owns `schema.prisma` and the migration history. When a new engine
+version changes its data model: read its changelog, copy the updated snippet
+from `node_modules/@ftisindia/form-builder/prisma/forms.prisma` into
+`prisma/schema.prisma`, run `npx prisma migrate dev`. The boot-time schema
+check fails fast with exactly that instruction if the database and engine
+ever disagree (`FORMS_SCHEMA_CHECK=off` is the emergency hatch).

package/template/docs/FORMS_CHECKLIST.md

@@ -0,0 +1,61 @@
+# Forms Module Completion Checklist
+
+The forms module must pass `MODULE_COMPLETION_CHECKLIST.md` verbatim, **plus**
+these form-builder-specific items (ecosystem guide §11). Re-verify after any
+engine upgrade or forms-module change.
+
+## Boundary
+
+- [ ] The engine package (`@ftisindia/form-builder`) compiles and unit-tests **without** the template; only `src/modules/forms` imports template services.
+- [ ] The engine's boundary lint passes: no `@nestjs/*`, `@prisma/*`, `@casl/*`, or template imports anywhere in the engine core; engine errors are engine-typed and mapped to HTTP exceptions only in the glue (`forms-error.mapper.ts`).
+
+## Schema ownership
+
+- [ ] Boot-time schema check proven both ways: green on a freshly migrated app; clear fail-fast message (naming the engine schema version and the snippet path) on a deliberately stale schema.
+- [ ] `prisma/forms.prisma` in the engine matches the models in the app's `schema.prisma`; upgrades follow copy-snippet → `prisma migrate dev`.
+
+## Permissions & registry
+
+- [ ] All 11 form permission keys exist in `permissionKeys`, are seeded, and `test/forms-permission-sync.spec.ts` passes (engine ↔ template set equality).
+- [ ] Every protected form route is in `routePermissionRegistry` (the boot-time registry validator passes).
+
+## Gating
+
+- [ ] Attach-time gating proven by test: lacking `forms.wireDangerous` ⇒ cannot save/publish a definition wiring a `dangerous` action; the `forms.allowedDangerousActions` org setting is respected at save/publish AND at execute time.
+- [ ] `forms.managePublicAccess` gating proven: lacking it ⇒ cannot set or unset `settings.access = 'public'` (including publishing an already-public draft); every flip writes an audit row with previous/next.
+
+## Tenancy
+
+- [ ] Cross-org tests: definition fetch, submission read, and file reference across orgs are rejected as not-found.
+
+## Transactionality & outbox
+
+- [ ] Phase-2 transactionality proven: an induced `lockEditing` failure rolls back persist **and** in-tx action logs **and** enqueued outbox rows.
+- [ ] Outbox worker runs inside `requestContext.run({ source: 'worker', jobId, orgId, userId, requestId })`; retries honor backoff; exhausted jobs park as `FAILED`; an audit row (`forms.outbox.delivered`) is written on final success.
+
+## Public forms
+
+- [ ] Public path: `@Public()` render/submit works without membership; a non-public form 404s on the public routes; org-scoped storage still enforced; permissioned paths unaffected.
+- [ ] Tier-1 abuse baseline active: public routes throttled tighter than the app default; per-IP/day caps read from typed settings (with per-form override) and enforced; IP/UA stamped on anonymous submissions; captcha seam invoked when enabled; captcha-enabled-without-adapter fails at publish, not at submit.
+
+## Files
+
+- [ ] Upload → submit → `LINKED` flow proven; a foreign user's `fileId` is rejected (IDOR); GC sweeps orphaned `TEMPORARY` files past TTL; public forms with file fields are rejected at publish.
+
+## Webhooks
+
+- [ ] Webhook destinations are gated by the `forms.webhookAllowedHosts` setting at save AND publish (`WEBHOOK_HOST_NOT_ALLOWED`); https required except loopback (`WEBHOOK_URL_INSECURE`).
+- [ ] Webhook jobs enqueue inside the submit transaction (idempotency key `<submissionId>:webhook:<i>`), never on draft saves or persist-less pipelines.
+- [ ] Deliveries are signed (`x-forms-signature`) when a secret is set; payload data passes sensitive-field redaction; failures retry then park as FAILED.
+- [ ] `forms:push` loads definitions only through the audited service path (real member RBAC, save-time lint, versioning) — never raw DB writes.
+
+## Export & redaction
+
+- [ ] `formSubmissions.export` enforced independently of `.read`; **every** export writes an audit row with form key, filters, row count, and included fields.
+- [ ] Credential/sensitive fields never appear in `FormActionLog` or `AuditLog` metadata (redaction test); dangerous actions log `[REDACTED]` for input and output.
+
+## Envelope & docs
+
+- [ ] Engine validation errors arrive as `{ error: { code, message, details: { errors: [...] } } }` through the global filter; lint failures carry `details.issues`.
+- [ ] Engine-thrown denials and not-founds are indistinguishable in shape from the template's own.
+- [ ] Swagger documents all form routes (dynamic payloads as `object`).

package/template/docs/REPORTS.md

@@ -0,0 +1,246 @@
+# Reports Module (`@ftisindia/report-builder`)
+
+This app ships with a definition-driven report engine. A report is **a
+declared, versioned view over one data source, plus the verbs users may apply
+to it** — filter, sort, search, paginate, export, and act on rows. Report
+definitions are versioned JSON documents in the database; the behaviors they
+reference — sources, row actions — are code this app registers. New reports
+over existing sources are **data**: most ship with zero backend code.
+
+- Engine architecture: `report-builder/report-builder-design.md` in the
+  starter repository (Rev 2 — the binding spec).
+- Completion standard: [`REPORTS_CHECKLIST.md`](./REPORTS_CHECKLIST.md) on top
+  of [`MODULE_COMPLETION_CHECKLIST.md`](./MODULE_COMPLETION_CHECKLIST.md).
+- The engine is **fully usable without the form builder** — the form adapter
+  is one optional source provider among many (the standalone guarantee).
+
+**Module structure (the standalone guarantee, made structural):**
+`ReportsModule` is self-contained — definitions, queries, views, row actions
+over custom sources, tags, and CSV/XLSX exports (sync + a reports-owned async
+worker and file storage). It imports **no** FormsModule. Form-backed reports
+(`source.kind: "form"`) and the delegated `editSubmission`/`updateStatus` verbs
+live in the **optional** `ReportsFormsModule`, the single artifact aware of
+both engines. Remove its import from `app.module.ts` and reports keeps working
+over custom sources alone.
+
+## The 60-second tour
+
+```text
+GET    /organisations/:orgId/reports                         reports.read     list definitions
+POST   /organisations/:orgId/reports                         reports.create   create draft
+GET    /organisations/:orgId/reports/:key                    reports.read     latest definition
+PATCH  /organisations/:orgId/reports/:key                    reports.update   edit draft (published ⇒ opens v+1)
+POST   /organisations/:orgId/reports/:key/publish            reports.publish  lint + freeze a new version
+POST   /organisations/:orgId/reports/:key/archive            reports.archive  archive the definition
+GET    /organisations/:orgId/reports/:key/meta?version=      reports.read     column/operator/action metadata
+POST   /organisations/:orgId/reports/:key/query              reports.read     THE grid endpoint (QuerySpec)
+GET    /organisations/:orgId/reports/:key/views              reports.read     saved views + compatibility
+POST   /organisations/:orgId/reports/:key/views              reports.read     create PERSONAL view
+POST   /organisations/:orgId/reports/:key/views/shared       reports.update   create SHARED view
+POST   /organisations/:orgId/reports/:key/actions/:n/prepare reports.read*    byFilter token (drift-safe bulk)
+POST   /organisations/:orgId/reports/:key/actions/:n         reports.read*    execute row/bulk action
+POST   /organisations/:orgId/reports/:key/export             reports.export   sync stream or 202 job
+GET    /organisations/:orgId/reports/exports/:jobId          reports.export   async export status
+GET    /organisations/:orgId/reports/exports/:jobId/download reports.export   download a finished export
+```
+
+`*` Row actions are additionally gated by their own declared permission keys
+(e.g. `formSubmissions.update`), checked when the action is wired into a
+definition AND again at execute time.
+
+Example definitions live in `src/modules/reports/examples/` — `org-members`
+(custom source, no form builder anywhere) and `abstract-review-board` (the
+form-backed quick path, indexed tier).
+
+## One contract: the QuerySpec
+
+The frontend never builds queries. Every grid interaction posts a declarative
+spec naming declared column ids and verbs; the backend validates, compiles,
+and applies them:
+
+```jsonc
+POST /organisations/:orgId/reports/abstract-review-board/query
+{
+  "filters": [{ "column": "track", "op": "eq", "value": "trk_ml" }],
+  "search": "transformer",
+  "sort": [{ "column": "createdAt", "dir": "desc" }],
+  "cursor": null,            // keyset cursor from the previous page
+  "pageSize": 50,
+  "count": "none",           // "none" | "estimated" | "exact-capped"
+  "columns": ["title", "track", "status", "createdAt"]
+}
+```
+
+Operators are typed per column (`contains` on a number column is a 400, not a
+seq scan). `GET /reports/:key/meta` describes every column, its operators, the
+wired actions, and export formats — a generic grid UI configures itself from
+it.
+
+## How a query executes (the performance contract)
+
+Slow reports come from four sins; the engine makes them structurally hard:
+
+- **No OFFSET, ever.** Pagination is keyset-only; cursors are opaque,
+  HMAC-signed, and bound to (report, version, sort, filters) — replay against
+  anything else is a 400 telling the client to restart.
+- **Unindexed shapes fail publish.** On the `indexed` tier, every
+  sortable/filterable/searchable column must name its backing index; publish
+  verifies the index against the catalog (expression, opclass, collation,
+  org-leading) AND runs `EXPLAIN` on representative shapes. The failure is
+  constructive: the 422 carries the exact migration SQL to apply.
+- **Counts are a choice.** Default `none` (hasMore comes free), `estimated`
+  (planner estimate, milliseconds), or `exact-capped` (`10000+` beyond cap).
+- **A statement budget backstops everything** — every report query carries
+  `statement_timeout` (`reports.statementTimeoutMs`, default 5s).
+
+The compiler builds every statement from code-owned manifests; user input
+never becomes an identifier and values travel only as bind parameters.
+**SQL expressions can exist only in code** — a definition referencing
+`"path": "title' || (SELECT ...)"` is rejected at save.
+
+## Custom sources (no form builder required)
+
+Register a source in code — one class, one decorator:
+
+```ts
+import { ReportSource } from './modules/reports/infrastructure/registry/report-extension.decorators';
+import type { ReportSourceDef, SourceManifest, SourceQuery } from '@ftisindia/report-builder';
+
+@Injectable()
+@ReportSource()
+export class OrgMembersReportSource implements ReportSourceDef {
+  key = 'org-members';
+  manifest(): SourceManifest { /* columns + types + capabilities + indexes */ }
+  baseQuery(): SourceQuery {
+    return {
+      from: '"Membership" m JOIN "User" u ON u."id" = m."userId"',
+      orgColumn: 'm."orgId"',
+      primaryTable: 'Membership',
+    };
+  }
+}
+```
+
+The source declares structure; the compiler owns query construction — a
+source never sees the QuerySpec, so it cannot be injected and cannot bypass
+the allowlist. The engine injects the org predicate first on every statement,
+plus the source's optional `rowScope` (row-level security in code).
+
+## Reports from forms (the quick path)
+
+Requires the optional `ReportsFormsModule` bridge (imported in `app.module.ts`
+by default in this template). Point a definition at a form and the adapter does
+the thinking:
+
+```jsonc
+{ "source": { "kind": "form", "key": "abstract-submission" }, ... }
+```
+
+- Fields with `reportable: true` become report columns (labels, types, lookup
+  data sources carried over); `indexHint: true` fields are sortable/filterable.
+- **Column-id convention:** a definition column over a form field must use the
+  field path (dots → `_`) as its column id; physical submission columns are
+  referenced as `$row.status`, `$row.createdAt`, `$row.updatedAt`,
+  `$row.createdBy`.
+- On the `indexed` tier the publish lint demands the generated columns + 
+  indexes (hashed `rb_*` names, immutable expressions, datetimes kept as
+  ISO-8601 UTC text + `COLLATE "C"`); the 422's `suggestionSql` is the exact
+  migration to apply — run it, publish again.
+- Grid verbs delegate to the form engine: `editSubmission` re-validates
+  against the submission's stamped `formVersion`; `updateStatus` runs the same
+  pipeline as the form. Both require `formSubmissions.update`. There is no
+  generic UPDATE — the report engine never mutates source rows itself.
+- Version note: columns resolve against the latest **published** form version.
+  Renamed-field mapping across versions needs rename metadata the form
+  definition format does not yet carry.
+
+## Performance tiers
+
+| Tier | Meaning | Publish gate |
+|---|---|---|
+| `live` | Query raw source/JSONB directly | Source row estimate under `reports.liveTierMaxRows` |
+| `indexed` | Hot columns physical + index-declared | Catalog + EXPLAIN lint pass (suggested SQL on failure) |
+| `materialized` | Reads hit a declared materialized relation | Relation exists; staleness bound declared; `meta.freshAsOf` always set |
+
+Tier upgrades are ordinary new versions: v5 `materialized` publishes after its
+migration lands while v4 keeps serving.
+
+## Row actions & drift-safe bulk
+
+Single rows / explicit lists go through `byIds` (capped at 1,000). Filter-based
+bulk (`byFilter`) is a two-step protocol because rows matching at confirmation
+may differ at execution:
+
+1. `POST .../actions/:name/prepare { selection: { byFilter } }` →
+   `{ expectedCount, asOf, actionToken }` (HMAC-signed, 5-minute TTL).
+2. `POST .../actions/:name { selection, actionToken, input, idempotencyKey }` —
+   the server re-resolves the selection; drift beyond tolerance (0 for
+   destructive actions) is a 409 with the current count. The
+   `idempotencyKey` is persisted: a retried execute returns the recorded
+   outcome instead of re-running.
+
+Execution walks rows in keyset order in transactional batches; every batch
+re-applies org + rowScope. Every bulk run writes an audit row with report key,
+version, action, row count, and the filter snapshot.
+
+## Tags & labels
+
+`manageTags` (built-in action, `reportTags.manage`) annotates rows with
+org-scoped tags without touching the source schema. Rows hydrate `$tags`; the
+virtual `$tags` column filters with `hasTag` / `hasAnyTag` (indexed EXISTS).
+Labels are single-valued tags by convention (`label:approved` replaces the
+row family's previous `label:*`). Curate the vocabulary with the
+`reports.tagVocabulary` setting (empty = free-form).
+
+## Exports
+
+`POST /reports/:key/export { format: "csv" | "xlsx", spec?, columns? }`:
+
+- Up to `reports.maxRowsSync` (default 10k): direct stream with
+  `Content-Disposition`. Larger: `202 { job }` — the job is picked up by the
+  reports-owned export worker (polling `ReportExportJob`, no forms outbox),
+  streamed into reports-owned org-scoped file storage
+  (`REPORTS_EXPORT_STORAGE_DIR`), polled at `GET /reports/exports/:jobId`, and
+  downloaded from `GET /reports/exports/:jobId/download`.
+- Every export — sync or async — runs inside ONE `REPEATABLE READ` snapshot
+  (duration-bounded by `reports.exportMaxSnapshotSeconds`); an export that
+  cannot finish in time is rejected with guidance to tighten filters or move
+  to the materialized tier.
+- `reports.export` is never implied by read; **every export writes an audit
+  row** with report key, version, filter snapshot, row count, and the exact
+  column list. Columns marked `exportable: false` are stripped regardless of
+  the requested projection.
+
+## Saved views
+
+Views store the QuerySpec **and the version they were authored against**.
+Listing views returns a `compatibility` verdict per view against the requested
+version — `ok` | `degraded` (names missing/retyped columns) | `incompatible` —
+so a new publish turns stale views into a visible, fixable state instead of a
+silent 500. Personal views need `reports.read`; shared views (no owner) need
+`reports.update`.
+
+## Org settings & env
+
+Typed settings (audited like all settings): `reports.statementTimeoutMs`
+(5000), `reports.exportMaxSnapshotSeconds` (120), `reports.maxRowsSync`
+(10000), `reports.countCap` (10000), `reports.liveTierMaxRows` (50000),
+`reports.resultCacheTtlMs` (0 = cache off), `reports.tagVocabulary` ([]).
+
+Env: `REPORTS_SCHEMA_CHECK` (`on`/`off`); `REPORTS_TOKEN_SECRET` (optional, min
+32 chars — cursor/token HMAC key; when empty a dedicated key is derived from
+`JWT_SECRET` via HKDF; rotating it invalidates outstanding cursors/tokens —
+clients restart from page one); and the reports-owned async-export worker:
+`REPORTS_EXPORT_WORKER_ENABLED` (default true), `REPORTS_EXPORT_POLL_MS`
+(default 5000), `REPORTS_EXPORT_STORAGE_DIR` (default `./var/report-exports`).
+
+## Engine upgrades (schema ownership)
+
+The app owns `schema.prisma` and the migration history; the engine ships the
+canonical snippet at `@ftisindia/report-builder/prisma/reports.prisma` plus
+`REPORTS_ENGINE_SCHEMA_VERSION`. The boot check verifies tables/columns AND
+the two **partial unique indexes** on `ReportSavedView`
+(`report_view_shared_uq`, `report_view_personal_uq`) — Prisma cannot express
+partial indexes, so they live as raw SQL in the `add_report_builder`
+migration. If a later `prisma migrate dev` proposes `DROP INDEX` for them,
+delete those lines; the boot check fails fast if they ever go missing.