// SPDX-License-Identifier: CC-BY-SA-4.0
= Contractiles A2ML v1 Specification
:toc:
:sectnums:

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

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

== 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

== Field Requirements

=== Mustfile

* Parameters section MUST include:
  - gateway_port
  - schema_version
* Each item in Checks MUST include:
  - description
  - run

=== 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

=== 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

=== Intentfile

Each required section MUST contain at least one bullet.

== 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`

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

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

== CLI

The A2ML tooling adds:

* `just contractiles-a2ml-validate`
* `just contractiles-a2ml-emit`
* `just contractiles-k9-validate`
* `just contractiles-a2ml-test`

=== Exit Codes

* `0` - Success
* `1` - Validation failure

=== Type Overrides

The validator and emitter support explicit types:

[source,bash]
----
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
----
