mtgodot-poc/audit/contracts/lifecycle.bootstrap-phase-host.md

lifecycle.bootstrap_phase_host

Scope

对比 40250 的应用启动、单帧处理顺序、网络阶段属主、Loading 入口清理、DEAD/CLOSE、窗口焦点/后台和最终销毁，与当前 Godot client_main、AppFlow、AppLifecycle、M2Client 和场景树行为。

Reference call chain

启动与每帧

• UserInterface/PythonApplication.cpp::Run
• UserInterface/PythonApplication.cpp::Process
  1. ELTimer_SetFrameMSec / CTimer::Advance
  2. CPythonNetworkStream::Process
  3. guild mark uploader/downloader、account connector
  4. keyboard/mouse input
  5. camera、resource manager、camera update、mouse update、UI update
• UserInterface/PythonApplicationEvent.cpp
• UserInterface/PythonApplicationProcedure.cpp

阶段属主与清理

• UserInterface/PythonNetworkStream.cpp::RecvPhasePacket
  • PHASE_CLOSE -> ClosePhase -> SetLoginPhase
  • PHASE_HANDSHAKE -> SetHandShakePhase
  • PHASE_LOGIN -> SetLoginPhase
  • PHASE_SELECT -> SetSelectPhase
  • PHASE_LOADING -> SetLoadingPhase
  • PHASE_GAME -> SetGamePhase
  • PHASE_DEAD 只消费阶段包，不改变网络阶段
• UserInterface/PythonNetworkStreamPhaseLogin.cpp::SetLoginPhase
• UserInterface/PythonNetworkStreamPhaseSelect.cpp::SetSelectPhase
• UserInterface/PythonNetworkStreamPhaseLoading.cpp::SetLoadingPhase
  • CPythonPlayer::Clear
  • CFlyingManager::DeleteAllInstances
  • CEffectManager::DeleteAllInstances
  • direct-enter 状态初始化
• UserInterface/PythonNetworkStreamPhaseGame.cpp::SetGamePhase
• UserInterface/PythonNetworkStreamPhaseGame.cpp::__LeaveGamePhase
  • PVP key、network actor、combo flag、character manager、item manager
• UserInterface/PythonNetworkStreamPhaseGameActor.cpp::__ClearNetworkActorManager

关闭与销毁

• EterLib/MSApplication.cpp::MessageProcess
• EterLib/MSWindow.cpp::WindowProcedure/Destroy
• UserInterface/PythonApplicationProcedure.cpp::WindowProcedure
  • WM_ACTIVATEAPP: 保存/恢复音量；全屏窗口最小化/恢复
  • WM_CLOSE: debug 退出，release 走 RunPressExitKey
• UserInterface/PythonApplication.cpp::Destroy
  • UI、事件、飞行物、角色、物品、背景、特效、网络、资源、声音、设备按显式顺序销毁

Current call chain

启动与每帧

• project/client_main.gd::_ready
  • AssetPack.ensure
  • 创建 AppFlow
• project/app_flow.gd::start
  • 创建并挂载一个 M2Client
  • 创建 LoadingScreen、AppLifecycle、ReconnectUI
  • 进入 Login
• extension/src/net/m2_client.cpp::_process/net_poll
  • 依次 pump classic/auth/game/mark 连接
  • classic 侧再转发 EntityStore 变化和 Godot signals
• project/game_scene.gd::_process
  • 主角同步、诊断、音频 listener/环境音
• project/app_flow.gd::_goto_game
  • 以协程构造 GameScene；等待模型时只让出帧，不夺取 M2Client._process 的网络 pump owner
• project/login.gd
  • 保留一条独立的 SceneTree 入口：自行创建 AppLifecycle、M2Client、登录层和 GameScene
  • 不经过 client_main.gd -> AppFlow，因此与主入口不是同一套阶段、关闭和销毁属主

阶段属主与清理

• extension/src/net/classic/classic_session.cpp::on_phase
  • LOGIN/SELECT/LOADING/GAME 映射到 INetSession::Stage
  • PHASE_CLOSE 直接映射为 Stage::Failed
  • PHASE_DEAD 没有 case，仅被前置的 time-sync 判断覆盖，未改变 stage
