&ND v2

+++document/meta
schemaVersion = "1"
id = "appendix-transport-v1"
title = "Appendix — Transport & Framing"
description = "Transport envelopes, framing assumptions, and interchange-safe packaging concerns."
family = "appendices"
group = "Core Semantics"
standing = "official"
lifecycle = "published"
normativity = "informative"
license = "CC-BY-4.0"
path = "specification/appendices/appendix-transport-v1"
order = 190
publish = true
keywords = ["AEON", "transport", "framing", "streaming", "headers", "resource limits"]
related = ["aeon-core-v1", "appendix-processing-model-v1", "appendix-error-model-v1"]
+++


# Appendix — Transport & Framing [# appendix-transport-framing]

[* Appendix to:] AEON Specification v1

This appendix defines how AEON documents are framed and transported.


## 1. Design Principles [# 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 [# 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-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 [# file-transport]


### 4.1 Single Document [# 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 [# extensions]

Common extensions (non-normative):

- [$ .aeon]
- [$ .aeon.txt]

Extensions have no semantic meaning.


## 5. Stream Transport [# stream-transport]

When streaming, each document MUST be framed using:


### 5.1 Length-Prefix Framing (Recommended) [# length-prefix-framing-recommended]

~~~$
<length>\n
<AEON document bytes>
~~~$

[* 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 [# delimiter-framing]

Explicit end marker after document.

[* Note:] Implementations MUST NOT assume EOF implies end-of-document.


## 6. Incremental Parsing [# 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 [# 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 [# security-considerations]


### 8.1 Header-First Policy [# 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 [# 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 [# no-remote-fetch]

Transport MUST NOT automatically fetch:

- Schemas
- Profiles
- Processors

All artifacts resolved locally by policy.


## 9. Relationship to Processing [# relationship-to-processing]

Transport occurs [* before] Phase 1 (Lexing).

Transport MUST NOT:

- Alter canonical paths
- Affect assignment ordering
- Inject metadata into document model