@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/backend/application/src/@aurora/modules/report-engine/report-db-pool.provider.spec.ts

@@ -0,0 +1,95 @@
+import { InternalServerErrorException } from '@nestjs/common';
+import { Pool } from 'pg';
+
+import { reportDbPoolProvider } from './report-db-pool.provider.js';
+
+const EXPECTED_POOL_CLASS = Pool;
+
+/**
+ * Unit tests for `reportDbPoolProvider`'s credential-resolution factory.
+ *
+ * Design D4 (fail-closed): the read-only pool MUST NOT silently fall back to
+ * the main write-capable credentials in production. Missing REPORTS_DB_USER
+ * in production is a BOOT FAILURE, not a warning.
+ *
+ * F3 cutover: the factory builds its OWN `pg.Pool` (design decision — the
+ * report-engine does NOT go through the Drizzle aggregation port), replacing
+ * the incumbent's own Sequelize pool. Same env vars, same fail-closed guard.
+ */
+describe('reportDbPoolProvider', () => {
+  const ORIGINAL_ENV = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  const buildPool = (): unknown => {
+    const factory = (reportDbPoolProvider as { useFactory: () => unknown }).useFactory;
+    return factory();
+  };
+
+  describe('Scenario: Production without a dedicated read-only role', () => {
+    it('throws instead of falling back to the main write-capable credentials', () => {
+      process.env['NODE_ENV'] = 'production';
+      delete process.env['REPORTS_DB_USER'];
+
+      expect(() => buildPool()).toThrow(InternalServerErrorException);
+    });
+
+    it('error message names REPORTS_DB_USER so the operator knows what to provision', () => {
+      process.env['NODE_ENV'] = 'production';
+      delete process.env['REPORTS_DB_USER'];
+
+      let caught: unknown;
+      try {
+        buildPool();
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).toBeInstanceOf(InternalServerErrorException);
+      const msg = (caught as InternalServerErrorException).message;
+      expect(msg).toContain('REPORTS_DB_USER');
+    });
+  });
+
+  describe('Scenario: Non-production dev fallback remains usable', () => {
+    it('does not throw and builds a pool using main credentials when REPORTS_DB_USER is unset', () => {
+      process.env['NODE_ENV'] = 'test';
+      delete process.env['REPORTS_DB_USER'];
+
+      expect(() => buildPool()).not.toThrow();
+    });
+  });
+
+  describe('Scenario: Production WITH a dedicated read-only role configured', () => {
+    it('does not throw when REPORTS_DB_USER is set', () => {
+      process.env['NODE_ENV'] = 'production';
+      process.env['REPORTS_DB_USER'] = 'reports_ro';
+      process.env['REPORTS_DB_PASSWORD'] = 'secret';
+
+      expect(() => buildPool()).not.toThrow();
+    });
+  });
+
+  describe('Scenario: F3 cutover — the factory builds a pg.Pool, not a Sequelize instance', () => {
+    it('returns an instance of pg.Pool', () => {
+      process.env['NODE_ENV'] = 'test';
+      delete process.env['REPORTS_DB_USER'];
+
+      const pool = buildPool();
+
+      expect(pool).toBeInstanceOf(EXPECTED_POOL_CLASS);
+    });
+
+    it('the built pool exposes the pg.Pool query surface (query/connect/end)', () => {
+      process.env['NODE_ENV'] = 'test';
+      delete process.env['REPORTS_DB_USER'];
+
+      const pool = buildPool() as { query: unknown; connect: unknown; end: unknown };
+
+      expect(typeof pool.query).toBe('function');
+      expect(typeof pool.connect).toBe('function');
+      expect(typeof pool.end).toBe('function');
+    });
+  });
+});

package/dist/templates/backend/application/src/@aurora/modules/report-engine/report-db-pool.provider.ts

