AEON v1 Contracts Specification

Status: official v1 contract specification Scope: contract-layer identifiers, contract artifact shapes, trusted registry format, resolution algorithm, and authority boundaries for AEON v1.

1. Contract Layer Purpose

The contract layer tells a processor which published profile/schema contract a document claims to target.

It is distinct from:

• the AEON language version
• implementation package versions
• consumer-specific business logic

2. Canonical Baseline Contracts

The canonical general-purpose baseline contracts for AEON v1 are:

• profile contract: aeon.gp.profile.v1
• schema contract: aeon.gp.schema.v1

Baseline artifacts:

• profile artifact
• schema artifact
• registry

These baseline contracts are official and published, but they are not implicit defaults. When no trusted external selection chooses a profile/schema, Core-only processing defaults apply.

3. Boundary Model

Authority split:

1. AEON Core

• lexing
• parsing
• canonical path assignment
• reference legality
• mode/datatype enforcement at the Core layer

1. contract/profile/schema layer

• published profile and schema contract identifiers
• structural validation model and allowed contract metadata
• trusted resolution policy

1. consumer layer

• allowlist/registry policy
• direct runtime object injection
• business/domain meaning beyond the published contract surface

Documents do not control the consumer. Header contract identifiers are routing hints only. Document-declared contract identifiers do not self-activate.

4. Contract Artifact Format

Authoritative contract artifacts are AEON files.

Rules:

• registry path values MUST point to .aeon authoritative artifacts
• derived JSON snapshots MAY exist for tooling, but are non-authoritative
• contract authority resides in the AEON source artifact, not a derived format

5. Profile Contract Shape

Canonical top-level keys for a profile contract:

Current baseline profile artifact:

Interpretation:

• this artifact defines the published GP baseline defaults once aeon.gp.profile.v1 is explicitly selected by trusted policy;
• it does not cause GP behavior to become active merely because no profile is declared.

6. Schema Contract Shape

Canonical top-level keys for a schema contract:

Rules:

• only these canonical metadata keys are valid in v1.0.0
• unknown top-level metadata keys fail closed
• transitional aliases are not allowed in v1.0.0
• if world is omitted, AEOS treats the schema as open
• the published aeon.gp.schema.v1 artifact declares world = "open" explicitly so the GP baseline policy is visible in the artifact itself

Current baseline schema artifact:

This artifact is the normative GP semantic layer for the reserved numeric datatype labels. Implementations MUST NOT claim GP schema support unless they honor these datatype rules substantively.

7. Canonical Schema Metadata Key Table

Locked canonical schema metadata keys:

1. schema_id
2. schema_version
3. rules
4. optional world
5. optional datatype_allowlist
6. optional datatype_rules

8. Canonical Registry Document Shape

Registry root shape:

Registry entry keys:

9. Resolution Algorithm

Trusted resolution algorithm:

1. read the document-declared contract ID
2. treat it as a hint only
3. look up the ID in a trusted local registry or allowlist
4. reject unknown IDs
5. resolve the trusted artifact path
6. verify the artifact exists
7. verify the artifact hash before load
8. parse the authoritative AEON contract artifact
9. validate canonical contract shape
10. continue with Core/AEOS processing

Fail-closed conditions:

• unknown ID
• missing artifact
• hash mismatch
• malformed contract document
• non-canonical metadata keys

10. Diagnostics Surface

Representative contract-resolution diagnostics:

• CONTRACT_UNKNOWN_PROFILE_ID
• CONTRACT_UNKNOWN_SCHEMA_ID
• CONTRACT_ARTIFACT_MISSING
• CONTRACT_ARTIFACT_HASH_MISMATCH

Representative schema-contract shape failures:

• missing canonical required fields
• unknown canonical metadata key
• contract ID mismatch between registry entry and loaded artifact

Diagnostics surfaces SHOULD preserve stable semantic code values and MAY attach phase metadata for display and tooling:

• phase when the producing pipeline phase is explicit
• phaseLabel when a stable human-readable phase name is available

Human-facing CLI output SHOULD prefer readable phase labels such as Reference Validation or Schema Validation over raw numeric phase bands.

11. Runtime and CLI Injection

Two trusted usage models are valid:

1. registry/allowlist resolution

• typical CLI/operator path

1. direct caller injection

• runtime APIs may accept schema/profile objects directly from the consumer
• CLI may accept explicit operator-supplied paths

In both cases, trust is established by the caller context, not by the document being consumed.

12. TypeScript Profile Position

The TypeScript-specific profile surface is an extension profile, not the language-neutral baseline.

Public baseline claims should point to:

• aeon.gp.profile.v1
• aeon.gp.schema.v1

TS-specific behavior may be published separately, but it must not redefine AEON Core v1 or the general-purpose baseline contracts.

13. Support Claims

Implementations may claim support at different layers:

1. Core-only support
2. Core + GP baseline support
3. Core + GP + additional contract support

Core conformance does not require GP support. However, any implementation claiming support for aeon.gp.profile.v1 or aeon.gp.schema.v1 MUST honor those contracts substantively rather than treating the IDs as decorative.