refactor(frontend): replace legacy semantic analyzer pipeline

doc/analysis/frontend_semantic_analyzer_research_report.md

@@ -393,7 +393,7 @@
 
 1. **没有 frontend -> LIR lowering。** 当前语义主链仍止步于 side table、diagnostics 与 class skeleton；函数体不会继续产生 LIR。
 2. **compile-ready 与 shared semantic 仍然分离。** `FrontendCompileCheckAnalyzer` 已经提供 compile-only final gate，但 `ConditionalExpression`、`ArrayExpression`、`DictionaryExpression`、`PreloadExpression`、`GetNodeExpression`、`CastExpression`、`TypeTestExpression` 与 `assert` 仍需要在进入 lowering 前被显式封口。
-3. **若干 executable-body 域仍保持 deferred / unsupported。** 参数默认值、lambda capture、`for` iterator binding、`match` pattern binding、block-local `const` 等尚未进入当前正式支持面。
+3. **若干 executable-body 域仍保持 deferred / unsupported。** 参数默认值、lambda capture、`match` pattern binding、block-local `const` 等尚未进入当前正式支持面。`for` iterator/body inventory 已在后续阶段 B/D0/L 转正，但 iteration planning 与 lowering route 仍未完成。
 4. **`self` 核心语义已经接通，但 signal use-site 与 coroutine 语义仍未闭环。** 当前代码已经支持 `self` 的 top binding 发布、static context fail-closed、property initializer fail-closed，以及将 `self` 解析为当前类实例 receiver；仍未形成稳定 frontend 合同的是 `.emit(...)`、`await signal` 等 signal/coroutine use-site，以及更完整的 context-sensitive diagnostics。
 5. **property initializer 仍不是完整实例初始化模型。** 当前支持面是“published subtree facts”，而不是 declaration-order / default-state / cycle-aware 的 class-member initializer 语义。
 6. **header superclass 的支持面仍受 MVP 限制。** path-based `extends`、autoload superclass、global-script-class superclass 与跨多个 gdcc module 的 superclass 绑定依然没有接通。

doc/module_impl/frontend/diagnostic_manager.md

@@ -212,15 +212,15 @@ deferred / unsupported diagnostics 一律通过 `DiagnosticManager` 发布。
 - `sema.unsupported_parameter_default_value`
   - variable analyzer 对 parameter default value 当前尚未接线时发出的 feature-boundary error
 - `sema.unsupported_variable_inventory_subtree`
-  - variable analyzer 对 lambda / `for` / `match` / block-local `const` inventory 边界发出的 feature-boundary error
+  - variable analyzer 对 lambda / `match` / block-local `const` inventory 边界发出的 feature-boundary error
 - `sema.variable_slot_publication`
   - var-type-post analyzer 对 supported callable-local `var` 因 earlier duplicate/shadowing reject 而无法发布 `slotTypes()` 时发出的 warning
   - warning message 若能在当前 callable 边界内找到幸存的 accepted local / parameter / capture，必须带出该幸存绑定的语义类别与声明位置
   - 该 warning 允许与 earlier `sema.variable_binding` 共存；compile-only gate 必须把“warning + 缺失 slot type”升级为 compile-blocking `sema.compile_check`
 - `sema.binding`
   - top binding 命中的 blocked / unknown / shadowing 诊断
 - `sema.unsupported_binding_subtree`
-  - top binding 对 parameter default、lambda、`for`、`match`、block-local `const` 等明确 unsupported subtree 的边界 error
+  - top binding 对 parameter default、lambda、`match`、block-local `const` 等明确 unsupported subtree 的边界 error
   - top binding 对 missing-scope / skipped subtree 的恢复诊断继续允许使用 warning
 - `sema.member_resolution`
   - chain binding 中 blocked / failed member step 的语义错误
@@ -266,10 +266,11 @@ deferred / unsupported diagnostics 一律通过 `DiagnosticManager` 发布。
 - `sema.compile_check`
   - compile-only `FrontendCompileCheckAnalyzer` 对进入 lowering 前仍不可编译的 surface 发出的最终 error
   - 同时覆盖：
