vendor: 引入 Lua 4.0.1 官方源码 + 移植评估文档 (lua_4.0 分支)

- Lua 4.0 是首个引入 lua_State* 的版本, 但 API 与 5.x 代际差异大
- 桥接层适配要点与工作量评估见 doc/ADAPTATION-lua40.md
- 本分支暂不承诺可编译, 后续按需移植

doc/ADAPTATION-lua40.md

@@ -0,0 +1,38 @@
+# Lua 4.0 分支移植评估（ADAPTATION.md）
+
+> 本分支已 vendor Lua 4.0.1 官方源码到 `lib/lua/`。
+> **桥接层尚未适配**——Lua 4.0 的 C API 与 5.x 存在代际差异，需要按本文档改造后方可使用。
+
+## 当前状态
+
+- ✅ Lua 4.0.1 源码就位
+- ❌ `lib/lua_runner.cpp` / `lib/lua_cj_api.cpp` 未适配（仍为 Lua 5.4 API）
+- ❌ 仓颉层 `src/bridge.cj` 无需改动（FFI 签名与版本无关）
+
+## 移植要点
+
+Lua 4.0 是第一个引入 `lua_State*` 的版本，但 API 与 5.x 有以下关键差异：
+
+| 能力 | Lua 5.4（当前桥接实现） | Lua 4.0 | 改造方案 |
+|---|---|---|---|
+| 创建状态机 | `luaL_newstate()` + `luaL_openlibs()` | `lua_open(stacksize)` + `lua_baselibopen()` 等逐个打开 | 重写 init |
+| 加载文件 | `luaL_loadfile()` + `lua_pcall()` 两步 | `lua_dofile(L, path)` 一步完成 | run() 重写；错误处理从 pcall 返回值改为 lua_dofile 返回码 |
+| 执行字符串 | `luaL_dostring()` | `lua_dostring(L, s)` | 直接映射 |
+| 调用栈顶函数 | `lua_pcall(L, nargs, MULTRET, 0)` | `lua_call(L, nargs, nresults)`（无保护，出错直接 abort） | 需包一层 `lua_cpcall` 或接受非保护语义 |
+| 函数引用表 | `luaL_ref(L, LUA_REGISTRYINDEX)` | `lua_ref(L, lock)` / `lua_getref` / `lua_unref` | loadFunction/callFunction 全套改名 |
+| 压栈 | `lua_pushinteger`(5.3+) / `lua_pushnumber` / `lua_pushboolean` | 仅 `lua_pushnumber` / `lua_pushstring`（无 integer 类型、boolean 用 number 0/1） | typed interop 退化为 number-only |
+| 取值 | `lua_tointeger` / `lua_isinteger` | 无 | capture_result() 统一 CJT_NUM |
+| 栈操作 | `lua_gettop` / `lua_settop` / `lua_remove` / `lua_pop` | 同名存在 ✅ | 兼容 |
+| extraspace I/O 重定向 | `lua_getextraspace()` | **不存在** | 改 Registry 存储 iopath*（参照 lua_5.1.5/lua_5.2.4 分支方案） |
+| print/io 劫持 | `lua_pushcfunction` + `lua_setglobal("print")` | `lua_register(L, name, func)` | 可映射 |
+
+## 预估工作量
+
+- 桥接层 C++：~300 行改动（init/run/loadfunction/callfunction/I-O 重定向五大块）
+- 测试：GTest 大部分可保留，PackagePathConfig 与 require 相关断言需按 4.0 语义重写
+- 构建系统：CMakeLists 文件集需按 4.0 源码列表调整（无 loadlib.c/loslib.c 等）
+
+## 结论
+
+技术上可移植但性价比低：Lua 4.0 发布于 2000 年，语言本身无 integer 类型、
+无保护调用、GC 与现代版本差异大。建议仅在确有历史脚本兼容需求时投入。