Appendix: Grammar Flow Cards

Status: informative companion appendix 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 ../structure-syntax-v1.md; 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:

Legal:

Illegal:

3. Attribute Entry Flow

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

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@{...}:type = value is legal; key:type@{...} = value is not.

Examples:

Rejected:

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 do not accept generic or bracket specs in Core v1 node-head syntax;
• 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:

Rejected floating form:

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:

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

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.