Specification / Draft v0.2
The AAES evidence export format
This draft describes aaes.export/v2, the format of the public sample and a format the public aaesverify v0.2.0 and v0.3.0 releases read. Current AAES Govern deployments write aaes.export/v3, which aaesverify v0.3.0 reads and this draft does not describe. v0.3.0 also reads aaes.export/v4 under the keying rules in its base specification. Start with the current v3 verification specification and its base specification. This page retains the historical v2 format and verification limits. A complete independent reader-conformance assessment remains future work.
This page describes AAES Govern’s controls. AAES Operate has private-work permissions, operational reviews and recorded-spend limits; it does not include Govern. About AAES Govern
Status and change policy
For current exports, use SPEC-V3.md at the v0.3.0 release, the v3 JSON Schema and current verification instructions. The v3 document defines the changes from its version-pinned v2 base.
The public Apache-2.0 aaesverify v0.2.0 release, and the later v0.3.0 release that also reads v3 and v4, provide an offline reference reader, exact preimage vectors and a versioned technical specification. Report any disagreement between the schemas, specification, vectors and reader through the public repository.
Status: draft v0.2 describes the aaes.export/v2 format. It does not describe aaes.export/v3, which current AAES Govern deployments write, or aaes.export/v4. The public sample is produced by demonstration tooling; no operational export from a client deployment exists yet.
Reviewers receive an export, a separately trusted signing public key, and any companion files listed in the evidence-pack manifest. The export holds the recorded entries and signatures. Optional timestamps and witnesses can corroborate a signed commitment when checked against trust material you choose.
| Identifier | What it names |
|---|---|
| Draft v0.2 | This web document revision. |
aaes.export/v2 | The export format this draft describes, read by aaesverify v0.2.0 and v0.3.0. Amounts use integer minor units, such as cents. |
aaes.records/v1 | A companion records file (sidecar) for checking stored-record fields against export commitments. |
aaes.evidence-pack/1 | The manifest identifying the files, scope, and exclusions in a review package. |
| Verifier release number | The software version, separate from the document and file-format identifiers. |
Change policy: each export schema identifier has a closed set of line types and fields. This draft does not promise that existing readers will accept new fields or new line types. Changes to the implemented export structure, field semantics, canonicalization, or hashing require a new export schema identifier. Corrections that bring this draft prose or JSON Schema into agreement with already-implemented bytes are recorded separately; earlier draft schemas may reject those bytes. Separate pack artifacts, such as the aaes.records/v1 sidecar, carry their own identifiers and do not change the export format. Editorial corrections are recorded in section 9.
Feedback: send review comments through the contact page.
1. The export file
An export is a UTF-8 JSON Lines file, one JSON object per line, maximum 4 MiB per line. Every line carries a type discriminator with one of three values: header, entry, or anchor. Exactly one header exists and it is the first line. A reader must reject a file with a missing, duplicate, or late header, a missing discriminator, or an unknown line type.
| Header field | Type | Meaning |
|---|---|---|
type | string | Required; always header. |
schema | string | aaes.export/v2 for the format described here; current AAES Govern writers emit aaes.export/v3. The public aaesverify v0.2.0 verifier accepts only aaes.export/v2; aaesverify v0.3.0 also accepts aaes.export/v3 and aaes.export/v4. Any other value fails with an unsupported-schema error. |
log_id | string | Identity of the log this export covers. Distinct from the log_id inside the signed head (section 4): the two have different naming conventions and need not be textually equal. |
tenant_id | string | The tenant this export covers. |
exported_at | RFC 3339 timestamp | When the export was written. |
entry_count | integer | Number of entry lines in the file. |
head | object | The signed tree head (section 4) at export time. |
public_key | string | The Ed25519 public key for head verification. The CLI can use the embedded key for an internal-consistency check. Supply --pubkey from a separately authenticated channel to establish deployment signer provenance; a mismatch with the embedded key fails closed. |
signing_key_id | string | Identifies the key that signed the head (for example ed25519-2d7f4034617bfe2e). An identifier does not establish trust. |
signature_algorithm | string | Signature algorithm for the head (currently ed25519). |
pre_anchor | boolean, optional | Declares an export written before the first anchor interval. An anchorless export requires this flag. Current writers also sign head.pre_anchor when the signing key is available. If only the unsigned header flag is present, verification requires an explicit --allow-pre-anchor opt-in. A signed head flag without the matching header flag is refused. |
2. Entries, the preimage, and the leaf
Each entry represents one journaled decision and has 14 required fields. amount_minor, amount_currency, and tombstone are optional. The preimage contains tenant_id, sequence, record_hash, intent_id, actor_id, capability, tier, allowed, grant_id, amount_minor, amount_currency, occurred_at, and linked_at, plus tombstone when present. It excludes type, chain_hash, and leaf. The chain hash and leaf are the exporter's claims, which a verifier recomputes and cross-checks rather than trusts.
| Entry field | Type | Meaning |
|---|---|---|
type | string | Required; always entry; excluded from the preimage. |
tenant_id | string | Tenant the decision belongs to. Required on every entry. |
sequence | integer | Position in the log. Strictly increasing; gaps are legal only when covered by a tombstone (below). |
record_hash | string (hex) | Hash of the sealed journal record this entry projects. |
intent_id | string | Identifier of the evaluated request. |
actor_id | string | The registered agent or human identity that acted. |
capability | string | Capability identifier acted upon. |
tier | integer | Risk tier assigned to the capability. |
allowed | boolean | The authorization decision: permit or refusal. Refusals are first-class entries. |
grant_id | string | Identifier of the grant where one was issued; empty when no grant was issued. A grant is authorization material, not proof of execution. |
amount_minor | integer | Estimated cost committed at the admission decision, in integer minor units of amount_currency; omitted when no cost was declared. This is estimated-cost admission accounting, not a settled charge. |
amount_currency | string | ISO 4217 currency of amount_minor; omitted when no cost was declared. |
occurred_at | RFC 3339 timestamp | When the decision occurred. |
linked_at | RFC 3339 timestamp | When the entry was linked into the chain. |
tombstone | object, optional | Records a retention removal. Required tombstone fields: from_sequence, to_sequence, reason, authorised_by, and removed_at; optional: policy_id, record_count, and receipt_count. The tombstone is part of the preimage, so the head signature covers it; the gap it names is the only thing that makes a missing sequence range legal. authorised_by is an attribution field; a recorded value is not proof the deletion was authorized. |
chain_hash | string (hex) | Claimed chain value (section 3). |
leaf | string (hex) | Claimed leaf value: SHA-256, hex-encoded, of the canonical preimage. |
Canonicalization. The preimage is serialized as canonical JSON: object keys sorted, integers emitted exactly, and every JSON number spelling normalized with exact decimal mantissa and exponent arithmetic, so 9007199254740993, 9007199254740993.0, and 9007199254740993e0 are byte-identical while values outside the IEEE-754 53-bit range stay distinct. Non-finite floats are rejected. Independent implementations must produce identical canonical bytes for the same value. The tagged technical specification, section 2, defines the byte encoding, including Go-compatible string escaping, UTF-8 key order, exact decimal normalization, time and byte-slice encoding. Use its reference vectors for independent implementations; a separately written reader and independent conformance assessment remain future work.
3. The hash chain
Entries link genesis to head in sequence order. The chain value of an entry is the SHA-256 hex of the concatenation of: the previous entry's chain hash as hexadecimal text (or the ASCII domain separator aaes/genesis for the first entry), one zero byte (0x00), and the entry's canonical preimage bytes. A verifier walks the full export, recomputing each chain value and leaf, and reports the first disagreement with the entry position rather than one opaque failure.
This verifier checks complete exports: the entries must cover the log for the tenant, in sequence order, because a partial window cannot match the head root. That is a deliberate choice for this verification path, not a claim that verifiable subsets are impossible. Verification checks the exported entries against the supplied signed head; a matching root does not establish that the head is the latest head, that no conflicting history exists, or that every relevant decision was captured.
4. The Merkle root and the signed tree head
The export contains entry leaves and signed tree heads. A verifier recomputes the Merkle root over the exported leaves and compares it with the root in the signed head, and checks that the head's tree_size and index agree with the exported entries. This draft does not specify a standalone inclusion-proof or consistency-proof wire format; receipt-level proofs are a separate artifact and a separate future section. The tagged technical specification, section 5, defines the construction: domain-separated leaf and parent hashes, duplicate-last pairing at every level, and the empty-tree constant. It is an AAES construction, not an RFC 6962 tree. Reference vectors are published with the reader.
| Tree head field | Type | Meaning |
|---|---|---|
log_id | string | Derived from the tenant id by a domain-separated SHA-256 derivation (versioned prefix aaes/log-id/1/) shared by producer and verifier. Required inside the signed payload; removing it invalidates the signature. |
index | integer | Sequence number of the last entry the head covers. |
root_hash | string (hex) | Merkle root over the leaves. |
tree_size | integer | Number of leaves the head covers. |
signed_at | RFC 3339 timestamp | When the head was signed. |
pre_anchor | boolean, optional | When true, commits the head to an export taken before the first anchor interval. Included in the signed payload when present; omitted when false. If it is omitted from an anchorless export, the unsigned header flag requires the explicit pre-anchor verification opt-in described above. |
signature | string (base64) | Required Ed25519 signature (RFC 8032) over the canonical JSON of the head with the signature field omitted. |
5. Anchors, timestamps, and witnesses
An anchor contains the required fields type (always anchor) and head, plus optional key_id, algorithm, timestamp, and witnesses. The writer records key_id and algorithm. If these optional fields are omitted, the reader uses the key supplied out of band. A head signed by a rotated key fails closed until that key is supplied. Key identifiers do not establish trust, and this draft does not yet specify how an export containing heads signed by multiple keys is verified with the published CLI.
Timestamps
The optional timestamp object contains authority, digest, and time. Optional fields are token, noop, and verified. It is designed for an RFC 3161 timestamp authority: an external service that attests when a commitment existed.
A noop timestamp is a placeholder. The exported verified field is metadata; a reviewer must verify the timestamp against their chosen trust roots. The profile supports SHA-256 only and performs no certificate revocation checking, so choose a compatible authority and trust policy.
Witnesses
An optional witness signs the commitment again. Each countersignature requires witness_id, signature, and signed_at. It may include public_key and an informational key_holder declaration. An embedded key or custody label does not establish independence: the reviewer must obtain and pin the witness's identity and key separately.
The tagged technical specification defines the head-payload digest and witness countersignatures in section 7, RFC 3161 validation and its limits in section 8, and the witness-trust file in section 14.
What these checks establish
A valid head signature establishes that the holder of your supplied key signed that head. If AAES alone holds the key, it could substitute a different, internally consistent history. A trusted timestamp can establish when a commitment existed; a pinned witness can attest to that commitment under its witness policy.
These checks do not establish that every action was captured or exclude conflicting histories. Detecting conflicting commitments, also called equivocation, additionally requires comparing separately retained commitments under a defined consistency and witness policy.
External timestamps and independent witnesses are supported but neither is configured by default. Your deployment operator selects, configures, and operates them. The verifier reports the counts it checked and those verified as independent. The --require-independent gate rejects an export unless at least one independent witness or timestamp verifies against caller-supplied trust material; passing that gate does not prove the broader properties above.
6. The evidence pack (aaes.evidence-pack/1)
The examiner deliverable is a directory, not a single file. Its manifest (aaes.evidence-pack/1) names the tenant, the export and records schema versions, the population statement, an explicit list of exclusions from the pack's evidentiary scope, and the file inventory, with the verifier binary and its SHA-256 recorded together when one is bundled. An unsigned manifest and a checksum stored beside a binary do not independently authenticate that binary; the pack inventory should arrive through an independently authenticated delivery channel, or the manifest should be separately authenticated.
SCOPE.md states the examination population and exclusions in plain language: journaled decisions for brokered and enforced tool calls in the supplied period, with evals, model behavior, certification, unseen calls, and pass-through observation listed as outside the population. A period-specific examination population must be distinguished from the history covered by the export's signed head.
The sealed journal records an examiner needs to match an export row to stored bytes (policy bundle hash, engine version, capability version, model identity) ship as a sidecar JSONL file, schema aaes.records/v1, that never mixes into the export. The sidecar is a separate artifact with its own identifier: export-only verification does not establish that sidecar records match their corresponding record_hash values; that is a separate sidecar-to-record_hash binding check, performed by tooling that understands the sidecar.
Every pack also prints what it does not prove: that every in-scope effect went through AAES, that agents are certified or "compliant", that the model behaved correctly, that observational receipts were enforced, or independent attestation without a pinned witness or timestamp authority.
7. Verifying
The public Apache-2.0 aaesverify v0.3.0 source and release binaries verify the aaes.export/v3 exports current AAES Govern deployments write and retained aaes.export/v2 exports, and read aaes.export/v4 files; v0.2.0 reads v2 only. A v4 file also takes --keyring for rotated keys and --expected-final for the final head you expect. Without --expected-final, a v4 result is at most UNPINNED_CONSISTENCY. Build from the public checkout or download the tagged binaries, and check SHA256SUMS.txt with its keyless cosign bundle as the release README describes. The verification package imports only standard-library code, hashing helpers and required shared types; tests enforce its dependency boundary. It shares some implementation with the producer, so a separately written reader remains a stronger check.
go build -o aaesverify ./cmd/aaesverify
./aaesverify --export export.jsonl --pubkey key.pubThe public verifier also accepts --allow-pre-anchor for the unsigned-header case described in section 1. Shared optional flags: --tsa-roots <roots.pem>, --witness-trust <witnesses.json>, --require-independent, and --json. From v0.3.0, --records <file> re-seals a current record/2 sidecar and binds it to a v3 --export, --receipt <file> verifies an aaes.trust-receipt/v1 decision receipt, and --evaluation <directory> checks a disclosed evaluation directory. Verification is offline, but trust material must be supplied separately: the signing public key and, when applicable, TSA roots and pinned witness keys. Embedded keys do not establish their own trust.
Verification establishes: every entry's canonical bytes hash to the leaf the export claims; the chain links genesis to head in sequence order; the recomputed Merkle root over the exported leaves equals the root in the signed tree head; the head signature verifies under the public key supplied out of band; and every anchor commits to a prefix of the same tree with a valid signature. It does not establish capture completeness, truth of recorded inputs, correctness of the recorded decision, downstream execution, or independence from AAES without a pinned witness or timestamp authority. Each class of failure is reported separately so a reviewer sees exactly which check failed.
8. Relationship to IETF SCITT
AAES does not claim IETF SCITT conformance. This format does not specify SCITT-compatible COSE signed statements or transparency-service receipts, and an AAES Govern signed tree head, timestamp, or witness signature is not a SCITT artifact merely because it provides a related function. A future integration would need an explicit mapping of statement encoding, registration, receipt format, verifiable data structure, and trust policy to a cited SCITT specification version. AAES also does not claim RFC 6962 conformance; the Merkle construction follows the transparency-log tradition with a deliberately simpler construction rather than a conformant one.
9. Conformance, known gaps, and changelog
The tagged technical specification provides a reader-conformance checklist in section 13 covering encoding and hashing, chain and tree, heads and anchors, witness and timestamp checks, and format handling. Structural validation, file-level validation, cryptographic verification and attestation-policy checks remain separate operations; passing the published line schema is not a verification result. Publication of this checklist does not establish an independent conformance assessment.
Machine-readable JSON Schemas for the export lines and the evidence-pack manifest are published at /spec/v2/export.schema.json (aaes.export/v2) and /spec/v1/evidence-pack-manifest.schema.json. The schemas describe JSON structure. They do not enforce cross-line relationships or cryptographic validity; date-time syntax, base64 decoding, key and signature lengths, and supported algorithm values require explicitly configured validation or verifier checks.
Remaining independent validation: a separately written reader should exercise the published definitions and vectors, including canonicalization edge cases, tenant/log binding, chain and Merkle construction, tombstone gaps, timestamp policy and pinned witness identity. For v2 and v3 exports, the public CLI accepts one signing key and fails closed on rotated-key history requiring another; multi-key operation needs an explicit supported procedure. Since v0.3.0 the public CLI performs the receipt and current-profile sidecar checks in section 7. Records outside that profile, receipt-chain seals and full evidence packs belong to the separate operator evidence tooling, and a public reader-conformance assessment has not been completed.
- November 5, 2026 (editorial): shortens the feedback line. No change to the v2 format.
- November 4, 2026 (editorial): states that aaesverify v0.3.0 performs receipt, current-profile sidecar and evaluation-disclosure checks. No change to the v2 format.
- October 29, 2026 (editorial): states that aaesverify v0.3.0 also reads
aaes.export/v4, with--keyringand--expected-final. No change to the v2 format. - October 22, 2026 (editorial): aaesverify v0.3.0 is released and reads
aaes.export/v3and this v2 format. No change to the v2 format. - October 21, 2026 (editorial): states that current AAES Govern deployments write
aaes.export/v3, which this draft does not describe and aaesverify v0.2.0 does not read. No change to the v2 format. - October 3, 2026 (editorial): aligns the web summary with the published v0.2.0 encoding and verification definitions, distinguishes embedded-key consistency checks from signer provenance, and separates export checks from stored-record sidecar binding. No wire-format change.
- October 1, 2026: public aaesverify v0.2.0 and the published JSON Schema support
aaes.export/v2, with integeramount_minorandamount_currencyfields. The records sidecar and evidence-pack manifest retain independent version identifiers. - September 22, 2026 (editorial): the machine-readable JSON Schemas for the export lines and the evidence-pack manifest are now listed in the public SchemaStore catalog, for editors and validation tooling that consume the catalog.
Sources
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), IETF, January 2017. Retrieved September 21, 2026, from rfc-editor.org/rfc/rfc8032.
- RFC 3161, Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP), IETF, August 2001. Retrieved September 21, 2026, from rfc-editor.org/rfc/rfc3161.
- RFC 6962, Certificate Transparency, IETF, June 2013. Retrieved September 21, 2026, from rfc-editor.org/rfc/rfc6962.
- IETF SCITT (Supply Chain Integrity, Transparency, and Trust) working group (background, not a normative reference). Retrieved September 21, 2026, from datatracker.ietf.org/wg/scitt/about.
Reviewing AAES for a client or a procurement? The verifier, the sample pack, and this specification are the materials available for technical review.