Appendix — Spans
Canonical topic owners: AEOS Specification v1 and AEON v1 Comments and Annotations Reference.
If this appendix conflicts with the canonical v1 spec set, the canonical v1 spec set wins.
1. Definition
A span identifies a source range in the original AEON text.
span: [start, end]startis inclusiveendis exclusiveoffsets are document-level offsets emitted by AEON Core
2. Purpose
Spans provide deterministic source linkage for:
diagnostics
auditing
tooling/editor highlighting
Spans are metadata and do not change AEON semantics.
3. Authority
Spans are produced by AEON Core.
Validators and downstream processors propagate spans.
Validators must not invent replacement spans for existing source-backed values.
4. Required Output Behavior
For AEOS/CTS-style diagnostics:
diagnostics should include a span when the target source region exists
span: nullis allowed only when no source region exists (for example missing required path)
5. Targeting Rule
A span should identify the narrowest source fragment responsible for the diagnostic (for example the offending literal or reference token).
6. Non-Goals
Spans are not:
semantic values
canonical paths
line/column replacements
7. Determinism
Given identical source and policy, diagnostics should carry stable spans.
8. Implementation Note
Current TypeScript implementation emits token positions with line/column plus offset in lexer tokens. Consumers relying on spans should treat AEON Core output as authoritative for unit/offset interpretation.