# Appendix — Transport & Framing **Appendix to:** AEON Specification v1 This appendix defines how AEON documents are framed and transported. ## 1. Design Principles 1. **Framing before meaning** — Headers readable before payload interpretation 2. **No execution for inspection** — Headers parse without processors 3. **Transport orthogonal to interpretation** — Framing doesn't affect semantics 4. **Fail closed** — Malformed framing causes rejection ## 2. Document Unit An **AEON Document Unit** consists of: 1. Optional framing metadata (transport-level) 2. AEON headers 3. AEON payload (body) 4. Optional envelope Transport framing MUST delimit exactly one document unit. ## 3. Headers as Control Surface Headers are the **only** part inspectable before full parsing: ```aeon aeon:version = "1.0" aeon:schema = "com.example.contact" aeon:profile = "com.example.api" ``` Rules: - Headers parseable without evaluating payload - Headers MUST NOT trigger processors - Headers immutable once read ## 4. File Transport ### 4.1 Single Document - An AEON file contains exactly one Document Unit - Encoding MUST match `aeon:encoding` if present - Reject files with conflicting encoding declarations ### 4.2 Extensions Common extensions (non-normative): - `.aeon` - `.aeon.txt` Extensions have no semantic meaning. ## 5. Stream Transport When streaming, each document MUST be framed using: ### 5.1 Length-Prefix Framing (Recommended) ``` \n ``` **Implementation note:** `@aeon/transport` uses a binary u32 big-endian length prefix (`[4 bytes length][payload]`) as the default framing format. This is compatible with stream transports where newline-delimited framing is not available. ### 5.2 Delimiter Framing Explicit end marker after document. **Note:** Implementations MUST NOT assume EOF implies end-of-document. ## 6. Incremental Parsing Implementations MAY support incremental parsing with guarantees: - Headers fully read before payload interpretation - Payload not partially evaluated - Assignment Events not emitted until document complete This prevents "early execution" attacks. ## 7. Multi-Document Containers AEON may be embedded in containers (archives, multipart messages). Rules: - Each document retains independent framing - Headers inspectable per document - No shared state implied ## 8. Security Considerations ### 8.1 Header-First Policy Consumers SHOULD: 1. Read framing 2. Read headers 3. Verify schema/profile against policy 4. Only then parse payload ### 8.2 Resource Limits Implementations SHOULD enforce limits on: - Document size - Nesting depth - Array lengths - Assignment Event count Framing MUST allow rejection before resource exhaustion. ### 8.3 No Remote Fetch Transport MUST NOT automatically fetch: - Schemas - Profiles - Processors All artifacts resolved locally by policy. ## 9. Relationship to Processing Transport occurs **before** Phase 1 (Lexing). Transport MUST NOT: - Alter canonical paths - Affect assignment ordering - Inject metadata into document model --- ## Related documents - [AEON Specification v1](./aeon-core-v1.md) - [Appendix — Processing Model](./appendix-processing-model-v1.md) - [Appendix — Error Model](./appendix-error-model-v1.md)