Module audit_context 

Request audit context: the attribution channel of data-change audit capture (ADR-0025).

The auditlog module’s capture function attributes a row change to WHO made it and WHERE it came from by reading session variables off the connection the write rides:

• app.actor — the authenticated principal (the token’s sub). Unset reads as NULL and the capture function falls back to 'system', so background jobs and unattributed writes stay distinguishable from named users without failing.
• app.correlation_id — the request correlation id (honored from X-Correlation-ID, else minted per request). This is the join key between an audit row and the request that caused it — logs, responses and audit rows carry the same value.
• app.client_ip, app.user_agent, app.http_method, app.resource_path — the request facts, for after-the-fact triage of a suspicious change.

All six are empty-string-when-unset on the wire: every reader wraps them in nullif(current_setting(..., true), ''), so an unset variable reads NULL there. Setting an empty string is therefore indistinguishable from never having set the variable — there is no partial-trust state to reason about.

bind_on is the application half of the channel; the composing service’s guard builds the context (actor off a signed token, the rest off the request) and the request scope carries it, exactly like the fence variables. The database half — the trigger reading them — is owned by the composed auditlog module.

Structs

RequestAuditContext

Who and where one request’s writes are attributed to (ADR-0025).

Constants

AUDIT_CONTEXT_VARS

Every session variable of the audit channel, in bind and reset order.

Functions

current_request_audit

The ambient request’s audit attribution, when this task runs inside the audited org request scope; None outside one (standalone deployments, jobs, relays — the honest no-attribution posture).

relay_ambient_audit_on

Re-bind the ambient request’s audit attribution onto a connection the caller opened itself — the audit twin of the fence relay (bind_org_scope_on): a hand-written write service’s fresh pool transaction carries none of the request connection’s variables, so the audit triggers on it would read an empty actor and stamp 'system'. Transaction-local (local = true): the attribution dies with the transaction, never leaking onto the next checkout of the pooled connection. With no ambient context this is a no-op.