@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/reports/infrastructure/forms-adapter/form-row-actions.ts

@@ -0,0 +1,171 @@
+import { Injectable } from '@nestjs/common';
+import { SubmissionService } from '@ftisindia/form-builder';
+import type { SubmissionRecord, SubmissionStatus, SubmitArgs } from '@ftisindia/form-builder';
+import { ReportAuthzDeniedError } from '@ftisindia/report-builder';
+import type {
+  ReportActionContext,
+  ReportRowActionDef,
+  ResolvedRow,
+  RowActionKind,
+} from '@ftisindia/report-builder';
+import { withFormsErrorMapping } from '../../../forms/application/services/forms-error.mapper';
+import { RequestFormsContext } from '../../../forms/infrastructure/request-forms-context';
+
+/**
+ * Form-backed row actions (report design §6.1) — verbs that DELEGATE, never a
+ * second write path. The report engine resolves rows and checks org +
+ * permissions; these handlers hand each row to the form engine's
+ * SubmissionService, so grid verbs run the SAME validation and action pipeline
+ * as the form itself. No Prisma access here, ever.
+ *
+ * Call path mirrors FormsSubmissionsService: the engine is called through the
+ * forms context seam (RequestFormsContext — the same AsyncLocalStorage request
+ * context the report engine's own seam reads), and every call is wrapped in
+ * withFormsErrorMapping so a form validation failure surfaces as the app's
+ * 422 envelope with the engine's `errors` array — not an opaque 500.
+ *
+ * Engine API constraint (read from SubmissionService): the only public update
+ * surface is submit/saveDraft with `submissionId`, and the built-in persist
+ * action rejects rows that are locked or already SUBMITTED. So edits apply to
+ * DRAFT rows; a locked/submitted row surfaces the engine's FormsStateError
+ * (409) untouched. The forms engine also runs its OWN transaction per
+ * delegated call — its public API takes no external tx — so a multi-row batch
+ * is one report-engine transaction wrapping N form-engine transactions, and a
+ * failed row stops the batch without rolling back rows already committed by
+ * the form engine. Documented seam, not a bug: the alternative would be a
+ * second write path (§6).
+ *
+ * NO generic softDelete is registered: §6.1 makes delete "a status transition
+ * the source declares", and the form engine declares no deleted status —
+ * SubmissionStatus is DRAFT | SUBMITTED. When the form engine grows one, a
+ * delegated action lands here beside these two.
+ */
+
+/** The submission statuses the form engine exposes (SubmissionStatus). */
+const SUBMISSION_STATUSES: readonly SubmissionStatus[] = ['DRAFT', 'SUBMITTED'];
+
+/**
+ * `editSubmission` (§6.1 "Edit"): patches a submission through the form
+ * engine, re-validating against the submission's STAMPED `formVersion`
+ * definition in submit mode — an edit can never be validated against the
+ * wrong schema generation. The patch is shallow-merged over the stored data,
+ * then the whole document rides the form's own submit pipeline.
+ */
+@Injectable()
+export class EditSubmissionRowAction implements ReportRowActionDef {
+  readonly name = 'editSubmission';
+  readonly kind: RowActionKind = 'transactional';
+  readonly requiredPermissions = ['formSubmissions.update'] as const;
+  readonly inputSchema = {
+    type: 'object',
+    properties: { data: { type: 'object' } },
+    required: ['data'],
+    additionalProperties: false,
+  };
+
+  constructor(
+    private readonly submissions: SubmissionService,
+    private readonly formsContext: RequestFormsContext,
+  ) {}
+
+  async execute(
+    rows: ResolvedRow[],
+    input: Record<string, unknown> | undefined,
+    actionCtx: ReportActionContext,
+  ): Promise<unknown> {
+    const orgId = requireOrgId(actionCtx);
+    // The action service ajv-validates inputSchema before execute (§6).
+    const patch = (input?.data ?? {}) as Record<string, unknown>;
+
+    let updated = 0;
+    for (const row of rows) {
+      const record = await this.loadRecord(orgId, row);
+      const args: SubmitArgs = {
+        orgId,
+        formKey: record.formKey,
+        // Re-validate against the stamped version, never the latest (§6.1).
+        version: record.formVersion,
+        data: { ...record.data, ...patch },
+        submissionId: record.id,
+      };
+      await withFormsErrorMapping(() => this.submissions.submit(args, this.formsContext));
+      updated += 1;
+    }
+    return { updated };
+  }
+
+  private async loadRecord(orgId: string, row: ResolvedRow): Promise<SubmissionRecord> {
+    // rows carry sourceRef.rowId = the FormSubmission id; the engine's get()
+    // re-checks org scope and formSubmissions.read through the forms seam.
+    return withFormsErrorMapping(() =>
+      this.submissions.get({ orgId, submissionId: row.sourceRef.rowId }, this.formsContext),
+    );
+  }
+}
+
+/**
+ * `updateStatus` (§6.1 "Status update"): a delegated transactional action.
+ * Status is not patched directly — the form engine couples status to its
+ * submit/saveDraft verbs, so SUBMITTED delegates to submit() (full pipeline,
+ * stamped-version validation) and DRAFT delegates to saveDraft(). Demoting an
+ * already-SUBMITTED row is rejected by the engine's persist action and
+ * surfaces as a conflict — the source, not the report layer, owns the legal
+ * transitions.
+ */
+@Injectable()
+export class UpdateSubmissionStatusRowAction implements ReportRowActionDef {
+  readonly name = 'updateStatus';
+  readonly kind: RowActionKind = 'transactional';
+  readonly requiredPermissions = ['formSubmissions.update'] as const;
+  readonly inputSchema = {
+    type: 'object',
+    properties: { status: { enum: [...SUBMISSION_STATUSES] } },
+    required: ['status'],
+    additionalProperties: false,
+  };
+
+  constructor(
+    private readonly submissions: SubmissionService,
+    private readonly formsContext: RequestFormsContext,
+  ) {}
+
+  async execute(
+    rows: ResolvedRow[],
+    input: Record<string, unknown> | undefined,
+    actionCtx: ReportActionContext,
+  ): Promise<unknown> {
+    const orgId = requireOrgId(actionCtx);
+    // ajv-validated against inputSchema before execute (§6).
+    const status = input?.status as SubmissionStatus;
+
+    let updated = 0;
+    for (const row of rows) {
+      const record = await withFormsErrorMapping(() =>
+        this.submissions.get({ orgId, submissionId: row.sourceRef.rowId }, this.formsContext),
+      );
+      const args: SubmitArgs = {
+        orgId,
+        formKey: record.formKey,
+        version: record.formVersion,
+        data: record.data,
+        submissionId: record.id,
+      };
+      await withFormsErrorMapping(() =>
+        status === 'SUBMITTED'
+          ? this.submissions.submit(args, this.formsContext)
+          : this.submissions.saveDraft(args, this.formsContext),
+      );
+      updated += 1;
+    }
+    return { updated };
+  }
+}
+
+/** Mirrors the engine's own manageTags guard: no org scope, no action. */
+function requireOrgId(actionCtx: ReportActionContext): string {
+  const orgId = actionCtx.ctx.orgId();
+  if (orgId === undefined) {
+    throw new ReportAuthzDeniedError('No organisation scope is active.');
+  }
+  return orgId;
+}