• extension/src/net/m2_client.cpp::pump_classic
  • Stage 变化才发 phase_changed
  • stage 表只有 close/handshake/login/select/loading/in_game/failed，没有 dead
  • EntityStore 的实体、死亡、掉落、地图 warp 变化在同一 pump 中派发
• project/ui/loading_screen.gd
  • 只按 phase_changed 显示/隐藏 Loading 遮罩
• project/game_scene.gd::_on_world_reset
  • 清 NetPlay、NetWorld、掉落、弹道、临时 UI 和 BGM
  • 由 M2Client 的 classic on_loading_phase 在保留旧 world 时触发；空 world 或已由 GC_WARP 预清理的连接不重复触发
• project/net_play.gd::clear_for_map_change
• project/net_world.gd::clear_for_map_change
• extension/src/net/entity_store.cpp::reset_for_map_change

窗口与后台

• project/app_lifecycle.gd::_notification
  • application paused/resumed 时保存/静音/恢复音频、暂停/恢复 M2Client 和 SceneTree
  • focus 只发 focus_changed，没有 40250 的音量/全屏处理
  • NOTIFICATION_WM_CLOSE_REQUEST 只发 close_requested
• AppFlow 与旧 login.gd 分别消费各自 AppLifecycle.close_requested，关闭时按网络→音频解绑→场景释放→进程退出顺序协调；两条入口仍不是同一个启动拓扑。

销毁

• AppFlow::_goto_login 对 GameScene/UI 使用 queue_free
• M2Client::~M2Client 为 default；连接由成员 RAII 析构关闭
• 未发现与 40250 CPythonApplication::Destroy 对应的、可观测且有顺序保证的网络/实体/特效/UI/音频总清理函数

Branch matrix

场景	40250	当前端	结论
启动/正常帧	固定在 Process 中先计时、网络，再输入、资源、相机和 UI	Godot 由 M2Client._process 持有网络 pump；_goto_game 等待模型只 yield 并同步视图	PARTIAL：跨节点顺序和模型构建期间的完整事件时序仍未证明一致
主入口/旧入口	CPythonApplication 只有一个启动和销毁拓扑	client_main.gd -> AppFlow 与旧的 login.gd 各自创建生命周期、客户端和游戏场景	GAP：主入口测试不能证明旧入口也遵守单一生命周期属主
LOGIN/SELECT	RecvPhasePacket 作为唯一阶段 owner，阶段切换先执行旧 phase leave，再安装新 process/leave 回调	ClassicSession::Stage、M2Client signals、AppFlow 三层分担	PARTIAL：状态 owner 不唯一，乱序和重复 phase 规则未统一
SELECT -> LOADING	SetLoadingPhase 先切 phase，再清 player、飞行物、特效和 direct-enter 状态	classic on_loading_phase 在阶段回调内先清旧 EntityStore 并发 world_reset，再继续 Loading；空 world 直接跳过	PARTIAL：NetPlay/NetWorld/特效的完整 owner 顺序和真实 server 包序仍待补齐
GAME -> DEAD	40250 的 PHASE_DEAD 本身不改 phase，死亡包在 Game phase 内走 GameOver/角色死亡链	ClassicSession 不发 dead phase；DeathUI 现在只从 GC_DEAD -> entity_dead 进入，和 40250 的死亡包入口一致	PARTIAL：死亡入口已闭环，GameOver/决斗例外、死亡动作和真实包序仍待补齐
PHASE_CLOSE	回调 SetLoginPhase，由登录阶段继续处理	PHASE_CLOSE -> Stage::Failed，再发 login_failed 或 disconnected	GAP：状态和 UI 入口不同
GC_WARP	进入 Loading，显式清旧 actor/物品/特效，再连接/加载新地图	EntityStore::reset_for_map_change -> world_reset -> connect_warp，并由 Loading 回调的空 world guard 避免重复 reset	PARTIAL：NetPlay/NetWorld/特效的完整 owner 顺序和真实 server 包序仍待补齐
断线重连	old phase leave、连接状态和角色数据按网络 owner 协调	ReconnectUI 负责重试，M2Client 重新建/切 session；场景可能保留，world reset 不是统一前置	PARTIAL；与 network.reconnect_warp 交叉记录
窗口失焦/后台	Windows WM_ACTIVATEAPP 保存/恢复音量并处理全屏，主循环仍由应用控制	focus 仅广播；application pause 会暂停 socket/SceneTree 并静音	PARTIAL / platform adaptation：行为不是 1:1
窗口关闭	WM_CLOSE 经退出键/退出流程，最终 Destroy	AppFlow/旧 login.gd 唯一消费 close_requested，先断开并解绑资源后退出；Windows 退出确认/保存细节仍未证明	PARTIAL
最终销毁	明确 manager 顺序、网络/声音/设备显式 Destroy	Godot queue_free + C++ default destructor/RAII	PARTIAL：资源最终可能释放，但副作用顺序与可观测状态未等价

