Data, persistence and state

Turns the PostgreSQL backend on only when QODIQA_PG_ENABLED is exactly 'true'. It reads the environment and either builds the connection pool or emits PG_DISABLED; the boot validator requires role passwords.

What it does

env → build pool or emit PG_DISABLED

Inputs

env → build pool or emit PG_DISABLED

Outputs

env → build pool or emit PG_DISABLED

Depends on

pg

Safeguards

boot validator requires role passwords

Builds the pool configuration from the environment with TLS, a maximum of 16 connections, a 1500ms acquire limit and a 30s statement timeout. TLS is verified in production and the time zone is UTC.

What it does

env → Pool config

Inputs

env → Pool config

Outputs

env → Pool config

Safeguards

TLS verify in prod; TimeZone UTC

Runs parameterized queries through the circuit breaker and reports slow or failed queries as PG_SLOW_QUERY and PG_QUERY_ERROR telemetry. It takes sql and returns the result.

What it does

sql → result; PG_SLOW_QUERY/PG_QUERY_ERROR

Inputs

sql → result; PG_SLOW_QUERY/PG_QUERY_ERROR

Outputs

sql → result; PG_SLOW_QUERY/PG_QUERY_ERROR

Safeguards

parameterized

Runs a function inside a transaction, using REPEATABLE READ by default, and retries serializable failures (code 40001) up to 5 times. The function receives the transaction handle.

What it does

fn(tx)

Inputs

fn(tx)

Outputs

fn(tx)

Sets a transaction-local value after checking it against the regex ^[A-Za-z0-9_-]$. It carries the RLS context and does not leak it to other pooled connections.

What it does

regex ^[A-Za-z0-9_-]$

Inputs

regex ^[A-Za-z0-9_-]$

Outputs

regex ^[A-Za-z0-9_-]$

Safeguards

RLS context, no pooled-conn leak

Provides a session pg_advisory_lock helper; the migration runner uses key 946812026. It is active through that helper and serialises DDL.

What it does

Active (via)

Safeguards

serialises DDL

Readiness monitor that runs a bounded SELECT 1 every 5 s and caches the result. It runs under BackgroundTaskRunner, and GET /ready never queries the database itself.

What it does

Active

Depends on

BackgroundTaskRunner

Safeguards

GET /ready never queries

Pool telemetry that exposes pool stats as Prometheus gauges. It is active, and the diagnostics and ready routes import the pool. It draws on metrics and pg_stat_*.

What it does

Active (diagnostics/ready routes import pool)

Depends on

metrics, pg_stat_*

Circuit breaker for PostgreSQL with CLOSED, OPEN and HALF_OPEN states, a probe lease and error classification. Thresholds come from env (5/30000/30000/2); when open it fails fast with PG_CIRCUIT_OPEN. State is in-memory.

What it does

env thresholds 5/30000/30000/2

Inputs

env thresholds 5/30000/30000/2

Outputs

env thresholds 5/30000/30000/2

State

in-memory

Safeguards

fail-fast PG_CIRCUIT_OPEN

Resolves a single TLS decision shared by all PostgreSQL clients, from QODIQA_PG_SSL* and NODE_ENV. It depends on fs, so every client follows one consistent connection policy.

What it does

QODIQA_PG_SSL*, NODE_ENV

Inputs

QODIQA_PG_SSL*, NODE_ENV

Outputs

QODIQA_PG_SSL*, NODE_ENV

Depends on

fs

Safeguards

true

Attaches an error listener to each pooled client and logs errors in aggregated form. This prevents a client error from crashing the process.

What it does

Active

Safeguards

prevents process crash

System pool using the qodiqa_system role, with no fallback to the app pool. It is used by pg-audit-backend and others, relies on the breaker, and fails closed with PG_ROLE_POOL_NOT_CONFIGURED.

What it does

Active (used by pg-audit-backend etc.)

Depends on

breaker

Safeguards

fail-closed PG_ROLE_POOL_NOT_CONFIGURED

Reporting pool for the qodiqa_reporting role, used by operator routes as set in the route header. It is active and carries the same safeguards as the system pool.

What it does

Active (operator routes per header)

Safeguards

same

Provides the qodiqa_control pool for the control-plane database connection. It is active when the control plane is set to pg.