@@ -0,0 +1,74 @@
+import type { Provider } from '@nestjs/common';
+import { InternalServerErrorException } from '@nestjs/common';
+import { Pool } from 'pg';
+
+import { REPORT_DB_POOL } from './report-db-pool.token.js';
+
+/**
+ * Creates the read-only `pg.Pool` connection pool for report execution.
+ *
+ * F3 cutover (design decision): the report-engine does NOT go through the
+ * Drizzle aggregation port — it talks to its OWN independent connection via
+ * the raw `pg` client (D3c). The incumbent built its own read-only Sequelize
+ * pool for the exact same reason (separate credentials from the main app
+ * connection); this factory preserves that shape 1:1, only swapping the
+ * underlying client library.
+ *
+ * Reads credentials from environment variables. In non-production environments,
+ * the main DB credentials are used as a DEV FALLBACK when `REPORTS_DB_USER` is
+ * unset, so the application still boots without a dedicated read-only role.
+ *
+ * Design D4 (fail-closed): in production, a missing `REPORTS_DB_USER` is a BOOT
+ * FAILURE, not a silent fallback — running the report engine against the main
+ * write-capable connection with no read-only safety net is unacceptable in prod.
+ *
+ * Environment variables (document in `cliter/reporting/CONTEXT.md`):
+ *   REPORTS_DB_USER     — read-only PostgreSQL role (SOPS-managed in prod)
+ *   REPORTS_DB_PASSWORD — password for the read-only role (SOPS-managed in prod)
+ *   REPORTS_DB_HOST     — DB host; falls back to DB_HOST or 'localhost'
+ *   REPORTS_DB_NAME     — DB name; falls back to DB_DATABASE or 'aurora'
+ *   REPORTS_DB_PORT     — DB port; falls back to DB_PORT or 5432
+ *
+ * HR-PORTS-001 COMPLY: no imports from @app or @api.
+ *
+ * @rule BR-REPORT (read-only-pool-preflight — design D4)
+ */
+export const reportDbPoolProvider: Provider = {
+  provide: REPORT_DB_POOL,
+  useFactory: (): Pool => {
+    const reportsDbUser = process.env['REPORTS_DB_USER'];
+
+    // Fail closed: production MUST NOT fall back to the main write-capable
+    // credentials. Same NODE_ENV gate used by bootstrapSeederIsEnabled() /
+    // main.ts / the iam+o-auth bootstrap seeders — this codebase's established
+    // convention for "dev-only fallback, refused in production".
+    if (!reportsDbUser && process.env['NODE_ENV'] === 'production') {
+      throw new InternalServerErrorException(
+        '[reportDbPoolProvider] REPORTS_DB_USER is not set. In production, a dedicated ' +
+          'read-only database role is MANDATORY (design D4: fail closed if it can write). ' +
+          'Provision the role and set REPORTS_DB_USER / REPORTS_DB_PASSWORD via SOPS before booting.',
+      );
+    }
+
+    const username = reportsDbUser ?? process.env['DB_USERNAME'] ?? 'postgres';
+    const password = process.env['REPORTS_DB_PASSWORD'] ?? process.env['DB_PASSWORD'] ?? '';
+    const host = process.env['REPORTS_DB_HOST'] ?? process.env['DB_HOST'] ?? 'localhost';
+    const database = process.env['REPORTS_DB_NAME'] ?? process.env['DB_DATABASE'] ?? 'aurora';
+    const port = parseInt(process.env['REPORTS_DB_PORT'] ?? process.env['DB_PORT'] ?? '5432', 10);
+
+    // pg.Pool has no `min` pool-size option (Sequelize's `pool.min`) — clients
+    // are created lazily on demand up to `max`; omitting it is behavior-neutral.
+    // acquire (ms to wait for a free connection) -> connectionTimeoutMillis.
+    // idle (ms before an idle client is closed) -> idleTimeoutMillis.
+    return new Pool({
+      host,
+      port,
+      user: username,
+      password,
+      database,
+      max: 5,
+      connectionTimeoutMillis: 30000,
+      idleTimeoutMillis: 10000,
+    });
+  },
+};

package/dist/templates/backend/application/src/@aurora/modules/report-engine/report-db-pool.token.ts

@@ -0,0 +1,17 @@
+/**
+ * DI token for the read-only `pg.Pool` connection pool used by the report engine.
+ *
+ * The pool is provided by `report-db-pool.provider.ts` and injected into
+ * `ReportQueryBuilder` and `ReportPreflightService`.
+ *
+ * Credentials are read from environment variables (documented in
+ * `cliter/reporting/CONTEXT.md`):
+ *   REPORTS_DB_USER     — read-only PostgreSQL role name
+ *   REPORTS_DB_PASSWORD — password for that role (managed via SOPS)
+ *   REPORTS_DB_HOST     — database host (defaults to MAIN DB host if unset)
+ *   REPORTS_DB_NAME     — database name (defaults to main DB name if unset)
+ *   REPORTS_DB_PORT     — port (defaults to 5432)
+ *
+ * HR-PORTS-001 COMPLY: no imports from @app or @api.
+ */
+export const REPORT_DB_POOL = 'REPORT_DB_POOL' as const;

