AEON Specification v1

Scope: normative overview of AEON Core v1, its boundaries, and the companion reference set.

1. What AEON Is

AEON is a human-readable, typed, semantics-first data notation.

At its core, an AEON document is a sequence of bindings:

key\identity\@{attributes}:type = value

Implementations may accept looser transport forms, but this overview defines the Core v1 model and points to the detailed companion references.

2. Smallest Useful Example

name:string = "AEON"
build:number = 1
active:toggle = on

This demonstrates:

• key/value assignment

• explicit datatype annotation

• deterministic literal interpretation

3. Document Model

AEON Core v1 is built from a small set of structural ideas:

• bindings

• keys

• structural identities

• values

• attributes

• references

• canonical paths

• comments/annotations

Bindings are separated by newline or comma at document/object level and may contain structured values such as objects, lists, tuples, nodes, and references. Structural identities, when present, are head metadata preserved by Core processors without changing canonical path identity.

4. Core Value Families

Core value families include:

• strings

• numbers

• infinity literals

• booleans

• switches

• hex, radix, and encoding literals

• date, time, datetime, and WTC forms

• objects, lists, tuples, and nodes

• clone and alias references

• separator literals

Normative detailed reference:

• value-types-v1

5. Structural Syntax Surface

Core structural syntax includes:

• bare and quoted keys

• attribute blocks

• nested attribute heads

• datatype annotations

• datatype clarifiers

• comma/newline element separation rules

• comma/newline binding rules

Quoted keys are part of Core v1 syntax, but empty quoted keys are invalid.

Normative detailed reference:

• structure-syntax-v1

6. Addressing and References

AEON Core v1 provides:

• canonical path identity using root/member/index segments

• quoted-segment disambiguation

• index-based element addressing

• attribute selectors for attribute-namespace traversal

• deterministic reference legality rules

Reference legality is fail-closed:

• forward references are invalid

• missing targets are invalid

• self-references are invalid

Normative detailed reference:

• addressing-references-v1

7. Comments and Annotation Channels

AEON distinguishes:

• plain comments

• structured annotation channels

• reserved structured channels

Comments do not alter parse semantics, path identity, reference legality, or assignment ordering.

Structured comments may attach deterministically to neighboring targets and may be emitted as a separate annotation stream.

Normative detailed reference:

• comments-annotations-v1

8. Behavior Modes and Datatype Policy

AEON Core v1 defines three behavior modes:

• transport

• strict

• custom

aeon:mode / aeon:header.mode is a declared document mode. It records the author's intended processing discipline, but it is not authoritative over the processor.

Processors apply an effective mode when enforcing mode-dependent rules:

• the effective mode MAY be selected by processor/runtime configuration;

• the effective mode MAY be inferred from the declared document mode when no external policy is supplied;

• processor/runtime configuration MUST remain authoritative when it supplies an effective mode;

• a document-declared mode MUST NOT force a processor to become stricter, looser, or custom-enabled against processor policy.

Effective mode resolution:

Core v1 behavior under the effective mode is:

• transport may omit datatype annotations and accepts custom datatype labels

• strict requires datatype presence and accepts only the reserved Core datatype surface by default

• custom requires datatype presence and accepts custom datatype labels

• explicit datatype annotations are validated in all modes

Implementations MAY still expose an explicit datatype-policy override as an implementation control. Datatype policy applies to the effective mode, not merely to a document-declared mode claim.

Authoritative compliance requirements and behavioral floors are defined in:

• AEON-v1-compliance

9. Deterministic Policy Knobs

Core v1 requires deterministic depth-policy controls for:

• max_attribute_depth

• max_separator_depth

• max_generic_depth

Core v1 also defines an optional event-budget control:

• max_events

Reference implementation defaults lock the depth-policy controls to 1, while conforming implementations must support a capability floor of at least 8.

When max_events is configured, implementations MUST fail closed if the emitted AES event count exceeds the configured value. This limit is a consumer-side resource budget and does not change source syntax or canonical path assignment.

10. Phase Boundaries

AEON Core is responsible for:

• lexical analysis

• parsing

• canonical path assignment

• reference legality

• annotation-stream extraction when enabled

Core does not define downstream application semantics such as:

• domain validation meaning

• profile-specific projection decisions

• schema/business-rule interpretation

AEOS/schema/profile layers build on top of Core rather than redefining it.

Document-declared conventions, profiles, and schemas are advisory until selected or trusted by the consumer/processor. They do not self-activate.

The standard GP security envelope, when used, is convention-driven. It is represented as a normal top-level object binding typed as :envelope rather than a Core-special key:

• aeon.gp.security.v1 defines the envelope structure

• aeon.gp.integrity.v1 defines canonical integrity hashing

• aeon.gp.signature.v1 defines signature representation

• aeon.gp.encryption.v1 defines encryption metadata representation

Header placement is part of Core syntax:

• shorthand header bindings (aeon:mode, aeon:profile, aeon:schema, aeon:version, etc.) form the document header only when they appear in the initial header block at the start of the document;

• a structured header (aeon:header = { ... }) MUST appear before any body binding;

• a structured header that appears after any body binding is invalid.

11. Conformance Surface

Normative conformance requirements are defined in:

• AEON-v1-compliance

• AEOS-spec-v1

• conformance-matrix

CTS protocol and lane baselines:

• cts/protocol/v1

• cts/core/v1

• cts/aes/v1

• cts/annotations/v1

• cts/aeos/v1

Core conformance should be reviewed by backbone behavior family, not only by individual suite file.

Current v1 backbone families are:

• canonical rendering and node normalization

• fail-closed parsing and deterministic rejection behavior

• addressing and canonical path semantics

• quoted-key and traversal disambiguation

• attribute traversal and attribute-depth semantics

• annotation attachment and slash-channel binding

• strict literal acceptance and rejection boundaries

• separator/path literal handling

• datatype-to-literal validation behavior

The anti-drift coverage state for those families is tracked in aeonite-cts/CONFORMANCE-COVERAGE.md.

12. Contracts

Canonical baseline v1 contracts are provided in:

• registry.json

• aeon.gp.profile.v1.aeon

• aeon.gp.schema.v1.aeon

These contracts are authoritative artifacts for the baseline general-purpose profile/schema set. They are official baseline contracts, not implicit defaults when no trusted profile/schema is selected.

13. Companion Reference Set

The official v1 documentation is intentionally split by concern:

• AEON-spec-v1 — overview and boundaries

• AEON-v1-compliance — mandatory conformance requirements

• AEOS-spec-v1 — AEOS validation layer

• value-types-v1 — value families and literal forms

• structure-syntax-v1 — keys, attributes, separators, newline behavior

• addressing-references-v1 — canonical paths and reference rules

• comments-annotations-v1 — comment channels and attachment behavior

• appendices/appendix-directive-block-capabilities — informative v1 reservation for capability-based evolution

This overview should stay short and stable. Detailed syntax, examples, and edge-case rules belong in the companion references.

14. Anti-Drift Requirement

AEON Core conformance is not satisfied by passing a small representative sample.

A conforming implementation must preserve behavior across the Core backbone families named above and their corresponding CTS lanes, especially:

• canonical output and normalization behavior

• fail-closed invalid syntax handling

• canonical path identity and quoted-key disambiguation

• reference legality and attribute traversal behavior

• annotation attachment behavior

• strict literal acceptance and rejection boundaries

Behavior must remain stable across implementations so the canonical backbone of the format does not fragment.