<!-- Generated from sources/appendices/v1/appendix-processing-model.aeon; do not edit. -->

<a id="appendix-processing-model"></a>
# Appendix — Processing Model

**Appendix to:** AEON Specification v1

Canonical topic owners: AEON Specification v1 and AEOS Specification v1.

This appendix is an orientation aid for the v1 processing pipeline. Canonical phase ownership lives in the top-level v1 specs and compliance documents.
If this appendix conflicts with the canonical v1 spec set, the canonical v1 spec set wins.

This appendix illustrates AEON's conceptual processing phases, Assignment Events, processor selection boundaries, tuple/indexed-path support, and annotation stream emission.

> [!WARNING]
> **v1 Baseline Surfaces**
>
> Tuple literal parsing (`TupleLiteral`), indexed path segment assignment (`[n]`), annotation stream record emission, and indexed reference targets are part of the consolidated v1 surface described by the canonical specs.

<a id="processing-phases"></a>
## 1. Processing Phases

Implementations should read these phases as a conceptual pipeline. Normative phase ownership and conformance requirements live in the canonical v1 specs and compliance documents.

```

┌─────────────────────────────────────────────────────────────────────────┐
│ Phase 1: Lexing                                                         │
│   Input → Tokens; classify comment channel prefixes                     │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 2: Structural Parse                                               │
│   Tokens → AST (objects, lists, tuples, scalars, bindings)              │
│   v1: emit TupleLiteral for (...) forms                                 │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 3: Canonical Path Resolution                                      │
│   Each node assigned a canonical path ($.foo.bar)                       │
│   v1: assign indexed segments to list/tuple elements ($.foo[0])         │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 4: Assignment Event Emission                                      │
│   Exactly one event per binding                                         │
│   v1: emit annotation stream records for structured comments            │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 5: Profile Interpretation                                         │
│   Processors invoked, datatype hints interpreted                        │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 6: Schema Validation                                              │
│   Constraints evaluated, violations reported                            │
│   v1: tuple constraints (TYPE_IS, LENGTH_EXACT, per-position)           │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 7: Reference Evaluation                                           │
│   References resolved to values or aliases                              │
│   v1: indexed path targets resolved ($.a[1])                            │
├─────────────────────────────────────────────────────────────────────────┤
│ Phase 8: Finalization                                                   │
│   Final document model materialized                                     │
└─────────────────────────────────────────────────────────────────────────┘
```

*Figure 1: AEON processing phases*

<a id="assignment-events"></a>
## 2. Assignment Events

<a id="definition"></a>
### 2.1 Definition

AEON projects each represented value occurrence into the transport-neutral
event model defined by [`aes.events.v1`](./aes-events-v1.md). Named
bindings, anonymous structural children, attribute entries, and node heads
can therefore each produce flat events.

<a id="required-fields"></a>
### 2.2 Portable fields

Every portable body event has `path` and `kind`. Scalar and other valued
kinds also have `value`. `datatype`, `identity`, `origin`, and `span`
are optional under their AES rules. `key`, nested AST values, attached
annotation maps, and raw source lexemes are not portable AES fields.

Attributes use ordinary flat descendant events below the owner's `.@`
address space. Structural children use indexed descendant events. Containers
and node literals do not embed their descendants.

<a id="example"></a>
### 2.3 Example

```aeon
p@{style = #FF0000}:point = { x = 23, y = 3 }
```

Portable body events include:

```text
path=$.p
kind=ObjectNode
datatype=point

path=$.p.@.style
kind=HexLiteral
value=ff0000

path=$.p.x
kind=NumberLiteral
value=23

path=$.p.y
kind=NumberLiteral
value=3
```

<a id="tuple-example-v1-baseline"></a>
### 2.4 Tuple Example (v1 baseline)

```aeon
score:tuple<string,int32> = ("alice", 95)
```

```text
path=$.score
kind=TupleLiteral
datatype=tuple<string,int32>

path=$.score[0]
kind=StringLiteral
value=alice

path=$.score[1]
kind=NumberLiteral
value=95
```