Equivalence matrix

项目	状态	证据
Preconditions	PARTIAL	当前入口有资源、扩展和 serverlist 检查，但没有统一阶段/关闭前置条件
Branch structure	PARTIAL	LOGIN/SELECT/LOADING/GAME 已映射；DEAD、CLOSE、窗口关闭和重复启动/关闭缺统一分支
Algorithms/formulas	MAPPED	主循环没有业务公式；计时和网络 pump owner 不同
State transition order	PARTIAL	参考由 RecvPhasePacket + phaseLeaveFunc 单 owner 串行；当前由 session/stage/signal/AppFlow 分散推进
Constants/units	PARTIAL	1500ms enter-game 等已有实现，但 frame/timer、Loading 清理和重连窗口未证明相同
Timing/event sources	PARTIAL	当前有 Godot _process、signal、协程和模型同步；网络 pump 已收敛到 M2Client owner，参考是 Windows message + phase callback
Resource/data sources	PARTIAL	当前资源由 scene/RAII 管理；参考是各 manager 显式拥有，且正常 Loading 与 close 清理源不同；client_main 与旧 login.gd 还存在两套资源/生命周期装配源
Protocol side effects	PARTIAL	LOGIN/SELECT/ENTERGAME/warp 已有路径；CLOSE、DEAD 和 loading reset 的副作用不等价
Interruption/failure/cleanup	PARTIAL	断线/warp/关闭消费者已有部分回归；普通重连 reset、重复关闭、socket 失败和 final destroy 的完整顺序仍缺证据

Evidence and regression boundary

project/app_flow_lifecycle_test.gd 已验证：AppFlow 只创建一个 AppLifecycle、登录/游戏切换不重复创建、游戏断线保留场景并按原槽位重进、显式槽位不存在时不错误自动选人，并且桌面关闭信号有唯一消费者。project/test_death_restart_parity.gd 另外验证 PHASE_DEAD 不作为死亡面板入口，GC_DEAD -> entity_dead 才打开 RestartDialog。project/gamescene_test.gd 和 project/channel_status_test.gd 只提供场景装配/频道状态旁证。它们没有证明 40250 的固定每帧顺序、Loading 清理、DEAD/CLOSE 的完整副作用、旧 login.gd 入口或最终销毁等价，因此本合同不能升级为 MAPPED。

Required tests

• 记录并断言 M2Client._process、GameScene/UI _process 和 loading 协程的同帧顺序，禁止等待模型时重入 pump 造成重复 phase/entered_game。
• LOGIN/SELECT/LOADING/GAME/DEAD/CLOSE 的正常、乱序、重复和断线状态矩阵；特别断言 PHASE_DEAD 的消费和 PHASE_CLOSE 的目标状态。
• SELECT -> LOADING、GC_WARP、普通重连三条路径分别验证 actor、飞行物、特效、NetPlay 动作、掉落、临时 UI、BGM 和 EntityStore 的清理顺序。
• focus out/in、application pause/resume、重复 pause/resume、窗口 close、网络失败和重复 close 的音频、socket、SceneTree、退出状态测试。
• GameScene queue_free、M2Client 析构、旧 session 关闭和再次启动的资源/信号泄漏测试。
• 分别从 client_main.tscn 和旧 login.gd 启动，验证 AppLifecycle、M2Client、GameScene、音频和 close 信号没有重复属主或悬空连接。