package/template/src/modules/reports/infrastructure/forms-adapter/forms-bridge-bootstrap.service.ts

@@ -0,0 +1,32 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { ReportRowActionRegistry, SourceProviderRegistry } from '@ftisindia/report-builder';
+import { FormReportSourceProvider } from './form-report-source.adapter';
+import {
+  EditSubmissionRowAction,
+  UpdateSubmissionStatusRowAction,
+} from './form-row-actions';
+
+/**
+ * The ONLY place the two engines meet (report design §3.2/§13). It registers
+ * the form-backed bits into the report engine's shared registries — the
+ * 'form' source provider and the delegated editSubmission/updateStatus verbs
+ * — only because THIS app ships the form builder. Removing
+ * ReportsFormsModule from the app leaves ReportsModule fully functional over
+ * custom sources, with no dangling form dependency.
+ */
+@Injectable()
+export class ReportsFormsBridgeBootstrap implements OnModuleInit {
+  constructor(
+    private readonly sourceProviders: SourceProviderRegistry,
+    private readonly actions: ReportRowActionRegistry,
+    private readonly formSourceProvider: FormReportSourceProvider,
+    private readonly editSubmission: EditSubmissionRowAction,
+    private readonly updateStatus: UpdateSubmissionStatusRowAction,
+  ) {}
+
+  onModuleInit(): void {
+    this.sourceProviders.register(this.formSourceProvider);
+    this.actions.register(this.editSubmission);
+    this.actions.register(this.updateStatus);
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-catalog.adapter.ts

@@ -0,0 +1,95 @@
+import { Injectable } from '@nestjs/common';
+import type { CatalogColumn, CatalogIndex, CatalogPort } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/**
+ * Catalog introspection for the publish-time lints (report design §5.2/§8):
+ * declared indexes are verified against pg_indexes, generated columns against
+ * information_schema, tier caps against the planner's pg_class estimates.
+ * Every lookup is scoped to current_schema() so other schemas (extensions,
+ * shadow databases) cannot shadow or leak into lint verdicts.
+ */
+@Injectable()
+export class PrismaReportsCatalog implements CatalogPort {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async indexesFor(table: string): Promise<CatalogIndex[]> {
+    const rows = await this.prisma.$queryRawUnsafe<
+      Array<{ indexname: string; tablename: string; indexdef: string }>
+    >(
+      `SELECT indexname, tablename, indexdef
+       FROM pg_indexes
+       WHERE schemaname = current_schema()
+         AND tablename = $1`,
+      table,
+    );
+
+    return rows.map((row) => ({
+      name: row.indexname,
+      table: row.tablename,
+      indexDef: row.indexdef,
+      isUnique: row.indexdef.includes('UNIQUE'),
+    }));
+  }
+
+  async columnsFor(table: string): Promise<CatalogColumn[]> {
+    const rows = await this.prisma.$queryRawUnsafe<
+      Array<{ column_name: string; data_type: string; is_generated: string }>
+    >(
+      `SELECT column_name, data_type, is_generated
+       FROM information_schema.columns
+       WHERE table_schema = current_schema()
+         AND table_name = $1`,
+      table,
+    );
+
+    return rows.map((row) => ({
+      name: row.column_name,
+      dataType: row.data_type,
+      isGenerated: row.is_generated === 'ALWAYS',
+    }));
+  }
+
+  async hasExtension(name: string): Promise<boolean> {
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ found: number }>>(
+      `SELECT 1 AS found FROM pg_extension WHERE extname = $1`,
+      name,
+    );
+
+    return rows.length > 0;
+  }
+
+  async estimatedRowCount(table: string): Promise<number> {
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ reltuples: unknown }>>(
+      `SELECT c.reltuples
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = current_schema()
+         AND c.relname = $1
+         AND c.relkind IN ('r', 'p')`,
+      table,
+    );
+
+    if (rows.length === 0) {
+      return 0;
+    }
+    const estimate = Number(rows[0].reltuples);
+    return Number.isFinite(estimate) ? Math.max(0, estimate) : 0;
+  }
+
+  async relationExists(name: string): Promise<boolean> {
+    // Tables, views, materialized views, and partitioned tables all count —
+    // the materialized tier reads from any of them (report design §8).
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ found: number }>>(
+      `SELECT 1 AS found
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE n.nspname = current_schema()
+         AND c.relname = $1
+         AND c.relkind IN ('r', 'v', 'm', 'p')`,
+      name,
+    );
+
+    return rows.length > 0;
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-query-executor.ts

@@ -0,0 +1,103 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import { ReportQueryBudgetError, type QueryExecutor, type SqlRow } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/** Hard ceiling on the per-statement budget — matches Prisma's own tx limits. */
+const MAX_STATEMENT_TIMEOUT_MS = 600_000;
+
+function assertValidStatementTimeout(ms: number): void {
+  if (!Number.isInteger(ms) || ms < 1 || ms > MAX_STATEMENT_TIMEOUT_MS) {
+    throw new Error(
+      `Invalid report statement timeout: ${ms} (expected an integer between 1 and ${MAX_STATEMENT_TIMEOUT_MS} ms).`,
+    );
+  }
+}
+
+/** Postgres 57014 — 'canceling statement due to statement timeout'. */
+function isStatementTimeout(error: unknown): boolean {
+  if (error instanceof Prisma.PrismaClientKnownRequestError) {
+    const meta = error.meta as { code?: unknown } | undefined;
+    if (meta?.code === '57014') {
+      return true;
+    }
+  }
+  const message = error instanceof Error ? error.message : '';
+  return message.includes('57014') || message.includes('canceling statement due to statement timeout');
+}
+
+/**
+ * Runs one compiler-built statement under a SET LOCAL statement_timeout on an
+ * open transaction client. SQL identifiers come only from code-owned manifests
+ * and every VALUE travels as a positional $1..$n bind; SET LOCAL cannot take
+ * binds, so the timeout — a VALIDATED INTEGER — is the one sanctioned
+ * interpolation exception (report design §2.1/§5.2).
+ *
+ * Shared between PrismaQueryExecutor (one-off transactions) and
+ * PrismaSnapshotRunner (the export's REPEATABLE READ transaction).
+ */
+export async function runBoundedQuery(
+  client: Prisma.TransactionClient,
+  sql: string,
+  params: readonly unknown[],
+  opts: { statementTimeoutMs: number },
+): Promise<SqlRow[]> {
+  assertValidStatementTimeout(opts.statementTimeoutMs);
+  try {
+    await client.$executeRawUnsafe(`SET LOCAL statement_timeout = ${opts.statementTimeoutMs}`);
+    return await client.$queryRawUnsafe<SqlRow[]>(sql, ...params);
+  } catch (error) {
+    if (isStatementTimeout(error)) {
+      // The runtime backstop (§5.2): a pathological plan fails fast, typed.
+      throw new ReportQueryBudgetError();
+    }
+    throw error;
+  }
+}
+
+/**
+ * EXPLAIN (FORMAT JSON) for the plan lint and estimated counts (§5.2/§5.4).
+ * Postgres returns one row shaped [{ "QUERY PLAN": <document> }]; drivers may
+ * surface the json column already parsed or as a string — the engine expects
+ * the parsed array-root document either way.
+ */
+export async function runExplain(
+  client: Prisma.TransactionClient,
+  sql: string,
+  params: readonly unknown[],
+): Promise<unknown> {
+  const rows = await client.$queryRawUnsafe<Array<Record<string, unknown>>>(
+    `EXPLAIN (FORMAT JSON) ${sql}`,
+    ...params,
+  );
+  const plan = rows[0]?.['QUERY PLAN'];
+  return typeof plan === 'string' ? (JSON.parse(plan) as unknown) : plan;
+}
+
+/**
+ * The engine's SQL seam (report design §5) over Prisma. Each call runs inside
+ * its own short transaction because SET LOCAL is transaction-scoped — outside
+ * one it would be a silent no-op and the statement budget would not exist.
+ */
+@Injectable()
+export class PrismaQueryExecutor implements QueryExecutor {
+  constructor(private readonly prisma: PrismaService) {}
+
+  query(
+    sql: string,
+    params: readonly unknown[],
+    opts: { statementTimeoutMs: number },
+  ): Promise<SqlRow[]> {
+    assertValidStatementTimeout(opts.statementTimeoutMs);
+    return this.prisma.$transaction((tx) => runBoundedQuery(tx, sql, params, opts), {
+      // Keep Prisma's transaction window above the statement budget so the
+      // budget — not Prisma's 5s interactive-tx default — is what fires.
+      timeout: opts.statementTimeoutMs + 1000,
+      maxWait: 5000,
+    });
+  }
+
+  explain(sql: string, params: readonly unknown[]): Promise<unknown> {
+    return this.prisma.$transaction((tx) => runExplain(tx, sql, params));
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-snapshot-runner.ts

@@ -0,0 +1,47 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import type { QueryExecutor, SnapshotRunner } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+import { runBoundedQuery, runExplain } from './prisma-query-executor';
+
+/**
+ * One REPEATABLE READ transaction per export (report design §9, finding #8):
+ * every keyset batch reads the same MVCC snapshot, so rows moving under the
+ * export can neither be skipped nor duplicated. The transaction is
+ * duration-bounded — an export that cannot finish inside the bound aborts
+ * (and the engine maps that to guidance: tighten filters or move the report
+ * to the materialized tier).
+ */
+@Injectable()
+export class PrismaSnapshotRunner implements SnapshotRunner {
+  constructor(private readonly prisma: PrismaService) {}
+
+  withSnapshot<T>(
+    opts: { maxDurationMs: number },
+    fn: (exec: QueryExecutor, asOf: Date) => Promise<T>,
+  ): Promise<T> {
+    return this.prisma.$transaction(
+      async (tx) => {
+        // Under REPEATABLE READ now() is the transaction (= snapshot) start
+        // time — the export's `asOf`, stamped into the job and file metadata.
+        const rows = await tx.$queryRawUnsafe<Array<{ now: unknown }>>('SELECT now() AS now');
+        const now = rows[0]?.now;
+        const asOf = now instanceof Date ? now : new Date();
+
+        // Executor bound to THIS transaction: same SET LOCAL budget + EXPLAIN
+        // logic as PrismaQueryExecutor, valid only while `fn` runs.
+        const exec: QueryExecutor = {
+          query: (sql, params, queryOpts) => runBoundedQuery(tx, sql, params, queryOpts),
+          explain: (sql, params) => runExplain(tx, sql, params),
+        };
+
+        return fn(exec, asOf);
+      },
+      {
+        isolationLevel: Prisma.TransactionIsolationLevel.RepeatableRead,
+        timeout: opts.maxDurationMs,
+        maxWait: 5000,
+      },
+    );
+  }
+}

package/template/src/modules/reports/infrastructure/prisma-tx-runner.ts

@@ -0,0 +1,18 @@
+import { Injectable } from '@nestjs/common';
+import type { EngineTx, TxRunner } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+
+/**
+ * The engine's transaction seam over PrismaService.$transaction. The opaque
+ * EngineTx brand is a Prisma.TransactionClient underneath; the stores cast it
+ * back. One TxRunner.run call is the engine's atomicity boundary (export job
+ * row + outbox enqueue, bulk-action ledger + audit — report design §6.3/§9).
+ */
+@Injectable()
+export class ReportsPrismaTxRunner implements TxRunner {
+  constructor(private readonly prisma: PrismaService) {}
+
+  run<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T> {
+    return this.prisma.$transaction((tx) => fn(tx as unknown as EngineTx));
+  }
+}

package/template/src/modules/reports/infrastructure/registry/registry-bootstrap.service.ts

@@ -0,0 +1,61 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import {
+  ReportRowActionRegistry,
+  ReportSourceRegistry,
+  ReportTagService,
+  SourceProviderRegistry,
+  createCustomSourceProvider,
+  createManageTagsAction,
+} from '@ftisindia/report-builder';
+import type { ReportRowActionDef, ReportSourceDef } from '@ftisindia/report-builder';
+import {
+  REPORT_ROW_ACTION_METADATA,
+  REPORT_SOURCE_METADATA,
+} from './report-extension.decorators';
+
+/**
+ * Populates the engine registries at startup — WITHOUT any form-builder
+ * dependency (the standalone guarantee extends to the glue, report design
+ * §3.2): the built-in manageTags action (§7), the 'custom' source provider
+ * over the code-owned source registry (the one provider the core ships), and
+ * a discovery scan for every app provider decorated with @ReportSource /
+ * @ReportRowAction (e.g. the org-members example source).
+ *
+ * Form-backed sources and the delegated editSubmission/updateStatus verbs are
+ * added by the OPTIONAL ReportsFormsModule, which registers the 'form'
+ * provider + actions into these same registries only when the app ships forms.
+ */
+@Injectable()
+export class ReportsRegistryBootstrapService implements OnModuleInit {
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly reflector: Reflector,
+    private readonly sourceRegistry: ReportSourceRegistry,
+    private readonly sourceProviders: SourceProviderRegistry,
+    private readonly actionRegistry: ReportRowActionRegistry,
+    private readonly tagService: ReportTagService,
+  ) {}
+
+  onModuleInit(): void {
+    this.actionRegistry.register(createManageTagsAction(this.tagService));
+    this.sourceProviders.register(createCustomSourceProvider(this.sourceRegistry));
+
+    for (const wrapper of this.discovery.getProviders()) {
+      const instance: unknown = wrapper.instance;
+      if (!instance || typeof instance !== 'object') {
+        continue;
+      }
+      const ctor = instance.constructor as object | undefined;
+      if (!ctor || ctor === Object) {
+        continue;
+      }
+      if (this.reflector.get<boolean>(REPORT_SOURCE_METADATA, ctor as never)) {
+        this.sourceRegistry.register(instance as ReportSourceDef);
+      }
+      if (this.reflector.get<boolean>(REPORT_ROW_ACTION_METADATA, ctor as never)) {
+        this.actionRegistry.register(instance as ReportRowActionDef);
+      }
+    }
+  }
+}

package/template/src/modules/reports/infrastructure/registry/report-extension.decorators.ts

@@ -0,0 +1,14 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const REPORT_SOURCE_METADATA = 'ftis:reports:source';
+export const REPORT_ROW_ACTION_METADATA = 'ftis:reports:row-action';
+
+/**
+ * The standardized extension story (report design §3.2/§6): implement the
+ * engine interface (ReportSourceDef / ReportRowActionDef), decorate the
+ * @Injectable class, list it as a provider — ReportsRegistryBootstrapService
+ * discovers and registers it at startup. Same three steps as the form
+ * registries.
+ */
+export const ReportSource = () => SetMetadata(REPORT_SOURCE_METADATA, true);
+export const ReportRowAction = () => SetMetadata(REPORT_ROW_ACTION_METADATA, true);

package/template/src/modules/reports/infrastructure/reports-job-queue.adapter.ts

@@ -0,0 +1,28 @@
+import { Injectable } from '@nestjs/common';
+import type { EngineTx, ReportsJobQueue } from '@ftisindia/report-builder';
+
+/**
+ * The async-export job queue (report design §9). The durable signal IS the
+ * `ReportExportJob` row the engine creates in the same transaction — the
+ * reports-owned ReportsExportDispatcherService polls that table for PENDING
+ * jobs. So `enqueue` is intentionally a no-op: there is no separate queue to
+ * write, and reports stays independent of the forms outbox.
+ *
+ * (An app that prefers an external queue can bind a different ReportsJobQueue
+ * — e.g. one that publishes to SQS — without changing the engine.)
+ */
+@Injectable()
+export class ReportsJobQueueNoop implements ReportsJobQueue {
+  async enqueue(
+    _job: {
+      type: string;
+      payload: Record<string, unknown>;
+      orgId: string;
+      actorUserId?: string | null;
+      idempotencyKey?: string;
+    },
+    _tx: EngineTx,
+  ): Promise<void> {
+    // The ReportExportJob row (committed with this tx) is the queue entry.
+  }
+}

package/template/src/modules/reports/infrastructure/request-reports-context.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@nestjs/common';
+import type { ReportsContext } from '@ftisindia/report-builder';
+import { RequestContextService } from '../../request-context/application/services/request-context.service';
+
+/**
+ * Binds the engine's ReportsContext seam to the app's AsyncLocalStorage
+ * request context (report design §13). Worker contexts (async export jobs)
+ * are restored by the forms outbox dispatcher before the engine runs, so the
+ * same adapter serves HTTP and worker callers (ecosystem guide §3).
+ */
+@Injectable()
+export class RequestReportsContext implements ReportsContext {
+  constructor(private readonly ctx: RequestContextService) {}
+
+  requestId() {
+    return this.ctx.getRequestId();
+  }
+
+  source(): 'http' | 'worker' {
+    return this.ctx.get()?.source ?? 'worker';
+  }
+
+  userId() {
+    return this.ctx.getUserId();
+  }
+
+  orgId() {
+    return this.ctx.getOrgId();
+  }
+
+  permissionKeys() {
+    return this.ctx.getPermissions();
+  }
+
+  isOwner() {
+    return this.ctx.getRbacContext()?.isOwner ?? false;
+  }
+
+  assertOrgScope(orgId: string) {
+    this.ctx.assertOrgScope(orgId);
+  }
+}