<a id="uniqueness-const-semantics"></a>
## 3. Uniqueness (Const Semantics)

AEON documents are immutable by construction:

- For any canonical path, there MUST be **at most one** Assignment Event
- Duplicate path bindings MUST raise an error
- No implicit override, merge, or replacement semantics

<a id="annotation-stream-emission-v1-baseline"></a>
## 4. Annotation Stream Emission (v1 baseline)

Annotation stream records are emitted in Phase 4, in parallel with Assignment Events. They do NOT appear in the AES.

See *Appendix: Annotation Stream* for record format and binding rules.

**Key invariants:**

- Annotation stream emission MUST NOT affect AES contents
- AES with all comments stripped MUST equal AES with comments present
- Annotation stream records are source-ordered

<a id="processor-registry"></a>
## 5. Processor Registry

<a id="definition-2"></a>
### 5.1 Definition

A **Processor** is a deterministic transformation function applied to Assignment Events.

<a id="design-principles"></a>
### 5.2 Design Principles

1. **No implicit execution** — Documents cannot invoke processors directly
2. **Profile-scoped authority** — Only the active profile enables processors
3. **Determinism** — Same input produces identical output
4. **No structural mutation** — Processors cannot add/remove nodes
5. **Explicit phase boundary** — Processors run in Phase 5 only

<a id="processor-binding"></a>
### 5.3 Processor Binding

Profiles declare processors bound to:

- Datatype hints (e.g., `point` → `geom.point`)
- Annotation keys (e.g., `style:color` → `core.hex`)
- Canonical paths

<a id="invocation"></a>
### 5.4 Invocation

During Phase 5, for each Assignment Event:

1. Profile determines applicable processors
2. Processors invoked in deterministic order
3. Each processor receives the event and current value
4. Processor may validate, transform, or attach metadata

<a id="processor-input"></a>
### 5.5 Processor Input

Processors receive:

- `path` — canonical path
- `value` — current value (may be `ListNode` or `TupleLiteral` in v1)
- `datatype` — if present
- `annotations` — if present

<a id="processor-output"></a>
### 5.6 Processor Output

Processors MAY:

- Return a transformed value
- Return the same value unchanged
- Raise a validation error

Processors MUST NOT:

- Return multiple values
- Alter the canonical path
- Emit new Assignment Events

<a id="reference-evaluation-phase"></a>
## 6. Reference Evaluation Phase

<a id="binding-visibility-rule"></a>
### 6.1 Binding Visibility Rule

A binding becomes eligible as a reference target **only after** its Assignment Event has been committed.

Self-references (e.g., `a = ~a`) are therefore invalid.

<a id="no-forward-references"></a>
### 6.2 No Forward References

References MUST target paths already bound earlier in the document.

The no-forward rule applies **independently per namespace** (data and attribute).

<a id="indexed-reference-targets-v1-baseline"></a>
### 6.3 Indexed Reference Targets (v1 baseline)

In v1 mode, references may target indexed paths:

```aeon
items  = (10, 20, 30)
second = ~items[1]     // clone of element at $.items[1]
```

Resolution proceeds using the same no-forward rule (referenced indexed path must be already bound).

<a id="resolution-semantics"></a>
### 6.4 Resolution Semantics

| Operator | Behavior |
| :--- | :--- |
| `~` (clone) | Resolve terminal value, copy |
| `~>` (pointer) | Return alias to named binding |

*Reference-resolution operators*

<a id="cycles"></a>
### 6.5 Cycles

Because AEON forbids forward references, cycles are unrepresentable.

<a id="error-reporting"></a>
## 7. Error Reporting

Diagnostics should reference:

- Canonical path
- Span (when available)
- Phase where error occurred

Example:

```

Error: Unknown processor "geom.point"
Path: $.p
Phase: Profile Interpretation
```

---

## Related documents

- [AEON Specification v1](./aeon-core-v1.md)
- [AEON Core v1 Compliance Specification](./aeon-core-v1-compliance.md)
- [AEOS Specification v1](./aeos-v1.md)
- [Portable AES Event Contract v1](./aes-events-v1.md)