package/dist/templates/backend/application/src/@aurora/modules/report-engine/report-engine.module.spec.ts

@@ -0,0 +1,119 @@
+/**
+ * Cross-module DI test for ReportEngineModule.forFeature().
+ *
+ * This test reproduces the bug described in the DI cross-module diagnosis:
+ *   - ReportRegistry (inside ReportEngineModule) injects @Optional() AURORA_REPORT.
+ *   - If AURORA_REPORT is provided in the IMPORTING module (e.g. ReportingModule)
+ *     instead of inside ReportEngineModule, NestJS encapsulation means ReportRegistry
+ *     receives null — the cube is invisible to the registry.
+ *
+ * The fix: ReportEngineModule.forFeature(cubes) co-locates AURORA_REPORT and
+ * ReportRegistry in the SAME DI scope, so the registry sees the cubes.
+ *
+ * RED test: this test FAILS against the current static @Module({}) because
+ * forFeature() does not exist yet.
+ * GREEN test: passes once forFeature() is implemented.
+ */
+import { Module } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+
+import type { ReportCube } from './report-cube.types.js';
+import { ReportEngineModule } from './report-engine.module.js';
+import { ReportRegistry } from './report-registry.js';
+
+// ---------------------------------------------------------------------------
+// Minimal valid cube (primaryTableAlias must appear in tenantColumns)
+// ---------------------------------------------------------------------------
+
+const fakeCube: ReportCube = {
+  key: 'test.cross-module-cube',
+  resultMode: 'client',
+  primaryTableAlias: 'test_table',
+  primaryTableSql: 'test_table t',
+  dimensions: [{ key: 'dim1', expression: 't.col1', tableAlias: 'test_table' }],
+  measures: [
+    { key: 'measure1', expression: 't.col2', tableAlias: 'test_table', aggregateFunction: 'SUM' },
+  ],
+  tenantColumns: {
+    test_table: { column: 't.tenant_id', isArray: false },
+  },
+  systemReports: [
+    { name: 'Test report', selection: { dimensions: ['dim1'], measures: ['measure1'] } },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Simulated consumer module — mirrors how ReportingModule imports the engine
+// ---------------------------------------------------------------------------
+
+@Module({
+  imports: [ReportEngineModule.forFeature([fakeCube])],
+})
+class ConsumerModule {}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ReportEngineModule.forFeature — cross-module DI scope', () => {
+  it('exports ReportRegistry that can find the cube registered via forFeature()', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [ConsumerModule],
+    }).compile();
+
+    const registry = moduleRef.get(ReportRegistry);
+    const found = registry.findByKey('test.cross-module-cube');
+
+    expect(found).toBeDefined();
+    expect(found?.key).toBe('test.cross-module-cube');
+  });
+
+  it('registry returns undefined for a cube that was NOT registered', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [ConsumerModule],
+    }).compile();
+
+    const registry = moduleRef.get(ReportRegistry);
+    expect(registry.findByKey('not-registered-cube')).toBeUndefined();
+  });
+
+  it('validates cube at registration time — throws for a cube missing tenantColumns', async () => {
+    const invalidCube: ReportCube = {
+      key: 'bad.cube',
+      resultMode: 'client',
+      primaryTableAlias: 'some_table',
+      primaryTableSql: 'some_table s',
+      dimensions: [],
+      measures: [],
+      // tenantColumns missing the 'some_table' alias — validateCubeRegistration throws
+      tenantColumns: {},
+      systemReports: [],
+    };
+
+    // forFeature should throw synchronously when validating the invalid cube
+    expect(() => ReportEngineModule.forFeature([invalidCube])).toThrow(
+      /missing a tenantColumns entry/,
+    );
+  });
+
+  it('ends the report pg.Pool on application shutdown (exits cleanly, no leaked sockets)', async () => {
+    // The report pool is the engine's OWN connection (separate read-only
+    // credentials); without teardown its sockets keep the Node event loop
+    // alive after app.close(), hanging the test run. Mirrors DrizzleConfigModule's teardown.
+    const fakePool = { end: vi.fn().mockResolvedValue(undefined), ended: false };
+    const moduleInstance = new ReportEngineModule(fakePool as never);
+
+    await moduleInstance.onApplicationShutdown();
+
+    expect(fakePool.end).toHaveBeenCalledTimes(1);
+  });
+
+  it('shutdown is a no-op when the pool is already ended (no double-end crash)', async () => {
+    const fakePool = { end: vi.fn().mockResolvedValue(undefined), ended: true };
+    const moduleInstance = new ReportEngineModule(fakePool as never);
+
+    await moduleInstance.onApplicationShutdown();
+
+    expect(fakePool.end).not.toHaveBeenCalled();
+  });
+});

