ModuLix building blocks

A useful ModuLix building block is more than a role or playbook. It combines a versioned content unit with the conditions required to run and verify it.

Building-block contract

Part	Required question	Public documentation can contain
Objective	What bounded outcome is intended?	Generic capability and success criteria
Content	Which immutable source version expresses the change?	Public repository and release link
Inputs	Which values influence behavior?	Names, types, safe examples, validation rules
Target scope	Which objects may change?	Generic target class and RFC-reserved examples
Runtime	Which controller, dependencies, and privileges are required?	Public compatibility contract
Preflight	What must be true before execution?	Non-sensitive checks and safe-stop criteria
Verification	How is observed state checked independently?	Generic read-only checks
Recovery	Who decides and what recovery class is available?	Decision model without credentials or targets
Evidence	What must be retained, for how long, and at what classification?	Evidence schema, not real environment records

Four layers of composition

1. Content layer: collections, roles, plugins, playbooks, and their immutable versions.
2. Input layer: inventory schema, non-secret variables, and references to secrets supplied through an approved runtime channel.
3. Execution layer: controller, execution environment, authorization, network boundary, and concurrency controls.
4. Assurance layer: preflight, tests, observation, approval, evidence, and recovery decisions.

Keeping the layers separate makes reviews clearer. A source change should not silently change an inventory; an inventory update should not silently replace the runtime; and a successful run should not silently become acceptance.

Example review statement

Apply a pinned public collection release to the customer-example test target represented by host01.example.com. Stop before execution if the target, content checksum, required privilege, or backup precondition differs from the approved record. Accept only after an independent state check.

This statement is deliberately not an executable rollout procedure. It records the boundary an environment-specific, authorized plan must fill in privately.

Public contract examples

Use the service-specific contracts for CoreDNS, DHCP, Forgejo, Keycloak, and Nexus Repository. They define review and assurance boundaries; they do not replace a versioned component runbook or an approved environment plan.

Use Blueprints to describe multi-block composition and Security to review trust boundaries.