Contractiles

Table of Contents

• 1. What It Does
• 2. Why It Exists
• 3. Where It Is Going
• 4. Quick Start
• 5. Required Tools
• 6. The Five Files
• 7. Layout
• 8. Usage Model
• 9. Status

Contractiles is a file-first contract system for operating, verifying, recovering, and evolving gateways. It centers on five artifacts you can copy into any repo to make runtime behavior and change control explicit and testable.

Version: v1.0.0

1. What It Does

• Defines a minimal operational surface (Justfile).

• Makes invariants explicit (Mustfile).

• Verifies integrity and provenance (Trustfile.hs).

• Encodes recovery and rollback (Dustfile).

• Records future intent (Intentfile).

2. Why It Exists

Operational failures usually come from missing or implicit contracts. Contractiles makes those contracts explicit, portable, and reviewable.

3. Where It Is Going

• Wire real validators and signatures into the trust spine.

• Provide language/runtime templates for gateways.

• Offer profile presets for common environments.

4. Quick Start

just setup
just run-gateway
just validate-policy
just compile-nickel
just gen-mustfile

5. Required Tools

• just

• rg (ripgrep)

• jq

• yq

• nickel

• openssl

• kyber-verify (or set KYBER_VERIFY_CMD)

6. The Five Files

• Justfile (repo root) - operational commands for day-to-day actions.

• Mustfile (contractiles/must/Mustfile) - the state contract: what must be true.

• Trustfile.hs (contractiles/trust/Trustfile.hs) - cryptographic and provenance checks.

• Dustfile (contractiles/dust/Dustfile) - recovery and rollback semantics.

• Intentfile (contractiles/lust/Intentfile) - declared future intent and roadmap direction.

7. Layout

contractiles/
├── Justfile
├── Mustfile
├── README.adoc
├── ROADMAP.adoc
├── contractiles/
│   ├── must/Mustfile
│   ├── trust/Trustfile.hs
│   ├── dust/Dustfile
│   └── lust/Intentfile
└── docs/
    └── CITATIONS.adoc

8. Usage Model

1. Keep the Justfile commands as the operational surface.

2. Treat Mustfile as the authoritative contract for validation.

3. Run Trustfile.hs in CI/CD or a controlled verification step.

4. Use Dustfile for deterministic recovery and rollback guidance.

5. Track future shape in Intentfile and keep it current.

9. Status

This repository is v0.0.1 and is focused on structure, contract vocabulary, and composable file conventions. The commands and verification scripts use common CLI tools and can be adjusted for your environment.