Version v0.1 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Contracts

Versioned schemas at the boundary between templates and consumers.

All schemas use JSON Schema draft 2020-12 and reject unknown fields.

Contract	Source	Purpose
`InfrastructureTemplate/v1alpha1`	`schemas/template-manifest.v1alpha1.json`	Template engines, paths, capabilities, and invariants
`TemplateInput/v1alpha1`	`schemas/template-input.v1alpha1.json`	Non-secret operator intent and credential references
`InfrastructureOutput/v1alpha1`	`schemas/template-output.v1alpha1.json`	Stable, non-secret handoff to downstream systems
`ainfra.plan/v1alpha1`	`schemas/plan-record.v1alpha1.json`	Exact reviewed-plan binding for lifecycle authorization
`ainfra.plan/v1alpha2`	`schemas/plan-record.v1alpha2.json`	Project-bound lifecycle authorization
`ainfra.run/v1alpha2`	`schemas/run-record.v1alpha2.json`	Immutable run identity
`ainfra.run-event/v1alpha1`	`schemas/run-event.v1alpha1.json`	Append-only lifecycle evidence
`ainfra.status/v1alpha1`	`schemas/status.v1alpha1.json`	Sanitized local status output
`ainfra.legacy-inspection/v1alpha1`	`schemas/legacy-inspection.v1alpha1.json`	Read-only legacy evidence report

Compatibility

The apiVersion is locked through the v1 series. An incompatible v2 requires a full migration rather than silent coercion.

Validation behavior

Unsupported apiVersion and kind values fail.
Unknown properties fail.
Secret-shaped standard outputs fail.
Undeclared capabilities fail.
Template paths cannot escape the template directory.
Secret references describe a source but do not contain the secret.

Run:

ainfra validate DOCUMENT

Positive and negative fixtures live under tests/fixtures/contracts/.

Reviewed-plan records

A reviewed-plan record binds the intended operation to the selected template and version, environment identity, canonical input path and bytes, template tree, remote backend configuration, and generated OpenTofu plan bytes. Apply and destroy must reject any changed binding before starting an infrastructure process.

Explicit compatibility mode writes ainfra.plan/v1alpha1 and reads normal records created by the Python implementation. Project mode writes ainfra.plan/v1alpha2, adding the canonical project root and exact project configuration and lockfile paths and digests. The two modes cannot cross-authorize.

Approval identifiers are exactly 20 lowercase hexadecimal characters. Plan files must resolve beneath their corresponding .ainfra/runs/<PLAN_ID>/ directory.

Run records and events

run.json repeats only non-secret immutable plan identity. Lifecycle evidence is append-only and ordered by a contiguous sequence number. Configuration, check-mode convergence verification, and post-destroy zero-resource verification are distinct stages; timestamps are informational and never override event order. Failed events contain only a stable AINFRA-E* code and a sanitized recovery category.

The older ainfra.run/v1alpha1 apply/destroy marker remains legacy success evidence. It is not treated as a durable event history and is never upgraded silently.