@ftisindia/create-app 0.1.6 → 0.3.0

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/migrations/20260625000000_form_builder_public_uploads/migration.sql

@@ -0,0 +1,7 @@
+-- AlterTable
+ALTER TABLE "UploadedFile" ALTER COLUMN "ownerId" DROP NOT NULL,
+ADD COLUMN "claimTokenHash" TEXT,
+ADD COLUMN "uploadedIp" TEXT;
+
+-- CreateIndex
+CREATE INDEX "UploadedFile_orgId_uploadedIp_createdAt_idx" ON "UploadedFile"("orgId", "uploadedIp", "createdAt");

package/template/prisma/schema.prisma

@@ -298,7 +298,7 @@ model AuditLog {
   @@index([createdAt])
 }
 // ─────────────────────────────────────────────────────────────────────────────
-// @ftisindia/form-builder — canonical Prisma model snippet (ENGINE_SCHEMA_VERSION 1)
+// @ftisindia/form-builder - canonical Prisma model snippet (ENGINE_SCHEMA_VERSION 3)
 //
 // 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
@@ -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 {
@@ -437,9 +441,11 @@ model UploadedFile {
   size     Int
   // sha256 hex.
   checksum String
-  // Two-factor ownership: uploader identity AND tenant scope (§10).
-  ownerId String
-  orgId   String
+  // Authenticated uploads have ownerId; anonymous public uploads have a claim token.
+  ownerId        String?
+  claimTokenHash String?
+  uploadedIp     String?
+  orgId          String
 
   status       FileStatus @default(TEMPORARY)
   submissionId String?
@@ -447,7 +453,8 @@ model UploadedFile {
   createdAt DateTime @default(now())
 
   @@index([orgId, status])
-  @@index([ownerId, status])
+  @@index([ownerId, status])
+  @@index([orgId, uploadedIp, createdAt])
   @@index([status, createdAt])
 }
 
@@ -531,7 +538,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/scripts/push-report.ts

@@ -0,0 +1,123 @@
+/**
+ * Push a report-definition JSON file into an organisation through the real
+ * report engine path: member RBAC, save/publish linting, versioning, and audit
+ * rows all stay intact.
+ *
+ *   npm run reports:push -- --file src/modules/reports/definitions/my-report.report.json \
+ *       --org <org-id-or-slug> --user <member-email> [--publish]
+ *
+ * Idempotent: if the file matches the latest stored version's authored content,
+ * nothing new is created. With --publish, a matching DRAFT is published in place.
+ * Runs under ts-node because it bootstraps Nest.
+ */
+import { readFileSync } from 'node:fs';
+import { NestFactory } from '@nestjs/core';
+import type { ReportDefinition } from '@ftisindia/report-builder';
+import { AppModule } from '../src/app.module';
+import { PrismaService } from '../src/database/prisma/prisma.service';
+import { RbacCacheService } from '../src/modules/access-control/application/services/rbac-cache.service';
+import { RequestContextService } from '../src/modules/request-context/application/services/request-context.service';
+import { ReportsDefinitionsService } from '../src/modules/reports/application/services/reports-definitions.service';
+import { CreateReportDefinitionDto } from '../src/modules/reports/dto/create-report-definition.dto';
+
+function argValue(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag);
+  return index !== -1 ? process.argv[index + 1] : undefined;
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** Version/status are managed by the engine - compare authored content only. */
+function normalized(schema: ReportDefinition): string {
+  const { version: _version, status: _status, ...rest } = schema;
+  return stableStringify(rest);
+}
+
+async function main() {
+  const file = argValue('--file');
+  const orgRef = argValue('--org');
+  const userEmail = argValue('--user');
+  const publish = process.argv.includes('--publish');
+  if (!file || !orgRef || !userEmail) {
+    throw new Error(
+      'Usage: npm run reports:push -- --file <path> --org <org-id-or-slug> --user <member-email> [--publish]',
+    );
+  }
+
+  const definition = JSON.parse(readFileSync(file, 'utf8')) as ReportDefinition;
+  if (!definition.key) {
+    throw new Error(`${file} does not look like a report definition (missing "key").`);
+  }
+
+  const app = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['error', 'warn'],
+  });
+  try {
+    const prisma = app.get(PrismaService);
+    const user = await prisma.user.findFirst({ where: { email: userEmail } });
+    if (!user) {
+      throw new Error(`No user found with email "${userEmail}".`);
+    }
+    const org = await prisma.organisation.findFirst({
+      where: { OR: [{ id: orgRef }, { slug: orgRef }] },
+    });
+    if (!org) {
+      throw new Error(`No organisation found with id or slug "${orgRef}".`);
+    }
+
+    const rbac = await app.get(RbacCacheService).getContext(user.id, org.id);
+    const requestContext = app.get(RequestContextService);
+    const definitions = app.get(ReportsDefinitionsService);
+
+    await requestContext.run(
+      { source: 'worker', orgId: org.id, userId: user.id, rbac },
+      async () => {
+        const latest = await prisma.reportDefinition.findFirst({
+          where: { orgId: org.id, key: definition.key },
+          orderBy: { version: 'desc' },
+        });
+
+        if (latest && normalized(latest.schema as unknown as ReportDefinition) === normalized(definition)) {
+          if (publish && latest.status === 'DRAFT') {
+            await definitions.publish(org.id, definition.key);
+            console.log(`Unchanged content - published existing draft v${latest.version}.`);
+          } else {
+            console.log(
+              `No changes - "${definition.key}" v${latest.version} (${latest.status}) already matches ${file}.`,
+            );
+          }
+          return;
+        }
+
+        const created = await definitions.create(
+          org.id,
+          definition as unknown as CreateReportDefinitionDto,
+        );
+        console.log(`Created "${created.key}" v${created.version} (DRAFT).`);
+        if (publish) {
+          await definitions.publish(org.id, created.key);
+          console.log(`Published "${created.key}" v${created.version}.`);
+        }
+      },
+    );
+  } finally {
+    await app.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

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/common/swagger/api-error-responses.ts

@@ -6,13 +6,15 @@ import {
   ApiGoneResponse,
   ApiInternalServerErrorResponse,
   ApiNotFoundResponse,
+  ApiPayloadTooLargeResponse,
   ApiServiceUnavailableResponse,
   ApiTooManyRequestsResponse,
   ApiUnauthorizedResponse,
+  ApiUnsupportedMediaTypeResponse,
 } from '@nestjs/swagger';
 import { ErrorResponseDto } from '../dto/error-response.dto';
 
-type ApiErrorStatus = 400 | 401 | 403 | 404 | 409 | 410 | 429 | 500 | 503;
+type ApiErrorStatus = 400 | 401 | 403 | 404 | 409 | 410 | 413 | 415 | 429 | 500 | 503;
 
 const errorResponseFactories = {
   400: ApiBadRequestResponse,
@@ -21,6 +23,8 @@ const errorResponseFactories = {
   404: ApiNotFoundResponse,
   409: ApiConflictResponse,
   410: ApiGoneResponse,
+  413: ApiPayloadTooLargeResponse,
+  415: ApiUnsupportedMediaTypeResponse,
   429: ApiTooManyRequestsResponse,
   500: ApiInternalServerErrorResponse,
   503: ApiServiceUnavailableResponse,
@@ -33,6 +37,8 @@ const descriptions: Record<ApiErrorStatus, string> = {
   404: 'The requested resource was not found.',
   409: 'The request conflicts with current resource state.',
   410: 'The resource is no longer available.',
+  413: 'The request payload is too large.',
+  415: 'The uploaded media type is not supported.',
   429: 'Too many requests.',
   500: 'Unexpected server error.',
   503: 'The service is temporarily unavailable.',
@@ -51,4 +57,4 @@ export function ApiErrorResponses(...statuses: ApiErrorStatus[]) {
 
 export function ApiProtectedErrorResponses(...extraStatuses: ApiErrorStatus[]) {
   return ApiErrorResponses(400, 401, 403, ...extraStatuses);
-}
+}

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,
 }));

package/template/src/modules/forms/application/services/data-sources/conference-tracks.data-source.ts

@@ -0,0 +1,32 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  DataSourceContext,
+  DataSourceDef,
+  DataSourceOption,
+} from '@ftisindia/form-builder';
+import { FormDataSource } from '../../../infrastructure/registry/form-extension.decorators';
+
+/**
+ * Example data source for src/modules/forms/examples/abstract-submission.form.json.
+ *
+ * Real apps should replace this static list with an org-scoped Prisma/API
+ * lookup using ctx.orgId. Keeping the shipped example self-contained makes
+ * the data-source registry usable immediately after scaffolding.
+ */
+@Injectable()
+@FormDataSource()
+export class ConferenceTracksDataSource implements DataSourceDef {
+  readonly key = 'conference-tracks';
+
+  fetch(
+    _params: Record<string, unknown>,
+    _ctx: DataSourceContext,
+  ): Promise<DataSourceOption[]> {
+    return Promise.resolve([
+      { value: 'clinical-research', label: 'Clinical Research' },
+      { value: 'public-health', label: 'Public Health' },
+      { value: 'biomedical-engineering', label: 'Biomedical Engineering' },
+      { value: 'data-science', label: 'Data Science' },
+    ]);
+  }
+}