-    - 当前首批显式封口的 `assert`、`ConditionalExpression`、`ArrayExpression`、`DictionaryExpression`、`PreloadExpression`、`GetNodeExpression`、`CastExpression`、`TypeTestExpression`
+    - 当前首批显式封口的 `assert`、`ForStatement`、`ConditionalExpression`、`ArrayExpression`、`DictionaryExpression`、`PreloadExpression`、`GetNodeExpression`、`CastExpression`、`TypeTestExpression`
     - compile surface 上 `expressionTypes()` / `resolvedMembers()` / `resolvedCalls()` 中仍残留的 `BLOCKED` / `DEFERRED` / `FAILED` / `UNSUPPORTED`
     - supported callable-local `var` 因 `sema.variable_slot_publication` warning 仍缺失 `slotTypes()` 的 lowering-only fact 缺洞
   - `assert` 在这里仍只是 compile-only blocked；共享 type-check 继续保留 Godot-compatible condition contract，不把它回退成 strict-bool `sema.type_check`
+  - `ForStatement` 已进入 shared semantic；当前 blocker 只锚定 statement root，不读取 iterable typed fact/iteration plan，也不进入 body，直到 route-aware CFG/lowering 接通
   - 上述 7 类表达式属于 frontend 已识别但 lowering 尚未接通的 temporary compile intercept，不代表 parser / grammar / shared semantic 路径已经把它们判成不支持语法
   - `ConditionalExpression` 当前单独被列入这份清单，是因为真正的 lowering 需要等 frontend CFG graph / condition-evaluation-region 合同冻结后再接通；现有 metadata-only `FrontendLoweringCfgPass` 仍属于过渡层
   - `DYNAMIC` 不属于 compile blocker；它保留为 frontend 已接受的 runtime-open 事实，而不是 lowering 未实现状态
@@ -330,6 +331,7 @@ deferred / unsupported diagnostics 一律通过 `DiagnosticManager` 发布。
 
 - `FrontendSemanticAnalyzer` 当前返回 `FrontendAnalysisData`
 - analyze 流程围绕同一份共享分析数据推进
+- interface/body suite resolver 路径会在每个 body statement boundary 刷新 `FrontendAnalysisData.diagnostics()`，让后一 statement 能读取 current-suite upstream diagnostic snapshot；suite export 在 patch transaction 应用后保留最终 body snapshot
 - analyze 现在已经具备独立的多 phase 主链路：
     - skeleton 结束后先发布 `updateModuleSkeleton(...)`
     - 再发布一次 pre-scope `updateDiagnostics(...)`
@@ -348,6 +350,7 @@ deferred / unsupported diagnostics 一律通过 `DiagnosticManager` 发布。
 - `analyzeForCompile(...)` 在共享 11 phase 之后追加：
     - 调用 `FrontendCompileCheckAnalyzer.analyze(...)`
     - 再次 `updateDiagnostics(...)`，把 compile-only final gate 的诊断写回最终边界快照
+- compile gate 运行前仍要求 stable diagnostics boundary 已发布，但 duplicate suppression 会冻结 live `DiagnosticManager.snapshot()`，避免 interface/body upstream diagnostics 因调用方尚未再次复制到 `FrontendAnalysisData` 而被漏看
 - 共享 `analyze(...)` 的结果当前仍只是 frontend semantic snapshot，不应直接视为 lowering-ready
 - inspection 与未来 LSP 入口继续消费共享 `analyze(...)`，不应被 `sema.compile_check` 污染
 - 未来 frontend -> LIR lowering 调用方必须：

doc/module_impl/frontend/frontend_chain_binding_expr_type_implementation.md

@@ -1,11 +1,14 @@
 # FrontendChainBinding / ExprType 实现说明
 
