<!-- AEON System -->

# AEON is a layered declaration ecosystem.

## A declaration is not a runtime object.

Most data formats begin by treating data as an object, tree, map, or document. Useful systems then grow around that foundation: schemas, serializers, runtime mappers, conventions, transforms, and execution surfaces.

Over time those layers can collapse into each other. Structure becomes mixed with meaning. Validation becomes mixed with execution. Metadata becomes mixed with content. Parsing becomes mixed with materialization.

AEON starts from a different premise: a declaration is not the same thing as a runtime object. From that distinction, the rest of the system follows.

[Language layer](#language-layer)  
[AES](#aes)  
[Contracts](#contracts)  
[Processing walkthrough](/walkthrough-processing.php)

<!-- Core Shift -->

## AEON preserves meaning without prematurely executing it.

AEON is not merely a serialization format. It is a layered declaration ecosystem built around deterministic assignment streams.

Rather than collapsing every concern into a single object model, AEON keeps identity, structure, metadata, relationships, validation, interpretation, and materialization as separate responsibilities.

```aeon
source text
  → syntax
  → assignment stream
  → form validation
  → meaning validation
  → materialization
```

Each phase moves forward. No layer quietly rewrites the meaning of an earlier layer.

<!-- Language Layer -->

## Different constructs carry different responsibilities.

Traditional formats often force identity, structure, metadata, and relationships into one structural model. AEON lets them coexist without collapsing into one another.

### Bindings
- **Definition:** map-centric identity and canonical addressing.

### Containers
- **Definition:** object, list, and tuple structure for nested values.

### Nodes
- **Definition:** ordered document-shaped structure for mixed content and markup-like trees.

### Attributes
- **Definition:** hard metadata attached locally to a binding, anonymous value, or node.

### References
- **Definition:** symbolic relationships through clone and pointer references.

### Comments
- **Definition:** soft metadata and annotation channels outside the ordinary value stream.

<!-- Bindings -->

## Bindings create identity.

A binding is not just a surface convenience. It declares that a value is assigned to a canonical path.

```aeon
user:object = {
  name:string = "Patrik"
}

paths:list<string> = [
  "$.user"
  "$.user.name"
]
```

That stable identity gives tools something precise to target: diagnostics, schema rules, references, canonical comparison, hashing, and audit output.

<!-- Containers -->

## Containers organize structure without pretending every shape is a domain object.

Objects, lists, and tuples provide hierarchical structure. They group values, preserve order where order matters, and give authors ordinary document shapes without requiring runtime materialization.

```aeon
config:object = {
  db:object = {
    host:string = "localhost"
  }
  ports:list<number> = [3000, 8080]
  point:tuple = (:number = 12, :number = 42)
}
```

Structure and runtime meaning remain separate. A container can be valid AEON long before a consumer decides what it means inside an application.

<!-- Nodes -->

## Nodes preserve ordered document structure.

Nodes let AEON represent ordered, nested, document-like structures without forcing them into map/list shapes. They are useful for templates, prose-adjacent data, and markup-like content.

```aeon
content:node =
  <paragraph (
    "Hello "
    <strong ("world")>
  )>

template:node =
  <article (
    <h1(~document.title)>
    <p(~document.summary)>
  )>
```

AEON Core preserves the node tree as declared. A Tonic may later materialize it as HTML, Markdown, &ND, a UI component tree, or something domain-specific, but that materialization is an explicit consumer choice.

<!-- Metadata -->

## Attributes and comments are different kinds of side channels.

Attributes are hard metadata: inline, structured, and attached to the thing they qualify. Semantic comments are soft metadata: advisory, annotative, or workflow-oriented side channels that do not become ordinary data bindings.

```aeon
title@{lang:string = "en"}:string = "Hello"

//# User-facing display title
title:string = "Hello"

//@ review.status("draft")
```

This separation lets a document carry provenance, rendering hints, semantic labels, profile hooks, documentation, and governance metadata without flattening all of those roles into content.

<!-- References -->

## References preserve relationships symbolically.

Clone references express value intent. Pointer references express address or identity intent. Keeping that distinction visible lets tools preserve dependency relationships instead of collapsing every reference into a terminal value immediately.

```aeon
db:object = {
  host:string = "localhost"
}

hostCopy:string = ~db.host
activeDb:object = ~>db
```

Indirection itself can be meaningful. Runtime materialization can resolve it later under consumer policy.

<!-- AES -->

## The Assignment Event Stream is the semantic spine.

The center of the AEON ecosystem is not a runtime object. AEON Core produces an ordered stream of assignment events that tools can inspect before meaning is accepted.

```aeon
AEON source
  → lexer
  → parser
  → canonical path resolution
  → AES emission
  → AEOS validation
  → meaning validation
  → Tonic materialization
```

Each event can preserve canonical path, source order, spans, datatype hints, attributes, references, and original structure. That stream becomes the stable handoff point between tools.

<!-- AEOS -->

## AEOS validates form without interpreting meaning.

AEOS answers structural questions: does this path exist, does the value have the expected literal family, does the representation satisfy the schema, and is the document shape acceptable?

It does not coerce values, resolve references, execute processors, or materialize domain objects. That restraint is what makes validation usable as a boundary.

```aeon
schemaCheck:validation = {
  path:string = "$.moon.hoursBeforeMidnight"
  required:boolean = true
  expectedType:string = "IntegerLiteral"
  result:toggle = on
}
```

<!-- Meaning Validation -->

## Sound data still needs contextual understanding.

After AEOS has accepted the representation, a consumer may still need to ask whether the claims make sense in the domain. This layer brings in context, policy, conventions, and application knowledge without making AEOS guess at meaning.

```aeon
patientBodyTemp@{unit:string = "cm"}:float = 99.8

meaningCheck:validation = {
  path:string = "$.patientBodyTemp"
  representation:toggle = on
  issue:string = "body temperature uses a length unit"
  expectedUnit:list<string> = ["celsius", "fahrenheit"]
  result:toggle = no
}
```

The value can be syntactically valid and structurally acceptable while still being wrong for the consumer. Meaning validation is where those domain contradictions are flagged before a Tonic creates runtime objects.

<!-- Tonics -->

## Materialization happens after representation and meaning are accepted.

A Tonic is a deterministic materializer that consumes AES, optionally relies on AEOS and meaning-validation guarantees, and creates a chosen output: a runtime object, graph, UI tree, exported file, minimized form, domain class, or rendered document.

```aeon
accepted:AES
  → Greeting tonic
  → runtime Greeting object

accepted:AES
  → Template tonic
  → rendered HTML

accepted:AES
  → Audit tonic
  → signature report
```

Transformation belongs at the edge of the system, not at the center.

<!-- Channels -->

## The ecosystem keeps channels distinct.

### AEON
- **Definition:** human-readable declaration language.

### AES
- **Definition:** canonical assignment event stream and tool handoff surface.

### AEOS
- **Definition:** schema and form validation.

### Meaning Validation
- **Definition:** consumer-owned context checks over otherwise sound AEON claims.

### Canonical Form
- **Definition:** stable representation for comparison, signing, hashing, and reproducible processing.

### Annotation Stream
- **Definition:** structured semantic commentary and consumer-defined side-channel languages.

### &ND
- **Definition:** native documentation language in the broader AEON ecosystem.

### NEON
- **Definition:** text/binary hybrid transport in the broader AEON ecosystem.

<!-- Contracts -->

## Schemas, profiles, and conventions answer different questions.

The ecosystem has multiple contract types because not every promise is the same kind of promise.

### Schemas
- **Definition:** form validation contracts: is this structurally acceptable?

### Profiles
- **Definition:** interpretation contracts: how should this be interpreted if the consumer trusts the profile?

### Conventions
- **Definition:** shared ecosystem contracts: what assumptions do compatible tools agree to use?

A document can declare a schema, profile, or convention. The consumer still decides whether that declaration maps to something trusted.

```aeon
meeting@{
  target:string = "zone"
  zone:string = "Australia/Melbourne"
  tzdbVersion:string = "2026b"
}:datetime = 2026-06-06T10:10:00
```

For example, the temporal convention treats these attributes as a shared interpretation agreement. AEON Core keeps them as ordinary metadata; a trusted temporal-aware consumer decides whether and how to apply them.

[See temporal example](/aeon-language.php#temporal-convention)

<!-- Tolerance -->

## AEON is human-friendly at the surface and hostile to semantic ambiguity.

AEON can permit multiple deterministic surface representations when they produce the same unambiguous structure.

```aeon
a:list<number> = [
  1
  2
  3
]

b:list<number> = [1, 2, 3]
```

But that tolerance stops before semantics. AEON rejects hidden coercion, runtime guessing, parser-specific repair heuristics, and invisible interpretation.

<!-- Conclusion -->

## AEON serializes declarations, not premature runtime meaning.

Most formats serialize values. AEON serializes declarations. AES becomes the stable semantic ledger. AEOS constrains representations. Meaning validation applies consumer context. Tonics materialize accepted meaning. Materialization happens last.

The system remains deterministic because each layer knows exactly what it is allowed to do, and what it must never do.

AEON describes. AEOS validates form. Consumers validate meaning. Tonics materialize. Meaning is deferred until explicitly requested.

[Open processing walkthrough](/walkthrough-processing.php)  
[Open annotations](/walkthrough-annotations.php)