<!-- AEON Language -->
# How AEON works: vocabulary, grammar, meaning layers, and processing boundaries.
## This is the how page.
This page explains the fundamental workings of the AEON language system: the visible syntax, the vocabulary AEON uses, the grammar shape, the layered processing model, and the philosophy that keeps meaning separate from authority.
Use this page when you already understand why AEON might matter and want to know how the language is built.
[Document shape](#document-shape)
[Processing model](#processing)
[AES](#aes)
[Processing walkthrough](/walkthrough-processing.php)
[Language guide](/language.php)
[Type reference](/type-reference.php)
<!-- Document Shape -->
## AEON starts with explicit bindings.
A binding connects a key to a value. A type annotation can make the intended value family visible. Attributes can add local side information without changing the value itself.
```aeon
title:string = "Release notes"
count:number = 7_000
published:toggle = on
width@{unit:string = "cm"}:number = 33
```
Objects, lists, tuples, references, and nodes build on the same visible pattern rather than introducing a second hidden language.
<!-- Vocabulary -->
## The everyday words are deliberately small.
### Binding
- **Definition:** a key, optional attributes, optional datatype annotation, and assigned value.
### Value
- **Definition:** the bound data itself: a scalar, container, reference, node, prose block, encoded value, or special literal.
### Attribute
- **Definition:** structured metadata attached locally to a binding or anonymous value head.
### Reference
- **Definition:** a value that points at another path. Clone references use ~path; pointer references use ~>path.
### Node
- **Definition:** a tagged tree value for ordered, nested, document-like structures.
### Semantic comment
- **Definition:** a structured side-channel comment that can carry notes, annotations, guidance, or workflow context without becoming ordinary data.
<!-- Grammar -->
## The grammar is meant to keep the visible form predictable.
AEON is shaped around assignments, typed values, containers, references, and nodes. The grammar exists to preserve what was written and produce deterministic events, not to infer hidden meaning.
```
binding = key attributes? type? "=" value
typed value = ":" type "=" value
object = "{" bindings "}"
list = "[" values "]"
tuple = "(" values ")"
node = "<" name attributes? children? ">"
reference = "~" path | "~>" path
```
The full normative grammar belongs in the specs and CTS. This page is the readable map of the moving parts.
<!-- Processing -->
## AEON separates reading, validation, and materialization.
Many parsers effectively read text and produce application objects in one move. AEON splits that path so each stage has a narrow responsibility and the consumer can choose how much to accept for the current context.
```
bytes → tokens → AES → AEOS → meaning validation → Tonic → runtime
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 → schema validation, no mutation or typecasting
meaning → consumer context, domain rules, and policy checks
Tonic → trusted materialization under consumer policy
```
Canonical form is not a required stop between meaning validation and materialization. It is a stable representation that can be produced from the accepted stream when a tool needs comparison, signing, hashing, or reproducible output.
<!-- AES -->
## The Assignment Event Stream is the handoff point between tools.
AEON Core reads source text and emits AES: ordered assignment events with paths, source order, datatype hints, attributes, references, and structure. That stream is the stable layer other processors consume.
```
source text → lexer → parser → AES
AES → AEOS validation
AES → meaning validation
AES → Tonic materialization
AES → canonical representation
AES → prettified AEON source
AES → compact/minified AEON source
```
- **Canonical** Stable equivalence, signatures, hashes, and deterministic comparison.
- **Prettified** Readable source formatting for people and docs.
- **Compact** Smaller transport while preserving the same accepted structure.
Those are projections from the event stream, not different interpretations of the document.
<!-- Annotation Stream -->
## Comments and semantic notes travel beside the assignment stream.
AEON can preserve semantic comments as an annotation stream instead of discarding them or turning them into ordinary data. This gives tools a place for documentation, workflow hints, rendering notes, or domain-specific side languages.
```
source text → AES
↘ annotation stream
AES → data, structure, paths, attributes
annotation stream → comments, semantic notes, tooling hints
```
A consumer that only needs data can ignore the annotation stream. A trusted tool that understands a comment language can opt into it without forcing every AEON processor to execute or interpret that language.
<!-- Meaning Layers -->
## Profiles, schemas, conventions, and Tonics add meaning without blurring authority.
AEON Core preserves structure and claims. Profiles name optional semantic behavior. Schemas validate shape. Conventions define ecosystem agreements. Meaning validation applies consumer context. Tonics materialize domain objects after the consumer has chosen what to trust.
```aeon
aeon:profile = "example.content.v1"
aeon:schema = "example.content.schema.v1"
document:object = {
title:string = "Release notes"
status:toggle = on
}
// The document declares claims.
// The consumer chooses which layers to trust.
```
[Open schemas](/schemas.php)
[Open ecosystem](/ecosystem.php)
<!-- Convention Example -->
## A convention is implemented as ordinary AEON metadata plus a trusted consumer rule.
Temporal data shows the pattern clearly. AEON Core can parse a datetime literal without deciding how every application should handle time zones, daylight-saving ambiguity, calendars, or timezone database drift.
```aeon
aeon:header = {
conventions = [
"aeon.gp.temporal.v1"
]
}
meeting@{
target:string = "zone"
zone:string = "Australia/Melbourne"
calendar:string = "iso8601"
tzdbVersion:string = "2026b"
disambiguation:string = "reject"
}:datetime = 2026-06-06T10:10:00
```
To AEON Core, this is still a binding named meeting with a datetime value and an attribute object. The convention does not add grammar, execute code, or force a runtime object into existence.
- **Declare** The header names aeon.gp.temporal.v1 so tools can see which ecosystem agreement the document is asking for.
- **Preserve** The parser preserves the datetime, attributes, source spans, and canonical path in the assignment stream.
- **Trust** A consumer decides whether that convention identifier maps to a trusted implementation.
- **Interpret** Only after that choice does a Tonic or profile-aware tool apply zone, calendar, tzdbVersion, and disambiguation behavior.
That is how conventions stay powerful without becoming hidden parser behavior: the document can make the claim, but the consumer owns adoption.
[See contracts](/ecosystem.php#contracts)
[Try in playground](/playground.php)
<!-- Philosophy -->
## The parser preserves claims; it does not decide their domain truth.
A value can be syntactically valid, structurally valid, and still fail domain meaning. AEON keeps that distinction visible so a consumer can validate before materializing runtime meaning.
```aeon
temperature:number = 0 // celsius, fahrenheit ?
---
temperature@{unit:string = "celsius"}:number = 0
---
temperature@{unit:string = "fahrenheit"}:number = 32
```
That is the language's deeper stance: keep meaning visible, keep trust explicit, and let each layer prove one thing and nothing more.
[Read philosophy](/philosophy.php)
[Open value types](/value-types.php)
<!-- Next -->
## Use the focused pages when you need a narrower view.
### Read the core authoring forms
_Language Guide_
Bindings, containers, references, nodes, modes, and common grammar shapes in a practical guide.
[Open guide](/language.php)
### Watch a document become trusted
_Processing Walkthrough_
Follow source text through assignment events, schema checks, meaning validation, canonical output, and Tonic materialization.
[Open processing](/walkthrough-processing.php)
### Understand special value features
_Value Types_
Null reasons, NaN, Infinity, prose, encoded values, semantic comments, and zoned round-trip time.
[Open value types](/value-types.php)
### Look up every core value form
_Type Reference_
A concise reference list for syntax, accepted literal values, aliases, and reserved names.
[Open reference](/type-reference.php)