Appendix — Spans

Status: informative summary for consolidated v1

Canonical topic owners: ../AEOS-spec-v1.md, ../comments-annotations-v1.md

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.

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.