Skip to content

CONTRACTILES-A2ML-V1.adoc

Latest commit

 

History

History
114 lines (79 loc) · 2.71 KB

CONTRACTILES-A2ML-V1.adoc

File metadata and controls

114 lines (79 loc) · 2.71 KB

Contractiles A2ML v1 Specification

Table of Contents

This document defines the v1 A2ML surface for Contractiles and the JSON emission format.

1. Scope

The Contractiles A2ML format models four files:

  • Mustfile (state contract)

  • Trustfile (cryptographic verification)

  • Dustfile (recovery and rollback)

  • Intentfile (future intent)

All files are A2ML documents with required sections and fixed fields.

2. Required Sections

Each file must include the following sections:

  • Mustfile: Parameters, Checks

  • Trustfile: Inputs, Verifications

  • Dustfile: Logs, Policy, Gateway, Dust-Events

  • Intentfile: Trust-Engine, Control-Plane, Pipeline, Introspection

3. Field Requirements

3.1. Mustfile

  • Parameters section MUST include:

    • gateway_port

    • schema_version

  • Each item in Checks MUST include:

    • description

    • run

3.2. Trustfile

  • Inputs section MUST include:

    • policy_path

    • policy_hash_path

    • schema_path

    • schema_sig_path

    • schema_pub_path

    • driver_paths

    • migrations_path

    • migrations_sig_path

    • migrations_pub_path

  • Each item in Verifications MUST include:

    • description

    • command

3.3. Dustfile

  • Logs entries MUST include: path, reversible, handler

  • Policy entries MUST include: path, rollback

  • Gateway entries MUST include: event, undo

  • Dust-Events entries MUST include: source, transform

3.4. Intentfile

Each required section MUST contain at least one bullet.

4. JSON Emission

The emitter outputs JSON with a stable schema and a spec version field:

  • type: mustfile | trustfile | dustfile | intentfile

  • spec_version: 1.0.0

The remaining fields match the A2ML structure:

  • Mustfile → parameters, checks

  • Trustfile → inputs, verifications

  • Dustfile → sections

  • Intentfile → future

5. Validation Pipeline

A v1 validator MUST:

  1. Run a2ml validate on each file for A2ML structural correctness.

  2. Enforce required sections and fields as specified above.

6. Profile Name

This spec can be referenced as the contractiles-v1 profile. Profiles only increase validation strictness and MUST NOT introduce execution or side effects.

7. CLI

The A2ML tooling adds:

  • just contractiles-a2ml-validate

  • just contractiles-a2ml-emit

  • just contractiles-k9-validate

  • just contractiles-a2ml-test

7.1. Exit Codes

  • 0 - Success

  • 1 - Validation failure

7.2. Type Overrides

The validator and emitter support explicit types:

deno run --allow-read --allow-write scripts/contractiles-a2ml-tool.js validate --type mustfile tests/contractiles/fixtures/invalid-mustfile.a2ml
deno run --allow-read --allow-write scripts/contractiles-a2ml-tool.js emit --type trustfile contractiles/trust/Trustfile.a2ml /tmp/trustfile.json