## ADDED Requirements

### Requirement: PostgreSQL 16 image policy

The `@suaveplan/testing-integration-postgres` plugin SHALL pin to `postgres:16` (name + major version). A follow-up operational change tracked at `docs/superpowers/specs/2026-04-25-test-suite-audit.md §5` will pin to `sha256:<digest>`.

#### Scenario: Image tag pinned

- **WHEN** the container factory is invoked without injection
- **THEN** the resulting container uses image `postgres:16`

### Requirement: Env-bridge contract

The plugin SHALL declare and forward the environment variable `POSTGRES_URL`. When `POSTGRES_URL` is set on the parent process at construction time, the fixture MUST enter env-bridge passthrough mode.

#### Scenario: env() returns POSTGRES_URL

- **WHEN** the fixture has started
- **THEN** `fixture.env()` returns `{ POSTGRES_URL: "postgres://…" }`

#### Scenario: Passthrough mode skips container

- **WHEN** `POSTGRES_URL` is set at construction
- **THEN** `start()` does not invoke the container factory AND `stop()` is a no-op

### Requirement: Configurable database / user / password

The fixture options SHALL accept `database?: string; user?: string; password?: string`. Defaults MUST be `database = "test"`, `user = "test"`, `password` randomly generated per run with at least 32 bytes of entropy. The container's `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` env vars MUST be set from these values.

#### Scenario: Defaults applied

- **WHEN** the fixture is constructed without options
- **THEN** `config.database === "test"` AND `config.user === "test"` AND `config.password` is a non-empty random string

### Requirement: Healthcheck contract — pg_isready

`isHealthy()` SHALL execute `pg_isready -U <user> -d <database>` **inside** the Postgres container via testcontainers' `exec` API. The fixture constructor SHALL accept an optional `execFn` that defaults to the container's exec method and MAY be substituted for tests. A 0 exit code means healthy; any other exit code resolves to `false`.

#### Scenario: pg_isready exit 0 is healthy

- **WHEN** `pg_isready` exits with code 0
- **THEN** `isHealthy()` resolves `true`

#### Scenario: Non-zero exit is unhealthy without throwing

- **WHEN** `pg_isready` exits with code 2
- **THEN** `isHealthy()` resolves `false` and does not throw

### Requirement: Error-code prefix

Errors thrown from the plugin SHALL carry codes matching `^INTEGRATION\.POSTGRES\.[A-Z_]+$` (e.g. `INTEGRATION.POSTGRES.START_FAILED`, `INTEGRATION.POSTGRES.EXEC_FAILED`).

#### Scenario: Coded exec failure

- **WHEN** the injected `execFn` throws
- **THEN** `isHealthy()` resolves `false` AND the OTel error counter records `code = "INTEGRATION.POSTGRES.EXEC_FAILED"`