Active UserInterface application/security review

• UserInterface/AbstractApplication.h 把鼠标、全局时间、服务器时间、中心位置、事件/默认相机和 IME update/tab/return/code-page/candidate/reading callbacks 作为应用宿主接口；这与当前仅由 Godot notification/signal 分散处理不是同一 host contract。
• UserInterface/PythonApplicationModule.cpp 暴露应用 process/update/render FPS、相机参数、硬件/软件光标、连接数据、文本 loader 和 pack 读取等 Python 边界；PythonApplicationLogo.cpp、PythonApplicationWebPage.cpp、MovieMan.cpp 管理视频/网页/媒体 surface 的创建、更新、跳过、淡出和释放。
• PythonSystem.cpp/PythonSystemModule.cpp 以 D3D adapter/resolution/frequency、窗口状态、音量、阴影级别、保存 ID、配置文件和 interface status 为权威；当前 AppLifecycle/系统设置只覆盖 Godot 的一部分状态，Windows display mode、旧配置格式和媒体资源清理没有等价证据。
• ProcessCRC.cpp/CheckLatestFiles.h、ProcessScanner.cpp、PythonExceptionSender.cpp、HackShield/NProtectGameGuard/WiseLogicXTrap 构成参考端完整性、进程扫描、安全组件和异常上报链。当前客户端没有对应 Windows 安全/CRC/异常服务链；这些是明确的部署能力差异，不应被普通启动测试掩盖。
• 本轮完成上述 UserInterface 应用/安全活跃文件静态核对，并修正 DeathUI 对不可达 phase_changed("dead") 的错误依赖；当前端基础 AppFlow 可运行，但 bootstrap/关闭/安全/发布合同继续为 PARTIAL。

Status

PARTIAL。本轮完成了 40250 参考调用链与当前实现调用链的逐分支审计，并修正了 DeathUI 对不可达 phase_changed("dead") 的错误依赖、classic Loading 阶段缺少旧 world 清理入口、主入口/旧入口遗漏关闭消费者，以及 _goto_game 等待模型时重复夺取网络 pump 的问题；DEAD/CLOSE 其余状态语义、focus/后台、旧入口分叉和显式销毁链仍存在未闭合差异，因此不能宣称已全部按 40250 修复。

Implementation round 2026-09-21T04:20Z — close request ownership

本轮针对 40250 PythonApplicationProcedure::WindowProcedure(WM_CLOSE) 和 CPythonApplication::Destroy 的关闭入口补齐 Godot 两条启动拓扑：

• AppFlow.start 将唯一的 AppLifecycle.close_requested 连接到 _on_close_requested；处理器具备幂等锁，先调用 M2Client.disconnect_from_server()，再解绑生命周期持有的音频、释放 GameScene，最后退出 SceneTree。
• 旧 login.gd 自己创建 AppLifecycle，因此也接入同样的断开/解绑/场景释放/退出顺序，避免只修 client_main 主入口。
• app_flow_lifecycle_test.gd 新增失败回归：没有消费者时失败，修复后验证 AppFlow 连接了唯一关闭处理器；Godot editor/headless 脚本加载检查通过。

仍保持 PARTIAL：Windows 退出确认与保存细节、真实 socket close 回调顺序、重复 close 与最终 native manager 销毁尚未由运行时 fixture 完整证明。

Implementation round 2026-09-21T04:25Z — frame pump ownership

本轮按 40250 CPythonApplication::Process 的单一网络处理 owner 修复进入游戏等待段：

• 删除 AppFlow::_goto_game 等待 _model_built 时的直接 client.net_poll()；每次循环只同步模型并让出一帧，由 M2Client._process 继续负责唯一网络 pump。
• 失败回归在 app_flow_lifecycle_test.gd 中检查 _goto_game 源码段不得重新调用 client.net_poll()；修复后生命周期、GameScene 和 world reset 回归均通过。

仍保持 PARTIAL：GameScene 内部模型构建仍有传入 pump callable 的资源加载适配，完整跨节点同帧顺序、阶段重复/乱序包和 entered_game 重入矩阵仍需运行时 fixture。