Read-only snapshot helper for paging, running under REPEATABLE READ READ ONLY, so a paged read sees one consistent snapshot. It is active.

What it does

Active

Retention pool for the qodiqa_retention role, limited to 2 connections. It is active and uses a least-privilege role, so retention work runs with limited rights.

What it does

Active

Safeguards

least-privilege role

Migration runner that applies migration files in order, verifying their checksums, and records progress in the table qodiqa_migrations. It uses an advisory lock and lock_timeout, and enforces checksum immutability.

What it does

files→DB qodiqa_migrations

Inputs

files→DB qodiqa_migrations

Outputs

files→DB qodiqa_migrations

State

table qodiqa_migrations

Safeguards

checksum immutability, advisory lock, lock_timeout

CLI command that reports migration status, showing which migrations are applied and which are still pending, so operators can check a database before or after a migration run.

What it does

CLI

CLI diagnosis of privilege gaps that reports PG_MIGRATE_ROLE_PRIVILEGE_DENIED in a friendly form when the migration role lacks a needed privilege.

What it does

CLI

Definer ownership check that verifies 47 definers and roles against the catalog and returns a problems[] list. It takes a client, depends on DR sql, and is tied to ER-16.

What it does

client → problems[]

Inputs

client → problems[]

Outputs

client → problems[]

Depends on

DR sql

Safeguards

ER-16

Checks schema ownership and repairs it as part of a DR restore, so the restored database objects are owned by the expected role. It is one step in the restore path.

What it does

DR restore

Placeholder-credential probe that proves placeholder migration-role passwords are rejected. It runs as a boot gate (QODIQA_PG_ROLE_CREDENTIAL_GATE), uses a pg Client, and is tied to IND-01.

What it does

Boot gate (QODIQA_PG_ROLE_CREDENTIAL_GATE)

Depends on

pg Client

Safeguards

IND-01

Role credential CLI run manually with the actions check, harden-unused and rotate. It reads admin credentials from the environment and does not print secrets.

What it does

Manual

Depends on

admin creds env

Safeguards

secrets not printed

Evidence-store readiness check that runs SELECT 1 against each store at boot, as a production gate. It depends on the pool.

Audit PG mirror write that inserts an entry into audit_chain, with an evidence record, only after the parent has committed. UNIQUE(prev_hash) and append-only guards protect it.

What it does

entry → audit_chain (+evidence record)

Inputs

entry → audit_chain (+evidence record)

Outputs

entry → audit_chain (+evidence record)

State

audit_chain, evidence_chain_records

Safeguards

UNIQUE(prev_hash), append-only guards

Audit chain load and query: loads all, compact or paged entries and queries by artifact, tenant or lineage. It depends on definers 043/048/058, with RLS enforced via those definers.

What it does

Active

Depends on

definers 043/048/058

Safeguards

RLS via definers

Persists chain verification: verifier progress, checkpoints, signed checkpoints and the mirror count. It depends on tables 059/070/073/074 and keeps state in those tables.

What it does

Active

Depends on

tables 059/070/073/074

State

those tables

Mirror Unicode projection that reversibly escapes per-field mirror columns. It is active through pg-audit-backend, and a strict decoder reads the escapes back.

What it does

Active via pg-audit-backend

Safeguards

strict decoder

Maps each entry to its 10 v8 columns, which are held in audit_chain. It is active and defines how an audit entry is laid out in that table.

What it does

Active

State

audit_chain v8 cols

Core audit and evidence schema in PostgreSQL covering audit_chain, heads, verifier, checkpoints, anchors, platform events, request_trails and the evidence chain. FORCE RLS and append-only guards protect it.

Transparency schema in PostgreSQL holding log entries, roots, verifications, heads and merkle checkpoints. It is active, with FORCE RLS and definers.

What it does

Active

State

PG

Safeguards

FORCE RLS; definers

Consent, DSR and erasure schema holding consent_*, dsr_*, subject_pseudonym_keys and the ledger. It is active, though revocation_events has no writer. RLS and an erasure allowlist (080) apply.

What it does

Active (revocation_events no writer)

State

PG

Safeguards

RLS; erasure allowlist (080)

Caveat Active (revocation_events no writer)

