# 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: ```aeon 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 ```aeon 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`](./aeon-core-v1-value-types.md) ## 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`](./aeon-core-v1-structure-syntax.md) ## 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`](./aeon-core-v1-addressing-references.md) ## 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`](./aeon-core-v1-comments-annotations.md) ## 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: | Declared `aeon:mode` | External effective mode | Resulting effective mode | | --- | --- | --- | | absent | absent | `transport` | | `transport` | absent | `transport` | | `strict` | absent | `strict` | | `custom` | absent | `custom` | | any value | `transport` | `transport` | | any value | `strict` | `strict` | | any value | `custom` | `custom` | *AEON 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`](./aeon-core-v1-compliance.md) ## 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`](./aeon-core-v1-compliance.md) - [`AEOS-spec-v1`](./aeos-v1.md) - [`conformance-matrix`](./aeon-v1-conformance-matrix.md) 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`](/artifacts/assets/contracts/v1/registry.json) - [`aeon.gp.profile.v1.aeon`](/artifacts/assets/contracts/v1/profiles/aeon.gp.profile.v1.aeon) - [`aeon.gp.schema.v1.aeon`](/artifacts/assets/contracts/v1/schemas/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`](./aeon-core-v1.md) — overview and boundaries - [`AEON-v1-compliance`](./aeon-core-v1-compliance.md) — mandatory conformance requirements - [`AEOS-spec-v1`](./aeos-v1.md) — AEOS validation layer - [`value-types-v1`](./aeon-core-v1-value-types.md) — value families and literal forms - [`structure-syntax-v1`](./aeon-core-v1-structure-syntax.md) — keys, attributes, separators, newline behavior - [`addressing-references-v1`](./aeon-core-v1-addressing-references.md) — canonical paths and reference rules - [`comments-annotations-v1`](./aeon-core-v1-comments-annotations.md) — comment channels and attachment behavior - [`appendices/appendix-directive-block-capabilities`](./appendix-directive-block-capabilities-v1.md) — 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. --- ## Related documents - [AEON Core v1 Compliance Specification](./aeon-core-v1-compliance.md) - [AEOS Specification v1](./aeos-v1.md) - [AEON v1 Conformance Matrix](./aeon-v1-conformance-matrix.md) - [AEON v1 Structure Syntax Reference](./aeon-core-v1-structure-syntax.md) - [AEON v1 Addressing, SANSA Literals, and References Reference](./aeon-core-v1-addressing-references.md) - [AEON v1 Comments and Annotations Reference](./aeon-core-v1-comments-annotations.md) - [AEON v1 Value Types Reference](./aeon-core-v1-value-types.md) - [AEON v1 Release Governance](./aeon-v1-release-governance.md) - [Official v1 Index](./aeon-v1-official-index.md) - [AEON v1 Contracts Specification](./aeon-v1-contracts.md) - [Appendix — Canonical AEON Form](./appendix-canonical-form-v1.md) - [Appendix — Assignment Event Stream (AES)](./appendix-aes-v1.md) - [Appendix — Processing Model](./appendix-processing-model-v1.md)