# Environments

A consumer does **not** provide an AWS account, a VPC, a subnet, an S3 state
bucket, or a runner key. 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).
- A state backend (an S3 bucket + DynamoDB lock table for infrastructure
  state).
- An IAM role surfaced to the consumer via attribute-based authorization
  (ABAC), scoped to the consumer's repository identity and resource tags.

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

```yaml
environment: dev
```

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

## First-run onboarding

When a consumer pipeline runs for the first time and **no environment is
defined** for the consumer's repo, the platform detects this and emits a
user-friendly onboarding prompt instead of failing opaquely. The prompt
tells the consumer:

1. That no environment is bound to their repo yet.
2. What the platform will provision on their behalf (account/network/state/
   role).
3. The expected turnaround for the platform team to grant the environment.
4. How to request an environment (contact the platform team).

The pipeline then exits without attempting a deployment. Once the platform
team binds an environment to the repo, the next pipeline run proceeds
normally.

## Autonomy by environment

| Environment | Autonomy | Gate |
|-------------|----------|------|
| dev | Full autonomy | Confidence ≥ 0.50 |
| qa | Held for attestation | QA attestation + confidence ≥ 0.75 |
| prod | Held for attestation | SRE attestation + confidence ≥ 0.90 |
| dr | Held for attestation | SRE attestation + confidence ≥ 0.95 + dr-drill |

`dev` is the only autonomous environment. Higher environments require human
attestation (a platform-runner deployment approval) and a higher confidence
threshold. Staging does not exist.

## Onboarding scaffold (current state)

The platform repo ships a minimal onboarding scaffold:

- [`core/environments/`](https://github.com/acdl/acdl/blob/main/core/environments/)
  — environment definitions (a sample `dev.json`).
- `core/environment_check.py` — checks whether an environment is defined for
  a given contract's repo + environment name; prints the friendly onboarding
  prompt when none is defined.
- `scripts/run_platform.sh` calls the check before contract validation.

The scaffold is minimal: the actual provisioning of a new environment is a
platform-team action today. Self-service environment provisioning is on the
[roadmap](../).