# 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. ```ts span: [start, end] ``` - `start` is inclusive - `end` is exclusive - offsets 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: null` is 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. --- ## Related documents - [AEOS Specification v1](./aeos-v1.md) - [AEON v1 Comments and Annotations Reference](./aeon-core-v1-comments-annotations.md) - [Appendix — Error Model](./appendix-error-model-v1.md)