# Contracts

A consumer declares intent in a **contract** — a small YAML file that
references the central deploy pipeline, names a module, selects an
environment, and supplies module-specific inputs. The platform validates,
resolves, and deploys it.

## The contract file

A consumer repo keeps its contract at `.acdl/contract.yaml`. A minimal
example (the `static-assets` module):

```yaml
uses: acdl/pipelines/deploy.yaml@v1.6
module: static-assets
environment: dev
inputs:
  bucket_name: my-static-site-assets
  region: us-east-1
```

A `microservice` example:

```yaml
uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
  image: my-registry/my-microservice:latest
  port: 8080
  env:
    LOG_LEVEL: info
```

## Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uses` | string | yes | Reference to the central deploy pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/deploy.yaml@v1.6`). Bare or `@main` references are discouraged. See [Versioning](../pipeline/versioning). |
| `module` | string | yes | Module name from the registry — any primitive or module (e.g. `static-assets`, `microservice`, `s3`). See the [module catalog](../modules/). |
| `environment` | string | yes | The platform-managed environment to deploy to (e.g. `dev`). See [Environments](../environments/). |
| `inputs` | object | yes | Module-specific inputs (see the module's README). |

## Validation

The contract is validated against
[`schemas/contract.schema.json`](https://github.com/acdl/acdl/blob/main/schemas/contract.schema.json).
An invalid contract (missing field, unknown module, wrong type) fails at the
validate-contract stage with a clear error.

## Sample contracts

Two reference examples exist in `contracts/`:

- [`contracts/static-assets.yaml`](https://github.com/acdl/acdl/blob/main/contracts/static-assets.yaml)
  — the `static-assets` module (uses `@v1.6`).
- [`contracts/microservice.yaml`](https://github.com/acdl/acdl/blob/main/contracts/microservice.yaml)
  — the `microservice` module (uses `@v1.6`).

Additionally, every module has a `modules/<name>/examples/` directory with
validated example contracts (`simple.yaml` + `complex.yaml` + variation
files). See the [module catalog](../modules/) for the full list.

## Multiple contracts

A consumer repo may contain more than one contract (e.g. one per service or
one per environment). Each contract is a separate deployment; each is
referenced by a CI definition in `.github/workflows/` that invokes the
central reusable workflow with the contract path. See the
[Consumer Guide](../consumer-guide/) for the multi-contract pattern.