package/dist/templates/backend/application/src/@aurora/modules/report-engine/report-engine.module.ts

@@ -0,0 +1,105 @@
+import { DynamicModule, Inject, Module, OnApplicationShutdown, Optional } from '@nestjs/common';
+import type { Pool } from 'pg';
+
+import { AURORA_REPORT } from './aurora-report.token.js';
+import {
+  CARDINALITY_GUARD_TOKEN,
+  ExecuteReportService,
+  SELECTION_VALIDATOR_TOKEN,
+} from './execute-report.service.js';
+import { checkCardinality } from './report-cardinality.guard.js';
+import type { ReportCube } from './report-cube.types.js';
+import { validateCubeRegistration } from './report-cube.validator.js';
+import { reportDbPoolProvider } from './report-db-pool.provider.js';
+import { REPORT_DB_POOL } from './report-db-pool.token.js';
+import { ReportPreflightService } from './report-preflight.service.js';
+import { ReportQueryBuilder } from './report-query.builder.js';
+import { ReportRegistry } from './report-registry.js';
+import { validateReportSelection } from './report-selection.validator.js';
+import { ReportTenantScoper } from './report-tenant.scoper.js';
+import { ClientMode } from './result-modes/client-mode.js';
+import { ServerMode } from './result-modes/server-mode.js';
+
+/**
+ * NestJS module for the report engine framework primitive.
+ *
+ * Use the dynamic `forFeature(cubes)` factory — it co-locates `AURORA_REPORT`,
+ * `ReportRegistry`, and `ExecuteReportService` in the SAME DI scope so the
+ * registry receives the cubes correctly.
+ *
+ * Background: NestJS provider encapsulation means a provider in an IMPORTED
+ * module (ReportRegistry) cannot see providers registered by the IMPORTING
+ * module (AURORA_REPORT in ReportingModule). `forFeature` solves this by
+ * placing both inside the same `ReportEngineModule` DI container.
+ *
+ * Exported providers:
+ *   - `ReportRegistry`         — find cubes by key, list all.
+ *   - `ExecuteReportService`   — full pipeline: resolve → validate → scope → execute.
+ *   - `ReportPreflightService` — OnModuleInit boot check (read-only pool verification).
+ *   - `AURORA_REPORT`          — the cubes array (so seeders in the consumer module
+ *                                can still inject it directly).
+ *
+ * HR-PORTS-001 COMPLY: no imports from @app or @api.
+ */
+@Module({})
+export class ReportEngineModule implements OnApplicationShutdown {
+  constructor(
+    // @Optional: the bare (non-forFeature) module class carries no provider for
+    // the token — only the DynamicModule returned by forFeature does.
+    @Optional()
+    @Inject(REPORT_DB_POOL)
+    private readonly reportDbPool: Pool | undefined,
+  ) {}
+
+  /**
+   * Ends the report pool on shutdown — without it, the pool's open sockets
+   * keep the Node event loop alive after `app.close()`, hanging every e2e run.
+   * Mirrors `DrizzleConfigModule`'s teardown (core-back).
+   */
+  async onApplicationShutdown(): Promise<void> {
+    if (this.reportDbPool && !this.reportDbPool.ended) {
+      await this.reportDbPool.end();
+    }
+  }
+
+  /**
+   * Creates a dynamic NestJS module that registers the provided cubes inside
+   * the engine's own DI scope — where `ReportRegistry` lives — so the registry
+   * receives them correctly.
+   *
+   * @param cubes - The `ReportCube[]` to register. Each cube is validated via
+   *   `validateCubeRegistration` before the module is created; an invalid cube
+   *   throws synchronously at module-definition time (before DI resolves).
+   */
+  static forFeature(cubes: ReportCube[]): DynamicModule {
+    for (const cube of cubes) {
+      validateCubeRegistration(cube);
+    }
+
+    return {
+      module: ReportEngineModule,
+      providers: [
+        { provide: AURORA_REPORT, useValue: cubes },
+        reportDbPoolProvider,
+        ReportRegistry,
+        ReportQueryBuilder,
+        ReportTenantScoper,
+        // ClientMode's constructor takes an OPTIONAL config (cap) that is NOT a DI
+        // dependency — register via factory so Nest does not try to resolve index [0].
+        { provide: ClientMode, useFactory: () => new ClientMode() },
+        ServerMode,
+        {
+          provide: SELECTION_VALIDATOR_TOKEN,
+          useValue: { validateReportSelection },
+        },
+        {
+          provide: CARDINALITY_GUARD_TOKEN,
+          useValue: { checkCardinality },
+        },
+        ExecuteReportService,
+        ReportPreflightService,
+      ],
+      exports: [ReportRegistry, ExecuteReportService, ReportPreflightService, AURORA_REPORT],
+    };
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/report-engine/report-preflight.service.ts

@@ -0,0 +1,152 @@
+import {
+  Inject,
+  Injectable,
+  InternalServerErrorException,
+  Logger,
+  OnModuleInit,
+} from '@nestjs/common';
+import type { Pool } from 'pg';
+
+import { REPORT_DB_POOL } from './report-db-pool.token.js';
+
+/**
+ * Boot-time preflight for the read-only report database pool.
+ *
+ * Runs once at `OnModuleInit`. Performs two checks:
+ *  1. Connectivity: executes `SELECT current_user` to confirm the pool can connect.
+ *  2. Effective write-denial: uses `has_table_privilege(current_user, oid, 'INSERT'|…)`
+ *     aggregated over every user table in non-system schemas to confirm the connected
+ *     role has NO effective INSERT, UPDATE, or DELETE capability on any persistent table.
+ *
+ * Why `has_table_privilege` instead of `information_schema.role_table_grants`?
+ *   `role_table_grants` records the LITERAL grantee of each privilege. When a DBA does
+ *   `GRANT writer_role TO reports_ro`, the INSERT privilege lives under `grantee = 'writer_role'`
+ *   — never under `'reports_ro'` — so filtering by `grantee = current_user` silently misses
+ *   all inherited privileges. PostgreSQL roles inherit by default (INHERIT is the default),
+ *   meaning `reports_ro` would have effective write capability while the query returns no rows.
+ *   That is a false-negative in the dangerous direction.
+ *
+ *   `has_table_privilege(current_user, oid, privilege)` resolves the FULL privilege chain:
+ *   direct grants + role membership inheritance + PUBLIC grants. It is the authoritative
+ *   PostgreSQL function for answering "can this session actually perform this operation?".
+ *
+ * Fail-closed invariant: any unexpected error during either check fails boot.
+ * Ambiguity = fail. The check passes ONLY on explicit "no effective write access" evidence.
+ *
+ * HR-PORTS-001 COMPLY: no imports from @app or @api.
+ *
+ * @rule BR-REPORT (read-only-pool-preflight — design D4)
+ */
+@Injectable()
+export class ReportPreflightService implements OnModuleInit {
+  private readonly logger = new Logger(ReportPreflightService.name);
+
+  constructor(
+    @Inject(REPORT_DB_POOL)
+    private readonly pool: Pool,
+  ) {}
+
+  async onModuleInit(): Promise<void> {
+    this.logger.log('Report read-only pool preflight starting…');
+
+    // Step 1: connectivity
+    try {
+      await this.pool.query('SELECT current_user');
+    } catch (err) {
+      const cause = err instanceof Error ? err.message : String(err);
+      throw new InternalServerErrorException(
+        `[ReportPreflightService] Read-only report pool failed connectivity check. ` +
+          `Root cause: ${cause}. ` +
+          `Ensure REPORTS_DB_* env vars are set and the role exists in the database.`,
+      );
+    }
+
+    // Dev guard: only ENFORCE read-only when a dedicated reporting role is configured.
+    // Without REPORTS_DB_USER the pool falls back to the MAIN (write-capable) credentials
+    // (see report-db-pool.provider) so the app can still boot in local development. In that
+    // case we do NOT abort boot — but we WARN loudly, because the engine is NOT running
+    // read-only. Production MUST set REPORTS_DB_USER (SOPS) so the fail-closed check below runs.
+    //
+    // Fail closed (D4): in production this dev fallback is REFUSED, not warned. Same
+    // NODE_ENV gate as reportDbPoolProvider — if REPORTS_DB_USER is missing in production,
+    // boot MUST fail here even if the pool provider itself somehow did not already throw.
+    if (!process.env['REPORTS_DB_USER']) {
+      if (process.env['NODE_ENV'] === 'production') {
+        throw new InternalServerErrorException(
+          `[ReportPreflightService] REPORTS_DB_USER is NOT set in production. The dev fallback ` +
+            `to the main (write-capable) database credentials is REFUSED in production (design D4: ` +
+            `fail closed if it can write). Provision a dedicated read-only role and set ` +
+            `REPORTS_DB_USER / REPORTS_DB_PASSWORD via SOPS before booting.`,
+        );
+      }
+
+      this.logger.warn(
+        '[ReportPreflightService] REPORTS_DB_USER is NOT set — the report pool is using the main ' +
+          '(write-capable) database credentials as a DEV FALLBACK. Read-only enforcement is SKIPPED. ' +
+          'This is for local development ONLY. In production you MUST provision a dedicated read-only ' +
+          'role and set REPORTS_DB_USER / REPORTS_DB_PASSWORD via SOPS — otherwise report execution ' +
+          'runs without the read-only safety net.',
+      );
+      return;
+    }
+
+    // Step 2: effective privilege check (fail-closed) — enforced whenever a dedicated
+    // reporting role is configured.
+    //
+    // has_table_privilege resolves the full privilege chain: direct grants +
+    // role-membership inheritance + PUBLIC grants. This is the only correct way
+    // to detect whether a role can effectively write, regardless of how that
+    // capability was granted.
+    await this.checkNoEffectiveWritePrivileges();
+
+    this.logger.log('Report read-only pool preflight passed: role has no effective write access.');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Effective privilege check — no side effects, no write operations
+  // ---------------------------------------------------------------------------
+
+  private async checkNoEffectiveWritePrivileges(): Promise<void> {
+    let hasWrite: boolean;
+
+    try {
+      // Aggregate over all persistent user tables (relkind 'r' = table, 'p' = partitioned table)
+      // in non-system schemas. For each table, ask whether current_user can INSERT, UPDATE,
+      // or DELETE via the effective privilege chain (direct + inherited + PUBLIC).
+      //
+      // bool_or returns NULL when there are no user tables — treated as false (no write access).
+      const result = await this.pool.query<{ has_write: boolean | null }>(
+        `SELECT bool_or(
+           has_table_privilege(current_user, c.oid, 'INSERT') OR
+           has_table_privilege(current_user, c.oid, 'UPDATE') OR
+           has_table_privilege(current_user, c.oid, 'DELETE')
+         ) AS has_write
+         FROM pg_catalog.pg_class c
+         JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+         WHERE c.relkind IN ('r', 'p')
+           AND n.nspname NOT IN ('pg_catalog', 'information_schema')`,
+      );
+
+      // bool_or returns NULL when no user tables exist — treat as no write access.
+      hasWrite = result.rows[0]?.has_write === true;
+    } catch (err) {
+      const cause = err instanceof Error ? err.message : String(err);
+      throw new InternalServerErrorException(
+        `[ReportPreflightService] Read-only pool preflight FAILED: ` +
+          `could not execute effective privilege introspection via has_table_privilege. ` +
+          `Root cause: ${cause}. ` +
+          `Verify the role can query pg_catalog.pg_class and pg_catalog.pg_namespace.`,
+      );
+    }
+
+    if (hasWrite) {
+      throw new InternalServerErrorException(
+        `[ReportPreflightService] Read-only pool preflight FAILED: ` +
+          `the database role "${process.env['REPORTS_DB_USER'] ?? 'unknown'}" has effective ` +
+          `INSERT, UPDATE, or DELETE access on at least one user table (including via inherited roles). ` +
+          `The report pool MUST connect with a role that has no effective write access on any table. ` +
+          `Revoke INSERT/UPDATE/DELETE from the role and all roles it inherits, then restart.`,
+      );
+    }
+  }
+}