Add token-based PEG frontend and CLI source parsing

docs/contributing/README.md

@@ -14,6 +14,7 @@
 | 各 crate 的依赖方向和系统边界 | [architecture/README](../architecture/README.md) | 根 README、docs 索引摘要 |
 | 对象头、句柄、引用协议与 GC 算法 | [objects.md](../runtime/objects.md) | core/src 文件表 |
 | Number、String、Dict、Cell、函数环境和异常数据 | [builtins.md](../runtime/builtins.md) | core/src 与 tests 文件表 |
+| token、PEG 规则、AST 与源码诊断 | [frontend.md](../runtime/frontend.md) | frontend 源码／测试／样例和 CLI |
 | 指令编码、栈效果、调用协议与执行限制 | [bytecode.md](../runtime/bytecode.md) | instruction／code／frame／eval 文件职责 |
 | 宿主基础信息、JSON 文件和旧库导入 | [host-information.md](../operations/host-information.md) | host、cli、server 与脚本 README |
 | 地区与文本编码边界 | [text-encoding.md](../runtime/text-encoding.md) | 配置主题与实际 I/O 入口 |
@@ -41,9 +42,9 @@
 
 Core 保持零外部依赖、不引入 Python type／元类、源码前端或宿主库。句柄构造保持私有；非法句柄检查放堆内部单元测试，不能为测试开放非法构造器。容器更新须经过 VM 的引用事务；call／execute 对象结果持有根，借用读取仍须由使用方按需 retain。
 
-Rust 实现依赖模块可见性、trait 和 rustfmt，不照搬 CPython C 符号命名规范。公开导出集中在 core/src/lib.rs，内部协作用 pub(crate) 或私有方法区分。当前没有 Endor 源码风格规范或通用配置框架。
+Rust 实现依赖模块可见性、trait 和 rustfmt，不照搬 CPython C 符号命名规范。Core 公开导出集中在 core/src/lib.rs，Frontend 导出集中在 frontend/src/lib.rs，内部协作用 pub(crate) 或私有方法区分。当前基础源码解析契约在 frontend.md，尚无完整 Endor 源码风格规范或通用配置框架。
 
-后续优先按实际需求扩充函数定义／迭代器等指令、宿主回调、错误传播和资源边界；新增前端或云服务机制需要相应设计，不写成既有功能。
+独立 Frontend 已提供 lexer/parser 和 AST；后续按实际需求接入名称／闭包分析和字节码编译、扩充迭代器等指令、宿主回调、错误传播和资源边界。语法可继续调整，AST 到字节码和云服务机制尚未实现，不写成既有功能。
 
 ## 导出与迁移
 

docs/contributing/handoff.md

@@ -4,13 +4,14 @@
 
 ## 当前项目与命名
 
-仓库为 endorphin-aster-vm，归属 ProjectEndorphin。包与目录为 core、storage、host、cli、server；core 的 Rust 库名为 endor_core，命令为 cli／server。旧部署服务、数据库和路径保留既有标识以保护数据。
+仓库为 endorphin-aster-vm，归属 ProjectEndorphin。包与目录为 core、frontend、storage、host、cli、server；core 的 Rust 库名为 endor_core，命令为 cli／server。旧部署服务、数据库和路径保留既有标识以保护数据。
 
 ## 已实现
 
 - EndorObject、稳定 Box、代际句柄、显式强引用及手动循环回收；VM 从空堆启动，没有 Python type／元类或语言根类。
 - Function、NativeFunction、Dict、Cell、异常数据、UTF-8 String 和无损表示优先的 Number。
 - 小型 wordcode、共享代码对象、操作数／控制流／栈校验、显式执行帧及 execute／call；MakeFunction 可在执行中创建带默认参数与共享闭包 Cell 的函数。对象返回值持有根，用后 release_value；借用读取不自动 retain。
+- Frontend 使用手写 lexer 与 peg 0.8.6，提供完整输入解析、基础函数／表达式 AST、Unicode 字节范围与行列诊断；CLI parse 可读 UTF-8 文件输出 AST，不执行源码。当前语法以未完成设计稿为起点，可以继续调整，见 [源码前端](../runtime/frontend.md)。
 - Host 文件信息独立于数据库：host.version、deployment.release 与 metadata put/get 使用 UTF-8 JSON。旧 PostgreSQL 基础信息只读导入缺失文件，不删除原库，见 [文件信息](../operations/host-information.md)。
 - Storage 只提供显式 DatabaseConfig／DatabaseConnection；没有默认数据库、自动应用建表或基础信息 KV。特殊类的名称／接口尚未定义，没有将连接接入 VM。
 - CLI 引导与文件信息，Server HTTP 存活／只读 VM 信息；生产 PostgreSQL 作为未来特殊类的预置资源保留。
@@ -21,7 +22,7 @@
 
 ## 尚未实现
 
-源码 lexer/parser 与编译器、迭代器等扩展指令、数值算术／相等／哈希、完整异常传播、可变 VM／异步数据库回调、生成器、自动 GC、堆快照、内存配额、取消及不可信代码沙箱。宿主回调 panic 后的执行根恢复也未完成。不能把未来设计写成已有能力。
+AST 到字节码编译器、名称／闭包与类型分析、源码闭包声明、导入／类／Agent 语法、迭代器等扩展指令、数值算术／相等／哈希、完整异常传播、可变 VM／异步数据库回调、生成器、自动 GC、堆快照、内存配额、取消及不可信代码沙箱。宿主回调 panic 后的执行根恢复也未完成。不能把未来设计写成已有能力。
 
 ## 工作约定
 
@@ -33,4 +34,4 @@
 
 ## 下一步
 
-函数创建指令完成后可以开始设计源码前端：先明确 Endor 的最小语法、token 与 AST，再依次实现 lexer、parser、名称／闭包分析及字节码生成。目标路径为源码 → token → AST → 现有字节码 → VM，不改成 AST 直接解释。最初可覆盖字符串／布尔／Nil、变量、位置参数函数、调用、return 和闭包；数字运算与异常传播按后续需求补齐，不作为开始前端的前置要求。当前尚未启动前端实现，也未把 Python 示例视作 Endor 语法规范；前端包的边界与语法仍待确定。
+前端已完成到 AST 的首版实现；下一步接 AST → 名称／局部槽与闭包分析 → 字节码 → 现有 VM，不改成 AST 直接解释。可以先连接字符串、名称、let、位置参数函数和调用，再补算术指令与数值语义。参数与返回类型目前只保存为语法节点，不引入 Python type／元类或借此实现整个语言类型系统。语法不必等外部设计稿全部定稿，按用户要求先实现可用子集、以后再调整；当前尚无源码执行命令。