<!-- RAG Document -->
## Understanding AEON: A Semantic Preservation System
### Read this first
If you approach AEON as typed JSON, a configuration language, a serialization format, a schema language, or a programming language, you will misunderstand most of its design.
AEON is best understood as a semantic preservation¹ architecture.
The language exists to preserve distinctions that other systems often collapse.
<!-- Core Principle -->
## Preserve distinctions until a trusted consumer explicitly chooses to collapse them.
Most systems perform semantic reduction early.
```
reference -> value
type -> runtime object
document -> HTML
list -> set
schema -> meaning
```
AEON attempts to delay those reductions.
<!-- Claims and Authority -->
## AEON separates claim, meaning, authority, and materialization.
```
claim
!=
meaning
!=
authority
!=
materialization
```
A document makes claims².
Validators verify form.
Consumers³ decide meaning.
Tonics⁴ materialize meaning.
The source itself possesses no executable authority.
<!-- Parsing Goal -->
## The purpose of parsing is preservation, not immediate runtime values.
Do not think:
```
source -> runtime object
```
Think:
```
source -> semantic representation
```
The purpose of parsing is not to obtain values.
The purpose of parsing is to preserve semantic structure.
<!-- AES -->
## Inside the processing model, AES is the central preservation artifact.
For authors, source text is the entry point. For implementers, AES is the artifact that makes preservation visible across processing stages.
It is AES⁵: Assignment Event Stream.
Mentally model the system as:
```
AEON Source
|
v
AES
|
v
Validation
|
v
Canonicalization
|
v
Materialization
```
Many AEON features only make sense when viewed through AES.
<!-- References -->
## Do not materialize references mentally.
The most common mistake is to turn a relationship graph into a value too early.
```aeon
a = 3
b = ~a
c = ~>b
```
Do not immediately think:
```
c = 3
```
Instead think:
```
a contains 3
b references a
c references b
```
The relationship graph is part of the document's meaning.
Resolution may occur later. Preservation occurs first.
<!-- Types -->
## Types are claims, not runtime classes.
```aeon
person:person = {
name = "Bob"
}
```
The parser does not know what a person is.
The parser preserves the claim.
Validation and materialization determine what the claim means.
<!-- Schemas -->
## Schemas adjudicate form. Schemas do not adjudicate truth.
A schema can determine exists, required, shape, declared type, and structural constraints.
A schema cannot inherently determine business meaning, truthfulness, or domain correctness.
Those belong to later layers.
<!-- Collections -->
## AEON Core intentionally contains few collection concepts.
A list remains a list. Additional collection semantics are layered through conventions.
```aeon
tags@{
collection = "set"
}:list<string>
```
This is not a native set.
It is list plus set intent.
Validation and materialization determine whether set semantics are enforced.
<!-- Comments and Annotations -->
## Annotations are preserved semantic channels.
Do not assume comments are ignored.
Do not assume comments execute.
Consumers may ignore annotations, validate them, interpret them, or reject them.
The existence of an annotation does not grant authority.
<!-- Nodes -->
## Nodes represent semantic document structure.
Nodes are not HTML, XML, or runtime objects.
They are structured semantic claims that may later materialize into HTML, Markdown, PDFs, documentation, or other projections.
<!-- Canonicalization -->
## Canonicalization removes representation differences, not semantic differences.
Canonicalization should make equivalent representations compare reliably without pretending non-equivalent claims are the same.
Examples of removable distinctions include whitespace, formatting, and ordering where explicitly irrelevant.
Examples of preserved distinctions include references, declared types, semantic relationships, and annotations.
<!-- Materialization -->
## Materialization is an explicit step.
The most common mistake is assuming materialization occurs automatically. It does not.
A Tonic may choose to materialize⁶ person as a Rust struct, TypeScript class, Python object, or HTML fragment.
The source document remains independent of those choices.
<!-- Language Independence -->
## Host languages are consumers, not authorities.
Do not model AEON around JavaScript.
Do not model AEON around Python.
Do not model AEON around Rust.
The semantic model exists independently of any host language.
<!-- Mental Model -->
## AEON transports meaning without transporting authority.
### The wrong mental model
```
AEON is a typed data format.
```
### The better mental model
```
AEON transports meaning without transporting authority.
```
Most design decisions become understandable from that perspective.
## Definitions
¹ **Semantic preservation:** the design principle of preserving distinctions such as type labels, references, comments, identity, order, and structure until a trusted consumer explicitly collapses them.
² **Claim:** something the document says about structure, type, intent, relationship, or meaning. Claims are preserved by AEON and accepted, rejected, or interpreted by consumers.
³ **Consumer:** the system receiving AEON. The consumer chooses which schemas, profiles, policies, conventions, and Tonics it trusts for the current context.
⁴ **Tonic:** a trusted materializer or consumer-side adapter that turns accepted AEON meaning into a runtime object, rendered document, API payload, or other projection.
⁵ **AES:** Assignment Event Stream. The ordered preservation artifact produced from AEON source, used by later validation, canonicalization, auditing, and materialization steps.
⁶ **Materialization:** the explicit step where accepted AEON meaning becomes a runtime object, rendered document, generated code, API payload, or other concrete output.