Policy governance schema holding change requests, provenance and tenant configs in PostgreSQL. It is active, with state kept in PG and RLS as the stated safeguard.

What it does

Active

State

PG

Safeguards

RLS

Control plane schema with the table control_plane_records and a guard. It is active when QODIQA_CONTROL_PLANE_BACKEND=pg, with RLS and monotonic, forward-only triggers.

What it does

Active when QODIQA_CONTROL_PLANE_BACKEND=pg

State

PG

Safeguards

monotonic/forward-only triggers

Alerting schema of 8 qodiqa_* tables in PostgreSQL, used by AlertStore. It is active and protected by RLS, with state kept in PG.

What it does

Active

Depends on

AlertStore

State

PG

Safeguards

RLS

Schema for compliance, certification, attestation, portal and webhooks, kept in PG. Tenant RLS is forced and UPDATE is column-scoped, so each tenant sees only its own rows.

Schema for the agent and action layer with 9 tables, kept in PG. Tenant RLS is forced and fails closed, and UPDATE is column-scoped.

Dormant tables schema: 9 tables with no code reference, 7 touched only by an import script. Marked STANDALONE TOOL and Not wired.

What it does

Not wired

State

PG

Caveat Not wired

Defines the tenant RLS policy model together with FORCE RLS, with state kept in PG. It is active and fails closed, so access is denied when the policy cannot be applied.

What it does

Active

State

PG

Safeguards

fail-closed

Definer-function set of 47 definers for cross-tenant reads, with per-role EXECUTE grants. It is active; the owner is qodiqa_definer and pg_temp is placed last in the search order.

What it does

Active

State

PG

Safeguards

owner qodiqa_definer, pg_temp last

Installs append-only guard triggers in the database that block UPDATE, DELETE and TRUNCATE, so audit tables can only be added to. The triggers live in PG.

Role model of 10 roles in the database, with ownership separation. Owner roles are NOLOGIN and BYPASSRLS is limited; state is kept in PG.

What it does

In DB

State

PG

Safeguards

NOLOGIN owners, BYPASSRLS limited

Control plane backend on PostgreSQL that takes a snapshot, pulls changes and refuses stale data. It uses a Redis notifier, stores records in control_plane_records, bounds calls to 5 s and uses versioned writes.

What it does

Active

Depends on

Redis notifier

State

control_plane_records

Safeguards

5 s bound, versioned writes

Control plane memory mode that seeds from JSON and keeps nothing persistent. It is the default when the env is unset, and production refuses it.

What it does

default when env unset

Inputs

default when env unset

Outputs

default when env unset

Safeguards

refused in prod

Caveat refused in prod

Retention scheduler that runs a 24 h cycle, first firing 5 min after start. Runs are recorded in audit_retention_runs. It is active.

What it does

Active

State

audit_retention_runs

Retention cycle that stamps retain_until on events and expires those not held. It runs on a schedule plus a manual route and works on platform_audit_events and request_trails, with role separation.

What it does

Active + manual route

State

platform_audit_events, request_trails

Safeguards

role-separated

Redis client factory that builds a high-availability-aware, self-healing client. It depends on deadline handling, and TLS and authentication are its safeguards.

Redis HA config that resolves a single, sentinel or cluster setup from the environment. Numeric env values are validated. It is active.

What it does

Active

Safeguards

validated numeric env

Redis connection config that builds auth and TLS settings and redacts them for display. It depends on fs, and URL redaction is the stated safeguard. It is active.

What it does

Active

Depends on

fs

Safeguards

URL redaction

Redis command deadline giving each command a timeout, plus a stall watchdog. It is active and fails closed on a partition.

What it does

Active

Safeguards

fail-closed on partition

Redis reconnect strategy offering both bounded and infinite retries, with a breaker cooldown between attempts. It is active.

What it does

Active

Redis health registry that maps each purpose to its health, so each Redis use can be checked separately. It is active.

What it does

Active

Redis persistence monitor with AOF and appendfsync diagnostics plus drift state. It uses CONFIG GET and protects replay-protection integrity. It is active at initialize, but the call site was not traced.

What it does

Active (initialize) — call site not traced

Depends on

CONFIG GET

Safeguards

replay-protection integrity

Caveat call site not traced

