AEON v1 Comments and Annotations Reference

Status: official v1 companion reference Scope: comment forms, structured channels, reserved meanings, and deterministic attachment behavior.

1. Comment Families

AEON v1 recognizes two broad families:

1. Plain comments

• line: // ...
• block: /* ... */
• file-header shebang: #!... on line 1, column 1 only

1. 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

2.1 Plain

Forms:

Meaning:

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

2.2 Documentation Channel

Forms:

Annotation kind:

• doc

Intended use:

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

2.3 Annotation Channel

Forms:

Annotation kind:

• annotation

Intended use:

• machine-readable metadata annotations attached to nearby targets.

2.4 Hint Channel

Forms:

Annotation kind:

• hint

Intended use:

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

2.5 Host Channel

Line form:

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 appendices/appendix-directive-block-capabilities.md for the informative upgrade strategy.

2.6 Reserved Channels

Forms:

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

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

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

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

7.1 Trailing Same-Line

Attaches to:

Rule:

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

7.2 Standalone Forward

Attaches to:

Rule:

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

7.3 Infix Container Comment

Attaches to:

Rule:

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

7.4 Postfix and Prefix Element Comments

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.

7.5 EOF Unbound

Attaches to:

Rule:

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

7.6 No Bindable Document

Attaches to:

Rule:

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

7. 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

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

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

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

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.