@ftisindia/create-app 0.1.6 → 0.2.0

package/package.json

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

package/template/.env.example

@@ -48,6 +48,7 @@ TEST_ORG_SLUG=demo
 # Form builder (@ftisindia/form-builder)
 FORMS_OUTBOX_ENABLED=true
 FORMS_OUTBOX_POLL_MS=5000
+FORMS_OUTBOX_HEARTBEAT_MS=60000
 FORMS_FILE_GC_INTERVAL_MS=3600000
 FORMS_FILE_TEMP_TTL_HOURS=24
 FORMS_MAX_UPLOAD_MB=25
@@ -65,3 +66,5 @@ REPORTS_TOKEN_SECRET=
 REPORTS_EXPORT_WORKER_ENABLED=true
 REPORTS_EXPORT_POLL_MS=5000
 REPORTS_EXPORT_STORAGE_DIR=./var/report-exports
+REPORTS_EXPORT_RETENTION_DAYS=7
+REPORTS_EXPORT_RETENTION_SWEEP_MS=3600000

package/template/_package.json

@@ -27,7 +27,7 @@
     "setup:ci": "node scripts/setup-local.mjs --yes",
     "test": "jest",
     "test:cov": "jest --coverage",
-    "test:e2e": "node scripts/test-db.mjs && jest --config test/jest-e2e.json --runInBand",
+    "test:e2e": "node scripts/test-db.mjs && node ./node_modules/jest/bin/jest.js --config test/jest-e2e.json --runInBand",
     "test:watch": "jest --watch",
     "db:reset": "prisma migrate reset"
   },
@@ -84,6 +84,9 @@
     "typescript-eslint": "8.60.0",
     "typescript": "5.9.3"
   },
+  "overrides": {
+    "js-yaml": "4.2.0"
+  },
   "lint-staged": {
     "*.{js,mjs,ts,json,md,yml,yaml}": "prettier --write",
     "*.{js,mjs,ts}": "eslint --fix"

package/template/docs/FORMS.md

@@ -38,10 +38,11 @@ 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.
+**transactional outbox** (in-process poller with Postgres row-lock claiming,
+idempotent enqueue, claim-token fencing, active-job heartbeat, 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)
 
@@ -57,11 +58,16 @@ import type { DataSourceDef, DataSourceContext, DataSourceOption } from '@ftisin
 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 })));
+  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 })));
   }
 }
 ```
@@ -119,19 +125,32 @@ A definition can declare webhook destinations that fire when a submission is
 - **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>`.
+  `forms.outbox.delivered` audit row). The Prisma store claims jobs with
+  `FOR UPDATE SKIP LOCKED`, assigns an opaque claim token, heartbeats active
+  `PROCESSING` rows with that token, and guards `DONE`/`PENDING`/`FAILED`
+  transitions with the same token so stale workers cannot settle reclaimed
+  jobs. A duplicate idempotency key is a no-op so retries do not roll back the
+  submission. Idempotency key: `<submissionId>:webhook:<index>`, also sent as
+  `x-forms-idempotency-key` for receiver-side dedupe.
 - **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`, …).
+  (`WEBHOOK_HOST_NOT_ALLOWED`, `WEBHOOK_URL_INSECURE`, …). Delivery does a
+  fresh DNS resolution, rejects private/reserved/link-local destinations in
+  `NODE_ENV=production`, pins the request to the resolved IP while preserving
+  Host/SNI, and refuses redirects instead of following them.
 - **Payload:** `{ event: 'submitted', orgId, formKey, formVersion, submissionId,
-  occurredAt, data? }` — `data` passes sensitive-field redaction; set
+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.
+  `x-forms-signature: sha256=<hmac-sha256(rawBody)>`. The engine computes the
+  signature before enqueueing; the outbox payload stores the raw body and
+  signature, not the shared secret. Old-format jobs containing `secret` are
+  sanitized to the new `{ rawBody, signature }` payload before delivery. The
+  secret lives only 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`)
 

package/template/docs/FORMS_CHECKLIST.md

@@ -1,61 +1,69 @@
 # 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.
