Appendix — Grammar Flow Cards

Scope: parser-context flow illustrations for AEON Core v1.

This appendix illustrates the legal flow through AEON Core v1 syntax by parser context. It is not a replacement for the AEON Core v1 Structure and Syntax Reference; when this appendix and the structure syntax reference conflict, the structure syntax reference wins.

The key framing is:

• the lexer produces tokens without deciding most structural legality;

• parser contexts decide what may legally follow;

• recovery may produce partial syntax trees, but a parse with errors is not a successful parse unless a recovery surface explicitly says so.

1. Document Flow

Rules:

• shorthand header bindings and structured header bindings are recognized only in the initial header block;

• after the first body binding, aeon:mode = "strict" is parsed as an ordinary typed binding unless another rule rejects it;

• top-level binding keys in one document must be unique after key decoding;

• duplicate top-level keys fail closed with DUPLICATE_KEY.

2. Binding Head Flow

Canonical binding head order is:

key\identity\@{attributes}:type = value

Legal:

a = 1
a\id\ = 1
a@{meta=1} = 1
a:int = 1
a\id\@{meta=1}:int = 1

Illegal:

a@{meta=1}\id\:int = 1
a:int@{meta=1} = 1
a@{x=1}@{y=2} = 1

3. Attribute Entry Flow

Attribute entries reuse the binding-head shape, but live inside @{...}:

a@{entry@{nested=1}:type = value} = payload

Rules:

• duplicate keys inside one attribute map fail closed with DUPLICATE_KEY;

• one nested attribute head is legal when max_attribute_depth allows it;

• repeated heads on one attribute entry are illegal, even when depth is raised;

• key\id\@{...}:type = value is legal; key:type@{...} = value and key@{...}\id\:type = value are not.

Examples:

a@{x=1, y=2} = 3
a@{x@{origin="core"} = 2} = 1

Rejected:

a@{x=1, x=2} = 3
a@{x@{y=1}@{z=2} = 3} = 4
a@{x:int@{y=1} = 2} = 3

4. Type Annotation Flow

Rules:

• binding and attribute-entry type annotations must be followed by =;

• anonymous typed values use :type = value only in list, tuple, and node-child contexts;

• node-head inline datatypes are syntactically narrower than ordinary binding types and accept generic arguments only for :node<T>;

• generic and separator depth policies are enforced by parser options.

5. Value Dispatch

Value starts include:

An identifier by itself is not a value. Use a reference marker for reference values.

6. Container Flow Matrix

Object attachment examples:

x@{meta=1} = { k = 2 }
x = { k@{meta=1} = 2 }

Rejected floating form:

x = { @{meta=1} k = 2 }

7. Node Head Flow

Rules:

• node heads may have one attribute block;

• repeated node head attribute blocks are illegal;

• child-bearing nodes require the final > after the child list closes.

8. Reference Path Flow

Rules:

• $ is the explicit root;

• dot traversal and bracket traversal address data namespace segments;

• .@.key and .@.["key"] address attribute namespace segments;

• empty quoted member segments and empty quoted attribute segments are invalid.

9. Comments And Trivia Flow

Comments are not values, bindings, or separators by themselves.

Examples:

a = 1 // comment
b = 2

The newline after the line comment separates the bindings; the comment itself does not.

a = 1 /* comment */ b = 2

Plain spaces plus a block comment do not create a document binding separator.

10. Ambiguity Checklist

These examples should remain mirrored by implementation tests or CTS cases when the behavior is normative.