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 -> meaningAEON attempts to delay those reductions.
Claims and Authority
AEON separates claim, meaning, authority, and materialization.
claim
!=
meaning
!=
authority
!=
materializationA 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 objectThink:
source -> semantic representationThe 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
MaterializationMany 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.
a = 3
b = ~a
c = ~>bDo not immediately think:
c = 3Instead think:
a contains 3
b references a
c references bThe relationship graph is part of the document's meaning.
Resolution may occur later. Preservation occurs first.
Types
Types are claims, not runtime classes.
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.
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.