+The forms module must pass `MODULE_COMPLETION_CHECKLIST.md` verbatim, plus
+these form-builder-specific items from the ecosystem guide. Re-verify after
+any engine upgrade or forms-module change.
+
+Last verified on 2026-06-13 against the generated dogfood app (`test-out`) with
+local PostgreSQL `postgres/root`: `npm run dogfood`, generated app
+`npm run build`, `npm run lint`, `npm test`, `npm run test:e2e`; engine
+`npm test`, `npm run lint`, `npm run typecheck`.
 
 ## 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`).
+- [x] The engine package (`@ftisindia/form-builder`) compiles and unit-tests without the template; only `src/modules/forms` imports template services.
+- [x] 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`.
+- [x] Boot-time schema check proven both ways: green on a freshly migrated app; clear fail-fast message naming the engine schema version and snippet path on a deliberately stale schema.
+- [x] `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).
+- [x] All 11 form permission keys exist in `permissionKeys`, are seeded, and `test/forms-permission-sync.spec.ts` passes (engine <-> template set equality).
+- [x] 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.
+- [x] 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.
+- [x] `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.
+- [x] 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.
+- [x] Phase-2 transactionality proven: an induced `lockEditing` failure rolls back persist and in-tx action logs and enqueued outbox rows.
+- [x] 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.
+- [x] Duplicate outbox enqueue with the same idempotency key is a no-op, not a submission-rolling unique violation.
+- [x] Claimed jobs carry an opaque `claimedBy` lease token; heartbeat and `DONE`/retry/failed terminal transitions are guarded by that token so stale workers cannot settle reclaimed jobs.
+- [x] Active `PROCESSING` jobs heartbeat while handlers run; e2e covers both the store primitive and the actual dispatcher wiring with a slow handler.
 
 ## 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.
+- [x] 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.
+- [x] 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.
+- [x] 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.
+- [x] Webhook destinations are gated by the `forms.webhookAllowedHosts` setting at save AND publish (`WEBHOOK_HOST_NOT_ALLOWED`); https required except loopback (`WEBHOOK_URL_INSECURE`).
+- [x] Webhook jobs enqueue inside the submit transaction (idempotency key `<submissionId>:webhook:<i>`), never on draft saves or persist-less pipelines.
+- [x] Deliveries are signed (`x-forms-signature`) when a secret is set and carry `x-forms-idempotency-key` for receiver-side dedupe; new outbox payloads store the precomputed signature, not the shared secret; legacy secret-bearing payloads are sanitized before delivery; payload data passes sensitive-field redaction; failures retry then park as FAILED.
+- [x] `forms:push` loads definitions only through the audited service path (real member RBAC, save-time lint, versioning) and 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.
+- [x] `formSubmissions.export` enforced independently of `.read`; every export writes an audit row with form key, filters, row count, and included fields.
+- [x] Credential/sensitive fields never appear in `FormActionLog` or `AuditLog` metadata (redaction test); dangerous actions log `[REDACTED]` for input and output; unknown credential-like keys (`apiKey`, `token`, etc.) are defensively redacted.
 
 ## 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`).
+- [x] Engine validation errors arrive as `{ error: { code, message, details: { errors: [...] } } }` through the global filter; lint failures carry `details.issues`.
+- [x] Engine-thrown denials and not-founds are indistinguishable in shape from the template's own.
+- [x] Swagger documents all form routes (dynamic payloads as `object`).

package/template/docs/REPORTS.md

@@ -150,8 +150,8 @@ the thinking:
   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
