nova-platform/docs/contracts/index.md

Contracts

A consumer declares intent in a contract — a small YAML file that names infrastructure (one or more modules), selects an environment, and supplies module-specific inputs. The platform validates, resolves, and deploys it.

The contract file

A minimal example (the static-assets module):

id: stsi
name: Static Assets Site
environment: dev
infrastructure:
  - module: static-assets
    version: "1.0.0"
    inputs:
      bucket_name: "${env.environment}-${contract.id}-assets"
      index_document: index.html

A microservice example:

id: msvc
name: Microservice
environment: dev
infrastructure:
  - module: microservice
    version: "1.0.0"
    inputs:
      service_name: "${env.environment}-${contract.id}-svc"
      desired_count: 2

Array-based infrastructure (D-015)

The infrastructure field is an array of module entries, not a map keyed by module name. This is a locked deviation from the Nova reference (D-015). Each entry is an object with module, version (optional), and inputs.

One entry = single-module deploy. N entries = multi-module manifest deployed in one pipeline run:

id: app
name: Pricing Service API
environment: dev
infrastructure:
  - module: microservice
    version: "1.0.0"
    inputs: { ... }
  - module: static-assets
    version: "1.0.0"
    inputs: { ... }

All modules deploy to the same environment in one pipeline run.

Fields

Field	Type	Required	Description
id	string	yes	Short operational acronym (^[a-z][a-z0-9-]{2,5}$, 3-6 chars). Becomes the stack name used for the Terraform state key and resource naming prefix. Stable across deploys and environment promotions.
name	string	yes	Full human-readable stack name (min 3 chars).
environment	string	yes	The platform-managed environment to deploy to (dev/qa/prod/dr). See Environments.
infrastructure	array	yes	Array of modules to deploy (D-015). minItems: 1.

Infrastructure item fields

Field	Type	Required	Description
module	string	yes	Module name from modules/registry.json (^[a-z][a-z0-9-]*$).
version	string	no	Semver pin (^\d+\.\d+\.\d+$). Omitted = latest non-deprecated version from the registry.
inputs	object	yes	Module-specific inputs (see the module's README / interface.json). No aws_* keys — the contract is engine-agnostic.

Validation

The contract is validated against schemas/contract.schema.json. An invalid contract (missing field, unknown module, wrong type) fails at the validate-contract stage with a clear error.

Interpolation tokens (D-016)

The resolver expands ${env.*} and ${contract.*} tokens after the environment is loaded. Unknown tokens raise ValueError (fail loud). Expansion is recursive (nested map/list values expand too).

Token	Resolves to	Example
${env.name}	the environment name	dev
${env.region}	the environment's AWS region	us-east-1
${env.account_id}	the environment's AWS account id	000000000000
${env.state_backend.bucket}	the environment's state bucket	nova-tfstate-dev-us-east-1
${env.state_backend.lock_table}	the environment's lock table	nova-tfstate-locks
${env.network.vpc_cidr}	the environment's VPC CIDR	10.0.0.0/16
${env.network.azs}	the environment's availability zones	["us-east-1a","us-east-1b"]
${contract.id}	the contract's operational acronym	stsi
${contract.name}	the contract's name field	Static Assets Site
${contract.environment}	the contract's environment field	dev

Sample contracts

Two reference examples exist in contracts/:

• contracts/static-assets.yml — the static-assets module (s3 + cloudfront + kms-key, D-038).
• contracts/microservice.yml — the microservice module (vpc + ecs-cluster + ecs-service + iam-role + ecr + alb, D-038).

Additionally, every module has a modules/<name>/examples/ directory with validated example contracts. See the module catalog for the full list.

Per-environment variants (D-033)

Each sample contract has per-environment variants that differ only in the environment field — all other fields are identical. Interpolation resolves environment-specific values at resolver time.

File	Environment
contracts/static-assets.yml	dev (default)
contracts/static-assets.dev.yml	dev
contracts/static-assets.qa.yml	qa
contracts/static-assets.prod.yml	prod
contracts/static-assets.dr.yml	dr
contracts/microservice.yml	dev (default)
contracts/microservice.dev.yml	dev
contracts/microservice.qa.yml	qa
contracts/microservice.prod.yml	prod
contracts/microservice.dr.yml	dr

Promotion = running the pipeline against the matching variant. See the Consumer Guide for the end-to-end flow.