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:

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)

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

End of Transport & Framing