-> 本文档作为 `FrontendChainBindingAnalyzer`、`FrontendExprTypeAnalyzer` 及其共享 body-phase support 的长期事实源，定义当前 phase 顺序、side-table / diagnostic owner 边界、局部 chain reduction 架构、已冻结的 published contract，以及后续工程必须遵守的 fail-closed 边界。本文档替代旧的规划性文档与验收流水账，不再保留进度记录或阶段日志。
+> 本文档作为 `FrontendBodyOwnerProcedures` 中 chain-binding、expression-typing owner 及其
+> 共享 body-phase support 的长期事实源，定义当前 phase 顺序、side-table / diagnostic owner
+> 边界、局部 chain reduction 架构、已冻结的 published contract，以及后续工程必须遵守的
+> fail-closed 边界。
 
 ## 文档状态
 
-- 状态：事实源维护中（`resolvedMembers()` / `resolvedCalls()` / `expressionTypes()`、shared expression semantic support、unary/binary expression semantics、class property initializer support island、subscript / assignment typed contract、explicit self assignment-target prefix publication、`:=` 局部类型稳定化与 expr-owned diagnostics 已落地）
-- 更新时间：2026-06-27
+- 状态：事实源维护中（`resolvedMembers()` / `resolvedCalls()` / `expressionTypes()`、SuiteResolver statement-local owner procedures、for header/body dispatch、typed overlay-aware expression semantics、property initializer support island与 expr-owned diagnostics 已落地）
+- 更新时间：2026-07-20
 - 适用范围：
   - `src/main/java/gd/script/gdcc/frontend/sema/**`
   - `src/main/java/gd/script/gdcc/frontend/sema/analyzer/**`
@@ -31,7 +34,8 @@
   - 不引入 whole-module fixpoint，不把 body 语义改造成多轮全局收敛
   - 不新增新的全局 side table，也不让已有 side table 互相越权
   - 不把 `FrontendBinding` 重塑为 usage-aware 模型
-  - 不在这里转正 parameter default、lambda、`for`、`match`、block-local `const`、class constant 的正式 body 语义
+  - 不在这里转正 parameter default、lambda、`match`、block-local `const`、class constant 的正式 body 语义
+  - 不在这里实现 for iteration planning、iterator slot refinement 或 lowering route classification
   - 不在这里扩张 keyed builtin、numeric promotion 或其它 typed-boundary 兼容矩阵；`StringName` / `String` 互转由 `frontend_implicit_conversion_matrix.md` 与 shared boundary helper 独立管理
 
 ---
@@ -40,7 +44,7 @@
 
 ### 1.1 主链路位置
 
-当前 `FrontendSemanticAnalyzer` 的稳定顺序是：
+当前 production `FrontendSemanticAnalyzer` 的稳定顺序是：
 
 1. `FrontendClassSkeletonBuilder.build(...)`
 2. `analysisData.updateModuleSkeleton(...)`
@@ -49,21 +53,18 @@
 5. `analysisData.updateDiagnostics(...)`
 6. `FrontendVariableAnalyzer.analyze(...)`
 7. `analysisData.updateDiagnostics(...)`
-8. `FrontendTopBindingAnalyzer.analyze(...)`
-9. `analysisData.updateDiagnostics(...)`
-10. `FrontendLocalTypeStabilizationAnalyzer.analyze(...)`
-11. `analysisData.updateDiagnostics(...)`
-12. `FrontendChainBindingAnalyzer.analyze(...)`
-13. `analysisData.updateDiagnostics(...)`
-14. `FrontendExprTypeAnalyzer.analyze(...)`
-15. `analysisData.updateDiagnostics(...)`
+8. `FrontendInterfacePhase.analyze(...)`
+9. `FrontendSuiteResolver.resolve(...)`，内部按 statement root 固定执行 top binding -> local type stabilization -> chain binding -> expr typing -> var type post
+10. `analysisData.updateDiagnostics(...)`
 
 这意味着：
 
