&ND v2

+++document/meta
schemaVersion = "1"
id = "aeon-core-v1-comments-annotations"
title = "AEON v1 Comments and Annotations Reference"
description = "Reference for comment forms, structured channels, reserved meanings, deterministic attachment, and annotation-related boundaries."
family = "aeon"
group = "Core References"
standing = "official"
lifecycle = "published"
normativity = "normative"
license = "CC-BY-4.0"
path = "specification/aeon-v1-documentation/aeon-v1-comments-and-annotations-reference"
order = 60
publish = true
keywords = ["AEON", "comments", "annotations", "structured channels", "attachment", "host directives"]
related = ["aeon-core-v1", "aeon-v1-conformance-matrix", "aeos-v1"]
+++


# AEON v1 Comments and Annotations Reference [# aeon-v1-comments-and-annotations-reference]

Scope: comment forms, structured channels, reserved meanings, and deterministic attachment behavior.


## 1. Comment Families [# comment-families]

AEON v1 recognizes two broad families:

1. Plain comments
  - line: [$ // ...]
  - block: [$ /* ... */]
  - file-header shebang: [$ #!...] on line 1, column 1 only

2. Structured comments
  - line channels: [$ //#], [$ //@], [$ //?], [$ //!], [$ //{], [$ //\[], [$ //(]
  - block channels: [$ /# ... #/], [$ /@ ... @/], [$ /? ... ?/], [$ /{ ... }/], [$ /\[ ... \]/], [$ /( ... )/]

Core rule:

- comments are trivia and do not alter parse semantics, canonical path assignment, or reference legality.


## 2. Channel Catalog [# channel-catalog]


### 2.1 Plain [# plain]

Forms:

~~~$ aeon
// plain
/* plain */
~~~$

Meaning:

- human-facing commentary only;
- not emitted into the structured annotation stream.


### 2.2 Documentation Channel [# documentation-channel]

Forms:

~~~$ aeon
//# docs
/# docs #/
~~~$

Annotation kind:

- [$ doc]

Intended use:

- documentation for nearby binding, element, or container target.


### 2.3 Annotation Channel [# annotation-channel]

Forms:

~~~$ aeon
//@ env(selected=true)
/@ env(selected=true) @/
~~~$

Annotation kind:

- [$ annotation]

Intended use:

- machine-readable metadata annotations attached to nearby targets.


### 2.4 Hint Channel [# hint-channel]

Forms:

~~~$ aeon
//? threshold: number = [>=0], [<=1]
/? threshold: number = [>=0], [<=1] ?/
~~~$

Annotation kind:

- [$ hint]

Intended use:

- schema/profile/editor hints or human-readable guidance associated with a nearby target.


### 2.5 Host Channel [# host-channel]

Line form:

~~~$ aeon
//! host-runtime-note
~~~$

Placement rule:

- [$ //!] is a file-header host directive only;
- it must appear on line 1, column 1;
- if a leading shebang line is present, it may instead appear on line 2, column 1;
- outside that slot, [$ //!] is treated as a plain line comment and has no host-directive meaning.

Shebang rule:

- [$ #!...] is accepted as a plain file-header comment only on line 1, column 1;
- one leading UTF BOM may appear before that file-header slot and is ignored for this purpose;
- outside that exact position, [$ #!] is not a comment introducer and is tokenized normally.

Annotation kind in lexer metadata:

- [$ host]

Current v1 emission note:

- host-channel comments are recognized by the lexer;
- they are not emitted into the structured annotation stream by the current reference implementation.

Fast-path format note:

- before Phase 1 parsing, implementations may expose a lightweight preflight/file-preamble inspection API that reads
  only the allowed shebang/host-directive slot;
- that preflight inspection must ignore at most one leading UTF BOM before any further detection;
- after BOM removal, a shebang is recognized only on the first physical line;
- [$ //! format:<id>] may appear only in the file-header slot: on the first physical line after BOM removal, or on the
  second physical line when the first is a shebang;
- [$ //! format:<id>] is a tooling side-channel for processor discovery and pre-parser routing only;
- it does not create bindings, does not modify header fields, and must not appear in AES, annotation-stream output, or
  canonical output.

Directive-block reservation note:

- future AEON lines may define a broader directive block using strict [$ //! key:value] lines for capability-based
  evolution;
- in v1, that broader block is reserved and non-operational;
- v1 processors MUST NOT activate [$ require], [$ feature], [$ profile], or [$ comment.*] semantics from [$ //!]
  comments;
- see [@ document:appendix-directive-block-capabilities-v1 | [$ appendices/appendix-directive-block-capabilities]] for
  the informative upgrade strategy.


### 2.6 Reserved Channels [# reserved-channels]

Forms:

~~~$ aeon
//{ structure
//[ profile
//( instructions

/{ structure }/
/[ profile ]/
/( instructions )/
~~~$

Annotation kind:

- [$ reserved]

Reserved subtypes:

- [$ structure]
- [$ profile]
- [$ instructions]

Current meaning:

- reserved namespace for standardized ecosystem/documentation use;
- must not change core parse or reference behavior.


## 3. Non-Influence Rule [# non-influence-rule]

Comments and annotations must not:

- create or remove bindings;
- change canonical path identity;
- change reference legality;
- change assignment ordering;
- act as list, tuple, node, or binding separators.

Implication:

- comments may appear between tokens and still attach to nearby targets;
- they do not redefine the grammar around them.


## 4. Attachment Targets [# attachment-targets]

Structured comments may attach to:

- a canonical path target;
- a span-only target when no canonical path target exists;
- an unbound status when nothing valid is available.

Target preference order:

1. [$ path]
2. [$ span]
3. [$ unbound]

Unbound reasons:

- [$ eof]
- [$ no_bindable]


## 5. Deterministic Attachment Rules [# deterministic-attachment-rules]

The current official v1 reference behavior is:

1. If the comment is inside a containing bindable span, try to attach to the nearest descendant target.
2. If no contained descendant wins, attach to the containing target itself.
3. Otherwise, prefer the nearest trailing same-line target.
4. Otherwise, prefer the nearest forward target.
5. If no path target exists, try the same logic with span-only bindables.
6. If nothing is available, mark the annotation unbound.

This produces deterministic results for prefix, postfix, infix, and standalone structured comments.


## 6. Neighbor Attachment Cases [# neighbor-attachment-cases]


### 6.1 Trailing Same-Line [# trailing-same-line]

~~~$ aeon
a = 1 //? required
~~~$

Attaches to:

~~~$ aeon
$.a
~~~$

Rule:

- same-line trailing structured comments bind to the completed assignment immediately before them.


### 6.2 Standalone Forward [# standalone-forward]

~~~$ aeon
//# docs
a = 1
~~~$

Attaches to:

~~~$ aeon
$.a
~~~$

Rule:

- standalone structured comments bind forward to the next available bindable target.


### 6.3 Infix Container Comment [# infix-container-comment]

~~~$ aeon
a = [1, /? in-list ?/ 2]
~~~$

Attaches to:

~~~$ aeon
$.a[1]
~~~$

Rule:

- when a comment sits inside a container between elements, the binder prefers the nearest indexed descendant rather than
  the container path itself.


### 6.4 Postfix and Prefix Element Comments [# postfix-and-prefix-element-comments]

~~~$ aeon
a = [1 /# post #/, /# pre #/ 2]
~~~$

Attaches to:

- [$ /# post #/] [>] [$ $.a\[0\]]
- [$ /# pre #/] [>] [$ $.a\[1\]]

Rule:

- postfix comments bind to the nearest completed element;
- prefix comments bind to the nearest following element.


### 6.5 EOF Unbound [# eof-unbound]

~~~$ aeon
a = 1
//# tail
~~~$

Attaches to:

~~~$ aeon
unbound(eof)
~~~$

Rule:

- if no forward bindable target exists after a standalone structured comment, it is unbound.


### 6.6 No Bindable Document [# no-bindable-document]

~~~$ aeon
//@ lonely
~~~$

Attaches to:

~~~$ aeon
unbound(no_bindable)
~~~$

Rule:

- if the document yields no bindable targets at all, structured comments are unbound.


## 7. Container Fallback [# container-fallback]

If a structured comment is contained within a bindable span and no nearer descendant target is valid, it may attach to
the containing target.

Practical effect:

- comments inside empty or non-indexed containers can fall back to the container assignment target.


## 8. Source Order and Emission [# source-order-and-emission]

Structured annotation records are emitted in source order.

Current reference implementation behavior:

- emits [$ doc], [$ annotation], [$ hint], and [$ reserved];
- skips [$ plain] and [$ host] during annotation-stream emission.


## 9. Form Preservation [# form-preservation]

Annotation stream records preserve:

- [$ kind]
- [$ form] ([$ line] or [$ block])
- raw source text
- source span
- resolved target

Reserved channels also preserve subtype:

- [$ structure]
- [$ profile]
- [$ instructions]


## 10. Newline and Block Behavior [# newline-and-block-behavior]

Rules:

- line comments terminate at newline;
- block comments may span newlines;
- unterminated block comments are a lexer error;
- comments are never newline substitutes or grammar separators by themselves.


## 11. Minimum Conformance Reminders [# minimum-conformance-reminders]

Implementations targeting the v1 annotation model must at minimum:

- recognize the official structured channel forms;
- preserve line vs block form in annotation records;
- attach deterministically using the official target preference order;
- preserve reserved subtypes;
- fail with deterministic unterminated block-comment diagnostics.