+- Known limitation: 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
@@ -202,6 +202,13 @@ row family's previous `label:*`). Curate the vocabulary with the
   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`.
+- The default local-disk storage is for a single app instance or for multiple
+  instances sharing the same mounted volume. For horizontal scaling without a
+  shared volume, bind an S3/GCS-backed `ExportFileSink` so downloads can land on
+  any node.
+- Finished async export files are retained for `REPORTS_EXPORT_RETENTION_DAYS`
+  (default 7) and swept by the reports export worker. After expiry, the job row
+  remains for audit/status history but the file is no longer downloadable.
 - 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
@@ -232,7 +239,9 @@ Env: `REPORTS_SCHEMA_CHECK` (`on`/`off`); `REPORTS_TOKEN_SECRET` (optional, min
 `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`).
+(default 5000), `REPORTS_EXPORT_STORAGE_DIR` (default `./var/report-exports`),
+`REPORTS_EXPORT_RETENTION_DAYS` (default 7; 0 disables cleanup), and
+`REPORTS_EXPORT_RETENTION_SWEEP_MS` (default 3600000).
 
 ## Engine upgrades (schema ownership)
 

package/template/docs/REPORTS_CHECKLIST.md

@@ -1,97 +1,152 @@
 # 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).
+This is the current go/no-go record for the reports module 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 and Standalone Guarantee
+
+- [x] The engine package (`@ftisindia/report-builder`) compiles and unit-tests
+  without the template and without `@ftisindia/form-builder` installed. Proof:
+  `.github/workflows/ci.yml` `report-builder-engine`.
+- [x] The engine boundary lint blocks `@nestjs/*`, `@prisma/*`, `@casl/*`,
+  `@ftisindia/form-builder`, and template imports from the core; engine errors
+  are mapped to HTTP only in `reports-error.mapper.ts`.
+- [x] `ReportsModule` imports no `FormsModule`. Custom-source reports, tags,
+  query, row actions, and async exports run from reports-owned glue. Form-backed
+  sources and delegated form verbs live only in `ReportsFormsModule`.
+
+## Schema Ownership
+
+- [x] Boot schema check passes on a migrated app and fails loudly on stale
+  schema. Proof: `test/reports-tiers.e2e-spec.ts`.
+- [x] The check verifies `report_view_shared_uq` and
+  `report_view_personal_uq`, and prints the raw SQL when missing.
+- [x] `packages/report-builder/prisma/reports.prisma` matches the template
+  Prisma models; app-owned migrations carry the raw partial indexes.
+
+## Permissions and Registry
+
+- [x] All report permission keys plus `formSubmissions.update` exist in the
+  template and are synced with the engine list. Proof:
+  `test/reports-permission-sync.spec.ts`.
+- [x] Every report route is listed in `routePermissionRegistry`; the registry
+  validator covers the report controllers.
+- [x] `reports.export` is enforced independently of `reports.read`. Proof:
+  `test/reports-query.e2e-spec.ts`.
+- [x] Row actions are checked at attach time and execute time. Proof:
+  engine linter/action-service unit tests plus route-level e2e for `manageTags`.
+
+## SQL Boundary
+
+- [x] Definition-side SQL is rejected by meta-schema/lint; SQL-shaped paths are
+  rejected before SQL compilation. Proof: engine linter unit tests and
+  `test/reports-query.e2e-spec.ts`.
+- [x] `$row.*` paths resolve only against manifest-exposed physical columns.
+- [x] User values reach SQL only through bind parameters. Proof:
+  `ParamSink`, compiler snapshot tests, and Postgres e2e.
+
+## Query Semantics
+
+- [x] Keyset pagination is proven at depth; `OFFSET` is not used; the row-id
+  tiebreaker is always appended. Proof: compiler tests and
+  `test/reports-query.e2e-spec.ts`.
+- [x] Cursor tamper and replay against changed sort/filter/version are rejected.
+- [x] Typed operators reject invalid combinations before SQL.
+- [x] Counts cover `none`, `estimated`, and the capped subquery `exact-capped`
+  shape.
+- [x] Org predicates compile first; cross-org query/export/action attempts are
+  denied, and cross-org `byIds` resolve to zero rows. Proof:
+  `test/reports-query.e2e-spec.ts`.
+- [x] Statement budgets are applied by `PrismaQueryExecutor` and mapped as typed
+  report errors.
+
+## Tiers and Publish Lint
+
+- [x] `live` tier publish fails above `reports.liveTierMaxRows`. Proof:
+  engine definition/tier-lint tests.
+- [x] `indexed` tier publish fails with migration SQL, and the same draft
+  publishes after applying the required indexes. Proof:
+  `test/reports-tiers.e2e-spec.ts`.
+- [x] Plan lint records compiled metadata at publish; queries use compiled
+  physical columns when present. Proof: engine tier-lint and definition-service
+  tests.
+- [x] `materialized` tier requires the declared relation and returns
+  `meta.freshAsOf`. Proof: `test/reports-tiers.e2e-spec.ts`.
+
+## Row Actions and Bulk
+
+- [x] Reports do not raw-update/delete source tables; mutations delegate to
+  registered action handlers.
+- [x] `byFilter` requires a token; prepare/execute works; drift returns 409;
+  expired tokens are rejected. Proof: engine action-service tests and
+  `test/reports-advanced.e2e-spec.ts`.
+- [x] Idempotency replays recorded outcomes without rerunning the handler.
+- [x] `byIds` is capped and cross-org ids resolve to zero rows. Proof:
+  engine action-service tests and `test/reports-query.e2e-spec.ts`.
+
+## Tags
+
+- [x] `manageTags` is gated by `reportTags.manage`; tags normalize; curated
+  vocabulary and `label:*` replacement are covered by engine tests.
+- [x] `$tags` hydration and `hasTag` filters are covered against the
+  `ReportRowTag` table. Proof: `test/reports-query.e2e-spec.ts`.
+
+## Exports
+
+- [x] Sync export streams with `Content-Disposition`; async export creates a
+  `ReportExportJob`, runs on the reports-owned worker, writes a storage fileId,
+  and is pollable/downloadable.
+- [x] Async export storage streams chunks to disk instead of buffering the whole
+  export in memory.
+- [x] Local async export files have retention cleanup:
+  `REPORTS_EXPORT_RETENTION_DAYS` plus worker sweep.
+- [x] Sync and async exports run in a `REPEATABLE READ` snapshot; over-long
+  snapshots map to the tier-guidance export error.
+- [x] Every export writes a PII-egress audit row; `exportable: false` columns are
+  stripped even when requested.
+- [x] XLSX output is structurally valid OOXML; CSV output has formula-injection
+  guarding.
+
+## Saved Views
+
+- [x] Shared-view create/update requires `reports.update`; duplicate shared
+  names are rejected by the partial unique index. Proof:
+  `test/reports-advanced.e2e-spec.ts`.
+- [x] Personal/shared compatibility reports `ok`, `degraded`, or
+  `incompatible` instead of throwing on stale views. Proof: engine view-service
+  tests and template e2e.
+
+## Envelope and Docs
+
+- [x] Engine error codes map through `reports-error.mapper.ts`; Swagger
+  decorators document the report routes.
+- [x] `docs/REPORTS.md` matches current storage topology, retention behavior,
+  tier coverage, and the form-field rename limitation.
+
+## Current E2E Coverage
+
+Template e2e coverage now includes the basic report lifecycle, keyset paging,
+typed operator rejection, meta, `reports.read` vs `reports.export`, saved views,
+tags, sync CSV export, SQL-boundary rejection, cross-org isolation for query /
+export / `byIds`, byFilter token protocol, drift, idempotent replay, async
+export worker + download + retention cleanup, XLSX validity, PII-egress audit,
+shared-view partial unique enforcement, indexed-tier failure, indexed-tier
+success after applying indexes, materialized tier `freshAsOf`, and boot
+schema-check failure.
+
+## Release and Operations Sign-Off
+
+- [x] OPS-2: async local-disk exports no longer buffer the whole file in memory.
+- [x] OPS-3: local async export files have retention cleanup and documented
+  retention env vars.
+- [x] LIM-1: form-backed renamed fields are documented as a known limitation
+  until form definitions carry rename metadata.
+- [x] OPS-1: deployment topology decision recorded. Single-node/shared-volume is
+  supported by the default local adapter; horizontal scaling without shared
+  storage requires rebinding `ExportFileSink` to object storage.
+- [ ] PKG-1: deliberate `@ftisindia/report-builder` version/publish decision
+  made for go-live, following engine-before-CLI publish order.
+- [ ] PROC-1: release commit/tag remains pending. `npm run sync-template` and
+  `npm run dogfood` have been run locally so the scaffolded CLI output carries
+  the same coverage.

package/template/prisma/migrations/20260616000000_add_form_outbox_claimed_by/migration.sql

@@ -0,0 +1,5 @@
+-- Add an opaque lease token for outbox claim ownership. Dispatchers must match
+-- this token when heartbeating or settling PROCESSING jobs.
+ALTER TABLE "FormOutboxJob" ADD COLUMN "claimedBy" TEXT;
+
+CREATE INDEX "FormOutboxJob_status_claimedBy_idx" ON "FormOutboxJob"("status", "claimedBy");

package/template/prisma/schema.prisma

@@ -416,6 +416,9 @@ model FormOutboxJob {
   idempotencyKey String?   @unique
   lastError      String?
   runAfter       DateTime?
+  // Opaque worker lease token. Heartbeats and terminal transitions must match
+  // this value so a stale worker cannot finish another worker's reclaimed job.
+  claimedBy      String?
 
   // Worker-context restoration + audit correlation (ecosystem guide §3).
   orgId           String?
@@ -426,6 +429,7 @@ model FormOutboxJob {
   updatedAt DateTime @updatedAt
 
   @@index([status, runAfter])
+  @@index([status, claimedBy])
 }
 
 model UploadedFile {
@@ -531,7 +535,7 @@ model ReportExportJob {
   // 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.
+  // Reports-owned storage key once the async export lands in file storage.
   fileId        String?
   rowCount      Int?
   error         String?

package/template/src/app.module.ts

@@ -42,9 +42,10 @@ import { SettingsModule } from './modules/settings/settings.module';
           limit: 100,
         },
       ],
-      // e2e suites create many users/submissions in seconds; rate limiting is
-      // not what they test. Production/dev behavior is unchanged.
-      skipIf: () => process.env.NODE_ENV === 'test',
+      // Most e2e suites create many users/submissions in seconds; enable
+      // throttling only in the dedicated abuse-control suite.
+      skipIf: () =>
+        process.env.NODE_ENV === 'test' && process.env.E2E_THROTTLE_ENABLED !== 'true',
     }),
     PrismaModule,
     HealthModule,

package/template/src/config/env.validation.ts

@@ -68,6 +68,7 @@ export const envSchema = z
     ORG_CONTEXT_MODE: z.literal('path').default('path'),
     FORMS_OUTBOX_ENABLED: booleanFromEnv.default(true),
     FORMS_OUTBOX_POLL_MS: z.coerce.number().int().positive().default(5000),
+    FORMS_OUTBOX_HEARTBEAT_MS: z.coerce.number().int().positive().default(60_000),
     FORMS_FILE_GC_INTERVAL_MS: z.coerce.number().int().positive().default(3_600_000),
     FORMS_FILE_TEMP_TTL_HOURS: z.coerce.number().int().positive().default(24),
     FORMS_MAX_UPLOAD_MB: z.coerce.number().int().positive().default(25),
@@ -83,6 +84,8 @@ export const envSchema = z
     REPORTS_EXPORT_WORKER_ENABLED: booleanFromEnv.default(true),
     REPORTS_EXPORT_POLL_MS: z.coerce.number().int().positive().default(5000),
     REPORTS_EXPORT_STORAGE_DIR: z.string().trim().min(1).default('./var/report-exports'),
+    REPORTS_EXPORT_RETENTION_DAYS: z.coerce.number().int().nonnegative().default(7),
+    REPORTS_EXPORT_RETENTION_SWEEP_MS: z.coerce.number().int().positive().default(3_600_000),
   })
   .superRefine((env, ctx) => {
     if (env.REPORTS_TOKEN_SECRET.length > 0 && env.REPORTS_TOKEN_SECRET.length < 32) {

package/template/src/config/forms.config.ts

@@ -4,6 +4,7 @@ import { getEnv } from './env.validation';
 export default registerAs('forms', () => ({
   outboxEnabled: getEnv().FORMS_OUTBOX_ENABLED,
   outboxPollMs: getEnv().FORMS_OUTBOX_POLL_MS,
+  outboxHeartbeatMs: getEnv().FORMS_OUTBOX_HEARTBEAT_MS,
   fileGcIntervalMs: getEnv().FORMS_FILE_GC_INTERVAL_MS,
   fileTempTtlHours: getEnv().FORMS_FILE_TEMP_TTL_HOURS,
   maxUploadMb: getEnv().FORMS_MAX_UPLOAD_MB,

package/template/src/config/reports.config.ts

@@ -13,4 +13,6 @@ export default registerAs('reports', () => ({
   exportWorkerEnabled: getEnv().REPORTS_EXPORT_WORKER_ENABLED,
   exportPollMs: getEnv().REPORTS_EXPORT_POLL_MS,
   exportStorageDir: getEnv().REPORTS_EXPORT_STORAGE_DIR,
+  exportRetentionDays: getEnv().REPORTS_EXPORT_RETENTION_DAYS,
+  exportRetentionSweepMs: getEnv().REPORTS_EXPORT_RETENTION_SWEEP_MS,
 }));