docs: update documentation references and compiler CLI guide

- Replace UNSUPPORTED_SYNTAX.md with INCOMPATIBLE_PHP_FEATURES.md in CLASS_INHERITANCE.md
- Update COMPILATION_MODES.md with correct command example using ldd instead of static compilation
- Replace syntax support documentation links with compatibility-focused documents in COMPILATION_MODES.md
- Rewrite COMPILER_CLI.md with concise

docs/CLASS_INHERITANCE.md

@@ -540,7 +540,7 @@ class EnhancedStorage {
 ## 📚 相关资源
 
 - **类型系统**: [NATIVE_TYPES.md](NATIVE_TYPES.md)
-- **语法限制**: [UNSUPPORTED_SYNTAX.md](UNSUPPORTED_SYNTAX.md)
+- **兼容性限制**: [INCOMPATIBLE_PHP_FEATURES.md](INCOMPATIBLE_PHP_FEATURES.md)
 - **编译模式**: [COMPILATION_MODES.md](COMPILATION_MODES.md)
 - **快速入门**: [QUICKSTART.md](QUICKSTART.md)
 

docs/COMPILATION_MODES.md

@@ -456,8 +456,8 @@ error while loading shared libraries
 # 设置库路径
 export LD_LIBRARY_PATH=/path/to/libs:$LD_LIBRARY_PATH
 
-# 或静态编译
-php bin/compiler.php src/ -o app --static
+# 检查实际链接路径和依赖
+ldd ./app
 ```
 
 ---
@@ -465,9 +465,9 @@ php bin/compiler.php src/ -o app --static
 ## 📚 相关文档
 
 - [快速入门指南](QUICKSTART.md) - 开始使用 AOT 编译器
-- [语法支持规范](UNSUPPORTED_SYNTAX.md) - 了解支持的语法
-- [性能优化指南](PERFORMANCE.md) - 提升编译和运行性能
-- [故障排除](TROUBLESHOOTING.md) - 解决常见问题
+- [兼容性清单](INCOMPATIBLE_PHP_FEATURES.md) - 了解当前限制
+- [构建速度研究](AOT_BUILD_SPEED_RESEARCH.md) - 优化编译流程
+- [兼容性分类](PHP_INCOMPATIBILITY_CLASSIFICATION.md) - 判断限制的性质和处理方向
 
 ---
 

docs/HIGH_PRECISION_TYPES.md

@@ -748,8 +748,8 @@ pi × 2: 6.2831800000000000
 - **类型系统规范**：[`docs/NATIVE_TYPES.md`](NATIVE_TYPES.md) — 完整的类型提升规则、声明语法、C++ API 参考
 - **BigInt PHPT 测试**：[`tests/aot/bigint/`](../tests/aot/bigint/) — BigInt 各项功能的集成测试
 - **Decimal PHPT 测试**：[`tests/aot/decimal/`](../tests/aot/decimal/) — Decimal 各项功能的集成测试
-- **BigFloat 集成测试**：[`tests/aot/bigfloat_operators.phpt`](../tests/aot/bigfloat_operators.phpt) — BigFloat 运算符测试
+- **BigFloat 集成测试**：[`tests/aot/bignumber/bigfloat_operators.phpt`](../tests/aot/bignumber/bigfloat_operators.phpt) — BigFloat 运算符测试
 - **C++ 运行时头文件**：
-  - [`phpx/include/phpx_big_int.h`](../phpx/include/phpx_big_int.h) — BigInt C++ API
-  - [`phpx/include/phpx_decimal.h`](../phpx/include/phpx_decimal.h) — Decimal C++ API
-  - [`phpx/include/phpx_big_float.h`](../phpx/include/phpx_big_float.h) — BigFloat C++ API
+  - [`phpx/include/phpx_big_int.h`](../../phpx/include/phpx_big_int.h) — BigInt C++ API
+  - [`phpx/include/phpx_decimal.h`](../../phpx/include/phpx_decimal.h) — Decimal C++ API
+  - [`phpx/include/phpx_big_float.h`](../../phpx/include/phpx_big_float.h) — BigFloat C++ API

docs/INCOMPATIBLE_PHP_FEATURES.md

@@ -15,14 +15,14 @@
 
 - 不支持可变变量 `$$var`。
 - PHP 8.4 property hooks 会降级为 AOT getter/setter；直接属性读写和动态对象读写均受支持。当前不支持对 hook 属性取引用。
-- 支持 `private(set)` 与 `protected(set)` 非对称属性可见性；在 PHP 8.2/8.3 后端通过自定义属性写 handler 执行同等作用域检查。
+- 支持 `private(set)` 与 `protected(set)` 非对称属性可见性；在 PHP 8.2～8.4 后端通过自定义属性写 handler 执行同等作用域检查。
 - 不支持闭包或箭头函数按引用返回。
 - `__construct()` 不允许返回值。
 - 参数默认值不允许出现在必填参数之前（`PHP`允许，但会直接丢弃此默认参数）。
 - 不支持引用可变参数 `&...$args`。
 - 联合类型、交叉类型、`nullable` 类型仍以 `mixed/any` 作为 C++ 表示，但静态阶段会利用已知表达式类型提前拒绝确定不兼容的参数、返回值和属性赋值；动态值仍保留运行时 type check。
 - 局部变量类型一旦被静态推断为具体 native 类型，不支持在同一作用域内重新赋值为不兼容类型。
-- attribute 参数不支持数组值和 `new` 表达式。
+- attribute 参数不支持非空数组值和 `new` 表达式。
 
 ## declare
 
@@ -33,6 +33,7 @@
 
 ## 调用与引用
 
+- TypePHP 使用严格参数数量规则：非 variadic 函数不接受声明范围之外的额外参数；`func_get_args()` 不会隐式放宽签名。
 - 闭包和箭头函数不支持引用参数。
 - 引用赋值不支持从复杂静态属性表达式建立引用。
 - 动态调用、闭包调用等编译期无法确定参数签名的调用，不能自动转换引用参数；需要显式使用 `refval()` 或等价关键词方法 `toRef()`。
@@ -41,6 +42,8 @@
 
 ## 对象模型
 
+- `toInt()`、`toString()`、`toArray()` 等保留关键词方法先于普通对象方法解析；需要参数的同名业务方法不按普通对象方法语义调用。
+- 固定值类型属性未显式初始化时使用类型零值，不保留 ZendPHP 的完整 uninitialized 状态；因此 `??` 等依赖 uninitialized 状态的表达式可能不同。
 - 禁止子类用同名 `private` 属性隐藏父类私有属性；`public` / `protected` 同名声明视为同一个继承 property slot，仍须满足类型、可见性和 `readonly` 兼容性要求。
 - 为避免 typed property 写入路径引入额外动态检查，native typed property 在右值类型不确定或与属性类型不一致时会退化为 `setProperty()`；部分标量赋值可能遵循 Zend 弱类型转换，而不是 AOT 默认 strict 语义。
 - constructor property promotion 的运行时属性可用，但 `ReflectionProperty::isPromoted()` 目前不返回标准 PHP 结果。

docs/MIXED_CPP_PHP.md

@@ -911,10 +911,10 @@ function get_adult_users() {
 
 ```bash
 # 保留中间文件
-php bin/compiler.php project -o app --keep-all
+php bin/compiler.php project --dry --build-dir /tmp/typephp-build
 
 # 查看生成的 C++ 代码
-cat build/app.cpp
+find /tmp/typephp-build -name '*.cc' -o -name '*.cpp'
 ```
 
 ### 2. 类型检查
@@ -1007,7 +1007,7 @@ php::Int php_calculator_add(php::Object calc, php::Int a, php::Int b) {
 - **示例项目**: `examples/prime/`
 - **PHPX 框架文档**: [链接]
 - **C++ 类型系统**: 参见 [NATIVE_TYPES.md](NATIVE_TYPES.md)
-- **AOT 编译器架构**: 参见 [ARCHITECTURE.md](ARCHITECTURE.md)
+- **AOT 编译器架构**: 参见 [后端中立 IR](BACKEND_NEUTRAL_IR.md) 和 [核心重构计划](REFACTORING_PLAN.md)
 
 ---
 

docs/NATIVE_TYPES.md

@@ -41,7 +41,7 @@ $user->profile = null; // ✅ 对象属性可显式设置为 null
 
 在 PHP 中，`unset($obj->prop)` 可以让对象属性脱离当前值状态，后续表现为未初始化或空值状态；对固定值类型属性赋值 `null` 也会把值状态改成空值。从 AOT 的类型系统角度看，这等价于把属性从声明的 `int`、`float`、`bool`、`string`、`array` 改变为 `null`/未初始化状态。AOT 编译器不允许这些固定值类型属性改变类型，因此属性永远是声明时的类型。
 
-具体类对象属性使用更严格的对象类型规则：`public MyClass $object` 可以被 `unset()` 或设置为 `null`；但再次赋值对象时，运行时对象类型必须是 `MyClass` 本身。与 PHP 不同，AOT 不允许把子类对象赋给基类属性。
+具体类对象属性使用静态对象类型规则：非空赋值必须满足 `is-a` 关系，因此允许把子类对象赋给基类属性，不允许把无继承关系的对象或基类对象赋给子类属性。非 nullable 属性可以 `unset()`，但不能赋值为 `null`。
 
 正确做法：
 

docs/PHP_INCOMPATIBILITY_CLASSIFICATION.md

@@ -72,6 +72,9 @@ These items should be documented with the exact boundary.
 | Reassigning a statically inferred native local to an incompatible type | Intentional Rule | This is the cost of native type optimization. Use dynamic zval variables when PHP-style type changes are required. |
 | Native `std::int` overflow and integer division behavior | Intentional Rule | Native numeric types trade PHP compatibility for performance and C++ storage. |
 | `__CLASS__` outside class context and `__TRAIT__` outside trait context | Intentional Rule | PHP returns an empty string for legacy compatibility. TypePHP rejects this as a clearer rule. |
+| Strict function argument counts | Intentional Rule | Non-variadic functions reject extra arguments. `func_get_args()` does not implicitly make a function variadic. |
+| Reserved keyword methods such as `toArray()` | Intentional Rule | Conversion keywords are resolved before ordinary object methods to keep conversion lowering static and predictable. |
+| Zero-initialized fixed typed property slots | Intentional Rule / Partial | Native fixed-layout slots use their type's zero value instead of preserving every Zend uninitialized-property transition. |
 
 ## Implementable but Currently Unsupported
 
@@ -109,27 +112,6 @@ These items should be documented with the exact boundary.
 | Native typed properties | Partial / Intentional Rule | Fast native paths may not preserve every PHP dynamic state transition. Unknown or incompatible values can fall back to `setProperty()`. |
 | Reflection metadata | Partial | Runtime declarations exist, but some AOT-specific metadata such as promoted-property flags may be incomplete. |
 
-## Outdated or Ambiguous Items in `UNSUPPORTED_SYNTAX.md`
-
-`UNSUPPORTED_SYNTAX.md` contains historical material and should not be treated as
-the authoritative current compatibility list without verification.
-
-Items that need review:
-
-- Attributes are not necessarily wholly unsupported. The current limitation is
-  narrower: some attribute argument forms, such as arrays and `new`, are not
-  supported.
-- Traits may no longer be purely "planned support"; current implementation and
-  tests should be checked before documenting them as unsupported.
-- `foreach` by-reference support is partial, not absent.
-- `break N` and `continue N` should be rechecked against current compiler
-  behavior before keeping them in the unsupported list.
-- DOM or `innerHTML` is not PHP language syntax and should not be listed as a
-  core AOT syntax incompatibility.
-- Duplicate function or class names should be documented carefully. Some cases
-  are PHP fatal errors, while conditional declarations are a separate dynamic
-  declaration problem.
-
 ## Documentation Rule
 
 When documenting a compatibility difference, use one of these labels:

docs/QUICKSTART.md

@@ -209,13 +209,13 @@ for ($i = 0; $i < 10; $i++) {  // 错误！
 ### 运行单个测试
 
 ```bash
-php run-tests.php --no-aot tests/aot/arrow-functions.phpt
+PHPT=1 php run-tests.php tests/aot/arrow_fn/001.phpt
 ```
 
 ### 运行所有测试
 
 ```bash
-php run-tests.php --no-aot tests/aot/
+PHPT=1 php run-tests.php tests/aot/
 ```
 
 ### 查看测试结果
@@ -263,13 +263,13 @@ project/
 ## 🔍 常见问题
 
 ### Q: 编译失败，提示 "Not implemented"
-**A**: 该语法特性暂不支持。查看 [语法支持规范](UNSUPPORTED_SYNTAX.md) 了解支持的语法。
+**A**: 先查看 [兼容性清单](INCOMPATIBLE_PHP_FEATURES.md) 判断它是 TypePHP 设计规则、部分支持还是当前尚未实现。
 
 ### Q: 如何调试编译后的程序？
-**A**: 使用 `--keep-all` 选项保留中间文件，查看生成的 C++ 代码。
+**A**: 使用 `--dry` 只生成中间代码，并通过 `--build-dir` 指定目录。
 
 ```bash
-php bin/compiler.php src/ -o app --keep-all
+php bin/compiler.php src/ --dry --build-dir /tmp/typephp-build
 ```
 
 ### Q: 编译速度慢怎么办？
@@ -285,9 +285,9 @@ php bin/compiler.php src/ -o app -j4  # 使用 4 个进程
 
 完成快速入门后，建议阅读：
 
-1. **[语法支持规范](UNSUPPORTED_SYNTAX.md)** - 详细了解支持的语法
+1. **[兼容性清单](INCOMPATIBLE_PHP_FEATURES.md)** - 了解当前限制
 2. **[编译模式详解](COMPILATION_MODES.md)** - 深入了解两种编译模式
-3. **[性能优化指南](PERFORMANCE.md)** - 提升程序性能
+3. **[构建速度研究](AOT_BUILD_SPEED_RESEARCH.md)** - 优化编译流程
 
 ---
 

docs/README.md

@@ -1,230 +1,34 @@
-# PHP AOT 编译器文档索引
+# TypePHP 编译器内部文档
 
-## 📚 文档概览
+本目录包含编译器实现、兼容性、构建模式和专项设计文档。用户侧使用手册位于独立的 `aot/docs` 仓库；这里的研究报告和重构计划可能描述历史状态，当前行为应以代码、测试和兼容性清单为准。
 
-本文档集合为 PHP AOT (Ahead-Of-Time) 编译器提供完整的使用指南和技术参考。
+## 当前权威文档
 
----
+- [AOT 与 PHP 不兼容特性清单](INCOMPATIBLE_PHP_FEATURES.md)：当前限制的简明清单。
+- [不兼容性分类](PHP_INCOMPATIBILITY_CLASSIFICATION.md)：区分 Hard Limit、Intentional Rule、Pending 和 Partial。
+- [编译器命令行](COMPILER_CLI.md)：当前 CLI 参数和项目配置。
+- [编译模式](COMPILATION_MODES.md)：binary、extension、library 模式。
+- [快速入门](QUICKSTART.md)：最小编译流程。
+- [编译期函数](COMPILE_TIME_FUNCTIONS.md)：`any()`、`refval()`、`objval()` 和关键词方法。
+- [原生类型](NATIVE_TYPES.md)、[高精度类型](HIGH_PRECISION_TYPES.md)、[Std 容器](STD_CONTAINERS.md)。
+- [通用与扩展方法](UNIVERSAL_METHODS.md)、[Generator](YIELD_GENERATOR.md)。
+- [类继承](CLASS_INHERITANCE.md)、[混合 C++/PHP](MIXED_CPP_PHP.md)。
 
-## 📖 核心文档
+## 架构与维护
 
-### 1. [语法支持规范](UNSUPPORTED_SYNTAX.md)
-**必读指数**: ⭐⭐⭐⭐⭐
+- [后端中立 IR](BACKEND_NEUTRAL_IR.md)
+- [核心重构计划](REFACTORING_PLAN.md)
+- [构建速度研究](AOT_BUILD_SPEED_RESEARCH.md)
+- [优化优先级](aot-optimization-priority.md)
+- [GMP 差异](GMP_GAP.md)
 
-详细说明：
-- ✅ 已支持的 PHP 语法特性（50+ 个）
-- ❌ 不支持的语法（7 种）
-- ⏳ 计划支持的语法（2 种）
-- 📊 编译模式对比表
-- 💡 代码结构最佳实践
+## 研究与历史资料
 
-**适合人群**: 所有使用者
+`hhvm-review.md`、`kphp-review.md`、`peachpie-review.md`、`phpstan-design-analysis.md`、`php-src-optimizer-analysis.md` 以及专利草案用于记录调研时点的比较和设计背景，不作为当前功能清单。
 
----
+## 维护规则
 
-### 1.1 [AOT 与 PHP 不兼容特性清单](INCOMPATIBLE_PHP_FEATURES.md)
-**必读指数**: ⭐⭐⭐⭐⭐
-
-内容概要：
-- 当前 AOT 与标准 PHP 的关键不兼容点
-- 编译期限制、运行时动态能力限制、AOT 扩展类型限制
-- 仅保留简明列表，不包含示例和长篇解释
-
-**适合人群**: 所有使用者、框架适配者
-
----
-
-### 1.2 [AOT 编译期函数与关键词方法](COMPILE_TIME_FUNCTIONS.md)
-**必读指数**: ⭐⭐⭐⭐
-
-内容概要：
-- AOT 专用编译期函数清单
-- `any()`、`refval()`、`objval()` 的语义和限制
-- `toAny()`、`toRef()` 等关键词方法
-- 当前实现风险和后续统一方向
-
-**适合人群**: 所有使用者、贡献者、框架适配者
-
----
-
-### 2. [快速入门指南](QUICKSTART.md)
-**必读指数**: ⭐⭐⭐⭐⭐
-
-内容概要：
-- 🚀 5 分钟快速开始
-- 📦 安装和配置
-- 🔧 基本使用示例
-- 🎯 第一个 AOT 编译项目
-
-**适合人群**: 新手用户
-
----
-
-### 3. [编译模式详解](COMPILATION_MODES.md)
-**必读指数**: ⭐⭐⭐⭐
-
-内容概要：
-- 🔹 扩展模式（Extension Mode）
-  - 编译为 .so/.dll 文件
-  - 在 php-fpm 中加载
-  - Web 应用场景
-  
-- 🔸 二进制模式（Binary Mode）
-  - 编译为独立可执行文件
-  - main() 函数要求
-  - CLI 和服务端应用
-
-**适合人群**: 开发者、架构师
-
----
-
-### 4. [测试指南](TESTING_GUIDE.md)
-**必读指数**: ⭐⭐⭐⭐
-
-内容概要：
-- 🧪 运行测试的方法
-- 📝 编写 phpt 测试文件
-- ✅ 测试规范和最佳实践
-- 🔍 调试测试失败
-- 📊 测试覆盖率分析
-
-**适合人群**: 测试人员、贡献者
-
----
-
-### 5. [性能优化指南](PERFORMANCE.md)
-**必读指数**: ⭐⭐⭐
-
-内容概要：
-- ⚡ 编译优化选项
-- 🎯 运行时性能调优
-- 📈 基准测试方法
-- 💾 内存管理策略
-
-**适合人群**: 高级用户、性能工程师
-
----
-
-### 6. [故障排除](TROUBLESHOOTING.md)
-**必读指数**: ⭐⭐⭐⭐
-
-内容概要：
-- ❗ 常见错误和解决方案
-- 🔧 调试技巧
-- 💬 FAQ 常见问题
-- 🆘 获取帮助
-
-**适合人群**: 所有使用者
-
----
-
-### 7. [架构设计](ARCHITECTURE.md)
-**必读指数**: ⭐⭐⭐
-
-内容概要：
-- 🏗️ 编译器架构概述
-- 📐 设计理念和原则
-- 🔗 组件和模块说明
-- 📊 数据流和工作流程
-
-**适合人群**: 贡献者、研究者
-
----
-
-### 8. [贡献指南](CONTRIBUTING.md)
-**必读指数**: ⭐⭐⭐
-
-内容概要：
-- 🤝 如何贡献代码
-- 📝 提交 PR 的流程
-- 🎨 代码规范
-- 🧪 测试要求
-
-**适合人群**: 贡献者
-
----
-
-### 9. [核心重构计划](REFACTORING_PLAN.md)
-**必读指数**: ⭐⭐⭐⭐
-
-内容概要：
-- 核心类职责拆分方向
-- TypeSystem、SymbolResolver、PropertyAccessResolver、CallResolver 等模块规划
-- 渐进式重构阶段计划
-- 测试门禁和风险控制要求
-
-**适合人群**: 核心开发者、架构重构参与者
-
----
-
-## 🎯 快速导航
-
-### 按使用场景
-
-#### 我想开始使用 AOT 编译器
-1. 阅读 [快速入门指南](QUICKSTART.md)
-2. 查看 [语法支持规范](UNSUPPORTED_SYNTAX.md) 了解限制
-3. 参考 [编译模式详解](COMPILATION_MODES.md) 选择模式
-
-#### 我想运行测试
-1. 阅读 [测试指南](TESTING_GUIDE.md)
-2. 使用 `php run-tests.php --no-aot tests/aot/` 命令
-3. 遇到问题查看 [故障排除](TROUBLESHOOTING.md)
-
-#### 我想优化性能
-1. 阅读 [性能优化指南](PERFORMANCE.md)
-2. 查看基准测试结果
-3. 应用优化建议
-
-#### 我想贡献代码
-1. 阅读 [贡献指南](CONTRIBUTING.md)
-2. 了解 [架构设计](ARCHITECTURE.md)
-3. Fork 项目并提交 PR
-
----
-
-## 📋 文档维护
-
-### 文档位置
-- ✅ 所有 `.md` 文档必须放在 `docs/` 目录下
-- ❌ 不要在其他目录创建文档文件
-
-### 文档更新
-- 保持文档与代码同步
-- 重大变更需要更新相关文档
-- 添加更新日期和版本信息
-
-### 文档质量
-- 使用清晰的标题和结构
-- 包含代码示例
-- 提供实际可运行的示例
-- 使用中文编写（除非特殊需要）
-
----
-
-## 🔗 外部资源
-
-- **PHP 官方文档**: https://www.php.net/manual/en/
-- **GitHub 仓库**: [项目地址]
-- **问题追踪**: [Issue Tracker]
-- **社区论坛**: [Community Forum]
-
----
-
-## 📞 联系方式
-
-- 技术支持：[support@example.com]
-- 商务合作：[business@example.com]
-- 社区讨论：[Slack/Discord 链接]
-
----
-
-## 📜 许可证
-
-本文档遵循 [MIT License](LICENSE)
-
----
-
-**最后更新**: 2024 年 3 月 18 日  
-**文档版本**: v1.0  
-**适用版本**: PHP AOT Compiler v1.x
+1. 当前兼容性变化同时更新 `INCOMPATIBLE_PHP_FEATURES.md` 和分类文档。
+2. 所有语法和语义限制统一链接到当前兼容性清单，避免维护重复清单。
+3. 功能是否支持应以 PHPT/PHPUnit 回归测试为依据。
+4. 历史研究文档保留原始比较结论，并在需要时注明调研日期，不应悄然改写为当前状态。

docs/UNIVERSAL_METHODS.md

@@ -1103,7 +1103,7 @@ function main(): void {
 
 - **高精度类型教程**：[`docs/HIGH_PRECISION_TYPES.md`](HIGH_PRECISION_TYPES.md)
 - **类型系统规范**：[`docs/NATIVE_TYPES.md`](NATIVE_TYPES.md)
-- **通用方法实现**：[`src/Php/UniversalMethodCall.php`](../src/Php/UniversalMethodCall.php)
+- **通用方法实现**：[`src/UniversalMethodCall.php`](../src/UniversalMethodCall.php)
 - **集成测试**：
   - [`tests/aot/string_method/`](../tests/aot/string_method/) — String 通用方法测试
   - [`tests/aot/array_method/`](../tests/aot/array_method/) — Array 通用方法测试