<!-- Generated from sources/contracts/v1/contracts-v1.aeon; do not edit. -->

<a id="aeon-v1-contracts-specification"></a>
# AEON v1 Contracts Specification

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

<a id="contract-layer-purpose"></a>
## 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

<a id="canonical-baseline-contracts"></a>
## 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:

- [`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)
- [`registry.json`](/artifacts/assets/contracts/v1/registry.json)

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.

<a id="boundary-model"></a>
## 3. Boundary Model

Authority split:

1. AEON Core
   
   - lexing
   - parsing
   - canonical path assignment
   - reference legality
   - mode/datatype enforcement at the Core layer
2. contract/profile/schema layer
   
   - published profile and schema contract identifiers
   - structural validation model and allowed contract metadata
   - trusted resolution policy
3. 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.

<a id="contract-artifact-format"></a>
## 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

<a id="profile-contract-shape"></a>
## 5. Profile Contract Shape

Canonical top-level keys for a profile contract:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `profile_id` | yes | string | contract identifier |
| `profile_version` | yes | string | semver for the published artifact |
| `core_id` | yes | string | target Core specification line |
| `description` | no | string | human-readable summary |
| `mode_default` | no | string | published default mode |
| `datatype_policy_default` | no | string | published default datatype policy |
| `collections` | yes | object\<string, collection\> | normative GP semantics for collection shapes |
| `containers` | yes | object\<string, container\> | normative GP semantics for object/node shapes |
| `datatype_semantics` | yes | object\<string, datatype semantics\> | normative GP semantics for datatype-family interpretations |
| `capabilities` | yes | object\<string, boolean\> | required processor support for GP profile claims |

*Profile contract top-level keys*

`collection` records use these canonical keys:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `ordered` | yes | boolean | whether family semantics treat element order as meaningful |
| `heterogeneous` | yes | boolean | whether elements may have different value/datatype shapes |
| `unique` | yes | boolean | whether duplicate elements are disallowed by the family |
| `fixed_length` | yes | boolean | whether arity is intrinsic to the family |

*Profile collection record keys*

`container` records use shape-specific canonical keys.

For `object`:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `ordered` | yes | boolean | whether member order is semantically significant |
| `heterogeneous` | yes | boolean | whether member values may have different value shapes |
| `unique_keys` | yes | boolean | whether member keys are unique within one object scope |

*Object collection fields*

For `node`:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `ordered` | yes | boolean | whether child order is semantically significant |
| `heterogeneous` | yes | boolean | whether children may have different value shapes |
| `unique_attributes` | yes | boolean | whether attribute keys are unique within one attribute block |
| `mixed_content` | yes | boolean | whether children may mix scalar and structural value shapes |

*Node collection fields*

`capabilities` records use these canonical keys:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `references` | yes | boolean | whether reference syntax support is required |
| `clones` | yes | boolean | whether clone-reference support is required |

*Profile capability record keys*

`datatype_semantics` records use these canonical keys:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `literal_family` | yes | string | AES literal family to which the datatype semantics apply |
| `clarifiers` | yes | string | profile-owned clarifier validation and interpretation: `none`, `radix_base`, `separator_chars`, or `encoding_name` |
| `alias_of` | no | string | canonical datatype family when this entry is an alias |
| `equivalent_to` | no | string | canonical datatype expression for fixed-shape aliases |

*Datatype-semantics record keys*

Datatype clarifier syntax itself remains a Core transport property. The
validation and interpretation of `radix[16]` as a radix base or `sep["."]` as
separator characters is a profile, schema, or processor concern and is made
explicit by this table. When `aeon.gp.profile.v1` is active, this table is
closed for clarifier-bearing datatype surfaces: a datatype not listed here must
not carry clarifiers, and an entry with `clarifiers = "none"` must not carry an
explicit clarifier list. `radix_base` requires exactly one integral numeric
clarifier from `2` through `64`. `separator_chars` requires one or more string
clarifiers. `encoding_name` requires exactly one string clarifier.

Current baseline profile artifact:

```aeon
profile_id = "aeon.gp.profile.v1"
profile_version = "1.0.0"
core_id = "aeon.core.v1"
description = "General-purpose AEON profile baseline for v1."
mode_default = "strict"
datatype_policy_default = "reserved_only"
collections = {
  list = {
    ordered = false
    heterogeneous = true
    unique = false
    fixed_length = false
  }
  tuple = {
    ordered = true
    heterogeneous = true
    unique = false
    fixed_length = true
  }
}
containers = {
  object = {
    ordered = false
    heterogeneous = true
    unique_keys = true
  }
  node = {
    ordered = true
    heterogeneous = true
    unique_attributes = true
    mixed_content = true
  }
}
datatype_semantics = {
  radix = {
    literal_family = "RadixLiteral"
    clarifiers = "radix_base"
  }
  decimal = {
    literal_family = "RadixLiteral"
    clarifiers = "none"
    equivalent_to = "radix[10]"
  }
  sep = {
    literal_family = "SeparatorLiteral"
    clarifiers = "separator_chars"
  }
  separator = {
    literal_family = "SeparatorLiteral"
    clarifiers = "separator_chars"
    alias_of = "sep"
  }
  kadot = {
    literal_family = "SeparatorLiteral"
    clarifiers = "none"
  }
  encoding = {
    literal_family = "EncodingLiteral"
    clarifiers = "encoding_name"
  }
  inline = {
    literal_family = "EncodingLiteral"
    clarifiers = "encoding_name"
  }
  embed = {
    literal_family = "EncodingLiteral"
    clarifiers = "encoding_name"
  }
}
capabilities = {
  references = true
  clones = true
}
```

Interpretation:

- this artifact defines the published GP baseline defaults once `aeon.gp.profile.v1` is explicitly selected by trusted policy;
- it fixes the GP collection meanings for `list` and `tuple`;
- it fixes the GP container meanings for `object` and `node`;
- it fixes GP datatype semantics for radix-family and separator-family reserved labels;
- it fixes the required processor capabilities for implementations claiming `aeon.gp.profile.v1` support;
- `collections` is closed for `aeon.gp.profile.v1`: only `list` and `tuple` have GP v1 collection semantics. Future profiles may define additional collection names without changing this artifact;
- `containers` is closed for `aeon.gp.profile.v1`: only `object` and `node` have GP v1 container semantics. Future profiles may define additional container names without changing this artifact;
- profile collection and container semantics are keyed by canonical family name. Alternative or reserved datatype names inherit the semantics of their canonical family, for example `obj`, `o`, and `envelope` inherit `object`;
- profile datatype semantics are keyed by canonical datatype family name. `radix` validates and interprets exactly one integral numeric clarifier from `2` through `64` as a radix base when the GP profile is active. `decimal` is a fixed GP alias for `radix[10]` and does not accept explicit clarifiers. `sep` and `separator` validate and interpret string clarifiers as separator characters. `kadot` carries unparameterized separator-family intent and does not accept explicit clarifiers, with stricter payload shape checks supplied by schema rules when required. `encoding`, `inline`, and `embed` validate and interpret exactly one string clarifier as an encoding-name claim;
- Core-only processing preserves datatype clarifiers but does not activate radix-base validation, separator splitting, separator ordering, or domain-specific separator meaning merely because the clarifier text is present;
- `capabilities` is closed for `aeon.gp.profile.v1`: only `references` and `clones` are defined as GP v1 capability requirements by this artifact;
- `capabilities.references = true` and `capabilities.clones = true` mean implementations claiming GP profile support must support those features. They do not require every GP document to use references or clones;
- profile collection and container semantics do not override schema constraints. For example, `list.heterogeneous = true` permits mixed element shapes by default, while a schema can still constrain a particular binding with `list<int32>` or other element rules;
- `indexed` is intentionally absent because index-addressability is a Core representation guarantee. AEON Core always emits index-addressable list/tuple elements and node child slots; the profile decides whether those positions carry semantic meaning;
- `ordered` defines whether lexical element order is semantically significant. AEON Core always preserves lexical source order and emits index-addressable elements irrespective of the selected collection semantics;
- `object.ordered = false` means object member order is not semantically significant in the GP profile. AEON Core may still preserve source order for diagnostics, AES emission, and canonicalization inputs;
- `node.ordered = true` means node child positions are semantically significant. AEON Core preserves node child order and exposes child slots with index-addressable paths;
- `unique_keys` and `unique_attributes` record GP uniqueness semantics; Core duplicate-key checks remain Core representation guarantees and are not delegated to materializers;
- materialization properties such as mutability, storage layout, allocation strategy, capacity, contiguous or linked storage, thread safety, lazy evaluation, persistence, sortedness, hash backing, and language-specific collection types belong to tonics or host bindings rather than this GP baseline profile;
- it does not cause GP behavior to become active merely because no profile is declared.

<a id="schema-contract-shape"></a>
## 6. Schema Contract Shape

Canonical top-level keys for a schema contract:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `schema_id` | yes | string | contract identifier |
| `schema_version` | yes | string | semver for the published artifact |
| `rules` | yes | list | schema rule list consumed by AEOS |
| `world` | no | `open` or `closed` | schema-wide unexpected-binding policy |
| `datatype_allowlist` | no | list\<string\> | allowed datatype labels for schema-side datatype constraints |
| `datatype_rules` | no | object\<string, constraints\> | datatype-wide GP semantics keyed by datatype base label |

*Schema contract top-level keys*

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

Schema `rules` use the AEOS `SchemaRule` shape. Each rule identifies targets
with exactly one `path` or `selector` and a `constraints` object. Programmatic
contract payloads carry `path` and `selector` as strings. Native AEON schema
authoring SHOULD encode those targets as SANSA literals, such as
`path:sansa = $.contact.name` or `selector:sansa = $.items.*.sku`, before
projection into the in-memory AEOS schema object.

Current baseline schema artifact:

```aeon
schema_id = "aeon.gp.schema.v1"
schema_version = "1.0.0"
world = "open"
rules = []
datatype_rules = {
  int = { type = "IntegerLiteral" }
  uint = { type = "IntegerLiteral", sign = "unsigned" }
  int8 = { type = "IntegerLiteral", min_value = "-128", max_value = "127" }
  int16 = { type = "IntegerLiteral", min_value = "-32768", max_value = "32767" }
  int32 = { type = "IntegerLiteral", min_value = "-2147483648", max_value = "2147483647" }
  int64 = { type = "IntegerLiteral", min_value = "-9223372036854775808", max_value = "9223372036854775807" }
  uint8 = { type = "IntegerLiteral", sign = "unsigned", min_value = "0", max_value = "255" }
  uint16 = { type = "IntegerLiteral", sign = "unsigned", min_value = "0", max_value = "65535" }
  uint32 = { type = "IntegerLiteral", sign = "unsigned", min_value = "0", max_value = "4294967295" }
  uint64 = { type = "IntegerLiteral", sign = "unsigned", min_value = "0", max_value = "18446744073709551615" }
  float = { type = "FloatLiteral" }
  float32 = { type = "FloatLiteral" }
  float64 = { type = "FloatLiteral" }
}
```

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.

<a id="canonical-schema-metadata-key-table"></a>
## 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`

<a id="canonical-registry-document-shape"></a>
## 8. Canonical Registry Document Shape

Registry root shape:

```json
{
  "contracts": [
    {
      "id": "aeon.gp.profile.v1",
      "kind": "profile",
      "version": "1.0.0",
      "path": "profiles/aeon.gp.profile.v1.aeon",
      "sha256": "…",
      "status": "active"
    }
  ]
}
```

Registry entry keys:

| Key | Required | Type | Meaning |
| :--- | :--- | :--- | :--- |
| `id` | yes | string | contract identifier |
| `kind` | yes | `profile` or `schema` | contract kind |
| `version` | yes | string | artifact semver |
| `path` | yes | string | trusted artifact path |
| `sha256` | yes | string | integrity hash for the target artifact |
| `status` | yes | `active` or `deprecated` | publication state |
| `compat` | no | object | optional compatibility metadata |

*Canonical registry entry keys*

<a id="resolution-algorithm"></a>
## 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

<a id="diagnostics-surface"></a>
## 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.

<a id="runtime-and-cli-injection"></a>
## 11. Runtime and CLI Injection

Two trusted usage models are valid:

1. registry/allowlist resolution
   
   - typical CLI/operator path
2. 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.

<a id="typescript-profile-position"></a>
## 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.

<a id="support-claims"></a>
## 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.

---

## Related documents

- [v1 Contract Artifacts](./contracts-artifacts-overview.md)
- [AEON Specification v1](./aeon-core-v1.md)
- [AEOS Specification v1](./aeos-v1.md)
- [Official v1 Index](./aeon-v1-official-index.md)
- [AEON v1 Release Governance](./aeon-v1-release-governance.md)