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

<a id="appendix-tonic-processor-governance"></a>
# Appendix — Tonic Processor Governance

**Appendix to:** AEON Specification v1

This appendix defines the canonical terminology for AEON's downstream materialization processor (Tonic), the phase boundary contract, reference policies, and determinism requirements.

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

This appendix covers downstream processor guidance and terminology.
If this appendix conflicts with the canonical v1 spec set, the canonical v1 spec set wins.

<a id="terminology"></a>
## 1. Terminology

**Tonic** is the canonical term for the downstream processor that consumes the Assignment Event Stream (AES) and materializes it into a runtime or domain representation.

- Previous terminology: "Elixir" — **deprecated**
- Public external naming: `AEON Tonic`
- Transitional aliases for the deprecated term are permitted for one major release cycle, with warnings

<a id="pipeline-contract"></a>
## 2. Pipeline Contract

```
Text → AEON Core → AES → AEOS (optional) → Tonic → Runtime
```

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  AEON Core  │ →  │     AES     │ →  │    AEOS     │ →  │    Tonic    │ →  │   Runtime   │
│  (Parse)    │    │  (Output)   │    │ (Optional)  │    │(Materialize)│    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
```

*Figure 1: AEON materialization pipeline*

Key invariants:

- Tonic consumes AES, never raw text
- Tonic operates after AEOS validation (if any)
- Tonic does not re-enter the AEON Core parse phase
- The pipeline is strictly ordered and fail-closed

<a id="tonic-responsibilities"></a>
## 3. Tonic Responsibilities

A Tonic MAY:

- Perform domain materialization (e.g., AEON → TypeScript object)
- Apply policy-driven runtime shaping
- Resolve references according to its declared reference mode
- Apply profile-specified processors
- Materialize references more conservatively than authorial intent when explicitly configured by the consumer/profile

A Tonic MUST NOT:

- Re-parse raw AEON text
- Mutate the AES
- Rewrite canonical paths
- Suppress core diagnostics
- Introduce implicit semantics based on document content

<a id="host-object-materialization-safety"></a>
### 3.1 Host-Object Materialization Safety

AEON member names are inert data at the Core and AES layers. A Tonic that
materializes those names into host-language objects MUST account for the target
runtime's object model.

Host-object materialization MUST prevent source-controlled AEON names from
mutating, shadowing, or escaping into host object metadata, prototypes,
constructors, reflection surfaces, magic attributes, framework control fields,
or equivalent host-specific authority surfaces.

Acceptable strategies include:

- map-like containers whose keys are always data;
- null-prototype or otherwise plain-data containers in runtimes with ambient
  prototype inheritance;
- fail-closed rejection of host-dangerous names;
- reversible escaping of host-dangerous names;
- schema-driven allowlists before materialization.

JavaScript-family Tonics MUST specifically defend against prototype pollution
through `__proto__` and `constructor.prototype` paths when projecting AEON data
into ordinary objects. Treating only `__proto__` as dangerous is insufficient
when `constructor` and `prototype` can still be used together to reach an
ambient prototype.

This requirement does not make those names invalid AEON member names. It applies
only when a Tonic, finalizer, binding adapter, or export path gives those names
meaning in a host runtime.

<a id="transitive-materialization-boundary"></a>
### 3.2 Transitive Materialization Boundary

A Tonic's own implementation language may be safe while its output is later
consumed by a less safe host runtime. For example, a Rust or PHP processor can
emit JSON that is inert in that processor but later merged into an ordinary
JavaScript object by a browser or Node.js application.

Processors that export AEON-derived names across a declared or reasonably
expected downstream host boundary SHOULD document whether target-runtime
dangerous names are preserved, escaped, rejected, or emitted only as inert
transport data. A processor MUST NOT claim an output is safe for a target host
object model unless it has applied an appropriate host-object safety strategy
for that target.

<a id="leap-second-materialization-policy"></a>
### 3.3 Leap Materialization and Gap Policies

The expanded policy vocabulary in this subsection is a draft `0.14.0` addition pending final specification review.

A leap-aware Tonic materializing a positive leap second into a non-leap-aware runtime MUST declare one of these export policies. `preserve` is available when the target itself is leap-aware:

| Policy | Required behavior |
| :--- | :--- |
| `preserve` | Retain the leap-aware value when the target supports it |
| `reject` | Fail rather than materialize a leap-second instant in the target |
| `foldPrevious` | Map second `60` onto second `59` while retaining the fractional position, colliding with the previous ordinary second |
| `foldNext` | Map second `60` onto the following ordinary second while retaining the fractional position, colliding with that second |
| `clampDown` | Map the entire leap interval to the greatest target-representable value before the leap boundary |
| `clampUp` | Map the entire leap interval to the first target-representable value after the leap boundary |
| `smear` | Transform through a named and sufficiently specified smear algorithm and interval |

*Leap-second export policies*

`reject` is lossless and fail-closed. Fold and clamp policies are explicitly lossy and may collapse multiple source claims into one target value. Both clamp directions depend on target precision, and a bare `clamp` policy is insufficient. `smear` changes the coordinate during the smear interval and requires policy identity and conversion data.

An authority-declared negative leap gap first maps to `zero` candidates and then uses a separate materialization policy family: `reject`, `null`, `previousValid`, `nextValid`, or `preserveClaim`. `previousValid` and `nextValid` explicitly transform to the nearest valid target coordinate on the corresponding side of the missing interval. `null` returns a reason-bearing typed null. `preserveClaim` retains the unresolved authored fields. These transformations are distinct from `earlier` and `later`, which select existing candidates after an ambiguous `many` mapping. A negative smear belongs to source or destination clock realization rather than resolution of an already-authored missing coordinate.

Import and export policies MUST be declared separately. A known smear can be inverted only when the algorithm, interval, direction, and required authority data are available. A folded or clamped value is not uniquely invertible; source provenance can expose the loss but cannot necessarily reconstruct an exact position within the leap second. A Tonic MUST preserve that result as ambiguous or unresolved, or reject it, rather than invent an instant.

Rejecting literal second `60` at a schema boundary does not prove that accepted `00-59` timestamps are aligned with unsmeared UTC. Source values may originate from POSIX or smeared clocks while carrying nominal UTC fields. `clockModel` and `smearPolicy` metadata are authored claims. Tonics SHOULD preserve and expose them when present, but MUST defer conversion to explicit trusted source, authority, and destination configuration rather than treating document metadata as executable authority.

<a id="determinism-requirements"></a>
## 4. Determinism Requirements

A Tonic MUST be deterministic:

**Given identical AES + configuration, Tonic output and diagnostics MUST be identical.**

Prohibited implicit dependencies:

- Current time or date
- Random values
- Network state
- Filesystem state (unless explicitly configured and stable)
- Process environment (beyond declared configuration)

<a id="reference-policy-modes"></a>
## 5. Reference Policy Modes

Each Tonic explicitly declares one reference mode:

| Mode | Behavior |
| :--- | :--- |
| `preserve` | References are kept as symbolic tokens in output (default) |
| `alias` | References create named aliases in runtime representation |
| `inline` | References are resolved and values are inlined (explicit opt-in only) |

*Tonic reference policy modes*

Reference mode MUST be declared in Tonic configuration, not inferred from document content.

DoS budgets are mandatory for non-trivial resolution behavior (particularly `alias` and `inline` modes).

Interpretation rule:

- AES remains the source of truth for authorial reference intent.
- Consumer/profile configuration decides how that intent is materialized at runtime.
- Runtime materialization policy may be more conservative than authorial intent, but the original reference kind must remain observable from AES.

Recommended budget dimensions include:

- maximum resolved/materialized node count
- maximum inline/reference depth
- maximum cumulative materialized weight for clone expansion

<a id="reference-diagnostic-transparency"></a>
### 5.1 Reference Diagnostic Transparency

Reference diagnostics MUST include:

- Origin anchor (the path of the reference source)
- Target anchor (the path being referenced)

<a id="two-stage-hook-model"></a>
## 6. Two-Stage Hook Model

Tonics that support processing hooks MUST follow a two-stage model:

<a id="stage-a-validate-plan"></a>
### Stage A: Validate / Plan

- No mutation
- Produce diagnostics and an action plan

<a id="stage-b-apply-materialize"></a>
### Stage B: Apply / Materialize

- Deterministic mutation allowed
- Apply action plan in fixed order

**Fail-closed invariant:** Stage B is skipped entirely if Stage A produces errors.

<a id="hook-precedence"></a>
### 6.1 Hook Precedence

When multiple hook types could match a binding:

1. Key/path hook (highest specificity)
2. Datatype hook
3. Auto-hook
4. Baseline handler

Hooks may defer to the next precedence level.

<a id="null-universe"></a>
## 7. Null Universe

Configurable null behavior is a Tonic policy decision, not a Core semantics decision.

Supported null modes (Tonic-declared):

- `void` — Value is absent/undefined
- `null` — Explicit `null` value (language-specific)
- `undefined` — Language-level undefined

The mode MUST be declared in Tonic configuration and applied consistently.

<a id="authority-boundary"></a>
## 8. Authority Boundary

| Layer | Responsibility |
| :--- | :--- |
| AEON Core | Parse, emit AES, assign canonical paths |
| AEOS | Structural validation (form-level constraints) |
| Tonic | Semantic interpretation, materialization, runtime shaping |

*Tonic authority boundaries*

AEOS remains a form validator. Semantic interpretation and materialization policy belong to Tonic.

This means:

- AEON documents may declare reference intent;
- AEOS may constrain reference form;
- Tonic still has final authority over runtime interpretation and cost controls.

<a id="compatibility-governance"></a>
## 9. Compatibility Governance

- Public documentation and conformance claims should use `Tonic`.
- Implementations may support deprecated `Elixir` aliases as a local compatibility policy.
- Implementations using deprecated terminology should emit deprecation warnings.
- Deprecated aliases must not change processor behavior or conformance claims.

<a id="related-v1-sections"></a>
## 10. Related v1 Sections

- AEON Specification v1 (core language boundary and conformance)
- AEOS Specification v1 (schema/validation boundary)
- Appendix — Processing Model (phase and processor model)
- Appendix — Error Model (diagnostics and fail-closed behavior)

---

## Related documents

- [AEON Specification v1](./aeon-core-v1.md)
- [AEOS Specification v1](./aeos-v1.md)
- [Portable AES Event Contract v1](./aes-events-v1.md)
- [AEON GP Temporal v1](./aeon-gp-temporal-v1.md)
- [Appendix — Processing Model](./appendix-processing-model-v1.md)
- [Appendix — Profiles Framework](./appendix-profiles-framework-v1.md)