-- `FrontendLocalTypeStabilizationAnalyzer` 运行在 top binding 之后、chain binding 之前，只回写符合条件的 `:=` local `BlockScope` slot
-- `FrontendChainBindingAnalyzer` 只运行在 skeleton、scope graph、variable inventory、`symbolBindings()` 与局部类型稳定化结果已发布之后
-- `FrontendExprTypeAnalyzer` 只运行在 `symbolBindings()`、`resolvedMembers()` 与当前 `resolvedCalls()` published surface 已发布之后
-- body phase 仍保持“先发布 member/call，再发布 expression type”的顶层边界，不回头重开更早 phase
+- production body facts 只通过 SuiteResolver 的 `FrontendTypedLexicalEnvironment` overlay 与 per-owner patch transaction 导出
+- chain binding owner procedure 只在当前 statement root 内消费已发布 / pending 的 binding 与 stabilized local slot fact
+- expr typing owner procedure 只在 chain-owned member/call facts 已对当前 root 可见后发布 expression facts 与 bare-call facts
+- 阶段 K 已删除 standalone chain/expr whole-module analyzer 与 window shim；focused tests
+  直接覆盖 `FrontendBodyOwnerProcedures`、typed overlay 与 per-owner patch export，不再维护
+  comparison publication path
 
 ### 1.2 当前 owner 边界
 
@@ -479,12 +480,13 @@ writable / compatibility 规则为：
 
 - parameter default
 - lambda subtree
-- `for` subtree
 - `match` subtree
 - block-local `const`
 - class constant
 - scope-local 手动 `type-meta`
 
+`ForStatement` 已使用 header-only statement boundary：iterator type 与 iterable expression 在外层 lexical context 中运行 owner procedures，flush 后通过普通 child-suite path 解析 `FOR_BODY`。For body 中的 ordinary expressions 与 locals 复用本合同；typed result 不能决定是否进入 body。Iteration plan 与 iterator exact refinement 属于后续独立 owner，不由 chain/expr owner 猜测。
+
 当前 remaining explicit-deferred expression set 固定为：
 
 - `ConditionalExpression`

doc/module_impl/frontend/frontend_compile_check_analyzer_implementation.md

@@ -4,8 +4,8 @@
 
 ## 文档状态
 
-- 状态：事实源维护中（compile-only final gate、显式 AST 封口、generic published-fact blocker、explicit self assignment-target prefix 去重、shared/compile 分流边界、unary/binary 非 blocker 合同已落地）
-- 更新时间：2026-04-26
+- 状态：事实源维护中（compile-only final gate、for statement-root 临时 blocker、显式 AST 封口、generic published-fact blocker、shared/compile 分流边界与 SuiteResolver stable facts 已落地）
+- 更新时间：2026-07-20（阶段 L：for shared semantic 已解封，compile-only 仅保留 root blocker）
 - 适用范围：
   - `src/main/java/gd/script/gdcc/frontend/sema/**`
   - `src/main/java/gd/script/gdcc/frontend/sema/analyzer/**`
@@ -39,11 +39,12 @@
 
 1. `analyze(...)`
    - 共享 frontend 语义入口
-   - 负责发布 8 个稳定 frontend phase 的 semantic facts
+   - 负责发布 skeleton/scope/variable、interface/body suite、shared semantic publication 与 diagnostics-only phase 的 frontend facts / diagnostics snapshots
+   - body semantic facts 只来自 `FrontendSuiteResolver` 的 per-owner patch transaction；shared analyzer 不再提供 legacy whole-phase body publication bypass
    - 不保证 lowering-ready
 2. `analyzeForCompile(...)`
    - compile-only 入口
-   - 先运行共享 8 phase
+   - 先运行共享 semantic pipeline
    - 再运行 `FrontendCompileCheckAnalyzer`
    - 最后刷新最终 diagnostics snapshot
 
@@ -54,6 +55,7 @@ inspection 与未来 LSP 必须继续消费共享 `analyze(...)`，而不是隐
 `FrontendCompileCheckAnalyzer` 当前只负责 diagnostics-only final gate：
 
 - 读取已经发布的 frontend 事实
+- 读取 compile-gate 入口处冻结的 live `DiagnosticManager` snapshot 作为 upstream duplicate-suppression 输入
 - 对 compile mode 仍不可接受的 surface 发出 `sema.compile_check`
 - 不创建新的 side table
 - 不改写已有 side table