Nonce, anomaly and rate stores on Redis, organised by key prefixes. State is held in Redis, and the stores are fail-closed according to the header.

What it does

Active

State

Redis

Safeguards

fail-closed (header)

Redis pub/sub channels for revocation, organisation status and the control plane. They are active and carry these changes between running instances.

What it does

Active

Redis memory fallbacks that keep receipts in process memory when REDIS_URL is unset. They are active, and state is held in process memory.

What it does

Active

State

process memory

File stores holding keys, policy, org/tenant, rbac, signing identities, investigations and prq-journal. Writes are atomic and keys are encrypted with a KEK. It depends on fs.

What it does

Active

Depends on

fs

State

files

Safeguards

atomic writes, KEK encryption of keys

Investigations store, file only, active and kept under data/. It saves investigation records to files rather than to a database.

Dashboard aggregation that does a paged scan at boot, then applies live bus updates, with bounded arrays. State stays in memory and a per-tenant filter applies. It uses the audit-log and logger.

What it does

Active

Depends on

audit-log, logger

State

memory only

Safeguards

per-tenant filter

Dashboard health registry that reports readiness of the nonce, anomaly and rate stores. It is active and feeds the dashboard health view.

DR file backup with a component registry, sealed manifest, encryption and a window guard. It runs from CLI, CronJob or systemd, writes to a backup dir, and uses an HMAC seal and AES-256-CBC.

What it does

CLI/CronJob/systemd

State

backup dir

Safeguards

HMAC seal, AES-256-CBC

DR PG dump using pg_dump: a snapshot-consistent, encrypted custom-format dump. It runs from the CLI, depends on pg_dump and qodiqa_backup, writes to a backup dir and is gated by roles.

What it does

CLI

Depends on

pg_dump, qodiqa_backup

State

backup dir

Safeguards

role gates

DR PG dump as JSON rows: a portable row dump and restore, run from the CLI. It depends on pg and the table registry and requires an RLS-exempt role.

What it does

CLI

Depends on

pg, table-registry

Safeguards

RLS-exempt role required

Table registry that lists the expected tables, derived from migrations, so coverage can be checked. DR uses it.

What it does

Used by DR

DR restore in 3 phases that fails closed, restoring into a clean target from the CLI. The target must be chosen explicitly and must not be the origin of the backup.

What it does

CLI

Safeguards

explicit non-source target

Post-restore integrity steps from the CLI: ownership repair, chain-head restore, erasure replay, mirror-count rebuild and validate probes, run after a DR restore.

What it does

CLI

DR verify, cycle and RTO tooling: a non-destructive verify, a backup, restore and validate cycle, and an RTO harness. It runs from the CLI or CI.

What it does

CLI/CI

DR retention that rotates backup directories on a GFS schedule, run from the CLI, so older backups are kept or removed according to the grandfather-father-son pattern.

What it does

CLI

Backup command set: full, incremental, verify, restore and pitr-restore, with encryption on by default, an HMAC seal and an offsite hook. It depends on pg_dump, pg_restore and openssl, and cites DD-005.

WAL archive: an archive_command script that writes into the WAL dir, so PostgreSQL write-ahead log segments are copied to a location for later recovery.

Backup scheduling config: K8s CronJobs, systemd timers and compose files. It is config only, with digest-pinned images and a placeholder registry.

What it does

Config only

Safeguards

digest-pinned images; placeholder registry

Caveat Config only

KEK re-encryption tools for files and webhook secrets, run manually by an operator. State covers files and webhook_endpoints.

What it does

Manual

State

files / webhook_endpoints

Backup role provisioning that grants pg_read_all_data to qodiqa_backup. It is run manually, needs a superuser, and is owner-gated for LIVE; state is a cluster role.

What it does

Manual (owner-gated for LIVE)

Depends on

superuser

State

cluster role

Caveat Manual (owner-gated for LIVE)

Migration ledger document recording reserved migration numbers and rules. Its header lists the migrations as 001–083 and 096–099, which is out of date against the files on disk.

What it does

Doc

Safeguards

header says "001–083 and 096–099 exist" — stale vs disk

Caveat header says "001–083 and 096–099 exist" — stale vs disk

Role-management policy document stating that role DDL happens in migrations only, and listing the bootstrap exceptions. It is a document, not code.

What it does

Doc