## ADDED Requirements

### Requirement: SurrealDB v3 image policy

The `@suaveplan/testing-integration-surrealdb` plugin SHALL pin to `surrealdb/surrealdb:v3.0.4` (name + minor version). A follow-up operational change tracked at `docs/superpowers/specs/2026-04-25-test-suite-audit.md §5` will pin to `sha256:<digest>`; that pinning is **out of scope** for this change.

#### Scenario: Image tag pinned

- **WHEN** the fixture's container factory is invoked without injection
- **THEN** the resulting `GenericContainer` is constructed with image `surrealdb/surrealdb:v3.0.4`

### Requirement: Env-bridge contract

The plugin SHALL declare and forward the following environment variables: `SURREALDB_URL`, `SURREALDB_USERNAME`, `SURREALDB_PASSWORD`. When all three are set on the parent process at construction time, the fixture MUST enter env-bridge passthrough mode and skip container start.

#### Scenario: env() returns the full set

- **WHEN** the fixture has started in container mode
- **THEN** `fixture.env()` returns a record whose keys are exactly `SURREALDB_URL`, `SURREALDB_USERNAME`, `SURREALDB_PASSWORD`

#### Scenario: Env-bridge passthrough

- **WHEN** all three env vars are set on `process.env` at construction
- **THEN** `start()` does not invoke the container factory AND `stop()` is a no-op

### Requirement: Healthcheck contract

`isHealthy()` SHALL issue an HTTP `GET /health` request to the SurrealDB endpoint. A 2xx response means healthy. Connection errors AND non-2xx responses MUST resolve to `false`, never throw.

#### Scenario: 2xx is healthy

- **WHEN** `/health` returns 200
- **THEN** `isHealthy()` resolves `true`

#### Scenario: Connection refused does not throw

- **WHEN** the endpoint refuses the connection
- **THEN** `isHealthy()` resolves `false` and does not throw

### Requirement: Random password per run

In container mode the fixture SHALL generate a fresh random password per `start()` call. The password MUST be at least 32 bytes of entropy, rendered as URL-safe base64 or hex.

#### Scenario: Two independent fixtures generate different passwords

- **WHEN** two fixtures start in the same process
- **THEN** their `config.password` values differ

### Requirement: Injectable factories

The fixture constructor SHALL accept optional `containerFactory` and `fetch` parameters. The defaults invoke `testcontainers` and the global `fetch`. Test-of-test code MAY substitute these to drive deterministic behaviour.

#### Scenario: Injected fetch drives health probe

- **WHEN** `fetch` is replaced with a stub that always returns a 503
- **THEN** `isHealthy()` resolves `false`

### Requirement: Error-code prefix

Errors thrown from the plugin SHALL carry codes matching `^INTEGRATION\.SURREALDB\.[A-Z_]+$` (e.g. `INTEGRATION.SURREALDB.START_FAILED`, `INTEGRATION.SURREALDB.STOP_FAILED`). Cross-cutting codes (`INTEGRATION.HEALTH_TIMEOUT`, `INTEGRATION.ABORTED`) are inherited from `@suaveplan/testing-integration`.

#### Scenario: Coded error on start failure

- **WHEN** the container fails to bind a port
- **THEN** `start()` rejects with a structured error whose `code === "INTEGRATION.SURREALDB.START_FAILED"`