@@ -99,20 +101,19 @@ compile gate 可以沿 callable body 和支持岛 property initializer 继续递
 
 - parameter default
 - lambda subtree
-- `for` subtree
 - `match` subtree
 - block-local `const`
 - missing-scope / skipped subtree
 
-这条边界的目的不是“少报错”，而是避免 compile gate 把已经被上游明确封口的恢复域重新打平成 lowering surface。
+这条边界的目的不是“少报错”，而是避免 compile gate 把已经被上游明确封口的恢复域重新打平成 lowering surface。`ForStatement` 不属于该跳过集合：它已进入 shared semantic，compile gate 会命中 statement root，但不会进入 body 重扫 facts。
 
 ---
 
 ## 3. 显式 AST Compile-Block 清单
 
 ### 3.1 statement 级封口
 
-`AssertStatement` 当前由 compile gate 显式拦截，并直接发出 `sema.compile_check` `error`。
+`AssertStatement` 与 `ForStatement` 当前由 compile gate 显式拦截，并直接发出 `sema.compile_check` `error`。
 
 这里需要同时保持两条事实：
 
@@ -121,6 +122,14 @@ compile gate 可以沿 callable body 和支持岛 property initializer 继续递
 
 因此，`assert` 的 compile-only block 只表达“lowering/backend 尚未接通”，而不是 source contract 已被收紧。
 
+`ForStatement` 使用更窄的临时 bridge：
+
+- blocker 只锚定 owning `ForStatement` root。
+- 不进入 body，不重新扫描 iterator/body 已发布的 semantic facts。
+- 不读取 iterable type、iteration plan、route readiness 或 diagnostic-derived state。
+- shared `analyze(...)` 不包含该 blocker；只有 `analyzeForCompile(...)` 会阻止 for 进入尚未支持的 CFG/lowering。
+- 后续 route-aware compile policy 只能替换该 blocker，不能控制 iterator inventory、completeness certificate 或 child-suite dispatch。
+
 ### 3.2 declaration 级封口
 
 脚本类 `static var` declaration 当前同样由 compile gate 显式拦截，并直接发出
@@ -335,6 +344,7 @@ compile gate 当前统一使用：
 
 当前“已有 upstream error”按以下条件判定：
 
+- upstream 诊断集合来自 compile gate 入口处冻结的 live `DiagnosticManager.snapshot()`，而不是之后会被本 gate 继续追加的 mutable manager
 - 同一 `sourcePath`
 - 同一 `FrontendRange`
 - severity 为 `ERROR`
@@ -371,6 +381,7 @@ compile gate 当前统一使用：
 这条规则同样适用于：
 
 - `assert`
+- `ForStatement`
 - `ConditionalExpression`
 - `ArrayExpression`
 - `DictionaryExpression`
@@ -397,6 +408,7 @@ compile gate 当前统一使用：
   - `DYNAMIC` 不误判为 blocker
   - `ConditionalExpression` 只在 compile-only 路径被拦截，不污染 shared analyze
   - `assert` 继续保持 shared condition contract，只在 compile-only 路径被拦截
+  - for shared semantic 正常发布 body facts，compile-only 路径只产生单一 statement-root blocker且不扫描 body
 - `FrontendSemanticAnalyzerFrameworkTest`
   - `analyze(...)` 与 `analyzeForCompile(...)` 的分离
   - compile gate 在 type-check 之后执行
@@ -415,7 +427,7 @@ compile gate 当前统一使用：
 
 - frontend -> LIR lowering 入口必须强制使用 `analyzeForCompile(...)`
 - lowering 在继续前必须检查 `diagnostics().hasErrors() == false`
-- `assert` 与 8 类显式拦截表达式的真正 lowering/backend 支持仍待后续阶段补齐
+- `assert`、for route-aware CFG/lowering 与 8 类显式拦截表达式的真正 lowering/backend 支持仍待后续阶段补齐
 
 若未来需要为 LSP 单独呈现 compile-only blocker，正确方向仍是：