# Environments

A consumer does **not** provide an AWS account, a VPC, a subnet, or an S3
state bucket. The platform manages environments.

## What an environment is

A named environment is a **platform-owned** bundle of:

- An **AWS account** (or a scoped partition of one).
- A **network** (VPC + subnets / AZs).
- A **state backend** (an S3 bucket + DynamoDB lock table for Terraform
  state).

A consumer selects an environment **by name** in their contract:

```yaml
environment: dev
```

The platform resolves the name to the underlying account/network/state
backend at run time. The consumer never sees the raw credentials.

## Environment definition shape (D-018)

Each environment is a JSON file in `core/environments/`. The field set is
reduced from the reference — the IAM role, autonomy, and confidence
threshold fields are out of scope for v1.0.

`core/environments/dev.json` (the sample):

```json
{
  "name": "dev",
  "description": "Sample dev environment for offline/local testing. account_id placeholder (000000000000) for offline mode.",
  "account_id": "000000000000",
  "region": "us-east-1",
  "state_backend": {
    "bucket": "nova-tfstate-dev-us-east-1",
    "lock_table": "nova-tfstate-locks"
  },
  "network": {
    "vpc_cidr": "10.0.0.0/16",
    "azs": ["us-east-1a", "us-east-1b"]
  }
}
```

### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | yes | The environment name (`dev`/`qa`/`prod`/`dr`). |
| `description` | string | no | Human-readable description. |
| `account_id` | string | yes | The AWS account id (placeholder `000000000000` for offline dev). |
| `region` | string | yes | The AWS region. |
| `state_backend.bucket` | string | yes | The S3 state bucket name. |
| `state_backend.lock_table` | string | yes | The DynamoDB lock table name (`nova-tfstate-locks` per D-022). |
| `network.vpc_cidr` | string | yes | The VPC CIDR block. |
| `network.azs` | array | yes | The availability zones. |

### Dropped from the reference (D-018)

- `runner_role_arn` — identity/authorization is out of scope.
- `autonomy` — human-in-the-loop gates are out of scope.
- `confidence_threshold` — the confidence signal is out of scope.

## State backend (D-022)

The Terraform state backend uses a dedicated DynamoDB lock table named
`nova-tfstate-locks` (NOT `nova-outbox` — the audit outbox is out of scope
for v1.0). The S3 state bucket is named `nova-tfstate-<account>-<region>`
with versioning enabled. See
[`terraform/bootstrap/README.md`](../../terraform/bootstrap/README.md) for
the bootstrap runbook that creates both.

## Autonomy by environment

| Environment | Autonomy | Operator action |
|-------------|----------|-----------------|
| dev | Fully autonomous | None — `terraform apply -auto-approve` runs automatically. |
| qa | Manual | An operator runs `run_platform.sh` against the `qa` contract. |
| prod | Manual | An operator runs `run_platform.sh` against the `prod` contract. |
| dr | Manual | An operator runs `run_platform.sh` against the `dr` contract. |

`dev` is the only autonomous environment. Higher environments require a
human operator to invoke the pipeline against the environment's contract
variant. There are no automated gates or attestation steps — those are out
of scope for v1.0. Staging does not exist.

## Onboarding scaffold (current state)

The platform repo ships a minimal onboarding scaffold:

- [`core/environments/`](../../core/environments/) — environment definitions
  (a sample `dev.json`).
- `core/environment_check.py` — checks whether an environment is defined
  for a given contract's environment name; raises `EnvironmentNotFoundError`
  when none is defined (D-019).
- `scripts/run_platform.sh` calls the check before contract validation.

The scaffold is minimal: provisioning a new environment is a platform-team
action today (bootstrap the state backend + network). Self-service
environment provisioning is a future milestone.