hyperpolymath/contractiles

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github		.github
.machine_readable		.machine_readable
contractiles		contractiles
docs		docs
dust		dust
examples		examples
ffi/zig		ffi/zig
k9		k9
lust		lust
must		must
mustfile		mustfile
runners/must		runners/must
scripts		scripts
src/abi		src/abi
trust		trust
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.nojekyll		.nojekyll
ABI-FFI-README.md		ABI-FFI-README.md
AI.a2ml		AI.a2ml
AI.djot		AI.djot
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Justfile		Justfile
LICENSE		LICENSE
MAINTAINERS.adoc		MAINTAINERS.adoc
Mustfile		Mustfile
README.adoc		README.adoc
ROADMAP.adoc		ROADMAP.adoc
RSR_OUTLINE.adoc		RSR_OUTLINE.adoc
SECURITY.md		SECURITY.md
codemeta.json		codemeta.json

Repository files navigation

Contractiles

Table of Contents

1. Format Policy (A2ML Canonical)
2. What It Does
3. Why It Exists
4. Where It Is Going
5. Quick Start
6. Required Tools
7. The Five Files
8. Layout
9. Usage Model
10. 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. Format Policy (A2ML Canonical)

Canonical contract format is now A2ML:
- contractiles/must/Mustfile.a2ml
- contractiles/trust/Trustfile.a2ml
- contractiles/dust/Dustfile.a2ml
- contractiles/lust/Intentfile.a2ml
Legacy mixed-format files (Mustfile, Trustfile.hs, Dustfile, Intentfile) are deprecated and retained only as compatibility shims.
New repositories should copy and edit the .a2ml files as the source of truth.

2. What It Does

Defines a minimal operational surface (Justfile).
Makes invariants explicit (Mustfile.a2ml).
Verifies integrity and provenance (Trustfile.a2ml).
Encodes recovery and rollback (Dustfile.a2ml).
Records future intent (Intentfile.a2ml).

3. Why It Exists

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

4. 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.

5. Quick Start

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

6. Required Tools

just
rg (ripgrep)
jq
yq
nickel
openssl
kyber-verify (or set KYBER_VERIFY_CMD)

7. The Five Files

Justfile (repo root) - operational commands for day-to-day actions.
Mustfile.a2ml (contractiles/must/Mustfile.a2ml) - canonical state contract.
Trustfile.a2ml (contractiles/trust/Trustfile.a2ml) - canonical integrity/provenance contract.
Dustfile.a2ml (contractiles/dust/Dustfile.a2ml) - canonical rollback/recovery contract.
Intentfile.a2ml (contractiles/lust/Intentfile.a2ml) - canonical intent/roadmap contract.
Legacy mirrors remain present but are deprecated.

8. Layout

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

9. Usage Model

Keep the Justfile commands as the operational surface.
Treat *.a2ml files as the authoritative contracts.
Use legacy non-A2ML files only for temporary compatibility.
Run trust verification in CI/CD from the A2ML contract definitions.
Track future shape in Intentfile.a2ml and keep it current.

10. Status

This repository is in an A2ML-canonical transition phase: .a2ml contract files are authoritative, and legacy mixed-format files remain only for compatibility while downstream tooling migrates.