AEOS Specification v1

Status: official v1 normative spec Scope: AEOS validation contract, active schema model, result envelope, and phase authority boundaries for AEON v1.

1. What AEOS Is

AEOS is the schema and representation-validation layer for AEON.

AEOS operates on AES, not on raw source text. It validates representational form and schema-declared constraints after AEON Core has already completed:

• lexing
• parsing
• canonical path assignment
• reference legality

AEOS does not redefine Core behavior. It consumes Core output.

2. Authority Boundary

2.1 AEON Core Owns

AEON Core is authoritative for:

• lexical validity
• syntax validity
• canonical path assignment
• quoted-key and path disambiguation
• reference legality
• missing targets
• forward references
• self-references
• mode/datatype enforcement at the Core layer

AEOS must not repeat or reinterpret those checks as if they were schema failures.

2.2 AEOS Owns

AEOS is authoritative for:

• rule-index validation
• presence checks
• representational type checks
• reference-form constraints on Core-emitted reference kinds
• reference-target constraints on Core-emitted target paths
• container-kind and arity checks
• numeric lexical-form checks
• string length and pattern checks
• datatype allowlist membership checks when configured in schema
• bounded resolved-endpoint validation when explicitly enabled by schema
• result-envelope emission

2.3 AEOS Does Not Own

AEOS must not:

• coerce values
• inject defaults
• mutate AES
• execute schema-side code
• impose domain/business semantics beyond the active schema constraint surface

Exception:

• when the active schema explicitly declares exact numeric bounds such as min_value or max_value,

AEOS may compare numeric magnitudes to enforce those declared constraints.

• when a rule declares resolve_reference_form: true, AEOS may follow a bounded reference chain

structurally in order to validate the terminal literal form against the referencing path. This does not transfer Core legality ownership, mutate AES, or authorize schema inheritance from the referenced path.

3. Inputs

AEOS validator input consists of:

• AES
• SchemaV1
• optional validator options

3.1 AES Input

AEOS consumes AES events keyed by canonical paths.

Relevant AEOS assumptions:

• canonical path is authoritative;
• datatype may be present or absent;
• value.type carries the Core-emitted literal/container/reference kind;
• span may be present as Core span data or tuple form.

Reference-bearing AES events may still be present in the stream, but AEOS treats their legality as already decided by Core. AEOS may validate schema constraints against the emitted reference kind, but it must not reinterpret missing-target, forward-reference, or self-reference conditions as schema failures.

3.2 Schema Contract Boundary

There are two schema layers to distinguish:

1. Contract document layer

• used by CLI/runtime contract loading
• canonical authoring form is an AEON .aeos document with top-level binding aeos:schema
• canonical path for the contract object is $.aeos
• the binding at $.aeos MUST carry datatype/type annotation schema
• canonical document fields:
• id
• version
• rules
• optional world
• optional reference_policy
• optional datatype_allowlist
• optional datatype_rules
• authoring-oriented helper fields may also appear at this layer so long as they are projected away before validation
• example: reference_target_path

1. Document header schema declaration layer

• used by documents that declare intended schema contracts in aeon:header
• canonical fields:
• schema
• optional schemas
• schema is singular and identifies the primary schema id declared by the document producer
• schemas is an optional object mapping named contexts to additional declared schema associations
• recommended reserved keys:
• authoring
• validation
• recommended custom keys use identifier-safe names with _ separators
• example: vendor_acme
• schemas entries are named associations, not cumulative instructions
• header schema declarations are descriptive metadata only; they do not dictate consumer processing behavior
• a consumer MAY choose to apply schema, MAY choose a context-specific entry from schemas, MAY ignore the declaration entirely, or MAY enforce a local schema instead
• when a consumer does select among declared header schema ids, schema is the default fallback when no context-specific association is used

1. In-memory SchemaV1 validator layer

• the object actually consumed by validate(aes, schema, options)
• current shipped validator shape:

The .aeos contract wrapper is handled before AEOS validation begins. AEOS validation itself operates on the in-memory schema object. Loaders MUST parse the .aeos file as AEON, materialize the object at $.aeos, validate the document contract, and project it into SchemaV1 before invoking validate(aes, schema, options). Document header schema declarations are a separate concern from .aeos schema documents: they identify which schema id the document declares for a given context, but they do not change the runtime SchemaV1 shape and they do not prescribe how any consumer must process the document.

4. Active Schema Model

4.1 SchemaV1

Current normative validator model:

4.2 SchemaRule

Rules are keyed by canonical path strings.

4.3 ConstraintsV1

Active shipped constraint surface:

Unknown constraint keys are schema errors.

Additional schema-surface notes:

• reference_policy?: 'allow' | 'forbid' is a schema-wide form control.
• .aeos is the canonical authoring extension for schema documents; SchemaV1 remains the canonical runtime object.
• reference and reference_kind constrain Core-emitted reference kinds without resolving them.
• reference_kind is valid only when reference: 'require'.
• reference_target_path is the preferred .aeos authoring constraint for target-domain matching.
• reference_target_pattern constrains the canonical target path declared by a reference.
• resolve_reference_form is boolean and opt-in.
• reference_target_pattern and resolve_reference_form are invalid when paired with reference: 'forbid'.
• resolve_reference_form is invalid when the rule still expects a reference type such as CloneReference

or PointerReference.

• attributes defines recursive constraints over attribute-entry payloads carried on AES events.
• closed_attributes is local to the current attribute object and rejects unknown attribute-entry keys.

5. Constraint Semantics

5.1 required

required: true means the canonical path must exist in AES.

Failure diagnostic:

• missing_required_field

Missing-path diagnostics use span: null.

5.2 type

type checks Core-emitted value kind.

Representative accepted names include:

• StringLiteral
• BooleanLiteral
• NullLiteral
• NumberLiteral
• IntegerLiteral
• FloatLiteral
• ObjectNode
• ListNode
• TupleLiteral
• CloneReference
• PointerReference

Current aliasing behavior:

• NumberLiteral satisfies NumberLiteral
• IntegerLiteral and FloatLiteral are distinguished from the raw numeric lexical form

Failure diagnostics:

• type_mismatch
• tuple_element_type_mismatch for indexed tuple/list element paths

Reference-form notes:

• type: CloneReference requires a clone reference at the constrained path.
• type: PointerReference requires a pointer reference at the constrained path.

5.3 attributes

attributes applies nested ConstraintsV1 rules to attribute entries attached to the constrained AES event.

This applies equally to:

• ordinary binding attributes
• anonymous child attributes on indexed AES paths such as $.values[0] and $.page[0]

Example:

5.4 closed_attributes

closed_attributes: true means the current attribute object admits only the attribute keys named in the nested attributes map.

Unknown attribute-entry keys are validator failures.

5.5 Attribute datatype-rule inheritance

When an attribute entry carries a datatype label and the active schema defines datatype_rules for that datatype, those datatype rules apply to the attribute entry by default.

Nested attributes.<key> constraints remain authoritative when they are more specific than inherited datatype rules.

• reference: 'require' accepts either CloneReference or PointerReference.
• reference: 'forbid' rejects both CloneReference and PointerReference.
• reference_kind: 'clone' | 'pointer' | 'either' refines reference: 'require' without evaluating the target.
• reference_policy: 'forbid' rejects reference-bearing AES events schema-wide.

5.3 reference_target_pattern

Target-domain constraint for reference-bearing paths:

Behavior:

• applies only to Core-emitted CloneReference and PointerReference events;
• validates the canonical target path string declared by the reference;
• does not resolve the referenced value;
• uses canonical formatting for quoted members, indexes, and attribute segments before matching.

Failure diagnostic:

• reference_target_mismatch

Schema-validation failures:

• invalid_reference_constraint for non-string patterns, invalid regexes, or contradictory combinations.

Authoring note:

• .aeos documents SHOULD prefer reference_target_path where the allowed target domain can be expressed

as a path selector such as $.ages[*].

• Loaders MUST project that selector into an equivalent internal target-matching form before AEOS validation.

5.4 resolve_reference_form

Opt-in resolved-endpoint validation:

Behavior:

• when true, AEOS may follow a bounded reference chain from the constrained path to its terminal literal endpoint;
• literal-form constraints such as type, min_value, max_value, min_length, max_length, pattern,

and datatype-rule checks apply to the resolved terminal literal form;

• reference-form constraints such as reference, reference_kind, and reference_target_pattern continue to

apply to the original reference event at the constrained path;

• AEOS does not mutate AES, inherit target-path schema obligations, or reinterpret Core legality failures.

Boundary notes:

• missing targets, forward references, self-references, and other Core legality failures remain Core-owned;
• cyclic or otherwise unresolvable chains do not become new AEOS schema errors merely because

resolve_reference_form is enabled;

• resolved-endpoint validation is bounded and deterministic.

