docs(frontend): reconcile AST guide with control flow and schema notes

crates/frontend/src/lexer.rs

@@ -1,4 +1,4 @@
-//! parser 及宿主分词入口；每次交给 PEG 一个剩余源码前缀，再把相对跨度换回原文绝对字节位置。
+//! parser 及宿主分词入口；每次交给 PEG 从游标起的剩余源码后缀，再把相对跨度换回原文绝对字节位置。
 use crate::{Diagnostic, Span, Token, TokenKind};
 
 /// Lex a reader snapshot and preserve provenance in any diagnostic.

docs/runtime/ast.md

@@ -25,6 +25,10 @@ ASDL 支持 module、产品类型 `(Type field, ...)`、构造器联合 `A(...)
 
 Rust 用 struct／enum、Vec／Option 表达结构；生成器在按值依赖图的回边放置 Box，Vec 已经断开按值递归。增加节点后，Rust 类型、两种语言的遍历接口和 JSON Schema 由同一次生成更新。
 
+中文节点、字段和构造器说明维护在 [generate_ast.py](../../scripts/generate_ast.py) 的 `TYPE_NOTES`、`FIELD_NOTES`、`VARIANT_NOTES` 中，由模板写入 Rust 和 TypeScript 源码。字段说明按所属类型区分，`span` 统一说明原文定位；访问器同时说明遍历顺序、失败退出和子树跳过规则。阅读 schema 时可对照 [Rust 节点](../../crates/frontend/src/ast/generated.rs)、[Rust 遍历器](../../crates/frontend/src/ast/visitor.rs) 或 [TypeScript 接口](../../crates/frontend/editor/ast.ts)。更改这些说明后也应运行生成命令，手改派生文件会在下次生成时丢失。
+
+本次注释补充保留 `Endor.asdl` 原文：其注释和空白也参与下述协议身份计算，直接添加中文注释会令已有 JSON 文档的 schema 标识失配。中文说明因此随生成源码维护；ASDL 仍是唯一结构定义源，说明字典不新增节点或改变协议结构。
+
 ## 根、声明、语句、表达式
 
 | 层级 | 当前数据模型 |
@@ -33,15 +37,16 @@ Rust 用 struct／enum、Vec／Option 表达结构；生成器在按值依赖图
 | Program | declarations: Vec<Decl> 与 span；声明种类为 Function、Class |
 | Decl／DeclKind | 声明的位置及其具体种类；Function 保存参数、返回类型名称和 Block；Class 保存名称、可选基类、字段及方法 |
 | Block | statements: Vec<Stmt> 与 span，不再用固定的 bindings／result 字段表示 |
-| Stmt／StmtKind | Binding、Assignment、MemberAssignment、Return、Expression、Declaration；每条语句有自身范围 |
+| Stmt／StmtKind | Binding、Assignment、MemberAssignment、If、While、Return、Expression、Declaration；每条语句有自身范围 |
+| IfStatement／WhileStatement | 条件和嵌套 Block；if 另有可选 otherwise，while 每轮重新求条件 |
 | MemberAssignment | 对象表达式、属性名称、右侧表达式与原文范围 |
 | Assignment | 名称目标、右侧表达式及原文范围；独立于 let 的 Binding 节点 |
 | ReturnStatement | 可选表达式与范围；当前源码中的 return 仍要求表达式 |
-| Expr／ExprKind | 名称、数字原文、字符串、符号、一元／二元运算、成员和调用 |
+| Expr／ExprKind | 名称、数字原文、字符串、符号、等待、一元／二元运算、成员和调用 |
 
 参数与返回类型仍为 Name，只保留语法，不实施类型或名称检查。Program::functions() 提供函数迭代便捷接口。旧的 Program.functions、Block.bindings／result／return_span 字段已移除；源码构造和使用方改为声明／语句列表。ExprKind 的既有表达式结构保留。
 
-AST 数据模型允许一般语句列表，不代表 parser 接受了所有组合。模块要求一个或多个函数／类声明；函数体接受 let／名称赋值／属性赋值／表达式语句，以及可选的末尾带值 return。Interactive 模式接受一次函数／类声明、let 绑定、名称／属性赋值或表达式，必须消费完整输入；不创建交互会话，不处理续行提示，不执行语言代码。多条交互提交由宿主分别解析。条件、循环、导入、trait 等尚未实现，也不加入 FunctionType 这种 Python 专用入口。
+AST 数据模型允许一般语句列表，不代表 parser 接受了所有组合。模块要求一个或多个函数／类声明；函数体接受 let／名称赋值／属性赋值／表达式语句、if／else 和 while，以及各块可选的末尾带值 return。Interactive 模式解析一次函数／类声明、控制流、let 绑定、名称／属性赋值或表达式，必须消费完整输入；不创建交互会话，不处理续行提示，不执行语言代码。多条交互提交由宿主分别解析。函数和交互根的条件、循环均有对应名称／初始化分析与跳转指令生成；具体 AST 仍需通过后续语义及字节码校验。导入和 trait 声明尚无源码语法，也没有 FunctionType 这种 Python 专用入口。
 
 ## 解析与位置