<!-- Philosophy -->
# AEON preserves meaning by refusing premature inference.
AEON is defined not only by what it transports, but by what it refuses to infer. A document may declare structure, types, references, contracts, and intent, but it does not get to prove those claims¹ about itself. Consumers bring the trusted contract.
That refusal is AEON's negative space semantics: references are not automatically values, type labels are not runtime classes, schemas are not truth, comments are not execution, and structure is not forced materialization. AEON keeps those spaces open until a trusted consumer chooses how to close them.
[Negative space](#negative-space)
[Meaning layers](#meaning)
[Security mindset](#security)
[Security model](https://github.com/AltoPelago/aeon/wiki/Security-Model)
<!-- Negative Space -->
## The uncollapsed distinctions are part of the meaning.
AEON is not best understood as typed JSON, a configuration format, a schema language, or a programming language. It is a semantic preservation² system. Its core principle is simple: preserve distinctions until a trusted consumer explicitly chooses to collapse them.
Most systems reduce meaning early. AEON delays that reduction. The gap between what the source claims and what a consumer later accepts is not accidental; it is where trust, validation, and materialization stay visible.
```aeon
reference -> value
type -> runtime object
document -> HTML
list -> set
schema -> meaning
```
Those reductions may be valid later, but they should be explicit, trusted, and auditable. AEON keeps the source independent of those later choices.
<!-- Meaning -->
## The parser preserves claims; it does not decide their domain truth.
AEON separates claim, meaning, authority, and materialization. A value can be syntactically valid, structurally valid, and still fail domain meaning. For example, 0 may be a valid number but an invalid temperature reading if the consumer requires a unit.
The point is not to eliminate meaning. The point is to prevent implicit, invisible, uncontrolled decisions about meaning.
At the surface, a binding can look like key plus value. Semantically, it is better to read it as identity plus claims: the name gives a document address, while the type label, value, attributes, comments, and references make claims preserved for later validation and materialization.
```aeon
person:person = {
name:string = "Bob"
}
```
Here person identifies a place in the document. :person claims a domain type. name:string creates a nested identity with a string claim. The parser preserves those claims; it does not decide whether this is a real person or construct a runtime object.
```aeon
temperature:number = 0 // celsius, fahrenheit ?
---
temperature@{unit:string = "celsius"}:number = 0
---
temperature@{unit:string = "fahrenheit"}:number = 32
```
<!-- Layers -->
## Each layer proves one thing and nothing more.
AEON's processing model is deliberately layered. The parser is not trying to turn source text directly into runtime objects. It is trying to preserve semantic representation. The lexer handles syntax. AEON Core³ produces the Assignment Event Stream⁴. AEOS⁵ validates form. Meaning validation applies consumer context. A Tonic⁶ may materialize meaning only after those earlier boundaries have held.
This keeps validation separate from execution and processing. No layer is allowed to quietly upgrade trust by doing work that belongs to another layer.
```aeon
bytes → tokens → AES → AEOS → meaning validation → Tonic → runtime
```
Many parsers effectively read text and materialize application objects in one move. AEON splits that path. The pre-parse boundary controls bytes and sizes before syntax is trusted. The lexer only recognizes syntax and advances without backtracking traps. The parser builds structure and paths without creating domain objects. AES records what was assigned. AEOS checks shape without silently mutating values or typecasting them. Meaning validation checks whether the accepted claims make sense for the consumer. Only after those checks can a consumer-selected Tonic materialize references and runtime objects, with limits in place for oversized graphs or memory-heavy reference expansion.
That split gives the consumer control over what the parser should accept, what should fail, and which later stages are allowed for the current context. A public upload, a signed internal document, and a local authoring draft can all use different acceptance boundaries without asking the document to secure itself.
Schemas belong to that discipline too. A schema can adjudicate form: existence, required fields, shape, declared type, and structural constraints. It does not inherently adjudicate truth, business meaning, or domain correctness.
```aeon
pre-parse → byte limits, encoding checks, size controls
lexer → syntax tokens, one pass, no backtracking traps
parser → structure and paths, no runtime objects
AES → ordered assignment events
AEOS → validation, no mutation or typecasting
Tonic → materialization after limits and policy
```
<!-- References -->
## References preserve relationships before they become values.
One common mistake is to materialize references mentally as soon as they appear. In AEON, the relationship graph is part of the meaning, so preservation comes before resolution.
```aeon
a = 3
b = ~a
c = ~>b
```
The better reading is not simply c equals 3. It is: a contains 3, b references a, and c references b. A trusted consumer may resolve that graph later, but the parser should not erase the distinction early.
<!-- Security -->
## Documents declare intent. Consumers decide trust.
Headers, contracts, profiles, schema declarations, and datatype labels are claims. They are useful claims, but they are not self-authenticating. A consumer verifies those claims against its own trusted registry, schema, profile, or policy.
This is AEON's zero-trust posture: the document can ask to be interpreted a certain way, but it must never select its own trusted execution surface.
There is a second security layer as well: the consumer⁷ controls what it is willing to accept before materialization. Byte limits, nesting limits, reference limits, datatype policy, schema requirements, profile allowlists, and Tonic permissions can all be set by the receiving context.
That creates a fail-first path for hostile or oversized input. A document should not be able to force expensive parsing, reference expansion, memory-heavy graphs, or weaponized payloads into runtime objects before the consumer has explicitly accepted the relevant layer.
Every verification check - against a registry, against a schema, against a policy - happens outside the document and under consumer authority. The document presents; the consumer decides.
```aeon
aeon:contracts = [
"example.weather.v1"
]
temperature:number = 0
```
<!-- Boundaries -->
## Explicit forms prevent accidental coercion.
AEON keeps similar-looking values distinct until a trusted consumer decides what to do with them. Strings that look numeric, toggles that read like words, and booleans that carry truth values are not collapsed into one vague space.
That restraint is practical security: validation can reject input before runtime objects exist, and audit tools can inspect what was claimed without first accepting what it means.
```aeon
amount:string = "0"
amount:number = 0
approved:toggle = no
verified:boolean = false
```
<!-- Why -->
## AEON avoids familiar data-format ambiguity by making claims visible.
YAML has the classic Norway problem: a value such as NO may be read as a boolean instead of a country code. JSON permits duplicate object keys, which leaves consumers to decide whether first key, last key, or error wins. CSV relies on tools that often infer dates, numbers, and identifiers differently. XML preserves structure, but most values arrive as strings until conventions or schemas give them stronger meaning.
AEON sidesteps these problems by keeping each claim explicit. A country code is a string. A toggle is a toggle. A duplicate key is an error rather than a mystery. A date is a date. A number-looking identifier can stay a string. A value like 7_000 is explicitly seven thousand rather than a locale-dependent spreadsheet guess. When a consumer needs stronger guarantees, AEOS can validate the assignment stream before anything becomes a runtime object.
```aeon
//# YAML Norway problem: "NO" can become false.
countryCode:string = "NO"
decision:toggle = no
//# JSON duplicate keys: consumers disagree on the winner.
id:string = "invoice-100"
id:string = "invoice-099" // duplicate key; AEON rejects this
//# CSV spreadsheet inference: values become dates or numbers.
sku:string = "00123"
shipDate:date = 2026-05-05
attendees:number = 7_000
//# XML conventions: text needs external typing rules.
quantity:number = 12
quantityText:string = "12"
```
<!-- Canonical -->
## Canonical form signs what was accepted without erasing author intent too early.
AEON distinguishes source text, accepted assignment events, canonical form⁸, and Tonic materialization. Author intent stays visible through parsing and validation; canonicalization gives tools a stable representation only after the consumer has chosen the rules it trusts.
That stable form is what makes cryptographic signing, tamper hashes, and encryption practical. A signer can hash the canonical stream instead of whatever whitespace, ordering, or editor formatting happened to be present in the source, while a Tonic can still materialize richer runtime objects later.
```aeon
document:object={
title:string="Release notes"
total:number=7_000
//? First names only
authors:list=[
"Bob"
"Alice"
]
}
signature:envelope={
algorithm:string="ed25519"
keyId:string="example.publisher.2026"
value:base64=$MEUCIQDx
}
```
A canonical representation can then normalize spacing, ordering, and numeric spelling for stable hashing while keeping the accepted values and envelope explicit.
```aeon
aeon:header = {
encoding = "utf-8"
mode = "transport"
profile = "core"
version = "1.0"
}
document:object = {
authors:list = ["Bob", "Alice"]
title:string = "Release notes"
total:number = 7000
}
signature:envelope = {
algorithm:string = "ed25519"
keyId:string = "example.publisher.2026"
value:base64 = $MEUCIQDx
}
```
<!-- Design Center -->
## AEON is readable because its responsibilities are narrow.
The core language preserves structure, identity, order, provenance, and symbolic references. It does not coerce, execute, materialize, or infer hidden context.
Flexibility enters through explicit layers: schemas, profiles, contracts, comments, security envelopes, and Tonics. Each layer can be verified, accepted, ignored, or rejected by the consumer.
AEON should not be modeled around JavaScript, Python, Rust, XML, YAML, or any other host language. Host languages are consumers. They are not authorities over the semantic model.
That is the philosophy: do not pretend messy real-world meaning does not exist. Give it visible paths, strict boundaries, and an audit trail.
## Definitions
¹ **Claim:** something the document says about structure, type, intent, relationship, or meaning. Claims are preserved by AEON and accepted, rejected, or interpreted by consumers.
² **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.
³ **AEON Core:** the core language and parser layer responsible for recognizing AEON syntax and preserving structure as assignment events, without deciding domain meaning.
⁴ **AES:** Assignment Event Stream. The ordered preservation artifact produced from AEON source, used by later validation, canonicalization, auditing, and materialization steps.
⁵ **AEOS:** the AEON schema layer. AEOS validates shape, required fields, declared types, and structural constraints; it does not prove business truth or domain meaning by itself.
⁶ **Tonic:** a consumer-side materializer or adapter that turns accepted AEON meaning into a runtime object, rendered document, API payload, or other projection under consumer policy.
⁷ **Consumer:** the system receiving AEON. The consumer chooses which schemas, profiles, policies, conventions, and Tonics it trusts for the current context.
⁸ **Canonical form:** a stable representation of accepted AEON used for comparison, signing, hashing, review, caching, and reproducible processing without preserving irrelevant formatting differences.