Add bytecode function creation with defaults and shared closures

docs/runtime/bytecode.md

@@ -22,14 +22,14 @@
 
 所有执行位置和跳转距离以**两字节代码单元**计数，包含扩展参数单元；不是字节偏移，也不一定等于逻辑指令下标。前跳从当前逻辑指令之后的位置加距离；后跳从该位置减距离。目标必须是完整逻辑指令的开头，不能跳进扩展参数中间。
 
-首版有 28 个可执行操作码和一个由编解码器处理的 EXTENDED_ARG：
+当前有 29 个可执行操作码和一个由编解码器处理的 EXTENDED_ARG：
 
 | 指令组 | 内容 |
 | --- | --- |
 | 常量与局部变量 | `LoadConst`、`LoadFast`、`StoreFast`、`DeleteFast` |
 | 名称与属性 | `LoadGlobal`、`StoreGlobal`、`DeleteGlobal`、`LoadAttr`、`StoreAttr` |
 | 栈操作 | `Nop`、`PopTop`、`Copy`、`Swap`、`PushNull` |
-| 调用与返回 | `Call`、`ReturnValue` |
+| 函数定义、调用与返回 | `MakeFunction`、`Call`、`ReturnValue` |
 | 控制流 | `JumpForward`、`JumpBackward`、`PopJumpIfFalse`、`PopJumpIfTrue` |
 | 真值与比较 | `ToBool`、`UnaryNot`、`CompareOp` |
 | 闭包 | `LoadDeref`、`StoreDeref`、`DeleteDeref`、`LoadClosure` |
@@ -79,6 +79,37 @@ Vm::execute(code, globals)
 
 普通函数调用采用 `[callable, NULL, arg0, ...]` 栈布局，CALL 参数是显式位置参数个数。NULL 是内部标记，与 `Value::Nil` 不同；如果第二个位置是实际值，就把它作为隐式接收者加在参数前。尚未实现属性描述符或自动方法绑定。
 
+## 在字节码中创建函数
+
+`MakeFunction`（操作码编号 28）将代码对象、已经求值的默认参数和共享 Cell 组装为一个新的语言函数。使用 `Instruction::make_function(default_count, closure_count)` 构造指令，两个计数均为 u16（0～65535）：参数低 16 位为默认参数数，高 16 位为闭包 Cell 数；大参数继续由 EXTENDED_ARG 编解码。不含默认参数和闭包时也可使用 `Instruction::simple(Opcode::MakeFunction)`。
+
+执行前后栈形状如下，右边为栈顶：
+
+```text
+[..., default0, ..., defaultN, cell0, ..., cellM, code]
+→ [..., function]
+```
+
+默认值按尾部位置参数的声明顺序排列，Cell 按目标代码的 free_variables 顺序排列。没有默认值或闭包时省略对应区域；每个默认值、每个 Cell 和代码对象都占一个栈项。函数名取自目标代码的 name；globals 使用当前帧的 globals，builtins 在创建时从该 globals 的可选 __builtins__ 字典捕获，与宿主 new_function 工厂一致。
+
+例如，无参数的函数定义与调用可生成如下逻辑指令。函数体代码对象预先放入当前代码的常量表中：
+
+```text
+LoadConst    body_code_index
+MakeFunction 0
+StoreGlobal  function_name_index
+LoadGlobal   function_name_index
+PushNull
+Call         0
+ReturnValue
+```
+
+嵌套函数使用 `LoadClosure` 取出当前帧的共享 Cell，再压入内层代码对象并执行 `MakeFunction`。创建函数不运行函数体；默认值表达式应先由外围代码求值，创建时保存其结果，因此同一函数的后续调用共享这些默认值。重复执行创建指令会产生不同函数对象，它们可以共享同一代码对象。
+
+静态校验根据两个计数检查所需栈高度、合流高度和最大栈深。执行时复用 new_function 校验代码对象种类、默认参数数量、闭包数量与 Cell 种类；NULL 调用标记不能用作任何输入值。类型和数量不匹配通过现有 VmError 返回。所有输入在完整校验及分配成功前都保持在栈中，成功后由函数持有其托管引用，再消费输入并压入函数的一份根；失败时沿现有帧清理路径释放输入。
+
+函数创建后不提供修改其默认值或闭包的指令。当前一条 MakeFunction 直接构造完整函数，不要求 tuple 对象或 CPython 3.13 起的 SET_FUNCTION_ATTRIBUTE；操作数格式和操作码编号均为 Endor 自有协议。
+
 ## 对象引用与返回值
 
 每个帧持有函数的一份执行根，函数继续保活代码、全局字典、内建字典、默认值及闭包。局部槽和求值栈中的每个对象值也各自持有执行根，重复出现分别计数。执行根复用现有外部强引用计数，所以循环回收能保留它们。
@@ -117,7 +148,7 @@ fn main() -> Result<(), endor_core::VmError> {
 }
 ```
 
-该示例直接提供指令，不表示已经支持 Endor 或 Python 源码解析。函数和嵌套函数目前由宿主工厂创建，尚无 MAKE_FUNCTION 指令；后续编译器接入时再补函数定义所需的操作。
+该示例直接提供指令，不表示已经支持 Endor 或 Python 源码解析。宿主仍负责准备代码对象和执行环境；函数既可由宿主 new_function 工厂创建，也可由上述 MakeFunction 在字节码运行期间创建。
 
 ## 限额、诊断与边界
 
@@ -125,11 +156,11 @@ fn main() -> Result<(), endor_core::VmError> {
 
 运行错误仍返回 `VmError`。`last_traceback()` 另提供从外到内的函数名、文件、代码首行和出错指令偏移；它保存独立元数据，不保活已经清理的帧。首行是代码声明的 first_line，不是由行号表推导出的实际错误源码行。成功的新一次调用会清空旧记录。尚无语言异常对象传播、raise／try／except 或完整源码行号表。
 
-暂未实现：lexer/parser、源码编译器、关键字／可变参数、生成器／协程、迭代器专用指令、数值算术、MAKE_FUNCTION、自动方法绑定、指令特化和 JIT。
+暂未实现：lexer/parser、源码编译器、关键字／可变参数、生成器／协程、迭代器专用指令、数值算术、自动方法绑定、指令特化和 JIT。
 
 ## 验证
 
-[execution.rs](../../crates/core/tests/execution.rs) 覆盖 wordcode、控制流校验、变量、循环、嵌套调用与默认参数、闭包、容器和返回值所有权、错误清理及帧／指令限额；已有 builtins 测试已迁移共享代码对象和持有式调用返回值。lib.rs 另有可供远端 rustdoc 执行的例子。
+[execution.rs](../../crates/core/tests/execution.rs) 覆盖 wordcode、控制流校验、变量、循环、嵌套调用与默认参数、闭包、字节码函数定义／默认值／环境捕获、容器和返回值所有权、函数创建失败与后续错误清理及帧／指令限额；已有 builtins 测试已迁移共享代码对象和持有式调用返回值。lib.rs 另有可供远端 rustdoc 执行的例子。
 
 验证命令与结果边界统一见 [验证](../operations/validation.md)。限额与环境隔离见 [配置](../operations/configuration.md)，文件职责见 [core 源码导航](../../crates/core/src/README.md)。