Module contract template

Status: Draft
Version: 0.1

1. Identity

• module_id:
• epoch:
• lifecycle: deploy | test | destroy | status
• maturity: planned | candidate | supported | deprecated

2. Purpose

• outcome:
• non-goals:

3. Inputs

3.1 Required inputs

List required inputs with types and constraints.

3.2 Optional inputs

List optional inputs with defaults and constraints.

3.3 Input resolution

Declare merge and precedence rules, including any module overlays.

4. Dependencies

4.1 Init targets

List required readiness markers (for example: proxmox, terraform-cloud).

4.2 Drivers

List required drivers and profiles.

4.3 External dependencies

List required external services and access conditions.

5. Outputs

5.1 Produced outputs

• exported values (machine-readable)
• files written (paths, formats, permissions)

5.2 Evidence

Minimum evidence set:

• run metadata (run_id, status, module_id)
• resolved inputs (redacted)
• driver invocations (argv, rc, duration)
• output inventory (non-secret paths)

6. Failure semantics

• stable exit codes used by the module runner
• remediation requirements for common failures

7. Security

• secrets handling rules
• redaction rules
• filesystem permission requirements

8. Compatibility

• supported versions and constraints
• upgrade notes

9. Change control

Breaking changes require an updated module contract and compatibility notes.