apps/portal-bff/src/audit/audit.service.spec.ts

@@ -2,26 +2,29 @@ import { Test } from '@nestjs/testing';
 import { trace } from '@opentelemetry/api';
 import { ClsService } from 'nestjs-cls';
 import { PrismaService } from 'nestjs-prisma';
-import { Prisma } from '@prisma/client';
 import { AuditWriter } from './audit.service';
 import type { AuditEventInput } from './audit.types';
 import { HashUserIdService } from './hash-user-id.service';
 
-interface AuditEventCreateCall {
+/**
-  data: {
+ * Fields of an audit row as captured from the parameterised raw
-    eventType: string;
+ * INSERT — same positional order as the SQL placeholders. Anything
-    audience: 'workforce' | 'customer';
+ * read from the mock goes through `extractInsertedRow` so the
-    outcome: 'success' | 'failure' | 'denied';
+ * tests assert against named fields rather than raw `$executeRawUnsafe`
-    subject: string | null;
+ * argument indices.
-    actorIdHash: string | null;
+ */
-    traceId: string | null;
+interface InsertedRow {
-    payload: Prisma.InputJsonValue | typeof Prisma.JsonNull;
+  eventType: unknown;
-  };
+  audience: unknown;
+  outcome: unknown;
+  subject: unknown;
+  actorIdHash: unknown;
+  traceId: unknown;
+  payloadJson: unknown;
 }
 
 interface MockTx {
   $executeRawUnsafe: jest.Mock;
-  auditEvent: { create: jest.Mock };
 }
 
 interface MockPrisma {
@@ -32,7 +35,6 @@ interface MockPrisma {
 function buildMocks(): { prisma: MockPrisma; cls: { get: jest.Mock } } {
   const tx: MockTx = {
     $executeRawUnsafe: jest.fn().mockResolvedValue(0),
-    auditEvent: { create: jest.fn().mockResolvedValue(undefined) },
   };
   const prisma: MockPrisma = {
     tx,
@@ -42,6 +44,25 @@ function buildMocks(): { prisma: MockPrisma; cls: { get: jest.Mock } } {
   return { prisma, cls };
 }
 
+/**
+ * Pull the inserted-row fields out of the `$executeRawUnsafe` mock.
+ * `recordEvent` calls `$executeRawUnsafe` twice — first to `SET LOCAL
+ * ROLE audit_writer`, then to issue the parameterised INSERT. The
+ * INSERT call has args (sql, eventType, audience, outcome, subject,
+ * actorIdHash, traceId, payloadJson).
+ */
+function extractInsertedRow(prisma: MockPrisma): InsertedRow {
+  const calls = prisma.tx.$executeRawUnsafe.mock.calls;
+  const insertCall = calls[1];
+  if (!insertCall) {
+    throw new Error(
+      `expected $executeRawUnsafe to be called at least twice (SET ROLE + INSERT), got ${calls.length}`,
+    );
+  }
+  const [, eventType, audience, outcome, subject, actorIdHash, traceId, payloadJson] = insertCall;
+  return { eventType, audience, outcome, subject, actorIdHash, traceId, payloadJson };
+}
+
 async function createSubject(): Promise<{
   writer: AuditWriter;
   prisma: MockPrisma;
@@ -75,35 +96,69 @@ describe('AuditWriter', () => {
     await writer.recordEvent(baseInput);
 
     expect(prisma.$transaction).toHaveBeenCalledTimes(1);
-    expect(prisma.tx.$executeRawUnsafe).toHaveBeenCalledWith('SET LOCAL ROLE audit_writer');
+    // recordEvent runs two raw statements per call: SET ROLE then
-    // SET ROLE must precede the INSERT, otherwise the runtime
+    // INSERT. SET ROLE must come first so the INSERT's privilege
-    // privilege check happens with the wrong role.
+    // check is against audit_writer, not the BFF's connection role.
-    const setRoleOrder = prisma.tx.$executeRawUnsafe.mock.invocationCallOrder[0];
+    const calls = prisma.tx.$executeRawUnsafe.mock.calls;
-    const createOrder = prisma.tx.auditEvent.create.mock.invocationCallOrder[0];
+    expect(calls.length).toBeGreaterThanOrEqual(2);
-    expect(setRoleOrder).toBeLessThan(createOrder);
+    expect(calls[0]?.[0]).toBe('SET LOCAL ROLE audit_writer');
+    expect(calls[1]?.[0]).toMatch(/INSERT INTO "audit"\."events"/);
   });
 
-  it('passes the input fields through to the create call', async () => {
+  it('does NOT use Prisma ORM create() — the raw INSERT keeps audit_writer free of SELECT', async () => {
+    // Bypassing the ORM is the explicit choice that lets ADR-0013's
+    // append-only role contract hold. Prisma's create() emits
+    // `INSERT … RETURNING *`, and RETURNING requires SELECT. Pin
+    // the constraint so a well-meaning refactor can't silently
+    // reintroduce the bug.
+    const { writer, prisma } = await createSubject();
+    await writer.recordEvent(baseInput);
+
+    // Sanity check: the only writes go through $executeRawUnsafe.
+    // No other tx method should be called.
+    const allowedTxKeys = new Set(['$executeRawUnsafe']);
+    const observedTxKeys = Object.keys(prisma.tx);
+    expect(observedTxKeys.every((k) => allowedTxKeys.has(k))).toBe(true);
+  });
+
+  it('parameterises the INSERT — never inlines values into SQL', async () => {
+    const { writer, prisma } = await createSubject();
+    await writer.recordEvent({
+      ...baseInput,
+      eventType: "auth'; DROP TABLE events; --",
+    });
+
+    const insertCall = prisma.tx.$executeRawUnsafe.mock.calls[1];
+    const sql = insertCall?.[0] as string;
+    // SQL itself must be the parameterised template; the malicious
+    // eventType has to land in the params array, not concatenated
+    // into the SQL.
+    expect(sql).toContain('$1');
+    expect(sql).not.toContain('DROP TABLE');
+    expect(insertCall?.[1]).toBe("auth'; DROP TABLE events; --");
+  });
+
+  it('passes the input fields through positionally to the parameterised INSERT', async () => {
     const { writer, prisma } = await createSubject();
     await writer.recordEvent({
       ...baseInput,
       payload: { route: '/auth/login', clientId: 'spa' },
     });
 
-    const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+    const row = extractInsertedRow(prisma);
-    expect(call.data.eventType).toBe('auth.login');
+    expect(row.eventType).toBe('auth.login');
-    expect(call.data.audience).toBe('workforce');
+    expect(row.audience).toBe('workforce');
-    expect(call.data.outcome).toBe('success');
+    expect(row.outcome).toBe('success');
-    expect(call.data.subject).toBe('user:42');
+    expect(row.subject).toBe('user:42');
-    expect(call.data.payload).toEqual({ route: '/auth/login', clientId: 'spa' });
+    expect(row.payloadJson).toBe(JSON.stringify({ route: '/auth/login', clientId: 'spa' }));
   });
 
-  it('records Prisma.JsonNull when no payload is provided', async () => {
+  it('sends payload as null (JSONB column nullable) when no payload is provided', async () => {
     const { writer, prisma } = await createSubject();
     await writer.recordEvent(baseInput);
 
-    const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+    const row = extractInsertedRow(prisma);
-    expect(call.data.payload).toBe(Prisma.JsonNull);
+    expect(row.payloadJson).toBeNull();
   });
 
   it('reads actorIdHash from CLS when not passed explicitly', async () => {
@@ -113,8 +168,7 @@ describe('AuditWriter', () => {
     await writer.recordEvent(baseInput);
 
     expect(cls.get).toHaveBeenCalledWith('actorIdHash');
-    const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+    expect(extractInsertedRow(prisma).actorIdHash).toBe('hash-from-cls');
-    expect(call.data.actorIdHash).toBe('hash-from-cls');
   });
 
   it('prefers an explicit actorIdHash over the CLS-resolved one', async () => {
@@ -123,8 +177,7 @@ describe('AuditWriter', () => {
 
     await writer.recordEvent({ ...baseInput, actorIdHash: 'hash-from-input' });
 
-    const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+    expect(extractInsertedRow(prisma).actorIdHash).toBe('hash-from-input');
-    expect(call.data.actorIdHash).toBe('hash-from-input');
   });
 
   it('stores actorIdHash = null when neither input nor CLS has one', async () => {
@@ -133,8 +186,7 @@ describe('AuditWriter', () => {
 
     await writer.recordEvent(baseInput);
 
-    const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+    expect(extractInsertedRow(prisma).actorIdHash).toBeNull();
-    expect(call.data.actorIdHash).toBeNull();
   });
 
   it('captures the active OTel trace id', async () => {
@@ -145,8 +197,7 @@ describe('AuditWriter', () => {
       const { writer, prisma } = await createSubject();
       await writer.recordEvent(baseInput);
 
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      expect(extractInsertedRow(prisma).traceId).toBe('abc123');
-      expect(call.data.traceId).toBe('abc123');
     } finally {
       getActiveSpanSpy.mockRestore();
     }
@@ -159,8 +210,7 @@ describe('AuditWriter', () => {
       const { writer, prisma } = await createSubject();
       await writer.recordEvent(baseInput);
 
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      expect(extractInsertedRow(prisma).traceId).toBeNull();
-      expect(call.data.traceId).toBeNull();
     } finally {
       getActiveSpanSpy.mockRestore();
     }
@@ -169,7 +219,8 @@ describe('AuditWriter', () => {
   it('propagates the underlying error — no catch-and-swallow', async () => {
     const { writer, prisma } = await createSubject();
     const dbError = new Error('permission denied for table events');
-    prisma.tx.auditEvent.create.mockRejectedValueOnce(dbError);
+    // First call (SET ROLE) succeeds, second (INSERT) rejects.
+    prisma.tx.$executeRawUnsafe.mockResolvedValueOnce(0).mockRejectedValueOnce(dbError);
 
     await expect(writer.recordEvent(baseInput)).rejects.toThrow(
       'permission denied for table events',
@@ -186,13 +237,13 @@ describe('AuditWriter — typed event methods', () => {
         sessionId: 'sid-1',
       });
       expect(hashUserId.hash).toHaveBeenCalledWith('user-oid');
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      const row = extractInsertedRow(prisma);
-      expect(call.data.eventType).toBe('auth.sign_in');
+      expect(row.eventType).toBe('auth.sign_in');
-      expect(call.data.audience).toBe('workforce');
+      expect(row.audience).toBe('workforce');
-      expect(call.data.outcome).toBe('success');
+      expect(row.outcome).toBe('success');
-      expect(call.data.actorIdHash).toBe('hash(user-oid)');
+      expect(row.actorIdHash).toBe('hash(user-oid)');
-      expect(call.data.subject).toBe('session:sid-1');
+      expect(row.subject).toBe('session:sid-1');
-      expect(call.data.payload).toEqual({ amr: ['pwd', 'mfa'] });
+      expect(row.payloadJson).toBe(JSON.stringify({ amr: ['pwd', 'mfa'] }));
     });
   });
 
@@ -201,11 +252,11 @@ describe('AuditWriter — typed event methods', () => {
       const { writer, prisma, hashUserId } = await createSubject();
       await writer.signInFailed({ failureKind: 'state-mismatch' });
       expect(hashUserId.hash).not.toHaveBeenCalled();
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      const row = extractInsertedRow(prisma);
-      expect(call.data.eventType).toBe('auth.sign_in.failed');
+      expect(row.eventType).toBe('auth.sign_in.failed');
-      expect(call.data.outcome).toBe('failure');
+      expect(row.outcome).toBe('failure');
-      expect(call.data.actorIdHash).toBeNull();
+      expect(row.actorIdHash).toBeNull();
-      expect(call.data.payload).toEqual({ failureKind: 'state-mismatch' });
+      expect(row.payloadJson).toBe(JSON.stringify({ failureKind: 'state-mismatch' }));
     });
 
     it('merges payload with failureKind under the same key', async () => {
@@ -214,20 +265,21 @@ describe('AuditWriter — typed event methods', () => {
         failureKind: 'entra-error',
         payload: { entraError: 'access_denied', entraErrorDescription: 'user cancelled' },
       });
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      const row = extractInsertedRow(prisma);
-      expect(call.data.payload).toEqual({
+      expect(row.payloadJson).toBe(
-        failureKind: 'entra-error',
+        JSON.stringify({
-        entraError: 'access_denied',
+          failureKind: 'entra-error',
-        entraErrorDescription: 'user cancelled',
+          entraError: 'access_denied',
-      });
+          entraErrorDescription: 'user cancelled',
+        }),
+      );
     });
 
     it('hashes the actor oid when one is provided (rare — identity-after-rejection path)', async () => {
       const { writer, prisma, hashUserId } = await createSubject();
       await writer.signInFailed({ failureKind: 'amr-missing', actor: { oid: 'user-oid' } });
       expect(hashUserId.hash).toHaveBeenCalledWith('user-oid');
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      expect(extractInsertedRow(prisma).actorIdHash).toBe('hash(user-oid)');
-      expect(call.data.actorIdHash).toBe('hash(user-oid)');
     });
   });
 
@@ -236,11 +288,11 @@ describe('AuditWriter — typed event methods', () => {
       const { writer, prisma, hashUserId } = await createSubject();
       await writer.signOut({ actor: { oid: 'user-oid' }, sessionId: 'sid-2' });
       expect(hashUserId.hash).toHaveBeenCalledWith('user-oid');
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      const row = extractInsertedRow(prisma);
-      expect(call.data.eventType).toBe('auth.sign_out');
+      expect(row.eventType).toBe('auth.sign_out');
-      expect(call.data.outcome).toBe('success');
+      expect(row.outcome).toBe('success');
-      expect(call.data.actorIdHash).toBe('hash(user-oid)');
+      expect(row.actorIdHash).toBe('hash(user-oid)');
-      expect(call.data.subject).toBe('session:sid-2');
+      expect(row.subject).toBe('session:sid-2');
     });
   });
 
@@ -254,11 +306,13 @@ describe('AuditWriter — typed event methods', () => {
         ageMs: 13 * 60 * 60 * 1000,
       });
       expect(hashUserId.hash).toHaveBeenCalledWith('user-oid');
-      const call = prisma.tx.auditEvent.create.mock.calls[0]?.[0] as AuditEventCreateCall;
+      const row = extractInsertedRow(prisma);
-      expect(call.data.eventType).toBe('auth.session.expired');
+      expect(row.eventType).toBe('auth.session.expired');
-      expect(call.data.outcome).toBe('success');
+      expect(row.outcome).toBe('success');
-      expect(call.data.subject).toBe('session:sid-3');
+      expect(row.subject).toBe('session:sid-3');
-      expect(call.data.payload).toEqual({ reason: 'absolute', ageMs: 13 * 60 * 60 * 1000 });
+      expect(row.payloadJson).toBe(
+        JSON.stringify({ reason: 'absolute', ageMs: 13 * 60 * 60 * 1000 }),
+      );
     });
   });
 });

apps/portal-bff/src/audit/audit.service.ts

@@ -2,7 +2,6 @@ import { Injectable } from '@nestjs/common';
 import { trace } from '@opentelemetry/api';
 import { ClsService } from 'nestjs-cls';
 import { PrismaService } from 'nestjs-prisma';
-import { Prisma } from '@prisma/client';
 import type {
   AuditEventInput,
   SignInActor,
@@ -118,6 +117,7 @@ export class AuditWriter {
     const traceId = trace.getActiveSpan()?.spanContext().traceId ?? null;
     const actorIdHash =
       input.actorIdHash ?? this.cls.get<string | undefined>('actorIdHash') ?? null;
+    const payloadJson = input.payload === undefined ? null : JSON.stringify(input.payload);
 
     await this.prisma.$transaction(async (tx) => {
       // Lock the connection to audit_writer for the duration of this
@@ -125,27 +125,40 @@ export class AuditWriter {
       // pool's next consumer sees the original role.
       await tx.$executeRawUnsafe(`SET LOCAL ROLE audit_writer`);
 
-      await tx.auditEvent.create({
+      // Deliberately NOT `tx.auditEvent.create(...)`. The Prisma ORM
-        data: {
+      // create() emits `INSERT … RETURNING *` to hydrate the entity
-          eventType: input.eventType,
+      // it returns, and Postgres requires SELECT on every column
-          audience: input.audience,
+      // listed in RETURNING. `audit_writer` is granted INSERT only
-          outcome: input.outcome,
+      // (ADR-0013 §"Append-only by role grants"); RETURNING fails
-          subject: input.subject ?? null,
+      // with the deeply misleading "permission denied for table
-          actorIdHash,
+      // events" error code 42501. Raw parameterised INSERT keeps
-          traceId,
+      // the role contract strict — audit_writer never needs SELECT.
-          payload: this.toJsonInput(input.payload),
+      //
-        },
+      // `gen_random_uuid()` is built into Postgres 13+ (the dev /
-      });
+      // prod target is 17). The enum + jsonb casts are needed
+      // because the parameter values are sent as TEXT over the
+      // wire.
+      await tx.$executeRawUnsafe(
+        `INSERT INTO "audit"."events"
+           (id, event_type, audience, outcome, subject, actor_id_hash, trace_id, payload)
+         VALUES (
+           gen_random_uuid(),
+           $1,
+           $2::"audit"."AuditAudience",
+           $3::"audit"."AuditOutcome",
+           $4,
+           $5,
+           $6,
+           $7::jsonb
+         )`,
+        input.eventType,
+        input.audience,
+        input.outcome,
+        input.subject ?? null,
+        actorIdHash,
+        traceId,
+        payloadJson,
+      );
     });
   }
-
-  // Prisma's `Json` field accepts `Prisma.JsonNull` (null literal in
-  // SQL JSONB) or a serialisable value; explicit `undefined` skips
-  // the column. Map `payload` accordingly.
-  private toJsonInput(
-    payload: AuditEventInput['payload'],
-  ): Prisma.InputJsonValue | typeof Prisma.JsonNull {
-    if (payload === undefined) return Prisma.JsonNull;
-    return payload as Prisma.InputJsonValue;
-  }
 }

apps/portal-bff/src/auth/auth.controller.spec.ts

@@ -229,22 +229,36 @@ describe('AuthController.callback', () => {
   });
 
   it('records createdAt + absoluteExpiresAt on the session (ADR-0010 §"TTL policy")', async () => {
-    const before = Date.now();
+    // Force the ADR-0010 default for this test — apps/portal-bff/.env
-    const { controller } = makeController();
+    // may have a custom SESSION_ABSOLUTE_TIMEOUT_SECONDS for local
-    const res = makeResStub();
+    // experiments and Nx auto-loads it. Asserting on the default in
-    const session = makeSessionStub();
+    // a test that doesn't override it then fails non-deterministically.
-    const req = makeReqStub({
+    const originalAbsolute = process.env['SESSION_ABSOLUTE_TIMEOUT_SECONDS'];
-      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    delete process.env['SESSION_ABSOLUTE_TIMEOUT_SECONDS'];
-      session,
+    try {
-    });
+      const before = Date.now();
+      const { controller } = makeController();
+      const res = makeResStub();
+      const session = makeSessionStub();
+      const req = makeReqStub({
+        signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+        session,
+      });
 
-    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+      await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
 
-    const after = Date.now();
+      const after = Date.now();
-    expect(session.createdAt).toBeGreaterThanOrEqual(before);
+      expect(session.createdAt).toBeGreaterThanOrEqual(before);
-    expect(session.createdAt).toBeLessThanOrEqual(after);
+      expect(session.createdAt).toBeLessThanOrEqual(after);
-    // Default absoluteSeconds = 43200 (12 h) per ADR-0010.
+      // Default absoluteSeconds = 43200 (12 h) per ADR-0010.
-    expect(session.absoluteExpiresAt).toBe((session.createdAt as number) + 43_200 * 1000);
+      expect(session.absoluteExpiresAt).toBe((session.createdAt as number) + 43_200 * 1000);
+    } finally {
+      if (originalAbsolute === undefined) {
+        delete process.env['SESSION_ABSOLUTE_TIMEOUT_SECONDS'];
+      } else {
+        process.env['SESSION_ABSOLUTE_TIMEOUT_SECONDS'] = originalAbsolute;
+      }
+    }
   });
 
   it('registers the new session in the user_sessions index after save', async () => {

docs/decisions/0013-audit-trail-separated-postgres-append-only.md

@@ -1,6 +1,7 @@
 ---
 status: accepted
 date: 2026-04-29
+last-updated: 2026-05-13
 decision-makers: R&D Lead
 tags: [security, observability, data]
 ---
@@ -95,6 +96,8 @@ enum AuditOutcome {
 
 **Writer.** A NestJS `AuditService` exposes a single typed method per event family. Inside a request, the service uses the same Prisma transaction as the business action where applicable; outside a request (background expirations, scheduled jobs), it uses a fresh transaction. Writer connection runs under the `audit_writer` role and has only `INSERT` on `audit.events` — any attempt to `UPDATE` or `DELETE` is rejected by Postgres regardless of code intent.
 
+> **Implementation trap — Prisma ORM cannot be used for the write.** Prisma's `tx.auditEvent.create(...)` issues `INSERT … RETURNING *` to hydrate the entity it returns. Postgres requires the `SELECT` privilege on every column listed in `RETURNING`, and `audit_writer` has `INSERT` only by design — there is no `SELECT` grant on the writer role. The ORM path therefore fails at runtime with `PostgresError 42501 / "permission denied for table events"`, an error whose message mentions neither `SELECT` nor `RETURNING`. The write path uses **parameterised `$executeRawUnsafe`** with no `RETURNING` clause; the schema-level `id UUID @default(uuid())` from Prisma is replaced server-side with `gen_random_uuid()` in the SQL. This is a deliberate consequence of the role-separation contract and is pinned by a spec test. The alternative — granting `SELECT` on `audit.events` to `audit_writer` — would collapse the writer / reader role separation that the rest of this ADR rests on, so we go the other way.
+
 **Events emitted in v1.**
 
 | `event_type`                   | When                                                                                                                       | `outcome` |
@@ -161,7 +164,7 @@ Hooks for **admin actions** and **sensitive data access** are designed-in: the w
 - `apps/portal-bff/prisma/schema.prisma` enables the `multiSchema` preview, declares the `audit` schema alongside `public`, and carries the `AuditEvent` model with `AuditAudience` (`workforce | customer`) and `AuditOutcome` (`success | failure | denied`) enums.
 - The migration `prisma/migrations/*_init_audit_schema/migration.sql` creates `audit.events`, `ALTER`s table + enum types to be owned by `audit_owner`, and re-applies the role grants explicitly: `INSERT` to `audit_writer`, `SELECT` to `audit_reader`, `SELECT, DELETE` to `audit_archiver` (SELECT is needed for archiver to evaluate the `created_at` predicate of "delete older than retention"). No grant of `UPDATE` or `TRUNCATE` to anyone — including the migrator's own login at runtime; only fresh schema migrations amend the table.
 - The roles themselves and the schema with default privileges are provisioned earlier by `infra/local/init/postgres/01-init.sql` (dev) — production replicates the same SQL via the future on-prem infrastructure ADR.
-- `apps/portal-bff/src/audit/audit.service.ts` exposes a single `AuditWriter.recordEvent(input)` method. Every write runs in a transaction whose first statement is `SET LOCAL ROLE audit_writer`, so the runtime contract holds even if the BFF connection is otherwise privileged. `trace_id` is auto-resolved from the active OTel span; `actor_id_hash` is read from CLS or accepted as an explicit override (placeholder until ADR-0009 / ADR-0010 land their guards). Failures propagate — no catch-and-swallow, per "blocking writes: no audit ⇒ no action".
+- `apps/portal-bff/src/audit/audit.service.ts` exposes a single `AuditWriter.recordEvent(input)` method. Every write runs in a transaction whose first statement is `SET LOCAL ROLE audit_writer`, so the runtime contract holds even if the BFF connection is otherwise privileged. The INSERT itself is a **parameterised `$executeRawUnsafe`**, not `tx.auditEvent.create(...)` — see the "Implementation trap" callout in the Writer section above for the RETURNING-requires-SELECT explanation. `trace_id` is auto-resolved from the active OTel span; `actor_id_hash` is read from CLS or accepted as an explicit override (placeholder until ADR-0009 / ADR-0010 land their guards). Failures propagate — no catch-and-swallow, per "blocking writes: no audit ⇒ no action".
 - BFF connects via the shared `DATABASE_URL` (the role switch is per-transaction). A separate `AUDIT_DATABASE_URL` connection pool is the production hardening, deferred — see "wired as features land" below.
 - Smoke-tested end to end against the local-dev Postgres: `audit_writer` INSERTs successfully, fails on `UPDATE` and `DELETE`; `audit_archiver` SELECTs + DELETEs successfully.