<!-- Why AEON -->

# AEON exists because important documents should not depend on hidden guesses.

## Friendly syntax is useful. Hidden behavior is the problem.

Configuration and document formats often look readable until a tool silently decides what a value means. A word becomes a boolean. A number-looking identifier loses leading zeroes. Duplicate keys disagree across consumers. A schema arrives too late to prevent runtime assumptions.

AEON is a correction to that pattern: make meaning visible, keep trust explicit, validate before materialization, and preserve deterministic processing from source text to runtime use.

The ambition is for those guarantees to hold across implementations, not just inside one parser or one runtime. An AEON document should mean the same thing wherever it is read, validated, canonicalized, and materialized.

[Try the playground](/playground.php)  
[See how it works](/aeon-language.php)  
[Start the walkthrough](/walkthrough.php)

<!-- Pain Points -->

## AEON is aimed at familiar failure modes.

### Readable is not the same as predictable

_Implicit Formats_

YAML and CSV-style convenience can hide coercion or spreadsheet inference behind friendly-looking text. AEON keeps strings, toggles, booleans, dates, numbers, null reasons, NaN, and Infinity visibly distinct.

### Richer meaning needs external machinery

_Bare Data_

JSON is useful, but richer source meaning usually needs schemas, conventions, serializers, or application code around it. AEON lets documents carry visible type and structural claims before a consumer chooses what to trust.

### Structure should not require so much ceremony

_Heavy Documents_

XML can preserve structure, but the cost is often verbosity, namespaces, schemas, and convention-heavy interpretation. AEON keeps common value forms explicit without making the document feel overloaded.

<!-- Examples -->

## Small ambiguities become expensive when systems disagree.

The most painful document bugs are often small: a country code, a duplicate key, a spreadsheet import, a quantity that was meant to stay text. AEON sidesteps these by making each claim explicit.

```aeon
//# A country code stays text.
countryCode:string = "NO"
decision:toggle = no

//# Duplicate keys are rejected instead of guessed.
invoiceId:string = "invoice-100"
invoiceId:string = "invoice-099" // duplicate key; invalid

//# Spreadsheet-shaped values keep their intended form.
sku:string = "00123"
attendees:number = 7_000
shipDate:date = 2026-05-05
```

The same point applies to richer source data. A document can describe values that are often flattened, stringified, or handled by out-of-band conventions in JSON pipelines.

```aeon
//# A value can declare integer intent beyond ordinary JSON number assumptions.
ledgerId:uint64 = 9007199254740993

//# Numeric edge cases and absence reasons stay visible.
sensorReading:nan = NaN
middleName:null = !notSet

//# Collection intent can be carried as a type claim.
roles:set<string> = ["admin", "reviewer"]
limits:map<string, number> = {
  requests:number = 1000
  burst:number = 50
}
```

Custom types can also preserve class-shaped intent without making AEON executable. The document records the state and the requested domain type; a trusted consumer decides whether that maps to a real class.

```aeon
//# A save file can describe a game character without constructing it.
hero:GameCharacter = {
  id:uuid = "7f2a5a1c-0c4d-4f7a-a6b5-4d3d06a7f701"
  name:string = "Alice"
  class:CharacterClass = "patissier"
  level:uint16 = 12
  health:HitPoints = 84
  inventory:set<ItemId> = ["rolling-pin", "sugar-glass", "copper-pan"]
  position:WorldPoint = {
    map:string = "market-quarter"
    x:int32 = 14
    y:int32 = 7
  }
}

//# The document claims GameCharacter.
//# The game runtime decides whether to materialize a Character object.
```

<!-- Stance -->

## AEON treats documents as claims, not authority.

A document may declare a profile, schema, contract, datatype, reference, or intent. Those claims are useful, but they do not authenticate themselves. The consumer brings the trusted registry, policy, schema, and materialization path.

That is why AEON separates source text, AES, AEOS validation, meaning validation, canonical form, and Tonic materialization. Each step has a narrow job, and no step is allowed to silently inherit authority from another.

```aeon
source text → AES → AEOS → meaning validation → canonical form → Tonic

document says: "this is what I claim"
consumer decides: "this is what I trust"
```

Use the language deep dive when you want to learn more about the vocabulary, grammar, processing layers, profiles, schemas, conventions, and Tonics. Use the philosophy deep dive when you want to further understand the security and trust model behind those choices.

[AEON language deep dive](/aeon-language.php)  
[Philosophy deep dive](/philosophy.php)

<!-- Outcome -->

## The result is human-readable data that can still be verified, transformed, signed, and safely materialized.

AEON is not trying to make documents clever. It is trying to make them honest. The file shows what it means to claim, and the surrounding system decides what it means to accept.

That is the difference between a readable file and a trustworthy document boundary.

[Explore capabilities](/capabilities.php)