# Portable AES Integrity Contract v1 Scope: deterministic logical bytes, digests, ordering policies, coverage, provenance, signatures, and AEON security-envelope composition for portable AES. Contract identifier: `aes.integrity.v1` Ordering policies: `aes.order.canonical-semantic.v1`, `aes.order.exact.v1` Signature-input contract: `aes.signature.v1` This contract operates on validated `aes.events.v1` records. It is independent of Telex, Film, JSON, AEON source spelling, and implementation-native event objects. An encoding decoder first recovers the transport-neutral stream; this contract then produces identical logical bytes from that stream. ## 1. Purpose and authority This document owns: - the deterministic structural byte mapping used for portable AES integrity; - binding of the event contract, effective profile and projection, ordering policy, scope, provenance policy, digest algorithm, and ordered records; - canonical-semantic and exact supplied-order policies; - SHA-256 digest production and comparison; - the domain-separated signature input; and - composition rules for carrying AES evidence in an AEON security envelope. It does not define event validity, Telex or Film bytes, private-key handling, trusted-key discovery, algorithm approval, authorization, encryption, ledger storage, or Assignment Event Transaction envelopes. `aeon.gp.integrity.v1` remains the AEON final-document-state hash. Its existing path/value serialization and signatures are not portable AES evidence and are not upgraded or reinterpreted by this contract. ## 2. Integrity input The logical integrity input is a map with exactly these fields: | Field | Logical value | | :--- | :--- | | `integrity` | `aes.integrity.v1` | | `events` | `aes.events.v1` | | `profile` | effective non-empty AES profile identifier | | `projection` | effective projection identifier, or null for body-only | | `ordering` | selected ordering-policy identifier | | `scope` | `aes.scope.body.v1` or `aes.scope.document.v1` | | `provenance` | `aes.provenance.excluded.v1` or `aes.provenance.included.v1` | | `digest` | `sha256` | | `records` | policy-produced record sequence | *AES integrity v1 table 1* Every field is present in the logical input. Carrier omission does not become integrity-input omission: an omitted AES profile expands to `aes.complete.v1`, and an omitted projection becomes logical null. The base digest does not bind a consumer's runtime resource limits. Limits do not change AES event meaning. An enclosing application or transaction contract that makes an effective-limits claim binds that separately as part of its own logical input; it does not inject local limits into this map. ## 3. Scope `aes.scope.body.v1` includes body records and excludes every header record. It still binds the effective projection, so the same body selected from two different projections is not silently treated as the same integrity input. `aes.scope.document.v1` includes the ordered header plane followed by the body plane and requires `projection=aeon.document.v1`. A later projection may register its own compatible document-scope rule. Document scope fails when no selected projection defines a header plane. Scope filtering occurs before provenance processing and ordering. ## 4. Provenance policy `aes.provenance.excluded.v1` removes `origin` and `span` from every covered record. It is the semantic-value policy and does not attest source bytes. `aes.provenance.included.v1` retains both fields exactly when present. A signer claiming source-backed verification additionally performs the source artifact audit defined by `aes.events.v1`; syntactic inclusion alone does not prove that an artifact was available or checked. All other core fields and all present extension fields remain covered. A field is never omitted merely because the signer does not understand it. ## 5. Ordering policies ### 5.1 Exact order `aes.order.exact.v1` preserves the supplied order of the covered records. Repeated addresses and repeated identical records remain distinct ordered occurrences. This is the policy for ledgers, prepared transactions, delivery evidence, and any application where chronology or repeated writes are significant. A relay that changes record order produces different logical bytes and cannot retain the former digest or signature as evidence over the new sequence. ### 5.2 Canonical-semantic order `aes.order.canonical-semantic.v1` asserts that supplied record order is not part of the evidence being signed. It is valid only when every covered address is unique within its address plane. A duplicate `(plane,address)` fails with `AES_INTEGRITY_AMBIGUOUS_CANONICAL_ORDER`; implementations do not use record contents as a tie-breaker to conceal repeated writes. Covered records are sorted by: 1. plane: header before body; 2. unsigned UTF-8 bytes of the canonical `header` or `path` string; and 3. no further key, because addresses are unique within a plane. Byte strings are compared lexicographically by unsigned octet. A shorter byte string sorts first when it is an exact prefix. No locale, Unicode normalization, host collation, numeric conversion, or path-segment interpretation is applied. Indexed semantic order remains represented by each canonical indexed address. Selecting this policy is an application assertion. It does not make order insignificant under every AES profile and does not replace exact order when chronology, repeated occurrences, or a ledger sequence matters. ## 6. Covered record structure Each record is encoded as a map of its present logical fields after the selected scope and provenance projections. Absence is represented by an absent map key; it is distinct from an empty string, empty array, and null. Datatype information is always the expanded `aes.events.v1` structure: - `datatype` is the base-name string; - `generics` is an ordered list of datatype maps or tagged numeric-literal maps; and - `clarifiers` is an ordered list of tagged string/numeric-literal maps. The Telex combined datatype descriptor is never an integrity input. Extension-field names and string values are included like other record map members. An integrity implementation validates the selected AES profile and registered extension surface before claiming semantic conformance. Portable scalar strings are encoded exactly as their Unicode scalar sequence. No normalization, case folding, numeric parsing, null reinterpretation, or reference resolution occurs. The record's normative `kind` is independently covered, so equal string payloads under distinct recognized representation kinds remain distinct integrity inputs. Source-only fields such as `raw` are not part of `aes.events.v1` and fail validation instead of entering the digest. ## 7. Deterministic structural byte mapping All marker and length characters below are ASCII. String payloads are UTF-8. Lengths count bytes, not Unicode scalar values or host string units. Unsigned decimal integers use `1` or a digit from `1` through `9` followed by digits; leading zeroes are forbidden. The recursive encoding `E(value)` is: | Logical value | Bytes | | :--- | :--- | | null | `n` | | string | `s` + decimal UTF-8 byte length + `:` + UTF-8 bytes | | list | `l` + decimal item count + `:` + each item encoded in order | | map | `m` + decimal member count + `:` + each encoded key then encoded value | *AES integrity v1 table 2* Map keys are strings and are emitted in unsigned UTF-8 byte order. Duplicate map keys are invalid. Maps are therefore independent of host insertion order. Counts and string lengths make delimiters inside strings inert; no escaping is performed. The complete logical bytes are: ```text UTF8("aes.integrity.v1") || 0x00 || E(integrity-input-map) ``` `0x00` is one zero octet. Implementations reject unpaired UTF-16 surrogates or any other input that is not a Unicode scalar sequence rather than replacing it during UTF-8 encoding. This mapping is an integrity encoding only. It is not an AES interchange format and does not compete with Telex or Film. ## 8. Digest AES v1 defines `sha256`. The digest is SHA-256 over the complete logical bytes. Its portable textual form is exactly 64 lowercase hexadecimal digits. The `digest=sha256` member is inside the hashed integrity-input map. Algorithm substitution therefore changes the preimage as well as the verification operation. Other algorithms require a new registered digest identifier and test vectors; accepting a host crypto name is insufficient. Digest comparison is exact over the 32 digest bytes. Text decoders first reject non-canonical hexadecimal spelling. ## 9. Signature input `aes.signature.v1` reuses the AEON signature-entry vocabulary where possible, but defines a separate coverage rule. A signature entry supplies: - signature algorithm `alg`; - opaque non-empty key identifier `kid`; - signature bytes `sig`; and - associated AES integrity evidence. The signature-context map has exactly: | Field | Logical value | | :--- | :--- | | `signature` | `aes.signature.v1` | | `integrity` | `aes.integrity.v1` | | `digest` | `sha256` | | `hash` | 64-character lowercase digest string | | `alg` | exact signature algorithm identifier | | `kid` | exact opaque key identifier | *AES integrity v1 table 3* Signature input bytes are: ```text UTF8("aes.signature.v1") || 0x00 || E(signature-context-map) ``` `sig` is excluded to avoid recursion. Binding `alg` and `kid` prevents metadata substitution without producing new valid evidence. Algorithm approval, key resolution, revocation, multi-signature policy, and timestamp authority remain security-profile concerns. ## 10. AEON security-envelope composition An AEON document may carry AES integrity evidence inside its ordinary `aeon:envelope`. The carrier preserves all integrity-input context fields, the digest, and signature fields. `aeon.gp.signature.v1` field names may be reused, but an entry identifies `aes.signature.v1`; it does not claim that an AES digest is an `aeon.gp.integrity.v1` final-state hash. The envelope remains outside the covered AES record stream. For document scope, the `aeon.document.v1` header plane and body plane are covered, while the security envelope containing the evidence is excluded to avoid recursion. Signing does not authorize an AES application or ASP write. The separate `aes.transaction.integrity.v1` contract reuses this structural mapping and additionally binds transaction identity, target, application/preparation contracts, preconditions, assertions, effective limits claims, authorization context, and extensions. That broader transaction digest is defined by `aes-transactions-v1`, not by this contract. Encryption composition remains deferred. A profile states whether this contract covers plaintext or a separately defined authenticated ciphertext structure before encrypted AES evidence is issued. ## 11. Processing procedure To compute AES integrity evidence: 1. Establish and validate `aes.events.v1`, its effective profile and projection, and any registered extension fields. 2. Require explicit ordering, scope, and provenance policies. 3. Select records by scope. 4. Remove `origin` and `span` only when the provenance policy requires it. 5. Apply the selected ordering policy, rejecting ambiguous canonical order. 6. Construct the complete integrity-input map with expanded defaults. 7. Encode it using the deterministic structural mapping. 8. Compute SHA-256 and render lowercase hexadecimal evidence. Verification repeats the same procedure from trusted policy inputs and compares the digest. It does not trust a carrier's context declarations merely because they accompany a matching digest; the verifier decides which contracts and policies are acceptable for the operation. ## 12. Diagnostics | Code | Condition | | :--- | :--- | | `AES_INTEGRITY_CONTEXT_REQUIRED` | ordering, scope, provenance, or stream context is absent | | `AES_INTEGRITY_UNSUPPORTED_CONTRACT` | integrity or event contract is unsupported | | `AES_INTEGRITY_UNSUPPORTED_ORDERING` | ordering policy is unknown | | `AES_INTEGRITY_UNSUPPORTED_SCOPE` | scope is unknown or unavailable for the projection | | `AES_INTEGRITY_UNSUPPORTED_PROVENANCE` | provenance policy is unknown | | `AES_INTEGRITY_UNSUPPORTED_DIGEST` | digest identifier is unknown | | `AES_INTEGRITY_AMBIGUOUS_CANONICAL_ORDER` | canonical-semantic input repeats an address in one plane | | `AES_INTEGRITY_INVALID_LOGICAL_VALUE` | a covered field cannot be represented by the structural mapping | | `AES_INTEGRITY_DIGEST_MISMATCH` | supplied and recomputed digests differ | | `AES_SIGNATURE_CONTEXT_INVALID` | signature algorithm, key identifier, or digest context is invalid | *AES integrity v1 table 4* ## 13. Conformance Independent implementations use the same logical input vectors and compare both complete logical bytes and SHA-256 digests. Required vectors cover empty streams with expanded defaults; canonical equality and exact-order inequality; duplicate-address handling; expanded datatypes; body and document scope; provenance policies; representation-kind distinctions for equal scalar payload strings; rejection of source-only raw spelling; extensions and map-key ordering; non-ASCII UTF-8 lengths; and signature binding of algorithm and key identity. Vectors are owned by an AES integrity CTS lane, not by Telex. Telex and Film decoders pass their recovered logical stream to that lane without contributing encoding bytes. --- ## Related documents - [AES v1](./aes-v1-index.md) - [Portable AES Event Contract v1](./aes-events-v1.md) - [telex.aes v1](./telex-aes-v1.md) - [Portable AES Compatibility Contract v1](./aes-compatibility-v1.md) - [Assignment Event Transaction Contract v1](./aes-transactions-v1.md) - [Appendix — Integrity Envelope](./appendix-integrity-envelope-v1.md)