Schema-validation failures:

• invalid_reference_constraint for non-boolean values or contradictory combinations.

5.5 type_is

Container kind constraint:

Behavior:

• list accepts ListNode / ListLiteral
• tuple accepts TupleLiteral

Failure diagnostic:

• wrong_container_kind

5.6 length_exact

Exact container arity constraint for tuple/list style containers.

Failure diagnostic:

• tuple_arity_mismatch

5.7 Numeric Form Constraints

Numeric lexical-form constraints:

• sign
• min_digits
• max_digits
• min_value
• max_value

Behavior:

• applies only to numeric literal forms;
• uses lexical representation for sign and digit-count checks;
• uses numeric magnitude only when min_value or max_value are explicitly declared;
• integer digit count excludes sign.

Failure diagnostic:

• numeric_form_violation

5.8 String Form Constraints

String constraints:

• min_length
• max_length
• pattern

Length semantics:

• measured in UTF-16 code units (JavaScript string.length)

Pattern semantics:

• ECMAScript regex strings
• full-string match semantics
• if anchors are omitted, AEOS adds ^ and $

Failure diagnostics:

• string_length_violation
• pattern_mismatch

5.9 datatype

Datatype constraint is a label-presence check only.

It does not perform semantic subtype reasoning. It validates the declared datatype string carried by AES when the rule requests one.

5.10 datatype_allowlist

Optional schema-level allowlist:

Behavior:

• if present, any rule using constraints.datatype must reference an allowed datatype string;
• this is membership checking only.

Failure diagnostic:

• datatype_allowlist_reject

5.11 world

Optional schema-level world policy:

Behavior:

• open is the default;
• open validates declared schema rules and ignores unexpected AES binding paths;
• closed rejects any non-header AES binding path not explicitly covered by schema.rules;
• rejection happens before downstream materialization is trusted.

Failure diagnostic:

• unexpected_binding

5.12 datatype_rules

Optional schema-level datatype semantics:

Behavior:

• keys are datatype base labels such as uint, int32, or float64;
• when an AES event carries a matching declared datatype, the mapped constraints are applied in addition to any path rule;
• this is how aeon.gp.schema.v1 makes reserved numeric labels operational without moving those semantics into Core.

Typical uses:

• uint => type = "IntegerLiteral", sign = "unsigned"
• int32 => type = "IntegerLiteral", min_value = "-2147483648", max_value = "2147483647"
• float32 => type = "FloatLiteral"

6. Validation Phases

Current shipped validator phases:

1. Envelope plumbing
2. Baseline invariants
3. Rule-index build / schema-shape validation
4. Presence checks
5. Type and reference checks
6. Container-kind checks
7. Numeric form checks
8. String form and pattern checks
9. Datatype allowlist enforcement during rule indexing
10. World-policy enforcement
11. Datatype-rule enforcement
12. Guarantees emission

6.1 Baseline Invariants

Active baseline checks include:

• duplicate AES binding paths
• invalid index segment shape in canonical paths
• optional trailing separator-delimiter policy

Active baseline checks do not include reference-legality validation. Missing targets, forward references, and self-references remain Core-owned even when reference events are present in AES.

Failure diagnostics include:

• duplicate_binding
• invalid_index_format
• trailing_separator_delimiter

7. Result Envelope

AEOS produces exactly one output shape.

Normative rules:

• ok is true only when errors.length === 0
• warnings do not flip ok to false
• envelope must not include AES input
• diagnostics use canonical path strings
• phase is currently fixed to schema_validation

7.1 Tooling Metadata Is Separate

Consumer tools may wrap AEOS results in larger command or editor payloads. Those wrappers are not part of the core ResultEnvelope contract.

In particular:

• CLI or editor output may expose declared contract metadata read from aeon:header
• runtime bind flows may expose both declared and applied contract ids
• such metadata is consumer/tooling provenance, not AEOS validator state

One valid tooling pattern is:

Interpretation:

• declared reflects producer-declared header metadata only
• applied reflects the contract ids actually selected by the consumer
• inspect-style read-only surfaces may expose only declared
• bind-style runtime surfaces may expose both declared and applied

8. Guarantees

AEOS guarantees are advisory representation tags keyed by canonical path.

Current shipped guarantees include tags such as:

• present
• integer-representable
• float-representable
• boolean-representable
• non-empty-string

Guarantees are emitted only on passing envelopes.

9. Validator Options

Current shipped validator options:

9.1 strict

Reserved for future AEOS-specific behavior.

Current validator does not materially change rule semantics based on this flag.

9.2 trailingSeparatorDelimiterPolicy

Optional policy for separator literal payloads ending in a declared separator.

Modes:

• off (default): ignore
• warn: emit warning
• error: emit error

This policy does not change Core parsing semantics.

10. Diagnostics

Current standard AEOS diagnostic codes include:

10.1 Baseline / Schema

• duplicate_binding
• rule_missing_path
• duplicate_rule_path
• unknown_constraint_key
• invalid_reference_constraint

10.2 Presence / Type / Container

• missing_required_field
• type_mismatch
• wrong_container_kind
• tuple_arity_mismatch
• tuple_element_type_mismatch
• invalid_index_format
• reference_forbidden
• reference_required
• reference_kind_mismatch
• reference_target_mismatch

10.3 Numeric / String / Datatype

• numeric_form_violation
• string_length_violation
• pattern_mismatch
• datatype_allowlist_reject
• trailing_separator_delimiter
• constraint_inapplicable

Vendor-prefixed diagnostics may use:

Reference-legality diagnostics such as missing-target, forward-reference, and self-reference failures belong to Core/AES, not to AEOS.

11. CLI / Runner Adapter

The shipped AEOS CTS adapter:

• reads JSON from stdin
• expects { aes, schema, options }
• writes ResultEnvelope JSON to stdout

The adapter is read-only and must not mutate validator behavior.

12. CTS Mapping

AEOS conformance should be reviewed by behavior family rather than by isolated test file.

Current v1 behavior-family anchors:

• result-envelope and validator output contract
• cts/aeos/v1/suites/00-envelope.json
• baseline invariants and Core-versus-AEOS authority boundary
• cts/aeos/v1/suites/01-baseline.json
• schema rule-index integrity
• cts/aeos/v1/suites/02-schema-rules.json
• presence and forbid semantics
• cts/aeos/v1/suites/03-presence.json
• representational type and datatype-label constraints
• cts/aeos/v1/suites/04-type.json
• cts/aeos/v1/suites/08-datatype-labels.json
• reference-form, reference-target, and resolved-reference constraints
• cts/aeos/v1/suites/16-reference-forms.json
• cts/aeos/v1/suites/17-reference-targets.json
• cts/aeos/v1/suites/18-resolved-reference-form.json
• cts/aeos/v1/suites/19-reference-security.json
• numeric lexical-form constraints
• cts/aeos/v1/suites/05-numeric-form.json
• string length and pattern constraints
• cts/aeos/v1/suites/06-string-form.json
• cts/aeos/v1/suites/07-pattern.json
• guarantee emission
• cts/aeos/v1/suites/09-guarantees.json
• container-kind and tuple-arity constraints
• cts/aeos/v1/suites/10-container-kinds.json
• cts/aeos/v1/suites/11-tuple-arity.json
• indexed-path validation and tuple positional checks
• cts/aeos/v1/suites/12-tuple-positional.json
• cts/aeos/v1/suites/13-indexed-path-validation.json
• separator-literal policy enforcement
• cts/aeos/v1/suites/14-separator-literal-policy.json
• structural container item validation
• cts/aeos/v1/suites/15-structural-container-items.json

Protocol governance:

• cts/protocol/v1/runner-contract.md
• cts/protocol/v1/lane-aeos.md

12.1 Mapping rule

When AEOS CTS grows, new suites should strengthen one of the behavior families above or introduce a newly documented AEOS behavior family explicitly.

AEOS CTS should not expand as an unclassified test pile.

13. Conformance Notes

A conforming AEOS v1 implementation must:

• consume canonical Core/AES output rather than redefining Core semantics;
• support the active SchemaV1 constraint surface documented here;
• emit the canonical ResultEnvelope shape;
• preserve deterministic canonical-path diagnostics;
• fail closed on validation errors.

13.1 Anti-drift requirement

AEOS conformance is not satisfied by passing only representative examples.

An implementation must preserve behavior across the AEOS validation families defined in this document and their corresponding CTS lanes, especially:

• schema rule validation
• presence checks
• type and datatype-label enforcement
• reference-form, reference-target, and resolved-reference enforcement
• numeric and string-form constraints
• container and indexed-path validation
• separator policy enforcement
• result-envelope and guarantee behavior

Core-owned semantics must remain Core-owned. AEOS must not reinterpret Core legality failures as schema-validation failures.